golden hour

/opt/saltstack/salt/lib/python3.10/site-packages/salt/states

File/Folder	Size	Actions
__init__.py	25 B
__pycache__	-
acme.py	5.08 KB
alias.py	2.49 KB
alternatives.py	6.75 KB
ansiblegate.py	7.93 KB
apache.py	3.95 KB
apache_conf.py	2.72 KB
apache_module.py	2.73 KB
apache_site.py	2.66 KB
aptpkg.py	1.42 KB
archive.py	68.24 KB
artifactory.py	6.84 KB
at.py	7.48 KB
augeas.py	10.57 KB
aws_sqs.py	2.59 KB
azurearm_compute.py	11.78 KB
azurearm_dns.py	26.05 KB
azurearm_network.py	89.12 KB
azurearm_resource.py	28.23 KB
beacon.py	7.58 KB
bigip.py	96.63 KB
blockdev.py	5.13 KB
boto3_elasticache.py	48.01 KB
boto3_elasticsearch.py	32.58 KB
boto3_route53.py	37.54 KB
boto3_sns.py	12.69 KB
boto_apigateway.py	82.83 KB
boto_asg.py	31.93 KB
boto_cfn.py	11.53 KB
boto_cloudfront.py	6.01 KB
boto_cloudtrail.py	13.18 KB
boto_cloudwatch_alarm.py	6.4 KB
boto_cloudwatch_event.py	12.33 KB
boto_cognitoidentity.py	13.69 KB
boto_datapipeline.py	18.5 KB
boto_dynamodb.py	29.32 KB
boto_ec2.py	71.98 KB
boto_elasticache.py	16.75 KB
boto_elasticsearch_domain.py	12.27 KB
boto_elb.py	55.1 KB
boto_elbv2.py	12.19 KB
boto_iam.py	69.16 KB
boto_iam_role.py	27.12 KB
boto_iot.py	25.33 KB
boto_kinesis.py	16.69 KB
boto_kms.py	12.11 KB
boto_lambda.py	35.52 KB
boto_lc.py	11.04 KB
boto_rds.py	26 KB
boto_route53.py	19.49 KB
boto_s3.py	9.32 KB
boto_s3_bucket.py	24.67 KB
boto_secgroup.py	32.62 KB
boto_sns.py	8.92 KB
boto_sqs.py	7.97 KB
boto_vpc.py	62.23 KB
bower.py	8.26 KB
btrfs.py	10.34 KB
cabal.py	5.73 KB
ceph.py	1.9 KB
chef.py	3.76 KB
chocolatey.py	16.15 KB
chronos_job.py	4.6 KB
cimc.py	14.32 KB
cisconso.py	3.14 KB
cloud.py	14.4 KB
cmd.py	40.92 KB
composer.py	8.38 KB
consul.py	5.4 KB
cron.py	23.39 KB
cryptdev.py	6.17 KB
csf.py	9.98 KB
cyg.py	7.05 KB
ddns.py	4.2 KB
debconfmod.py	6.33 KB
dellchassis.py	24.49 KB
disk.py	6.49 KB
docker_container.py	85.27 KB
docker_image.py	16.7 KB
docker_network.py	36.78 KB
docker_volume.py	6.72 KB
drac.py	4.17 KB
dvs.py	26.29 KB
elasticsearch.py	20.38 KB
elasticsearch_index.py	3.25 KB
elasticsearch_index_template.py	3.67 KB
environ.py	5.81 KB
eselect.py	2.27 KB
esxcluster.py	22.4 KB
esxdatacenter.py	4.44 KB
esxi.py	63.07 KB
esxvm.py	20.11 KB
etcd_mod.py	11 KB
ethtool.py	9.88 KB
event.py	2.48 KB
file.py	316.7 KB
firewall.py	1.33 KB
firewalld.py	26.08 KB
gem.py	7.13 KB
git.py	123.85 KB
github.py	27.25 KB
glance_image.py	2.26 KB
glassfish.py	21.47 KB
glusterfs.py	12.21 KB
gnomedesktop.py	7.47 KB
gpg.py	5.28 KB
grafana.py	12.11 KB
grafana4_dashboard.py	17.31 KB
grafana4_datasource.py	6.15 KB
grafana4_org.py	7.73 KB
grafana4_user.py	5.52 KB
grafana_dashboard.py	17.74 KB
grafana_datasource.py	5.31 KB
grains.py	15.57 KB
group.py	9.84 KB
heat.py	9.69 KB
helm.py	10.39 KB
hg.py	6.33 KB
highstate_doc.py	1.41 KB
host.py	8.64 KB
http.py	7.46 KB
icinga2.py	9.07 KB
idem.py	3.91 KB
ifttt.py	2.12 KB
incron.py	5.71 KB
influxdb08_database.py	2.85 KB
influxdb08_user.py	3.39 KB
influxdb_continuous_query.py	2.83 KB
influxdb_database.py	2.11 KB
influxdb_retention_policy.py	4.82 KB
influxdb_user.py	4.84 KB
infoblox_a.py	4.24 KB
infoblox_cname.py	4.19 KB
infoblox_host_record.py	6.59 KB
infoblox_range.py	6.85 KB
ini_manage.py	12.67 KB
ipmi.py	8.42 KB
ipset.py	9.66 KB
iptables.py	27.65 KB
jboss7.py	23.95 KB
jenkins.py	3.36 KB
junos.py	17.78 KB
kapacitor.py	6.46 KB
kernelpkg.py	6.42 KB
keyboard.py	2.01 KB
keystone.py	27.12 KB
keystone_domain.py	2.81 KB
keystone_endpoint.py	4.69 KB
keystone_group.py	3.25 KB
keystone_project.py	3.36 KB
keystone_role.py	2.33 KB
keystone_role_grant.py	4.08 KB
keystone_service.py	2.89 KB
keystone_user.py	3.47 KB
keystore.py	5.67 KB
kmod.py	8.59 KB
kubernetes.py	24.87 KB
layman.py	2.44 KB
ldap.py	19.78 KB
libcloud_dns.py	5.7 KB
libcloud_loadbalancer.py	5.66 KB
libcloud_storage.py	5.13 KB
linux_acl.py	24.42 KB
locale.py	2.52 KB
logadm.py	4.67 KB
logrotate.py	3.86 KB
loop.py	7.74 KB
lvm.py	13.33 KB
lvs_server.py	6.28 KB
lvs_service.py	4.38 KB
lxc.py	22.17 KB
lxd.py	7.88 KB
lxd_container.py	22.25 KB
lxd_image.py	10.59 KB
lxd_profile.py	7.11 KB
mac_assistive.py	1.55 KB
mac_keychain.py	5.59 KB
mac_xattr.py	3.15 KB
macdefaults.py	2.65 KB
macpackage.py	6.76 KB
makeconf.py	6.87 KB
marathon_app.py	4.45 KB
mdadm_raid.py	6.41 KB
memcached.py	3.95 KB
modjk.py	2.84 KB
modjk_worker.py	6.49 KB
module.py	18.64 KB
mongodb_database.py	1.65 KB
mongodb_user.py	6.26 KB
monit.py	2.68 KB
mount.py	50.32 KB
mssql_database.py	3 KB
mssql_login.py	3.64 KB
mssql_role.py	2.37 KB
mssql_user.py	3.51 KB
msteams.py	2.53 KB
mysql_database.py	6.05 KB
mysql_grants.py	8.49 KB
mysql_query.py	13.07 KB
mysql_user.py	9.51 KB
net_napalm_yang.py	9.15 KB
netacl.py	31.92 KB
netconfig.py	33.42 KB
netntp.py	12.51 KB
netsnmp.py	11.33 KB
netusers.py	16.1 KB
network.py	23.97 KB
neutron_network.py	3.96 KB
neutron_secgroup.py	4 KB
neutron_secgroup_rule.py	4.75 KB
neutron_subnet.py	4.29 KB
nexus.py	4.97 KB
nfs_export.py	4.92 KB
nftables.py	19.5 KB
npm.py	11.21 KB
ntp.py	2.12 KB
nxos.py	10.37 KB
nxos_upgrade.py	3.5 KB
openstack_config.py	3.26 KB
openvswitch_bridge.py	4.36 KB
openvswitch_db.py	2.24 KB
openvswitch_port.py	17.24 KB
opsgenie.py	4.07 KB
pagerduty.py	1.89 KB
pagerduty_escalation_policy.py	5.42 KB
pagerduty_schedule.py	6.09 KB
pagerduty_service.py	3.93 KB
pagerduty_user.py	1.18 KB
panos.py	48.13 KB
pbm.py	20.46 KB
pcs.py	36.46 KB
pdbedit.py	3.43 KB
pecl.py	3.65 KB
pip_state.py	38.55 KB
pkg.py	138.08 KB
pkgbuild.py	11.37 KB
pkgng.py	685 B
pkgrepo.py	27.53 KB
portage_config.py	5.01 KB
ports.py	5.65 KB
postgres_cluster.py	4.19 KB
postgres_database.py	6.08 KB
postgres_extension.py	5.68 KB
postgres_group.py	8.52 KB
postgres_initdb.py	2.84 KB
postgres_language.py	3.94 KB
postgres_privileges.py	7.86 KB
postgres_schema.py	4.34 KB
postgres_tablespace.py	6.62 KB
postgres_user.py	9.49 KB
powerpath.py	2.34 KB
probes.py	15.06 KB
process.py	1.32 KB
proxy.py	4.94 KB
pushover.py	3.13 KB
pyenv.py	6.07 KB
pyrax_queues.py	2.97 KB
quota.py	1.4 KB
rabbitmq_cluster.py	1.84 KB
rabbitmq_plugin.py	2.77 KB
rabbitmq_policy.py	4.59 KB
rabbitmq_upstream.py	7.9 KB
rabbitmq_user.py	8.89 KB
rabbitmq_vhost.py	3.04 KB
rbac_solaris.py	6.67 KB
rbenv.py	7.36 KB
rdp.py	1.28 KB
redismod.py	4.76 KB
reg.py	19.22 KB
restconf.py	6.41 KB
rsync.py	4.45 KB
rvm.py	6.56 KB
salt_proxy.py	1.34 KB
saltmod.py	33.12 KB
saltutil.py	8.91 KB
schedule.py	12.47 KB
selinux.py	18.61 KB
serverdensity_device.py	6.41 KB
service.py	37.89 KB
slack.py	4.98 KB
smartos.py	44.83 KB
smtp.py	2.3 KB
snapper.py	7.24 KB
solrcloud.py	4.48 KB
splunk.py	4.32 KB
splunk_search.py	3.17 KB
sqlite3.py	14.7 KB
ssh_auth.py	19.57 KB
ssh_known_hosts.py	7.92 KB
stateconf.py	494 B
status.py	2.21 KB
statuspage.py	17.29 KB
supervisord.py	10.48 KB
svn.py	8.14 KB
sysctl.py	4.11 KB
sysfs.py	2.13 KB
syslog_ng.py	2.97 KB
sysrc.py	2.82 KB
telemetry_alert.py	7.04 KB
test.py	13.09 KB
testinframod.py	1.35 KB
timezone.py	3.42 KB
tls.py	1.81 KB
tomcat.py	9.72 KB
trafficserver.py	8.82 KB
tuned.py	3.32 KB
uptime.py	1.87 KB
user.py	38.63 KB
vagrant.py	11.4 KB
vault.py	3.28 KB
vbox_guest.py	4.05 KB
victorops.py	3.32 KB
virt.py	80.41 KB
virtualenv_mod.py	11.21 KB
webutil.py	3.89 KB
win_certutil.py	4.8 KB
win_dacl.py	7.96 KB
win_dism.py	14.97 KB
win_dns_client.py	8.32 KB
win_firewall.py	6.87 KB
win_iis.py	31.56 KB
win_lgpo.py	24.99 KB
win_lgpo_reg.py	10.96 KB
win_license.py	1.6 KB
win_network.py	14.18 KB
win_path.py	6.39 KB
win_pki.py	5.56 KB
win_powercfg.py	3.79 KB
win_servermanager.py	10.4 KB
win_shortcut.py	7.81 KB
win_smtp_server.py	10.01 KB
win_snmp.py	6.64 KB
win_system.py	13.78 KB
win_wua.py	16.27 KB
win_wusa.py	3.53 KB
winrepo.py	2.74 KB
wordpress.py	4.82 KB
x509.py	27.86 KB
x509_v2.py	64.78 KB
xml.py	1.75 KB
xmpp.py	2.61 KB
zabbix_action.py	9.35 KB
zabbix_host.py	27.25 KB
zabbix_hostgroup.py	5.64 KB
zabbix_mediatype.py	16.89 KB
zabbix_template.py	35.14 KB
zabbix_user.py	17.6 KB
zabbix_usergroup.py	9.64 KB
zabbix_usermacro.py	9.69 KB
zabbix_valuemap.py	8.11 KB
zcbuildout.py	5.16 KB
zenoss.py	2.89 KB
zfs.py	34.48 KB
zk_concurrency.py	5.81 KB
zone.py	46.48 KB
zookeeper.py	11.55 KB
zpool.py	13.4 KB

