Documentation

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

New in version 2.0.

Synopsis

Allows the addition, modification and deletion of key/value entries in a consul cluster via 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.

Requirements (on host that executes module)

  • python >= 2.6
  • python-consul
  • requests

Options

parameter required default choices comments
cas
no None
    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
    no None
      opaque integer value that can be passed when setting a value.
      host
      no localhost
        host of the consul agent defaults to localhost
        key
        yes
          the key at which the value should be stored.
          port
          no 8500
            the port on which the consul agent is running
            recurse
            no
              if the key represents a prefix, each entry with the prefix can be retrieved by setting this to true.
              scheme
              (added in 2.1)
              no http
                the protocol scheme on which the consul agent is running
                session
                no None
                  the session that should be used to acquire or release a lock associated with a key/value pair
                  state
                  no present
                  • present
                  • absent
                  • acquire
                  • release
                  the action to take with the supplied key and value. If the state is 'present', the key contents will be set to the value supplied, 'changed' will be set to true only if the value was different to the current contents. 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
                  no None
                    the token key indentifying an ACL rule set that controls access to the key value pair
                    validate_certs
                    (added in 2.1)
                    no True
                      whether to verify the tls certificate of the consul agent
                      value
                      yes
                        the value should be associated with the given key, required if state is present

                        Examples

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

                        This is an Extras Module

                        For more information on what this means please read Extras Modules

                        For help in developing on modules, should you be so inclined, please read Community Information & Contributing, Helping Testing PRs and Developing Modules.