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

Note

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

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.

Terms

Parameter

Comments

Terms

list / elements=string

List of key(s) to retrieve.

Keyword parameters

This describes keyword parameters of the lookup. These are the values key1=value1, key2=value2 and so on in the following examples: lookup('community.general.consul_kv', key1=value1, key2=value2, ...) and query('community.general.consul_kv', key1=value1, key2=value2, ...)

Parameter

Comments

ca_path

string

added in community.general 12.6.0

The CA bundle to use for HTTPS connections.

Configuration:

client_cert

string

The client cert to verify the TLS connection.

Configuration:

datacenter

string

Retrieve the key from a consul datacenter other than the default for the consul host.

empty_value

string

added in community.general 13.1.0

Controls what is returned when a Consul value is null.

Choices:

  • "empty_string": Return an empty string.

  • "python_none": Return a Python null/None value.

  • "textual_none" (default): Return the string None. This is the legacy behavior.

host

string

The target to connect to, must be a resolvable address.

It is determined from ANSIBLE_CONSUL_URL if that is set.

Default: "localhost"

Configuration:

  • INI entry:

    [lookup_consul]
host = localhost

index

integer

If the key has a value with the specified index then this is returned allowing access to historical values.

port

integer

The port of the target host to connect to.

If you use ANSIBLE_CONSUL_URL this value is used from there.

Default: 8500

recurse

boolean

If true, retrieves all the values that have the given key as prefix.

Choices:

  • false ← (default)

  • true

scheme

string

Whether to use http or https.

If you use ANSIBLE_CONSUL_URL this value is used from there.

Default: "http"

token

string

The acl token to allow access to restricted values.

url

string

added in community.general 1.0.0

The target to connect to.

Should look like this: https://my.consul.server:8500.

Configuration:

validate_certs

boolean

Whether to verify the TLS connection or not.

Instead of setting this to false, please consider using ca_path instead.

Choices:

  • false

  • true ← (default)

Configuration:

Note

Configuration entries listed above for each entry type (Ansible variable, environment variable, and so on) 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. The entry types are also ordered by precedence from low to high priority order. For example, an ansible.cfg entry (further up in the list) is overwritten by an Ansible variable (further down in the list).

Notes

Note

  • When keyword and positional parameters are used together, positional parameters must be listed before keyword parameters: lookup('community.general.consul_kv', term1, term2, key1=value1, key2=value2) and query('community.general.consul_kv', term1, term2, key1=value1, key2=value2)

  • On a macOS controller this lookup can abort the worker process it runs in, with Ansible reporting A worker was found in a dead state. Lookups run in a forked process, and resolving the system proxy configuration there initializes macOS frameworks that are not safe to use after a fork(); see https://github.com/ansible/ansible/issues/49207. Setting any proxy environment variable, for example no_proxy, skips the system proxy lookup and avoids the crash.

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 Value

Key

Description

Return value

dictionary

Value(s) stored in consul.

Returned: success

Authors

  • Unknown