Documentation

consul_session - manipulate consul sessions

New in version 2.0.

Synopsis

allows the addition, modification and deletion of sessions in a consul cluster. These sessions can then be used in conjunction with key value pairs to implement distributed locks. In depth documentation for working with sessions can be found here http://www.consul.io/docs/internals/sessions.html

Requirements (on host that executes module)

  • python >= 2.6
  • python-consul
  • requests

Options

parameter required default choices comments
checks
 no None
    a list of checks that will be used to verify the session health. If all the checks fail, the session will be invalidated and any locks associated with the session will be release and can be acquired once the associated lock delay has expired.
    datacenter
    		 no None
      name of the datacenter in which the session exists or should be created.
      delay
      		 no 15s
        the optional lock delay that can be attached to the session when it is created. Locks for invalidated sessions ar blocked from being acquired until this delay has expired. Valid units for delays include 'ns', 'us', 'ms', 's', 'm', 'h'
        host
        		 no localhost
          host of the consul agent defaults to localhost
          name
          		 no None
            the name that should be associated with the session. This is opaque to Consul and not required.
            node
            		 no None
              the name of the node that with which the session will be associated. by default this is the name of the agent.
              port
              		 no 8500
                the port on which the consul agent is running
                scheme
                (added in 2.1)
                		 no http
                  the protocol scheme on which the consul agent is running
                  state
                  		 no present
                  • present
                  • absent
                  • info
                  • node
                  • list
                  whether the session should be present i.e. created if it doesn't exist, or absent, removed if present. If created, the ID for the session is returned in the output. If absent, the name or ID is required to remove the session. Info for a single session, all the sessions for a node or all available sessions can be retrieved by specifying info, node or list for the state; for node or info, the node name or session id is required as parameter.
                  validate_certs
                  (added in 2.1)
                  		 no True
                    whether to verify the tls certificate of the consul agent

                    Examples

                    - name: register basic session with consul
  consul_session:
    name: session1

- name: register a session with an existing check
  consul_session:
    name: session_with_check
    checks:
      - existing_check_name

- name: register a session with lock_delay
  consul_session:
    name: session_with_delay
    delay: 20s

- name: retrieve info about session by id
  consul_session: id=session_id state=info

- name: retrieve active sessions
  consul_session: state=list

                    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.