Edit: docker_network.py

"""
Management of Docker networks

.. versionadded:: 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
    :py:func:`pip.install <salt.modules.pip.install>`:

.. code-block:: bash

salt myminion pip.install docker

To upgrade from docker-py_ to docker_, you must first uninstall docker-py_,
    and then install docker_:

.. code-block:: bash

salt myminion pip.uninstall docker-py
        salt myminion pip.install docker

.. _docker: https://pypi.python.org/pypi/docker
.. _docker-py: https://pypi.python.org/pypi/docker-py

These states were moved from the :mod:`docker <salt.states.docker>` state
module (formerly called **dockerng**) in the 2017.7.0 release.
"""

import copy
import logging
import random
import string

import salt.utils.dockermod.translate.network
from salt._compat import ipaddress
from salt.exceptions import CommandExecutionError

log = logging.getLogger(__name__)

# Define the module's virtual name
__virtualname__ = "docker_network"
__virtual_aliases__ = ("moby_network",)

def __virtual__():
    """
    Only load if the docker execution module is available
    """
    if "docker.version" in __salt__:
        return __virtualname__
    return (False, __salt__.missing_fun_string("docker.version"))

def _normalize_pools(existing, desired):
    pools = {"existing": {4: None, 6: None}, "desired": {4: None, 6: None}}

