# consul_session – Manipulate consul sessions

- Synopsis

- Requirements

- Parameters

- Examples

- Status

## 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 at http://www.consul.io/docs/internals/sessions.html

## Requirements

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

- python-consul

- requests

## Parameters

Parameter | Choices/Defaults | Comments
--- | --- | ---

behavior
string

Choices:
- delete
- release ←

The optional behavior that can be attached to the session when it is created. This controls the behavior when a session is invalidated.

checks list |  | 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 string |  | The name of the datacenter in which the session exists or should be created.
delay integer | Default: 15 | 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. Durations are in seconds.
host string | Default: "localhost" | The host of the consul agent defaults to localhost.
id string |  | ID of the session, required when state is either `info` or `remove`.
name string |  | The name that should be associated with the session. Required when state=node is used.
node string |  | The name of the node that with which the session will be associated. by default this is the name of the agent.
port integer | Default: 8500 | The port on which the consul agent is running.
scheme string | Default: "http" | The protocol scheme on which the consul agent is running.

state
string

Choices:
- absent
- info
- list
- node
- present ←

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`, 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
boolean

Choices:
- no
- yes ←

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

## Status

- This module is not guaranteed to have a backwards compatible interface. [preview]

- This module is maintained by the Ansible Community. [community]

### Authors

- Steve Gargan (@sgargan)

Hint

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