o

�N�g<"�@s�dZd
dl
Z
d
dlZdZe
�e�
Zddddd�Zd	d
�Z	ddd
�
Z
ddd�
Zddd�
Zddd�
Z
d dd�
Zddd�
Zd dd�
ZdS)!a

Execution module to work with etcd

:depends:  - python-etcd or etcd3-py

Configuration
-------------

To work with an etcd server you must configure an etcd profile. The etcd config
can be set in either the Salt Minion configuration file or in pillar:

.. code-block:: yaml

    my_etd_config:
      etcd.host: 127.0.0.1
      etcd.port: 4001

It is technically possible to configure etcd without using a profile, but this
is not considered to be a best practice, especially when multiple etcd servers
or clusters are available.

.. code-block:: yaml

    etcd.host: 127.0.0.1
    etcd.port: 4001

In order to choose whether to use etcd API v2 or v3, you can put the following
configuration option in the same place as your etcd configuration.  This option
defaults to true, meaning you will use v2 unless you specify otherwise.

.. code-block:: yaml

    etcd.require_v2: True

When using API v3, there are some specific options available to be configured
within your etcd profile.  They are defaulted to the following...

.. code-block:: yaml

    etcd.encode_keys: False
    etcd.encode_values: True
    etcd.raw_keys: False
    etcd.raw_values: False
    etcd.unicode_errors: "surrogateescape"

``etcd.encode_keys`` indicates whether you want to pre-encode keys using msgpack before
adding them to etcd.

.. note::

    If you set ``etcd.encode_keys`` to ``True``, all recursive functionality will no longer work.
    This includes ``tree`` and ``ls`` and all other methods if you set ``recurse``/``recursive`` to ``True``.
    This is due to the fact that when encoding with msgpack, keys like ``/salt`` and ``/salt/stack`` will have
    differing byte prefixes, and etcd v3 searches recursively using prefixes.

``etcd.encode_values`` indicates whether you want to pre-encode values using msgpack before
adding them to etcd.  This defaults to ``True`` to avoid data loss on non-string values wherever possible.

``etcd.raw_keys`` determines whether you want the raw key or a string returned.

``etcd.raw_values`` determines whether you want the raw value or a string returned.

``etcd.unicode_errors`` determines what you policy to follow when there are encoding/decoding errors.

.. note::

    The etcd configuration can also be set in the Salt Master config file,
    but in order to use any etcd configurations defined in the Salt Master
    config, the :conf_master:`pillar_opts` must be set to ``True``.

    Be aware that setting ``pillar_opts`` to ``True`` has security implications
    as this makes all master configuration settings available in all minion's
    pillars.

�NZetcd�get�set�rm�ls)�get_�set_�rm_�ls_c
Cstj
jjs
tj
jjrtSd
S)z1
    Only return if python-etcd is installed
    )FzRThe etcd_mod execution module cannot be loaded: python etcd library not available.)�salt�utilsZ	etcd_utilZHAS_ETCD_V2ZHAS_ETCD_V3�__virtualname__�r
r
�I/opt/saltstack/salt/lib/python3.10/site-packages/salt/modules/etcd_mod.py�__virtual__[s

rFcK�$td
t
|fi|�
�
}|j||
d�S)a�

    .. versionadded:: 2014.7.0

    Get a value from etcd, by direct path.  Returns None on failure.

    CLI Examples:

    .. code-block:: bash

        salt myminion etcd.get /path/to/key
        salt myminion etcd.get /path/to/key profile=my_etcd_config
        salt myminion etcd.get /path/to/key recurse=True profile=my_etcd_config
        salt myminion etcd.get /path/to/key host=127.0.0.1 port=2379
    �etcd_util.get_conn�
�recurse)�	__utils__�__opts__r��keyr�profile�kwargs�clientr
r
rrhs
rcK�(td
t
|fi|�
�
}|j||
||d�S)a

    .. versionadded:: 2014.7.0

    Set a key in etcd by direct path. Optionally, create a directory
    or set a TTL on the key.  Returns None on failure.

    CLI Example:

    .. code-block:: bash

        salt myminion etcd.set /path/to/key value
        salt myminion etcd.set /path/to/key value profile=my_etcd_config
        salt myminion etcd.set /path/to/key value host=127.0.0.1 port=2379
        salt myminion etcd.set /path/to/dir '' directory=True
        salt myminion etcd.set /path/to/key value ttl=5
    r)�ttl�	directory)rrr)r�valuerrrrrr
