salt.states.docker_network

Management of Docker networks

depends

docker Python module

salt myminion pip.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.

salt.states.docker_network.absent(name)

Ensure that a network is absent.

name

Name of the network

Usage Example:

network_foo:
  docker_network.absent

salt.states.docker_network.present(name, skip_translate=None, ignore_collisions=False, validate_ip_addrs=True, containers=None, reconnect=True, **kwargs)

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.

name

Network name

skip_translate

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:

• docker-py Low-level API

• Docker Engine API

New in version 2018.3.0.

ignore_collisionsFalse

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.

validate_ip_addrsTrue

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.

containers

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:

1. It does not support setting static IPs, aliases, or links in the container's IP configuration.

2. If a 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.

reconnectTrue

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

driver

Network driver

mynet:
  docker_network.present:
    - driver: macvlan

driver_opts (or driver_opt, or options)

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

check_duplicateTrue

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

internalFalse

If True, restricts external access to the network

mynet:
  docker_network.present:
    - internal: True

labels

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 (or ipv6)False

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.

attachableFalse

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.

scope

Specify the network's scope (local, global or swarm)

mynet:
  docker_network.present:
    - scope: local

ingressFalse

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

IPAM driver to use, if different from the default one

mynet:
  docker_network.present:
    - ipam_driver: foo

ipam_opts

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

subnet

Subnet in CIDR format that represents a network segment

iprange (or ip_range)

Allocate container IP from a sub-range within the subnet

Subnet in CIDR format that represents a network segment

gateway

IPv4 or IPv6 gateway for the master subnet

aux_addresses (or aux_address)

A dictionary of mapping container names to IP addresses which should be allocated for them should they connect to the network. Either a dictionary of option names and values or a Python list of strings in the format 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