for pool in existing["Config"]:
        subnet = ipaddress.ip_network(pool.get("Subnet"))
        pools["existing"][subnet.version] = pool

for pool in desired["Config"]:
        subnet = ipaddress.ip_network(pool.get("Subnet"))
        if pools["desired"][subnet.version] is not None:
            raise ValueError("Only one IPv{} pool is permitted".format(subnet.version))
        else:
            pools["desired"][subnet.version] = pool

if pools["desired"][6] and not pools["desired"][4]:
        raise ValueError(
            "An IPv4 pool is required when an IPv6 pool is used. See the "
            "documentation for details."
        )

# The pools will be sorted when comparing
    existing["Config"] = [
        pools["existing"][x] for x in (4, 6) if pools["existing"][x] is not None
    ]
    desired["Config"] = [
        pools["desired"][x] for x in (4, 6) if pools["desired"][x] is not None
    ]

def present(
    name,
    skip_translate=None,
    ignore_collisions=False,
    validate_ip_addrs=True,
    containers=None,
    reconnect=True,
    **kwargs
):
    """
    .. versionchanged:: 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 :ref:`NETWORK CONFIGURATION
        <salt-states-docker-network-present-netconf>` and :ref:`IP ADDRESS
        MANAGEMENT (IPAM) <salt-states-docker-network-present-ipam>` sections
        may not accurately reflect what is available on the minion. The
        :py:func:`docker.get_client_args
        <salt.modules.dockermod.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`_

.. versionadded:: 2018.3.0

.. _`docker-py Low-level API`: http://docker-py.readthedocs.io/en/stable/api.html#docker.api.container.ContainerApiMixin.create_container
    .. _`Docker Engine API`: https://docs.docker.com/engine/api/v1.33/#operation/ContainerCreate

ignore_collisions : False
        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.

.. versionadded:: 2018.3.0

validate_ip_addrs : True
        For parameters which accept IP addresses/subnets as input, validation
        will be performed. To disable, set this to ``False``.

.. versionadded:: 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 :py:func:`docker_container.running
               <salt.states.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 :py:func:`docker_container.running
               <salt.states.docker_container.running>`, leaving the container
               unattached at the end of the Salt run.

For these reasons, it is recommended to use
            :ref:`docker_container.running's network management support
            <salt-states-docker-container-network-management>`.

reconnect : True
        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 :ref:`managing static
        IPs in docker_container.running
        <salt-states-docker-container-network-management>`. 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.

.. versionadded:: 2018.3.0

.. _salt-states-docker-network-present-netconf:

**NETWORK CONFIGURATION ARGUMENTS**

driver
        Network driver

.. code-block:: yaml

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:

.. code-block:: yaml

mynet:
              docker_network.present:
                - driver: macvlan
                - driver_opts: macvlan_mode=bridge,parent=eth0

.. code-block:: yaml

mynet:
              docker_network.present:
                - driver: macvlan
                - driver_opts:
                  - macvlan_mode=bridge
                  - parent=eth0

.. code-block:: yaml

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 :ref:`idiosyncrasies <yaml-idiosyncrasies>`
        with how PyYAML loads nested data structures:

.. code-block:: yaml

mynet:
              docker_network.present:
                - driver: macvlan
                - driver_opts:
                    macvlan_mode: bridge
                    parent: eth0

check_duplicate : True
        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.

.. code-block:: yaml

mynet:
              docker_network.present:
                - check_duplicate: False

internal : False
        If ``True``, restricts external access to the network

.. code-block:: yaml

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:

.. code-block:: yaml

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 :ref:`idiosyncrasies
        <yaml-idiosyncrasies>` with how PyYAML loads nested data structures:

.. code-block:: yaml

foo:
              docker_network.present:
                - labels:
                    foo: ''
                    bar: baz
                    hello: world

.. versionchanged:: 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

.. code-block:: yaml

mynet:
              docker_network.present:
                - enable_ipv6: True

.. note::
            While it should go without saying, this argument must be set to
            ``True`` to :ref:`configure an IPv6 subnet
            <salt-states-docker-network-present-ipam>`. 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.

.. _`Docker IPv6 docs`: https://docs.docker.com/v17.09/engine/userguide/networking/default_network/ipv6/

attachable : False
        If ``True``, and the network is in the global scope, non-service
        containers on worker nodes will be able to connect to the network.

.. code-block:: yaml

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``)

.. code-block:: yaml

mynet:
              docker_network.present:
                - scope: local

ingress : False
        If ``True``, create an ingress network which provides the routing-mesh in
        swarm mode

.. code-block:: yaml

mynet:
              docker_network.present:
                - ingress: True

.. _salt-states-docker-network-present-ipam:

**IP ADDRESS MANAGEMENT (IPAM)**

This state supports networks with either IPv4, or both IPv4 and IPv6. If
    configuring IPv4, then you can pass the :ref:`IPAM pool arguments
    <salt-states-docker-network-present-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 :ref:`here <salt-states-docker-network-present-ipam-examples>` for
    some examples). `These docs`_ also have more information on these
    arguments.

.. _`These docs`: http://docker-py.readthedocs.io/en/stable/api.html#docker.types.IPAMPool

*IPAM ARGUMENTS*

ipam_driver
        IPAM driver to use, if different from the default one

.. code-block:: yaml

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:

.. code-block:: yaml

mynet:
              docker_network.present:
                - ipam_driver: foo
                - ipam_opts: foo=bar,baz=qux

.. code-block:: yaml

mynet:
              docker_network.present:
                - ipam_driver: foo
                - ipam_opts:
                  - foo=bar
                  - baz=qux

.. code-block:: yaml

mynet:
              docker_network.present:
                - ipam_driver: foo
                - ipam_opts:
                  - foo: bar
                  - baz: qux

.. code-block:: yaml

mynet:
              docker_network.present:
                - ipam_driver: macvlan
                - ipam_opts:
                    foo: bar
                    baz: qux

.. _salt-states-docker-network-present-ipam-pool-arguments:

*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``.

.. _salt-states-docker-network-present-ipam-examples:

*IPAM CONFIGURATION EXAMPLES*

Below is an example of an IPv4-only network (keep in mind that ``subnet``
    is the only required argument).

.. code-block:: yaml

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:

.. code-block:: yaml

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.

.. code-block:: yaml

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
    """
    ret = {"name": name, "changes": {}, "result": False, "comment": ""}

