consul_kv - Manipulate entries in the key/value store of a consul cluster

New in version 2.0.

Synopsis

Requirements

The below requirements are needed on the host that executes this module.

  • python >= 2.6
  • python-consul
  • requests

Parameters

Parameter Choices/Defaults Comments
cas
Used when acquiring a lock with a session. If the cas is 0, then Consul will only put 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.
flags
Opaque integer value that can be passed when setting a value.
host Default:
localhost
Host of the consul agent.
key
required
The key at which the value should be stored.
port Default:
8500
The port on which the consul agent is running.
recurse
bool
    Choices:
  • no ←
  • yes
If the key represents a prefix, each entry with the prefix can be retrieved by setting this to yes.
scheme
(added in 2.1)
 Default:
http
The protocol scheme on which the consul agent is running.
session
The session that should be used to acquire or release a lock associated with a key/value pair.
state
    Choices:
  • absent
  • acquire
  • present ←
  • release
The action to take with the supplied key and value. If the state is 'present' and `value` is set, the key contents will be set to the value supplied and `changed` will be 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 will be returned. The state 'absent' will remove the key/value pair, again 'changed' will be 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 will be true if the attempt is successful, false otherwise.
token
The token key indentifying an ACL rule set that controls access to the key value pair
validate_certs
bool

(added in 2.1)
    Choices:
  • no
  • yes ←
Whether to verify the tls certificate of the consul agent.
value
required
The value should be associated with the given key, required if state is present.

Examples

# If the key does not exist, the value associated to the "data" property in `retrieved_key` will be `None`
# If the key value is empty string, `retrieved_key["data"]["Value"]` will be `None`
- name: retrieve a value from the key/value store
  consul_kv:
    key: somekey
  register: retrieved_key

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

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

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

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

Status

This module is flagged as preview which means that it is not guaranteed to have a backwards compatible interface.

Maintenance

This module is flagged as community which means that it is maintained by the Ansible Community. See Module Maintenance & Support for more info.

For a list of other modules that are also maintained by the Ansible Community, see here.

Author

  • Steve Gargan (@sgargan)
  • Colin Nolan (@colin-nolan)

Hint

If you notice any issues in this documentation you can edit this document to improve it.