Merge pull request #14737 from chouseknecht/docker_network_proposal

Adding docker_network module proposal.

docs/proposals/docker/docker_network_module.md

@@ -0,0 +1,130 @@
+# Docker_Network Module Proposal
+
+## Purpose and Scope:
+
+The purpose of Docker_network is to create networks, connect containers to networks, disconnect containers from 
+networks, and delete networks.
+
+Docker network will manage networks using docker-py to communicate with either a local or remote API. It will
+support API versions >= 1.14. API connection details will be handled externally in a shared utility module similar to
+how other cloud modules operate.
+
+## Parameters:
+
+Docker_network will accept the parameters listed below. Parameters related to connecting to the API will be handled in 
+a shared utility module, as mentioned above.
+
+```
+containers:
+
+network_name:
+  description:
+    - Name of the network to operate on.
+  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.
+  default: present
+  choices:
+    - absent
+    - present
+    
+```
+
+
+## Examples:
+
+```
+- name: Create a network
+  docker_network:
+    name: network_one
+
+- name: Remove all but selected list of containers
+  docker_network:
+    name: network_one
+    connected:
+      - containera
+      - containerb
+    disconnect_all: yes
+
+- name: Remove a container from the network
+  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
+  docker_network:
+    name: network_one
+    connected:
+      - containerc
+      
+- name: Create a network with options (Not sure if 'ip_range' is correct 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'
+      
+```
+
+## Returns:
+
+```
+{
+    changed: True,
+    failed: false
+    rc: 0
+    action: created | removed | none
+    results: {
+        < results from docker inspect for the affected network >
+    }
+}
+```