try:
        network = __salt__["docker.inspect_network"](name)
    except CommandExecutionError as exc:
        msg = exc.__str__()
        if "404" in msg:
            # Network not present
            network = None
        else:
            ret["comment"] = msg
            return ret

# map container's IDs to names
    to_connect = {}
    missing_containers = []
    stopped_containers = []
    for cname in __utils__["args.split_input"](containers or []):
        try:
            cinfo = __salt__["docker.inspect_container"](cname)
        except CommandExecutionError:
            missing_containers.append(cname)
        else:
            try:
                cid = cinfo["Id"]
            except KeyError:
                missing_containers.append(cname)
            else:
                if not cinfo.get("State", {}).get("Running", False):
                    stopped_containers.append(cname)
                else:
                    to_connect[cid] = {"Name": cname}

if missing_containers:
        ret.setdefault("warnings", []).append(
            "The following containers do not exist: {}.".format(
                ", ".join(missing_containers)
            )
        )

if stopped_containers:
        ret.setdefault("warnings", []).append(
            "The following containers are not running: {}.".format(
                ", ".join(stopped_containers)
            )
        )

# We might disconnect containers in the process of recreating the network,
    # we'll need to keep track these containers so we can reconnect them later.
    disconnected_containers = {}

try:
        kwargs = __utils__["docker.translate_input"](
            salt.utils.dockermod.translate.network,
            skip_translate=skip_translate,
            ignore_collisions=ignore_collisions,
            validate_ip_addrs=validate_ip_addrs,
            **__utils__["args.clean_kwargs"](**kwargs)
        )
    except Exception as exc:  # pylint: disable=broad-except
        ret["comment"] = exc.__str__()
        return ret

