salt.pillar.consul_pillar module

Use Consul K/V as a Pillar source with values parsed as YAML

depends
  • python-consul

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

my_consul_config:
  consul.host: 127.0.0.1
  consul.port: 8500
  consul.token: b6376760-a8bb-edd5-fcda-33bc13bfc556
  consul.scheme: http
  consul.consistency: default
  consul.dc: dev
  consul.verify: True

All parameters are optional.

The consul.token requires python-consul >= 0.4.7.

If you have a multi-datacenter Consul cluster you can map your pillarenv entries to your data centers by providing a dictionary of mappings in consul.dc field:

my_consul_config:
  consul.dc:
    dev: us-east-1
    prod: us-west-1

In the example above we specifying static mapping between Pillar environments and data centers: the data for dev and prod Pillar environments will be fetched from us-east-1 and us-west-1 datacenter respectively.

In fact when consul.dc is set to dictionary keys are processed as regular expressions (that can capture named parameters) and values are processed as string templates as per PEP 3101.

my_consul_config:
  consul.dc:
    ^dev-.*$: dev-datacenter
    ^(?P<region>.*)-prod$: prod-datacenter-{region}

This example maps all Pillar environments starting with dev- to dev-datacenter whereas Pillar environment like eu-prod will be mapped to prod-datacenter-eu.

Before evaluation patterns are sorted by length in descending order.

If Pillar environment names correspond to data center names a single pattern can be used:

my_consul_config:
  consul.dc:
    ^(?P<env>.*)$: '{env}'

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

ext_pillar:
  - consul: my_consul_config

ext_pillar:
  - consul: my_consul_config root=salt

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

ext_pillar:
  - consul: my_consul_config
  - consul: my_other_consul_config

Either the minion_id, or the role, or the environment grain may be used in the root path to expose minion-specific information stored in consul.

ext_pillar:
  - consul: my_consul_config root=salt/%(minion_id)s
  - consul: my_consul_config root=salt/%(role)s
  - consul: my_consul_config root=salt/%(environment)s

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

ext_pillar:
  - consul: my_consul_config root=salt-shared
  - consul: my_other_consul_config root=salt-private/%(minion_id)s

If using the role or environment grain in the consul key path, be sure to define it using /etc/salt/grains, or similar:

role: my-minion-role
environment: dev

It's possible to lock down where the pillar values are shared through minion targeting. Note that double quotes " are required around the target value and cannot be used inside the matching statement. See the section on Compound Matchers for more examples.

ext_pillar:
  - consul: my_consul_config root=salt target="L@salt.example.com and G@osarch:x86_64"

The data from Consul can be merged into a nested key in Pillar.

ext_pillar:
  - consul: my_consul_config pillar_root=consul_data

By default, keys containing YAML data will be deserialized before being merged into Pillar. This behavior can be disabled by setting expand_keys to false.

ext_pillar:
  - consul: my_consul_config expand_keys=false
salt.pillar.consul_pillar.consul_fetch(client, path)

Query consul for all keys/values within base path

salt.pillar.consul_pillar.ext_pillar(minion_id, pillar, conf)

Check consul for all data

salt.pillar.consul_pillar.fetch_tree(client, path, expand_keys)

Grab data from consul, trim base path and remove any keys which are folders. Take the remaining data and send it to be formatted in such a way as to be used as pillar data.

salt.pillar.consul_pillar.get_conn(opts, profile)

Return a client object for accessing consul

salt.pillar.consul_pillar.pillar_format(ret, keys, value, expand_keys)

Perform data formatting to be used as pillar data and merge it with the current pillar data