Current File : //lib/python2.7/site-packages/salt/states/docker_network.pyo
�
���^c @@ s� d Z d d l m Z m Z m Z d d l Z d d l Z d d l Z d d l Z d d l Z
d d l m Z d d l
m Z d d l m Z d d l m Z e j e � Z d Z d f Z d
� Z d � Z e e e e e d � Z d
� Z d � Z d S( u�
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.
i ( t absolute_importt print_functiont unicode_literalsN( t CommandExecutionError( t six( t range( t ipaddressu docker_networku moby_networkc C@ s# d t k r t St t j d � f S( u?
Only load if the docker execution module is available
u docker.version( t __salt__t __virtualname__t Falset missing_fun_string( ( ( s> /usr/lib/python2.7/site-packages/salt/states/docker_network.pyt __virtual__8 s c C@ s� i i d d 6d d 6d 6i d d 6d d 6d 6} x; | d D]/ } t j | j d � � } | | d | j <q; Wxm | d D]a } t j | j d � � } | d | j d k r� t d j | j � � � qy | | d | j <qy W| d d r
| d d r
t d � � n g d D]( } | d | d k r| d | ^ q| d <g d
D]( } | d | d k rJ| d | ^ qJ| d <d S( Ni i u existingu desiredu Configu Subnetu! Only one IPv{0} pool is permitteduV An IPv4 pool is required when an IPv6 pool is used. See the documentation for details.( i i ( i i ( t NoneR t
ip_networkt gett versiont
ValueErrort format( t existingt desiredt poolst poolt subnett x( ( s> /usr/lib/python2.7/site-packages/salt/states/docker_network.pyt _normalize_poolsA s$
,
c * K@ sU
i | d 6i d 6t d 6d d 6} y t d | � } WnB t k
rz } | j � }
d |
k ri t } n |
| d <| Sn Xi } g } g }
x� t d | p� g � D]� } y t d | � } Wn t k
r� | j | � np Xy | d
} Wn t k
r
| j | � nA X| j d i � j d t � r=|
j | � n i | d
6| | <q� W| r�| j d g � j d j
d j | � � � n |
r�| j d g � j d j
d j |
� � � n i } y? t d t j
j j j d | d | d | t d | � �} Wn' t k
r(} | j � | d <| Sn Xi } d d d d g } | j t d d � d � x9 | D]1 } y | j | � | | <Wn t k
r�n XqcWd | k r�t | � d k r�d | d <| Sn | d } nS | j d f � } y t d | | � } Wn' t k
r&} | j � | d <| Sn Xt } | t k r�t j d | � d! j
| � | d <t j d" | | � d j d# � t d$ � D� � } y3 | j d% t � } t d& | d t d' t | �Wn0 t k
r�} d( j
| j � � | d <| Sn X| t k r
| | d% <n z:y t d | � } Wn0 t k
rV} d) j
| j � � | d <| Sn Xt | � | d* <| | d+ <t | d+ d, � } t | d+ d, � } d- � } | d. k o�| d k o�| | d+ d, d. � r�g | d+ d, <n t d/ | | d0 d1 �} | r t } n:| | d | <t d2 r?t | d <d3 | d <| Sn | d4 r t j | d4 � } | of| rx� | D]� } y~ t d | � } | d5 d6 | } | j d7 � p�g } | j d8 � p�g }! | r�| | | d7 <n |! r�|! | | d8 <n Wn t t t f k
rqpn XqpWn n t | � }" |" d r<|" Sn i | d4 <Wd9 y t d: | � Wn> t k
r�} | j d g � j d; j
| | j � � � n XXn | r�t j d< | � t d2 r�t | d <d= | d <| Sn | | d <y t d& | d t | �Wn3 t k
r6} d> j
| | j � � | d <| Sn\ X| t k rId? n d@ }# t | d |# <dA j
| | t k rxd@ n dB � | d <i i d4 6} n | t k o�| o�| r�| } n x. t | � D] } | | d4 k r�| | =n q�Wg }$ | r� x�t! j" | � D]�\ } }% i }& | | k r�x� dC dD f dE dF f d7 dG f d8 dH f f D]k \ }' }( y |% |' |& |( <Wn t t# f k
r�qLn1 X|' j$ dI � r�|& |( j% dJ d � d. |& |( <n qLWn y t dK | | |& � Wn� t k
ry } |& r |$ j | j � � nq y t dK | | � Wn& t k
rB } |$ j | j � � n4 X| d j | | k r_ dL n dM g � j |% d
� n4 X| d j | | k r� dL n dM g � j |% d
� qWn |$ r� | d r� | d c dN 7<n | d c dN j |$ � dO 7<n
t | d <xM t! j" | � D]< \ } }) | | k rM
| d j dP g � j |) d
� n q
W| S(Q u>
.. 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
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:
- 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
u nameu changesu resultu u commentu docker.inspect_networku 404u args.split_inputu docker.inspect_containeru Idu Stateu Runningu Nameu warningsu+ The following containers do not exist: {0}.u , u. The following containers are not running: {0}.u docker.translate_inputt skip_translatet ignore_collisionst validate_ip_addrsu args.clean_kwargsu ipamu ipam_driveru ipam_optsu
ipam_poolsu docker.get_client_argsu ipam_configi ud Cannot mix the 'ipam' argument with any of the IPAM config arguments. See documentation for details.u docker.create_ipam_configu" Docker network '%s' already existsu< Network '{0}' already exists, and is configured as specifiedu" Details of docker network '%s': %sc s@ s! | ] } t j t j � Vq d S( N( t randomt choicet stringt ascii_lowercase( t .0t _( ( s> /usr/lib/python2.7/site-packages/salt/states/docker_network.pys <genexpr>| s i u enable_ipv6u docker.create_networkt enable_ipv6u1 Failed to create temp network for comparison: {0}u# Failed to inspect temp network: {0}u
EnableIPv6u IPAMu Configc S@ s t | � d d g k r t St S( Nu Gatewayu Subnet( t sortedt TrueR ( R ( ( s> /usr/lib/python2.7/site-packages/salt/states/docker_network.pyt <lambda>� s i u docker.compare_networkst ignoreu Name,Id,Created,Containersu testu* Network would be recreated with new configu
Containersu NetworkSettingsu Networksu Linksu AliasesNu docker.remove_networku) Failed to remove temp network '{0}': {1}.u Network '%s' will be createdu Network will be createdu# Failed to create network '{0}': {1}u recreatedu createdu Network '{0}' {1}u was replaced with updated configu IPv4Addressu ipv4_addressu IPV6Addressu ipv6_addressu linksu aliasesu Addressu /u# docker.connect_container_to_networku reconnectedu connectedu . u .u disconnected(& R R R t __str__R t __utils__t appendt KeyErrorR t
setdefaultR t joint saltt utilst dockert translatet networkt Exceptiont extendt popt lenR$ t logt debugt traceR t boolt __opts__t copyt deepcopyR t _remove_networkt listR t iteritemst AttributeErrort endswitht rsplit(* t nameR R R t
containerst reconnectt kwargst retR1 t exct msgt
to_connectt missing_containerst stopped_containerst cnamet cinfot cidt disconnected_containerst ipam_kwargst ipam_kwarg_namest keyt ipam_configt
ipam_poolst create_networkt
temp_net_nameR" t
temp_net_infot existing_pool_countt desired_pool_countt is_default_poolt changest netinfot net_linkst net_aliasest
remove_resultt actiont errorst connect_infot connect_kwargst key_namet arg_namet c_info( ( s> /usr/lib/python2.7/site-packages/salt/states/docker_network.pyt present_ s� � �
(
(c C@ s� i | d 6i d 6t d 6d d 6} y t d | � } WnB t k
rz } | j � } d | k ri d } q{ | | d <| Sn X| d k r� t | d <d j | � | d <| St d r� d | d <d
j | � | d <| St | � S( u�
Ensure that a network is absent.
name
Name of the network
Usage Example:
.. code-block:: yaml
network_foo:
docker_network.absent
u nameu changesu resultu u commentu docker.inspect_networku 404u Network '{0}' already absentu testu Network '{0}' will be removedN( R R R R' R R$ R R: R= ( RC RG R1 RH RI ( ( s> /usr/lib/python2.7/site-packages/salt/states/docker_network.pyt absent} s*
c C@ sw i | d d 6i d 6t d 6d d 6} g } x� | d D]� } y t d | � } Wn t k
rj | } n X| j d d � j d � } y t d
| | d � Wn% t k
r� } d j | | � } q7 X| d j d g � j | � q7 W| rd
j | � | d <| Sy t d | d � Wn& t k
rC} d j | � | d <n0 Xt | d d <t | d <d j | d � | d <| S( u<
Remove network, including all connected containers
u Nameu nameu changesu resultu u commentu
Containersu docker.inspect_containeru /u( docker.disconnect_container_from_networku* Failed to disconnect container '{0}' : {1}u disconnectedu
u docker.remove_networku Failed to remove network: {0}u removedu Removed network '{0}'(
R R R R t lstripR R+ R) R, R$ ( R1 RG Rb RO RN RM RH ( ( s> /usr/lib/python2.7/site-packages/salt/states/docker_network.pyR= � s8
!
( t __doc__t
__future__R R R R; t loggingR R t# salt.utils.docker.translate.networkR- t salt.exceptionsR t salt.extR t salt.ext.six.movesR t salt._compatR t getLoggert __name__R6 R t __virtual_aliases__R R R R R$ Rh Ri R= ( ( ( s> /usr/lib/python2.7/site-packages/salt/states/docker_network.pyt <module> s2 � � � +
Mini Shell