Management of Docker networks
New in version 2017.7.0.
depends: | docker Python module |
---|
Note
Older releases of the Python bindings for Docker were called docker-py in PyPI. All releases of docker, and releases of docker-py >= 1.6.0 are supported. These python bindings can easily be installed using pip.install
:
salt myminion pip.install docker
To upgrade from docker-py to docker, you must first uninstall docker-py, and then install docker:
salt myminion pip.uninstall docker-py
salt myminion pip.install docker
These states were moved from the docker
state module (formerly called dockerng) in the 2017.7.0 release.
Ensure that a network is absent.
Usage Example:
network_foo: docker_network.absent
Changed in version 2018.3.0: Support added for network configuration options other than driver
and driver_opts
, as well as IPAM configuration.
Ensure that a network is present
Note
This state supports all arguments for network and IPAM pool configuration which are available for the release of docker-py installed on the minion. For that reason, the arguments described below in the NETWORK CONFIGURATION and IP ADDRESS MANAGEMENT (IPAM) sections may not accurately reflect what is available on the minion. The docker.get_client_args
function can be used to check the available arguments for the installed version of docker-py (they are found in the network_config
and ipam_config
sections of the return data), but Salt will not prevent a user from attempting to use an argument which is unsupported in the release of Docker which is installed. In those cases, network creation be attempted but will fail.
This function translates Salt SLS input into the format which docker-py expects. However, in the event that Salt's translation logic fails (due to potential changes in the Docker Remote API, or to bugs in the translation code), this argument can be used to exert granular control over which arguments are translated and which are not.
Pass this argument as a comma-separated list (or Python list) of arguments, and translation for each passed argument name will be skipped. Alternatively, pass True
and all translation will be skipped.
Skipping tranlsation allows for arguments to be formatted directly in the format which docker-py expects. This allows for API changes and other issues to be more easily worked around. See the following links for more information:
New in version 2018.3.0.
Since many of docker-py's arguments differ in name from their CLI counterparts (with which most Docker users are more familiar), Salt detects usage of these and aliases them to the docker-py version of that argument. However, if both the alias and the docker-py version of the same argument (e.g. options
and driver_opts
) are used, an error will be raised. Set this argument to True
to suppress these errors and keep the docker-py version of the argument.
New in version 2018.3.0.
For parameters which accept IP addresses/subnets as input, validation will be performed. To disable, set this to False
.
New in version 2018.3.0.
A list of containers which should be connected to this network.
Note
As of the 2018.3.0 release, this is not the recommended way of managing a container's membership in a network, for a couple reasons:
docker_container.running
state replaces a container, it will not be reconnected to the network until the docker_network.present
state is run again. Since containers often have require
requisites to ensure that the network is present, this means that the docker_network.present
state ends up being run before the docker_container.running
, leaving the container unattached at the end of the Salt run.For these reasons, it is recommended to use docker_container.running's network management support.
If containers
is not used, and the network is replaced, then Salt will keep track of the containers which were connected to the network and reconnect them to the network after it is replaced. Salt will first attempt to reconnect using the same IP the container had before the network was replaced. If that fails (for instance, if the network was replaced because the subnet was modified), then the container will be reconnected without an explicit IP address, and its IP will be assigned by Docker.
Set this option to False
to keep Salt from trying to reconnect containers. This can be useful in some cases when managing static IPs in docker_container.running. For instance, if a network's subnet is modified, it is likely that the static IP will need to be updated in the docker_container.running
state as well. When the network is replaced, the initial reconnect attempt would fail, and the container would be reconnected with an automatically-assigned IP address. Then, when the docker_container.running
state executes, it would disconnect the network again and reconnect using the new static IP. Disabling the reconnect behavior in these cases would prevent the unnecessary extra reconnection.
New in version 2018.3.0.
NETWORK CONFIGURATION ARGUMENTS
Network driver
mynet:
docker_network.present:
- driver: macvlan
Options for the network driver. Either a dictionary of option names and values or a Python list of strings in the format varname=value
. The below three examples are equivalent:
mynet: docker_network.present: - driver: macvlan - driver_opts: macvlan_mode=bridge,parent=eth0
mynet: docker_network.present: - driver: macvlan - driver_opts: - macvlan_mode=bridge - parent=eth0
mynet: docker_network.present: - driver: macvlan - driver_opts: - macvlan_mode: bridge - parent: eth0
The options can also simply be passed as a dictionary, though this can be error-prone due to some idiosyncrasies with how PyYAML loads nested data structures:
mynet:
docker_network.present:
- driver: macvlan
- driver_opts:
macvlan_mode: bridge
parent: eth0
If True
, checks for networks with duplicate names. Since networks are primarily keyed based on a random ID and not on the name, and network name is strictly a user-friendly alias to the network which is uniquely identified using ID, there is no guaranteed way to check for duplicates. This option providess a best effort, checking for any networks which have the same name, but it is not guaranteed to catch all name collisions.
mynet:
docker_network.present:
- check_duplicate: False
If True
, restricts external access to the network
mynet:
docker_network.present:
- internal: True
Add metadata to the network. Labels can be set both with and without values, and labels with values can be passed either as key=value
or key: value
pairs. For example, while the below would be very confusing to read, it is technically valid, and demonstrates the different ways in which labels can be passed:
mynet: docker_network.present: - labels: - foo - bar=baz - hello: world
The labels can also simply be passed as a YAML dictionary, though this can be error-prone due to some idiosyncrasies with how PyYAML loads nested data structures:
foo: docker_network.present: - labels: foo: '' bar: baz hello: world
Changed in version 2018.3.0: Methods for specifying labels can now be mixed. Earlier releases required either labels with or without values.
Enable IPv6 on the network
mynet: docker_network.present: - enable_ipv6: True
Note
While it should go without saying, this argument must be set to True
to configure an IPv6 subnet. Also, if this option is turned on without an IPv6 subnet explicitly configured, you will get an error unless you have set up a fixed IPv6 subnet. Consult the Docker IPv6 docs for information on how to do this.
If True
, and the network is in the global scope, non-service containers on worker nodes will be able to connect to the network.
mynet: docker_network.present: - attachable: True
Note
This option cannot be reliably managed on CentOS 7. This is because while support for this option was added in API version 1.24, its value was not added to the inpsect results until API version 1.26. The version of Docker which is available for CentOS 7 runs API version 1.24, meaning that while Salt can pass this argument to the API, it has no way of knowing the value of this config option in an existing Docker network.
Specify the network's scope (local
, global
or swarm
)
mynet:
docker_network.present:
- scope: local
If True
, create an ingress network which provides the routing-mesh in swarm mode
mynet:
docker_network.present:
- ingress: True
IP ADDRESS MANAGEMENT (IPAM)
This state supports networks with either IPv4, or both IPv4 and IPv6. If configuring IPv4, then you can pass the IPAM pool arguments below as individual arguments. However, if configuring IPv4 and IPv6, the arguments must be passed as a list of dictionaries, in the ipam_pools
argument (click here for some examples). These docs also have more information on these arguments.
IPAM ARGUMENTS
IPAM driver to use, if different from the default one
mynet:
docker_network.present:
- ipam_driver: foo
Options for the IPAM driver. Either a dictionary of option names and values or a Python list of strings in the format varname=value
. The below three examples are equivalent:
mynet: docker_network.present: - ipam_driver: foo - ipam_opts: foo=bar,baz=qux
mynet: docker_network.present: - ipam_driver: foo - ipam_opts: - foo=bar - baz=qux
mynet: docker_network.present: - ipam_driver: foo - ipam_opts: - foo: bar - baz: qux
The options can also simply be passed as a dictionary, though this can be error-prone due to some idiosyncrasies with how PyYAML loads nested data structures:
mynet:
docker_network.present:
- ipam_driver: macvlan
- ipam_opts:
foo: bar
baz: qux
IPAM POOL ARGUMENTS
Allocate container IP from a sub-range within the subnet
Subnet in CIDR format that represents a network segment
host=ipaddr
.IPAM CONFIGURATION EXAMPLES
Below is an example of an IPv4-only network (keep in mind that subnet
is the only required argument).
mynet: docker_network.present: - subnet: 10.0.20.0/24 - iprange: 10.0.20.128/25 - gateway: 10.0.20.254 - aux_addresses: - foo.bar.tld: 10.0.20.50 - hello.world.tld: 10.0.20.51
Note
The aux_addresses
can be passed differently, in the same way that driver_opts
and ipam_opts
can.
This same network could also be configured this way:
mynet: docker_network.present: - ipam_pools: - subnet: 10.0.20.0/24 iprange: 10.0.20.128/25 gateway: 10.0.20.254 aux_addresses: foo.bar.tld: 10.0.20.50 hello.world.tld: 10.0.20.51
Here is an example of a mixed IPv4/IPv6 subnet.
mynet: docker_network.present: - ipam_pools: - subnet: 10.0.20.0/24 gateway: 10.0.20.1 - subnet: fe3f:2180:26:1::/123 gateway: fe3f:2180:26:1::1
© 2019 SaltStack.
Licensed under the Apache License, Version 2.0.
https://docs.saltstack.com/en/latest/ref/states/all/salt.states.docker_network.html