Use etcd data as a Pillar source

New in version 2014.7.0.

  • python-etcd or etcd3-py

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

  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.


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.

After the profile is created, configure the external pillar system to use it. Optionally, a root may be specified.

  - etcd: my_etcd_config

  - etcd: my_etcd_config root=/salt

Using these configuration profiles, multiple etcd sources may also be used:

  - etcd: my_etcd_config
  - etcd: my_other_etcd_config

The minion_id may be used in the root path to expose minion-specific information stored in etcd.

  - etcd: my_etcd_config root=/salt/%(minion_id)s

Minion-specific values may override shared values when the minion-specific root appears after the shared root:

  - etcd: my_etcd_config root=/salt-shared
  - etcd: my_other_etcd_config root=/salt-private/%(minion_id)s

Using the configuration above, the following commands could be used to share a key with all minions but override its value for a specific minion:

etcdctl set /salt-shared/mykey my_value
etcdctl set /salt-private/special_minion_id/mykey my_other_value
salt.pillar.etcd_pillar.ext_pillar(minion_id, pillar, conf)

Check etcd for all data