community.general.consul_kv – Fetch metadata from a Consul key value store.

Note

This plugin is part of the community.general collection (version 3.8.1).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install community.general.

To use it in a playbook, specify: community.general.consul_kv.

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 controller node that executes this lookup.

python-consul python library https://python-consul.readthedocs.io/en/latest/#installation

Parameters

Parameter	Choices/Defaults	Configuration	Comments
_raw list / elements=string			List of key(s) to retrieve.
client_cert string		ini entries: [lookup_consul] client_cert = None env:ANSIBLE_CONSUL_CLIENT_CERT	The client cert to verify the ssl connection.
datacenter string			Retrieve the key from a consul datacenter other than the default for the consul host.
host string	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 string			If the key has a value with the specified index then this is returned allowing access to historical values.
port string	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	Choices: no ← yes		If true, will retrieve all the values that have the given key as prefix.
scheme string	Default: "http"		Whether to use http or https. If you use `ANSIBLE_CONSUL_URL` this value will be used from there.
token string			The acl token to allow access to restricted values.
url string added in 1.0.0 of community.general		ini entries: [lookup_consul] url = None env:ANSIBLE_CONSUL_URL	The target to connect to, should look like this: `https://my.consul.server:8500`.
validate_certs string	Default: "yes"	ini entries: [lookup_consul] validate_certs = yes env:ANSIBLE_CONSUL_VALIDATE_CERTS	Whether to verify the ssl connection or not.

Examples

- ansible.builtin.debug:
    msg: 'key contains {{item}}'
  with_community.general.consul_kv:
    - 'key/to/retrieve'

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

- name: retrieving a KV from a remote cluster on non default port
  ansible.builtin.debug:
    msg: "{{ lookup('community.general.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 dictionary	success	Value(s) stored in consul.

Authors

Unknown (!UNKNOWN)

© 2012–2018 Michael DeHaan
© 2018–2021 Red Hat, Inc.
Licensed under the GNU General Public License version 3.
https://docs.ansible.com/ansible/latest/collections/community/general/consul_kv_lookup.html

Docs

Docs4dev

Title here