Return data to an etcd server or cluster

  • python-etcd

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

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

Authentication with username and password, 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

Etcd Returner Schema

The etcd returner has the following schema underneath the path set in the profile:


The job key contains the jid of each job that has been returned. Underneath this job are two special keys. One of them is ".load.p" which contains information about the job when it was created. The other key is ".lock.p" which is responsible for whether the job is still valid or it is scheduled to be cleaned up.

The contents if ".lock.p" contains the modifiedIndex of the of the ".load.p" key and when configured via the "etcd.ttl" or "keep_jobs" will have the ttl applied to it. When this file is expired via the ttl or explicitly removed by the administrator, the job will then be scheduled for removal.


This key is essentially a namespace for all of the events (packages) that are submitted to the returner. When an event is received, the package for the event is written under this key using the "tag" parameter for its path. The modifiedIndex for this key is then cached as the event id although the event id can actually be arbitrary since the "index" key contains the real modifiedIndex of the package key.


Underneath the minion.job key is a list of minions ids. Each minion id contains the jid of the last job that was returned by the minion. This key is used to support the external job cache feature of Salt.


Underneath this key is a list of all of the events that were received by the returner. As mentioned before, each event is identified by the modifiedIndex of the key containing the event package. Underneath each event, there are three sub-keys. These are the "index" key, the "tag" key, and the "lock" key.

The "index" key contains the modifiedIndex of the package that was stored under the event key. This is used to determine the original creator for the event's package and is used to keep track of whether the package for the event has been modified by another event (since event tags can be overwritten preserving the semantics of the original etcd returner).

The "lock" key is responsible for informing the maintenance service that the event is still in use. If the returner is configured via the "etcd.ttl" or the "keep_jobs" option, this key will have the ttl applied to it. When the "lock" key has expired or is explicitly removed by the administrator, the event and its tag will be scheduled for removal. The createdIndex for the package path is written to this key in case an application wishes to identify the package path by an index.

The other key under an event, is the "tag" key. The "tag" key simply contains the path to the package that was registered as the tag attribute for the event. The value of the "index" key corresponds to the modifiedIndex of this particular path.


Called in the master's event loop every loop_interval. Removes any jobs, and returns that are older than the etcd.ttl option (seconds), or the keep_jobs option (hours).



Return event to etcd server

Requires that configuration enabled via 'event_return' option in master config.


Return a dict containing the last function called for all the minions that have called a function.


Return the information returned when the specified job id was executed.


Return a list of all job ids that have returned something.

salt.returners.etcd_return.get_jids_filter(count, filter_find_job=True)

Return a list of all job ids :param int count: show not more than the count of most recent jobs :param bool filter_find_jobs: filter out 'saltutil.find_job' jobs


Return the load data that marks a specified jid.


Return a list of all minions that have returned something.

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 profile.

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

Save the load to the specified jid.