Merge pull request #14756 from chouseknecht/docker_network_proposal

Updating docker_network module proposal.

docs/proposals/docker/docker_network_module.md

@@ -15,7 +15,27 @@ Docker_network will accept the parameters listed below. Parameters related to co
 a shared utility module, as mentioned above.
 
 ```
-containers:
+connected:
+  description:
+    - List of container names or container IDs to connect to a network.
+  default: null
+
+driver:
+  description:
+    - Specify the type of network. Docker provides bridge and overlay drivers, but 3rd party drivers can also be used.
+  default: bridge
+
+force:
+  description:
+    - With state 'absent' forces disconnecting all containers from the network prior to deleting the network. With
+      state 'present' will disconnect all containers, delete the network and re-create the network.
+  default: false
+
+incremental:
+  description:
+    - By default the connected list is canonical, meaning containers not on the list are removed from the network.
+      Use incremental to leave existing containers connected.
+  default: false
 
 network_name:
   description:
@@ -23,52 +43,23 @@ network_name:
   default: null
   required: true
 
-driver:
-  description:
-    - Specify the type of network. Docker provides bridge and overlay drivers, but 3rd party drivers can also be used.
-  default: bridge
-
 options:
   description:
     - Dictionary of network settings. Consult docker docs for valid options and values.
   default: null
-
-connected:
-  description:
-    - List of container names or container IDs to connect to a network.
-  default: null
-  
-disconnected:
-  description:
-    - List of container names or container IDs to disconnect from a network.
-  default: null
-
-disconnect_all:
-  description:
-    - Disconnect all containers, unless the containers is in the provided list of connected containers. If no
-      list of connected containers is provided, all containers will be disconnnected.
-  default: false
-
-force:
-  description:
-    - With state 'absent' forces disconnecting all containers from the network prior to deleting the network. With
-      state 'present' will disconnect all containers, delete the network and re-create the network.
-    default: false
     
 state:
   description:
     - "absent" deletes the network. If a network has connected containers, it cannot be deleted. Use the force option
       to disconnect all containers and delete the network.
     - "present" creates the network, if it does not already exist with the specified parameters, and connects the list
-      of containers provided via the connected parameter. Use disconnected to remove a set of containers from the
-      network. Use disconnect_all to remove from the network any containers not included in the containers parameter.
-      If disconnected is provided with no list of connected parameter, all containers will be removed from the 
-      network. Use the force options to force the re-creation of the network.
+      of containers provided via the connected parameter. Containers not on the list will be disconnected. An empty
+      list will leave no containers connected to the network. Use the incremental option to leave existing containers
+      connected. Use the force options to force re-creation of the network.
   default: present
   choices:
     - absent
     - present
-    
 ```
 
 
@@ -85,34 +76,33 @@ state:
     connected:
       - containera
       - containerb
-    disconnect_all: yes
+      - containerc
 
-- name: Remove a container from the network
+- name: Remove a single container
   docker_network:
     name: network_one
-    disconnected:
-      - containerb
-
-- name: Delete a network, disconnected all containers
-  docker_network:
-    name: network_one
-    state: absent
-    force: yes
-    
-- name: Add a container to a network
+    connected: "{{ fulllist|difference(['containera']) }}"
+       
+- name: Add a container to a network, leaving existing containers connected
   docker_network:
     name: network_one
     connected:
       - containerc
-      
-- name: Create a network with options (Not sure if 'ip_range' is correct name)
+    incremental: yes
+   
+- name: Create a network with options (Not sure if 'ip_range' is correct key name)
   docker_network
     name: network_two
     options:
       subnet: '172.3.26.0/16'
       gateway: 172.3.26.1
       ip_range: '192.168.1.0/24'
-      
+
+- name: Delete a network, disconnecting all containers
+  docker_network:
+    name: network_one
+    state: absent
+    force: yes      
 ```
 
 ## Returns: