# salt.pillar.consul_pillar

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