r
rr{s
r�cKs"td
t
|fi|�
�
}|�||
�S)a�
    .. versionadded:: 2016.3.0

    Sets a dictionary of values in one call.  Useful for large updates
    in syndic environments.  The dictionary can contain a mix of formats
    such as:

    .. code-block:: python

        {
          '/some/example/key': 'bar',
          '/another/example/key': 'baz'
        }

    Or it may be a straight dictionary, which will be flattened to look
    like the above format:

    .. code-block:: python

        {
            'some': {
                'example': {
                    'key': 'bar'
                }
            },
            'another': {
                'example': {
                    'key': 'baz'
                }
            }
        }

    You can even mix the two formats and it will be flattened to the first
    format.  Leading and trailing '/' will be removed.

    Empty directories can be created by setting the value of the key to an
    empty dictionary.

    The 'path' parameter will optionally set the root of the path to use.

    CLI Example:

    .. code-block:: bash

        salt myminion etcd.update "{'/path/to/key': 'baz', '/another/key': 'bar'}"
        salt myminion etcd.update "{'/path/to/key': 'baz', '/another/key': 'bar'}" profile=my_etcd_config
        salt myminion etcd.update "{'/path/to/key': 'baz', '/another/key': 'bar'}" host=127.0.0.1 port=2379
        salt myminion etcd.update "{'/path/to/key': 'baz', '/another/key': 'bar'}" path='/some/root'
    r)rr�update)�fields�pathrrrr
r
rr �s2
r cKr)a�
    .. versionadded:: 2016.3.0

    Makes a best effort to watch for a key or tree change in etcd.
    Returns a dict containing the new key value ( or None if the key was
    deleted ), the modifiedIndex of the key, whether the key changed or
    not, the path to the key that changed and whether it is a directory or not.

    If something catastrophic happens, returns {}

    CLI Example:

    .. code-block:: bash

        salt myminion etcd.watch /path/to/key
        salt myminion etcd.watch /path/to/key timeout=10
        salt myminion etcd.watch /patch/to/key profile=my_etcd_config index=10
        salt myminion etcd.watch /patch/to/key host=127.0.0.1 port=2379
    r)r�timeout�index)rr�watch)rrrr#r$rrr
r
rr%�s
r%�
/cK� td
t
|
fi|�
�
}|�|�
S)aa

    .. versionadded:: 2014.7.0

    Return all keys and dirs inside a specific path. Returns an empty dict on
    failure.

    CLI Example:

    .. code-block:: bash

        salt myminion etcd.ls /path/to/dir/
        salt myminion etcd.ls /path/to/dir/ profile=my_etcd_config
        salt myminion etcd.ls /path/to/dir/ host=127.0.0.1 port=2379
    r)rrr�r"rrrr
r
rr	��

r	cKr)a�

    .. versionadded:: 2014.7.0

    Delete a key from etcd.  Returns True if the key was deleted, False if it was
    not and None if there was a failure.

    CLI Example:

    .. code-block:: bash

        salt myminion etcd.rm /path/to/key
        salt myminion etcd.rm /path/to/key profile=my_etcd_config
        salt myminion etcd.rm /path/to/key host=127.0.0.1 port=2379
        salt myminion etcd.rm /path/to/dir recurse=True profile=my_etcd_config
    rr)rrrrr
r
rr�s
rcKr')aq

    .. versionadded:: 2014.7.0

    Recurse through etcd and return all values.  Returns None on failure.

    CLI Example:

    .. code-block:: bash

        salt myminion etcd.tree
        salt myminion etcd.tree profile=my_etcd_config
        salt myminion etcd.tree host=127.0.0.1 port=2379
        salt myminion etcd.tree /path/to/keys profile=my_etcd_config
    r)rr�treer(r
r
rr*
r)r*)FN)NNF)rN)FNr
N)r&N)�__doc__�loggingZsalt.utils.etcd_utilr
r�	getLogger�__name__�logZ__func_alias__rrrr r%r	rr*r
r
r
r�<module>
sL




6