salt.modules.etcd_mod¶
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:
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.
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.
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...
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 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.
- salt.modules.etcd_mod.get_(key, recurse=False, profile=None, **kwargs)¶
New in version 2014.7.0.
Get a value from etcd, by direct path. Returns None on failure.
CLI Examples:
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
- salt.modules.etcd_mod.ls_(path='/', profile=None, **kwargs)¶
New in version 2014.7.0.
Return all keys and dirs inside a specific path. Returns an empty dict on failure.
CLI Example:
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
- salt.modules.etcd_mod.rm_(key, recurse=False, profile=None, **kwargs)¶
New in version 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:
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
- salt.modules.etcd_mod.set_(key, value, profile=None, ttl=None, directory=False, **kwargs)¶
New in version 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:
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
- salt.modules.etcd_mod.tree(path='/', profile=None, **kwargs)¶
New in version 2014.7.0.
Recurse through etcd and return all values. Returns None on failure.
CLI Example:
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
- salt.modules.etcd_mod.update(fields, path='', profile=None, **kwargs)¶
New in version 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:
{ '/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:
{ '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:
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'
- salt.modules.etcd_mod.watch(key, recurse=False, profile=None, timeout=0, index=None, **kwargs)¶
New in version 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:
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
