community.general.consul_kv module – Manipulate entries in the key/value store of a Consul cluster

Note

This module 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

  • Allows the retrieval, addition, modification and deletion of key/value entries in a Consul cluster using the agent. The entire contents of the record, including the indices, flags and session are returned as value.

  • If the key represents a prefix then note that when a value is removed, the existing value if any is returned as part of the results.

  • See http://www.consul.io/docs/agent/http.html#kv for more details.

Parameters

Parameter

Comments

ca_path

string

The CA bundle to use for https connections.

If unset, the value of the CONSUL_CACERT environment variable is used when set. This is supported since community.general 13.4.0.

cas

string

Used when acquiring a lock with a session. If the cas is 0, then Consul only puts the key if it does not already exist. If the cas value is non-zero, then the key is only set if the index matches the ModifyIndex of that key.

datacenter

string

added in community.general 10.0.0

The name of the datacenter to query. If unspecified, the query defaults to the datacenter of the Consul agent on host.

flags

string

Opaque positive integer value that can be passed when setting a value.

host

string

Host of the Consul agent.

If unset, the host component of url is used, and localhost when url is not set either.

key

string / required

The key at which the value should be stored.

port

integer

The port on which the consul agent is running.

If unset, the port component of url is used, and 8500 when that does not specify one either.

recurse

boolean

If the key represents a prefix, each entry with the prefix can be retrieved by setting this to true.

Choices:

  • false

  • true

retrieve

boolean

If the state is present and value is set, perform a read after setting the value and return this value.

Choices:

  • false

  • true ← (default)

scheme

string

The protocol scheme on which the Consul agent is running.

If unset, a true value in the CONSUL_HTTP_SSL environment variable selects https, otherwise the scheme component of url is used, and http when that does not specify one either. A false CONSUL_HTTP_SSL does not downgrade an https url.

session

string

The session that should be used to acquire or release a lock associated with a key/value pair.

state

string

The action to take with the supplied key and value. If the state is present and value is set, the key contents is set to the value supplied and changed is set to true only if the value was different to the current contents. If the state is present and value is not set, the existing value associated to the key is returned. This behavior will be deprecated in the future. Use community.general.consul_kv_info to read key/value entries instead. The state absent is used to remove the key/value pair, again changed is set to true only if the key actually existed prior to the removal. An attempt can be made to obtain or free the lock associated with a key/value pair with the states acquire or release respectively. A valid session must be supplied to make the attempt changed is true if the attempt is successful, false otherwise.

Choices:

  • "absent"

  • "acquire"

  • "present" ← (default)

  • "release"

token

string

The token to use for authorization.

If unset, the value of the CONSUL_HTTP_TOKEN environment variable is used. This is supported since community.general 13.4.0.

url

string

added in community.general 13.4.0

The address of the Consul agent, in the host:port or scheme://host:port form. The scheme and the port are optional, the host is not.

host, port and scheme take precedence over the components of this option.

If unset, the value of the CONSUL_HTTP_ADDR environment variable is used when set. An address these modules cannot use, a unix:// socket for example, makes the module fail, unless host, port and scheme are all set, in which case the address is not consulted at all.

validate_certs

boolean

Whether to verify the TLS certificate of the Consul agent.

If unset, the value of the CONSUL_HTTP_SSL_VERIFY environment variable is used when set. This is supported since community.general 13.4.0.

Choices:

  • false

  • true ← (default)

value

string

The value should be associated with the given key, required if state is present.

Omitting value with state=present to read a key will be deprecated in the future. Use community.general.consul_kv_info instead.

Attributes

Attribute

Support

Description

action_group

Action group: community.general.consul

added in community.general 13.2.0

Use group/community.general.consul in module_defaults to set defaults for this module.

check_mode

Support: full

Can run in check_mode and return changed status prediction without modifying target.

diff_mode

Support: none

Returns details on what has changed (or possibly needs changing in check_mode), when in diff mode.

See Also

See also

community.general.consul_kv_info

Retrieve entries from the key/value store of a Consul cluster.

Examples

- name: Add or update the value associated with a key in the key/value store
  community.general.consul_kv:
    key: somekey
    value: somevalue

- name: Remove a key from the store
  community.general.consul_kv:
    key: somekey
    state: absent

- name: Add a node to an arbitrary group using Consul inventory (see consul.ini)
  community.general.consul_kv:
    key: ansible/groups/dc1/somenode
    value: top_secret

- name: Register a key/value pair with an associated session
  community.general.consul_kv:
    key: stg/node/server_birthday
    value: 20160509
    session: "{{ sessionid }}"
    state: acquire

Authors

  • Steve Gargan (@sgargan)

  • Colin Nolan (@colin-nolan)