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 4.8.3).

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.

Parameters

Parameter

Comments

_raw

list / elements=string

List of key(s) to retrieve.

client_cert

string

The client cert to verify the ssl connection.

Configuration:

  • INI entry:

    [lookup_consul]
client_cert = None

  • Environment variable: ANSIBLE_CONSUL_CLIENT_CERT

datacenter

string

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

host

string

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

Default: “localhost”

Configuration:

  • INI entry:

    [lookup_consul]
host = localhost

  • Environment variable: ANSIBLE_CONSUL_URL

index

string

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

port

string

The port of the target host to connect to.

If you use ANSIBLE_CONSUL_URL this value will be used from there.

Default: 8500

recurse

boolean

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

Choices:

  • no ← (default)

  • yes

scheme

string

Whether to use http or https.

If you use ANSIBLE_CONSUL_URL this value will be used from there.

Default: “http”

token

string

The acl token to allow access to restricted values.

url

string

added in 1.0.0 of community.general

The target to connect to, should look like this: https://my.consul.server:8500.

Configuration:

  • INI entry:

    [lookup_consul]
url = None

  • Environment variable: ANSIBLE_CONSUL_URL

validate_certs

string

Whether to verify the ssl connection or not.

Default: “yes”

Configuration:

  • INI entry:

    [lookup_consul]
validate_certs = yes

  • Environment variable: ANSIBLE_CONSUL_VALIDATE_CERTS

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

Description

_raw

dictionary

Value(s) stored in consul.

Returned: success

Authors

  • Unknown

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.