consul.api.session module

class consul.api.session.Session(agent)

Bases: object

create(name=None, node=None, checks=None, lock_delay=15, behavior='release', ttl=None, dc=None, token=None)

Creates a new session. There is more documentation for sessions here.

name is an optional human readable name for the session.

node is the node to create the session on. if not provided the current agent’s node will be used.

checks is a list of checks to associate with the session. if not provided it defaults to the serfHealth check. It is highly recommended that, if you override this list, you include the default serfHealth.

lock_delay is an integer of seconds.

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.

when ttl is provided, the session is invalidated if it is not renewed before the TTL expires. If specified, it is an integer of seconds. Currently it must be between 10 and 86400 seconds.

token is an optional ACL token to apply to this request. ACL required : session:write

By default the session will be created in the current datacenter but an optional dc can be provided.

Returns the string session_id for the session.

Parameters:

• name (str | None)

• lock_delay (int)

• behavior (str)

• ttl (int | None)

• token (str | None)

destroy(session_id, dc=None, token=None)

Destroys the session session_id

token is an optional ACL token to apply to this request. ACL required : session:write

Returns True on success.

Parameters:

token (str | None)

list(index=None, wait=None, consistency=None, dc=None, token=None)

Returns a tuple of (index, sessions) of all active sessions in the dc datacenter. dc defaults to the current datacenter of this agent.

index is the current Consul index, suitable for making subsequent calls to wait for changes since this query was last run.

wait the maximum duration to wait (e.g. ’10s’) to retrieve a given index. this parameter is only applied if index is also specified. the wait time by default is 5 minutes.

consistency can be either ‘default’, ‘consistent’ or ‘stale’. if not specified consistency will the consistency level this client was configured with.

token is an optional ACL token to apply to this request. ACL required : session:read

The response looks like this:

 (index, [
     {
         "LockDelay": 1.5e+10,
         "Checks": [
             "serfHealth"
         ],
         "Node": "foobar",
         "ID": "adf4238a-882b-9ddc-4a9d-5b6758e4159e",
         "CreateIndex": 1086449
     },
   ...
])

Parameters:

token (str | None)

node(node, index=None, wait=None, consistency=None, dc=None, token=None)

Returns a tuple of (index, sessions) as per session.list, but filters the sessions returned to only those active for node.

index is the current Consul index, suitable for making subsequent calls to wait for changes since this query was last run.

wait the maximum duration to wait (e.g. ’10s’) to retrieve a given index. this parameter is only applied if index is also specified. the wait time by default is 5 minutes.

consistency can be either ‘default’, ‘consistent’ or ‘stale’. if not specified consistency will the consistency level this client was configured with.

token is an optional ACL token to apply to this request. ACL required : session:read

Parameters:

• node (str)

• token (str | None)

info(session_id, index=None, wait=None, consistency=None, dc=None, token=None)

Returns a tuple of (index, session) for the session session_id in the dc datacenter. dc defaults to the current datacenter of this agent.

index is the current Consul index, suitable for making subsequent calls to wait for changes since this query was last run.

wait the maximum duration to wait (e.g. ’10s’) to retrieve a given index. this parameter is only applied if index is also specified. the wait time by default is 5 minutes.

consistency can be either ‘default’, ‘consistent’ or ‘stale’. if not specified consistency will the consistency level this client was configured with.

token is an optional ACL token to apply to this request. ACL required : session:read

Parameters:

• session_id (str)

• token (str | None)

renew(session_id, dc=None, token=None)

This is used with sessions that have a TTL, and it extends the expiration by the TTL.

dc is the optional datacenter that you wish to communicate with. If None is provided, defaults to the agent’s datacenter.

token is an optional ACL token to apply to this request. ACL required : session:write

Returns the session.

Parameters:

token (str | None)