# Separate out the IPAM config options and build the IPAM config dict
    ipam_kwargs = {}
    ipam_kwarg_names = ["ipam", "ipam_driver", "ipam_opts", "ipam_pools"]
    ipam_kwarg_names.extend(
        __salt__["docker.get_client_args"]("ipam_config")["ipam_config"]
    )
    for key in ipam_kwarg_names:
        try:
            ipam_kwargs[key] = kwargs.pop(key)
        except KeyError:
            pass
    if "ipam" in ipam_kwargs:
        if len(ipam_kwargs) > 1:
            ret["comment"] = (
                "Cannot mix the 'ipam' argument with any of the IPAM config "
                "arguments. See documentation for details."
            )
            return ret
        ipam_config = ipam_kwargs["ipam"]
    else:
        ipam_pools = ipam_kwargs.pop("ipam_pools", ())
        try:
            ipam_config = __utils__["docker.create_ipam_config"](
                *ipam_pools, **ipam_kwargs
            )
        except Exception as exc:  # pylint: disable=broad-except
            ret["comment"] = exc.__str__()
            return ret

# We'll turn this off if we decide below that creating the network is not
    # necessary.
    create_network = True

if network is not None:
        log.debug("Docker network '%s' already exists", name)

# Set the comment now to say that it already exists, if we need to
        # recreate the network with new config we'll update the comment later.
        ret[
            "comment"
        ] = "Network '{}' already exists, and is configured as specified".format(name)
        log.trace("Details of docker network '%s': %s", name, network)

