consul_kv – Fetch metadata from a Consul key value store

Synopsis

  • Lookup metadata for a playbook from the key value store in a Consul cluster. Values can be easily set in the kv store with simple rest commands
  • curl -X PUT -d 'some-value' http://localhost:8500/v1/kv/ansible/somedata

Requirements

The below requirements are needed on the local master node that executes this lookup.

Parameters

Parameter Choices/Defaults Configuration Comments
_raw
list / required
List of key(s) to retrieve.
client_cert
-
added in 2.8
ini entries:

[lookup_consul]
client_cert = VALUE

env:ANSIBLE_CONSUL_CLIENT_CERT
The client cert to verify the ssl connection.
datacenter
-
added in 2.9
Retrieve the key from a consul datatacenter other than the default for the consul host.
host
-
added in 2.8
 Default:
"localhost"
ini entries:

[lookup_consul]
host = localhost

env:ANSIBLE_CONSUL_URL
The target to connect to, must be a resolvable address. Will be determined from ANSIBLE_CONSUL_URL if that is set.
ANSIBLE_CONSUL_URL should look like this: https://my.consul.server:8500
index
-
If the key has a value with the specified index then this is returned allowing access to historical values.
port
-
Default:
8500
The port of the target host to connect to.
If you use ANSIBLE_CONSUL_URL this value will be used from there.
recurse
boolean
Default:
"no"
If true, will retrieve all the values that have the given key as prefix.
scheme
-
added in 2.8
 Default:
"http"
Whether to use http or https.
If you use ANSIBLE_CONSUL_URL this value will be used from there.
token
-
The acl token to allow access to restricted values.
validate_certs
-
added in 2.8
 Default:
"yes"
ini entries:

[lookup_consul]
validate_certs = yes

env:ANSIBLE_CONSUL_VALIDATE_CERTS
Whether to verify the ssl connection or not.

Examples

- debug:
    msg: 'key contains {{item}}'
  with_consul_kv:
    - 'key/to/retrieve'

- name: Parameters can be provided after the key be more specific about what to retrieve
  debug:
    msg: 'key contains {{item}}'
  with_consul_kv:
    - 'key/to recurse=true token=E6C060A9-26FB-407A-B83E-12DDAFCB4D98'

- name: retrieving a KV from a remote cluster on non default port
  debug:
    msg: "{{ lookup('consul_kv', 'my/key', host='10.10.10.10', port='2000') }}"

Return Values

Common return values are documented here, the following are the fields unique to this lookup:

Key Returned Description
_raw
-
Value(s) stored in consul.


Status

Authors

  • UNKNOWN

Hint

If you notice any issues in this documentation, you can edit this document to improve it.

Hint

Configuration entries for each entry type have a low to high priority order. For example, a variable that is lower in the list will override a variable that is higher up.