community.general.consul_session module – Manipulate Consul sessions

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_session.

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.

Parameters

Parameter

Comments

behavior

string

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

Choices:

  • "delete"

  • "release" ← (default)

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.

checks

list / elements=string

Checks that are used to verify the session health. If all the checks fail, the session is invalidated and any locks associated with the session are released 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

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.

Default: 15

host

string

Host of the Consul agent.

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

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 is associated. By default this is the name of the agent.

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.

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.

state

string

Whether the session should be present or absent, or which session information should be retrieved.

Choices:

  • "absent": The session is removed if present. id is required to remove the session.

  • "info": Retrieves info for a single session. The session id is required.

  • "list": Retrieves all available sessions.

  • "node": Retrieves all the sessions for a node. The node name is required.

  • "present" (default): The session is created if it does not exist. If created, the id for the session is returned in the output.

token

string

added in community.general 5.6.0

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.

ttl

integer

added in community.general 5.4.0

Specifies the duration of a session in seconds (between 10 and 86400).

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)

Attributes

Attribute

Support

Description

action_group

Action group: community.general.consul

added in community.general 8.3.0

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

check_mode

Support: none

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.

Examples

- name: Register basic session with Consul
  community.general.consul_session:
    name: session1

- name: Register a session with an existing check
  community.general.consul_session:
    name: session_with_check
    checks:
      - existing_check_name

- name: Register a session with lock_delay
  community.general.consul_session:
    name: session_with_delay
    delay: 20s

- name: Retrieve info about session by id
  community.general.consul_session:
    id: session_id
    state: info

- name: Retrieve active sessions
  community.general.consul_session:
    state: list

- name: Register session with a ttl
  community.general.consul_session:
    name: session-with-ttl
    ttl: 600 # sec

Authors

  • Steve Gargan (@sgargan)

  • Håkon Lerring (@Hakon)