temp_net_name = "".join(
            random.choice(string.ascii_lowercase) for _ in range(20)
        )

try:
            # When using enable_ipv6, you *must* provide a subnet. But we don't
            # care about the subnet when we make our temp network, we only care
            # about the non-IPAM values in the network. And we also do not want
            # to try some hacky workaround where we choose a small IPv6 subnet
            # to pass when creating the temp network, that may end up
            # overlapping with a large IPv6 subnet already in use by Docker.
            # So, for purposes of comparison we will create the temp network
            # with enable_ipv6=False and then munge the inspect results before
            # performing the comparison. Note that technically it is not
            # required that one specify both v4 and v6 subnets when creating a
            # network, but not specifying IPv4 makes it impossible for us to
            # reliably compare the SLS input to the existing network, as we
            # wouldng't know if the IPv4 subnet in the existing network was
            # explicitly configured or was automatically assigned by Docker.
            enable_ipv6 = kwargs.pop("enable_ipv6", None)
            kwargs_tmp = kwargs
            driver = kwargs.get(
                "driver",
            )
            driver_opts = kwargs.get("options", {})
            bridge_name = driver_opts.get("com.docker.network.bridge.name", None)

if driver == "bridge" and bridge_name is not None:
                tmp_name = str(bridge_name) + "comp"
                kwargs_tmp["options"]["com.docker.network.bridge.name"] = tmp_name[-14:]
            __salt__["docker.create_network"](
                temp_net_name,
                skip_translate=True,  # No need to translate (already did)
                enable_ipv6=False,
                **kwargs_tmp
            )
        except CommandExecutionError as exc:
            ret["comment"] = "Failed to create temp network for comparison: {}".format(
                exc.__str__()
            )
            return ret
        else:
            # Replace the value so we can use it later
            if enable_ipv6 is not None:
                kwargs["enable_ipv6"] = enable_ipv6

try:
            try:
                temp_net_info = __salt__["docker.inspect_network"](temp_net_name)
            except CommandExecutionError as exc:
                ret["comment"] = "Failed to inspect temp network: {}".format(
                    exc.__str__()
                )
                return ret
            else:
                temp_net_info["EnableIPv6"] = bool(enable_ipv6)

# Replace the IPAM configuration in the temp network with the IPAM
            # config dict we created earlier, for comparison purposes. This is
            # necessary because we cannot create two networks that have
            # overlapping subnets (the Docker Engine will throw an error).
            temp_net_info["IPAM"] = ipam_config

