# salt.states.docker_network

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.

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