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

Note

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

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