salt.states.etcd_mod¶

Manage etcd Keys¶

New in version 2015.8.0.

depends:

python-etcd or etcd3-py

This state module supports setting and removing keys from etcd.

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.

Etcd profile configuration can be overridden using following arguments: host, port, username, password, ca, client_key and client_cert. The v3 specific arguments can also be used for overriding if you are using v3.

my-value:
  etcd.set:
    - name: /path/to/key
    - value: value
    - host: 127.0.0.1
    - port: 2379
    - username: user
    - password: pass

Available Functions¶

set

This will set a value to a key in etcd. Changes will be returned if the key has been created or the value of the key has been updated. This means you can watch these states for changes.
```
/foo/bar/baz:
  etcd.set:
    - value: foo
    - profile: my_etcd_config
```

wait_set

Performs the same functionality as set but only if a watch requisite is True.

/some/file.txt:
  file.managed:
    - source: salt://file.txt

/foo/bar/baz:
  etcd.wait_set:
    - value: foo
    - profile: my_etcd_config
    - watch:
      - file: /some/file.txt

rm

This will delete a key from etcd. If the key exists then changes will be returned and thus you can watch for changes on the state, if the key does not exist then no changes will occur.
```
/foo/bar/baz:
  etcd.rm:
    - profile: my_etcd_config
```

wait_rm

Performs the same functionality as rm but only if a watch requisite is True.

/some/file.txt:
  file.managed:
    - source: salt://file.txt

/foo/bar/baz:
  etcd.wait_rm:
    - profile: my_etcd_config
    - watch:
      - file: /some/file.txt

salt.states.etcd_mod.directory(name, profile=None, **kwargs)¶

Create a directory in etcd.

name

The etcd directory name, for example: /foo/bar/baz.

profile

Optional, defaults to None. Sets the etcd profile to use which has been defined in the Salt Master config.

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

salt.states.etcd_mod.mod_watch(name, **kwargs)¶: The etcd watcher, called to invoke the watch command. When called, execute a etcd function based on a watch call requisite.

Note

This state exists to support special handling of the watch requisite. It should not be called directly.

Parameters for this function should be set by the state being triggered.

salt.states.etcd_mod.rm(name, recurse=False, profile=None, **kwargs)¶

Deletes a key from etcd

name

The etcd key name to remove, for example /foo/bar/baz.

recurse

Optional, defaults to False. If True performs a recursive delete.

profile

Optional, defaults to None. Sets the etcd profile to use which has been defined in the Salt Master config.

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

salt.states.etcd_mod.set_(name, value, profile=None, **kwargs)¶

Set a key in etcd

name

The etcd key name, for example: /foo/bar/baz.

value

The value the key should contain.

profile

Optional, defaults to None. Sets the etcd profile to use which has been defined in the Salt Master config.

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

salt.states.etcd_mod.wait_rm(name, recurse=False, profile=None, **kwargs)¶

Deletes a key from etcd only if the watch statement calls it. This function is also aliased as wait_rm.

name

The etcd key name to remove, for example /foo/bar/baz.

recurse

Optional, defaults to False. If True performs a recursive delete, see: https://python-etcd.readthedocs.io/en/latest/#delete-a-key.

profile

Optional, defaults to None. Sets the etcd profile to use which has been defined in the Salt Master config.

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

salt.states.etcd_mod.wait_set(name, value, profile=None, **kwargs)¶

Set a key in etcd only if the watch statement calls it. This function is also aliased as wait_set.

name

The etcd key name, for example: /foo/bar/baz.

value

The value the key should contain.

profile

The etcd profile to use that has been configured on the Salt Master, this is optional and defaults to None.

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