Merge pull request #14756 from chouseknecht/docker_network_proposal

Updating docker_network module proposal.

docs/proposals/docker/docker_network_module.md

@@ -15,60 +15,51 @@ Docker_network will accept the parameters listed below. Parameters related to co
 a shared utility module, as mentioned above.
 
 ```
-containers:
-
-network_name:
+connected:
   description:
-    - Name of the network to operate on.
+    - List of container names or container IDs to connect to a network.
   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:
+force:
   description:
-    - Dictionary of network settings. Consult docker docs for valid options and values.
-  default: null
+    - 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
 
-connected:
+incremental:
   description:
-    - List of container names or container IDs to connect to a network.
-  default: null
+    - 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
 
-disconnected:
+network_name:
   description:
-    - List of container names or container IDs to disconnect from a network.
+    - Name of the network to operate on.
   default: null
+  required: true
 
-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:
+options:
   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
+    - Dictionary of network settings. Consult docker docs for valid options and values.
+  default: null
     
 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,27 +76,21 @@ state:
     connected:
       - containera
       - containerb
-    disconnect_all: yes
-
-- name: Remove a container from the network
-  docker_network:
-    name: network_one
-    disconnected:
-      - containerb
+      - containerc
 
-- name: Delete a network, disconnected all containers
+- name: Remove a single container
   docker_network:
     name: network_one
-    state: absent
-    force: yes
+    connected: "{{ fulllist|difference(['containera']) }}"
        
-- name: Add a container to a network
+- name: Add a container to a network, leaving existing containers connected
   docker_network:
     name: network_one
     connected:
       - containerc
+    incremental: yes
    
-- name: Create a network with options (Not sure if 'ip_range' is correct name)
+- name: Create a network with options (Not sure if 'ip_range' is correct key name)
   docker_network
     name: network_two
     options:
@@ -113,6 +98,11 @@ state:
       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: