Return data to an etcd server or cluster

  • python-etcd or etcd3-py

In order to return to an etcd server, a profile should be created in the master configuration file:

  etcd.port: 2379

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.port: 2379

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.


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.

Additionally, two more options must be specified in the top-level configuration in order to use the etcd returner:

etcd.returner: my_etcd_config
etcd.returner_root: /salt/return

The etcd.returner option specifies which configuration profile to use. The etcd.returner_root option specifies the path inside etcd to use as the root of the returner system.

Once the etcd options are configured, the returner may be used:

CLI Example:

salt '*' --return etcd

A username and password can be set:

etcd.username: larry  # Optional; requires etcd.password to be set
etcd.password: 123pass  # Optional; requires etcd.username to be set

You can also set a TTL (time to live) value for the returner:

etcd.ttl: 5

Authentication with username and password, and ttl, currently requires the master branch of python-etcd.

You may also specify different roles for read and write operations. First, create the profiles as specified above. Then add:

etcd.returner_read_profile: my_etcd_read
etcd.returner_write_profile: my_etcd_write

Included for API consistency


Return a dict of the last function called for all minions


Return the information returned when the specified job id was executed


Return a list of all job ids


Return the load data that marks a specified jid


Return a list of minions

salt.returners.etcd_return.prep_jid(nocache=False, passed_jid=None)

Do any work necessary to prepare a JID, including sending a custom id


Return data to an etcd server or cluster

salt.returners.etcd_return.save_load(jid, load, minions=None)

Save the load to the specified jid

salt.returners.etcd_return.save_minions(jid, minions, syndic_id=None)

Included for API consistency