existing_pool_count = len(network["IPAM"]["Config"])
            desired_pool_count = len(temp_net_info["IPAM"]["Config"])

is_default_pool = (
                lambda x: True if sorted(x) == ["Gateway", "Subnet"] else False
            )

if (
                desired_pool_count == 0
                and existing_pool_count == 1
                and is_default_pool(network["IPAM"]["Config"][0])
            ):
                # If we're not explicitly configuring an IPAM pool, then we
                # don't care what the subnet is. Docker networks created with
                # no explicit IPAM configuration are assigned a single IPAM
                # pool containing just a subnet and gateway. If the above if
                # statement resolves as True, then we know that both A) we
                # aren't explicitly configuring IPAM, and B) the existing
                # network appears to be one that was created without an
                # explicit IPAM configuration (since it has the default pool
                # config values). Of course, it could be possible that the
                # existing network was created with a single custom IPAM pool,
                # with just a subnet and gateway. But even if this was the
                # case, the fact that we aren't explicitly enforcing IPAM
                # configuration means we don't really care what the existing
                # IPAM configuration is. At any rate, to avoid IPAM differences
                # when comparing the existing network to the temp network, we
                # need to clear the existing network's IPAM configuration.
                network["IPAM"]["Config"] = []

changes = __salt__["docker.compare_networks"](
                network, temp_net_info, ignore="Name,Id,Created,Containers"
            )

if not changes:
                # No changes to the network, so we'll be keeping the existing
                # network and at most just connecting containers to it.
                create_network = False

else:
                ret["changes"][name] = changes
                if __opts__["test"]:
                    ret["result"] = None
                    ret["comment"] = "Network would be recreated with new config"
                    return ret

if network["Containers"]:
                    # We've removed the network, so there are now no containers
                    # attached to it. However, once we recreate the network
                    # with the new configuration we may need to reconnect the
                    # containers that were previously connected. Even if we're
                    # not reconnecting, we still need to track the containers
                    # so that we can report on which were disconnected.
                    disconnected_containers = copy.deepcopy(network["Containers"])
                    if not containers and reconnect:
                        # Grab the links and aliases from each connected
                        # container so that we have them when we attempt to
                        # reconnect later
                        for cid in disconnected_containers:
                            try:
                                cinfo = __salt__["docker.inspect_container"](cid)
                                netinfo = cinfo["NetworkSettings"]["Networks"][name]
                                # Links and Aliases will be None if not
                                # explicitly set, hence using "or" instead of
                                # placing the empty list inside the dict.get
                                net_links = netinfo.get("Links") or []
                                net_aliases = netinfo.get("Aliases") or []
                                if net_links:
                                    disconnected_containers[cid]["Links"] = net_links
                                if net_aliases:
                                    disconnected_containers[cid][
                                        "Aliases"
                                    ] = net_aliases
                            except (CommandExecutionError, KeyError, ValueError):
                                continue

remove_result = _remove_network(network)
                if not remove_result["result"]:
                    return remove_result

# Replace the Containers key with an empty dict so that when we
                # check for connnected containers below, we correctly see that
                # there are none connected.
                network["Containers"] = {}
        finally:
            try:
                __salt__["docker.remove_network"](temp_net_name)
            except CommandExecutionError as exc:
                ret.setdefault("warnings", []).append(
                    "Failed to remove temp network '{}': {}.".format(
                        temp_net_name, exc.__str__()
                    )
                )

if create_network:
        log.debug("Network '%s' will be created", name)
        if __opts__["test"]:
            # NOTE: if the container already existed and needed to be
            # recreated, and we were in test mode, we would have already exited
            # above with a comment about the network needing to be recreated.
            # So, even though the below block to create the network would be
            # executed to create the network both when it's being recreated and
            # when it's being created for the first time, the below comment is
            # still accurate.
            ret["result"] = None
            ret["comment"] = "Network will be created"
            return ret

kwargs["ipam"] = ipam_config
        try:
            __salt__["docker.create_network"](
                name,
                skip_translate=True,  # No need to translate (already did)
                **kwargs
            )
        except Exception as exc:  # pylint: disable=broad-except
            ret["comment"] = "Failed to create network '{}': {}".format(
                name, exc.__str__()
            )
            return ret
        else:
            action = "recreated" if network is not None else "created"
            ret["changes"][action] = True
            ret["comment"] = "Network '{}' {}".format(
                name,
                "created" if network is None else "was replaced with updated config",
            )
            # Make sure the "Containers" key exists for logic below
            network = {"Containers": {}}

