Session

class consulate.api.session.Session(uri, adapter, datacenter=None, token=None)

Create, destroy, and query Consul sessions.

create(name=None, behavior='release', node=None, delay=None, ttl=None, checks=None)

Initialize a new session.

None of the fields are mandatory, and in fact no body needs to be PUT if the defaults are to be used.

Name can be used to provide a human-readable name for the Session.

Behavior can be set to either release or delete. This controls the behavior when a session is invalidated. By default, this is release, causing any locks that are held to be released. Changing this to delete causes any locks that are held to be deleted. delete is useful for creating ephemeral key/value entries.

Node must refer to a node that is already registered, if specified. By default, the agent’s own node name is used.

LockDelay (delay) can be specified as a duration string using a “s” suffix for seconds. The default is 15s.

The TTL field is a duration string, and like LockDelay it can use “s” as a suffix for seconds. If specified, it must be between 10s and 3600s currently. When provided, the session is invalidated if it is not renewed before the TTL expires. See the session internals page for more documentation of this feature.

Checks is used to provide a list of associated health checks. It is highly recommended that, if you override this list, you include the default “serfHealth”.

Parameters:
  • name (str) – A human readable session name
  • behavior (str) – One of release or delete
  • node (str) – A node to create the session on
  • delay (str) – A lock delay for the session
  • ttl (str) – The time to live for the session
  • checks (lists) – A list of associated health checks
Return str:

session ID

destroy(session_id)

Destroy an existing session

Parameters:session_id (str) – The session to destroy
Returns:bool
info(session_id)

Returns the requested session information within a given dc. By default, the dc of the agent is queried.

Parameters:session_id (str) – The session to get info about
Returns:dict
list()

Returns the active sessions for a given dc.

Returns:list
node(node)

Returns the active sessions for a given node and dc. By default, the dc of the agent is queried.

Parameters:node (str) – The node to get active sessions for
Returns:list
renew(session_id)

Renew the given session. This is used with sessions that have a TTL, and it extends the expiration by the TTL. By default, the dc of the agent is queried.

Parameters:session_id (str) – The session to renew
Returns:dict