Merge pull request #14737 from chouseknecht/docker_network_proposal

Adding docker_network module proposal.
This commit is contained in:
Brian Coca 2016-03-02 10:08:52 -05:00
commit 2a1f955ea5

View file

@ -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 >
}
}
```