# If no containers were specified in the state but we have disconnected
    # some in the process of recreating the network, we should reconnect those
    # containers.
    if containers is None and reconnect and disconnected_containers:
        to_connect = disconnected_containers

# Don't try to connect any containers which are already connected. If we
    # created/re-created the network, then network['Containers'] will be empty
    # and no containers will be deleted from the to_connect dict (the result
    # being that we will reconnect all containers in the to_connect dict).
    # list() is used here because we will potentially be modifying the
    # dictionary during iteration.
    for cid in list(to_connect):
        if cid in network["Containers"]:
            del to_connect[cid]

errors = []
    if to_connect:
        for cid, connect_info in to_connect.items():
            connect_kwargs = {}
            if cid in disconnected_containers:
                for key_name, arg_name in (
                    ("IPv4Address", "ipv4_address"),
                    ("IPV6Address", "ipv6_address"),
                    ("Links", "links"),
                    ("Aliases", "aliases"),
                ):
                    try:
                        connect_kwargs[arg_name] = connect_info[key_name]
                    except (KeyError, AttributeError):
                        continue
                    else:
                        if key_name.endswith("Address"):
                            connect_kwargs[arg_name] = connect_kwargs[arg_name].rsplit(
                                "/", 1
                            )[0]
            try:
                __salt__["docker.connect_container_to_network"](
                    cid, name, **connect_kwargs
                )
            except CommandExecutionError as exc:
                if not connect_kwargs:
                    errors.append(exc.__str__())
                else:
                    # We failed to reconnect with the container's old IP
                    # configuration. Reconnect using automatic IP config.
                    try:
                        __salt__["docker.connect_container_to_network"](cid, name)
                    except CommandExecutionError as exc:
                        errors.append(exc.__str__())
                    else:
                        ret["changes"].setdefault(
                            "reconnected"
                            if cid in disconnected_containers
                            else "connected",
                            [],
                        ).append(connect_info["Name"])
            else:
                ret["changes"].setdefault(
                    "reconnected" if cid in disconnected_containers else "connected", []
                ).append(connect_info["Name"])

if errors:
        if ret["comment"]:
            ret["comment"] += ". "
        ret["comment"] += ". ".join(errors) + "."
    else:
        ret["result"] = True

# Figure out if we removed any containers as a result of replacing the
    # network and did not reconnect them. We only would not have reconnected if
    # a list of containers was passed in the "containers" argument, and there
    # were containers connected to the network prior to its replacement which
    # were not part of that list.
    for cid, c_info in disconnected_containers.items():
        if cid not in to_connect:
            ret["changes"].setdefault("disconnected", []).append(c_info["Name"])

return ret

def absent(name):
    """
    Ensure that a network is absent.

name
        Name of the network

Usage Example:

.. code-block:: yaml

network_foo:
          docker_network.absent
    """
    ret = {"name": name, "changes": {}, "result": False, "comment": ""}

if network is None:
        ret["result"] = True
        ret["comment"] = "Network '{}' already absent".format(name)
        return ret

if __opts__["test"]:
        ret["result"] = None
        ret["comment"] = "Network '{}' will be removed".format(name)
        return ret

return _remove_network(network)

def _remove_network(network):
    """
    Remove network, including all connected containers
    """
    ret = {"name": network["Name"], "changes": {}, "result": False, "comment": ""}

errors = []
    for cid in network["Containers"]:
        try:
            cinfo = __salt__["docker.inspect_container"](cid)
        except CommandExecutionError:
            # Fall back to container ID
            cname = cid
        else:
            cname = cinfo.get("Name", "").lstrip("/")

try:
            __salt__["docker.disconnect_container_from_network"](cid, network["Name"])
        except CommandExecutionError as exc:
            errors = "Failed to disconnect container '{}' : {}".format(cname, exc)
        else:
            ret["changes"].setdefault("disconnected", []).append(cname)

if errors:
        ret["comment"] = "\n".join(errors)
        return ret

try:
        __salt__["docker.remove_network"](network["Name"])
    except CommandExecutionError as exc:
        ret["comment"] = "Failed to remove network: {}".format(exc)
    else:
        ret["changes"]["removed"] = True
        ret["result"] = True
        ret["comment"] = "Removed network '{}'".format(network["Name"])

return ret