# salt.returners.etcd_return

Return data to an etcd server or cluster

depends:

  - python-etcd or etcd3-py

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

    my_etcd_config:
      etcd.host: 127.0.0.1
      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.host: 127.0.0.1
    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.

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.

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 '*' test.ping --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

salt.returners.etcd_return.clean_old_jobs()

  Included for API consistency

salt.returners.etcd_return.get_fun(fun)

  Return a dict of the last function called for all minions

salt.returners.etcd_return.get_jid(jid)

  Return the information returned when the specified job id was executed

salt.returners.etcd_return.get_jids()

  Return a list of all job ids

salt.returners.etcd_return.get_load(jid)

  Return the load data that marks a specified jid

salt.returners.etcd_return.get_minions()

  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

salt.returners.etcd_return.returner(ret)

  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