diff --git a/docs/proposals/docker/docker_network_module.md b/docs/proposals/docker/docker_network_module.md new file mode 100644 index 0000000000..4b07e3072d --- /dev/null +++ b/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 > + } +} +``` \ No newline at end of file