consul.api.agent module¶

class consul.api.agent.Agent(agent)[source]¶

Bases: object

The Agent endpoints are used to interact with a local Consul agent. Usually, services and checks are registered with an agent, which then takes on the burden of registering with the Catalog and performing anti-entropy to recover from outages.

self()[source]¶: Returns configuration of the local agent and member information.

services()[source]¶

Returns all the services that are registered with the local agent. These services were either provided through configuration files, or added dynamically using the HTTP API. It is important to note that the services known by the agent may be different than those reported by the Catalog. This is usually due to changes being made while there is no leader elected. The agent performs active anti-entropy, so in most situations everything will be in sync within a few seconds.

Return type:: Any

service_definition(service_id)[source]¶: Returns a service definition for a single instance that is registered with the local agent.

checks()[source]¶

Returns all the checks that are registered with the local agent. These checks were either provided through configuration files, or added dynamically using the HTTP API. Similar to services, the checks known by the agent may be different than those reported by the Catalog. This is usually due to changes being made while there is no leader elected. The agent performs active anti-entropy, so in most situations everything will be in sync within a few seconds.

Return type:: Any

members(wan=False)[source]¶

Returns all the members that this agent currently sees. This may vary by agent, use the nodes api of Catalog to retrieve a cluster wide consistent view of members.

For agents running in server mode, setting wan to True returns the list of WAN members instead of the LAN members which is default.

Parameters:: wan (bool)

maintenance(enable, reason=None, token=None)[source]¶

The node maintenance endpoint can place the agent into “maintenance mode”.

enable is either ‘true’ or ‘false’. ‘true’ enables maintenance mode, ‘false’ disables maintenance mode.

reason is an optional string. This is simply to aid human operators.

Parameters:

enable (bool)
reason (str | None)
token (str | None)

join(address, wan=False, token=None)[source]¶

This endpoint instructs the agent to attempt to connect to a given address.

address is the ip to connect to.

wan is either ‘true’ or ‘false’. For agents running in server mode, ‘true’ causes the agent to attempt to join using the WAN pool. Default is ‘false’.

Parameters:

address (str)
wan (bool)
token (str | None)

force_leave(node, token=None)[source]¶

This endpoint instructs the agent to force a node into the left state. If a node fails unexpectedly, then it will be in a failed state. Once in the failed state, Consul will attempt to reconnect, and the services and checks belonging to that node will not be cleaned up. Forcing a node into the left state allows its old entries to be removed.

node is the node to change state for.

Parameters:

node (str)
token (str | None)

class Service(agent)[source]¶

Bases: object

register(name, service_id=None, address=None, port=None, tags=None, check=None, token=None, meta=None, weights=None, script=None, interval=None, ttl=None, http=None, timeout=None, enable_tag_override=False, extra_checks=None, replace_existing_checks=False, tagged_addresses=None, connect=None)[source]¶

Add a new service to the local agent. There is more documentation on services here.

name is the name of the service.

If the optional service_id is not provided it is set to name. You cannot have duplicate service_id entries per agent, so it may be necessary to provide one.

address will default to the address of the agent if not provided.

An optional health check can be created for this service is one of `Check.script`_, `Check.http`_, `Check.tcp`_, `Check.ttl`_ or `Check.docker`_.

token is an optional `ACL token`_ to apply to this request. Note this call will return successful even if the token doesn’t have permissions to register this service.

meta specifies arbitrary KV metadata linked to the service formatted as {k1:v1, k2:v2}.

weights specifies weights for the service; default to {“Passing”: 1, “Warning”: 1}.

tagged_addresses specifies alternative addresses for the service, e.g. for use with Connect. Formatted as { “lan”: “<address>”, “wan”: “<address>” }.

connect specifies configuration for Connect. Formatted as { “sidecar_service”: {} }.

script, interval, ttl, http, and timeout arguments are deprecated. use check instead.

replace_existing_checks Missing health checks from the request will be deleted from the agent. Using this parameter allows to idempotently register a service and its checks without having to manually deregister checks.

enable_tag_override is an optional bool that enable you to modify a service tags from servers(consul agent role server) Default is set to False. This option is only for >=v0.6.0 version on both agent and servers. for more information https://developer.hashicorp.com/consul/docs/fundamentals/service

Parameters:

name (str)
port (int | None)
token (str | None)
ttl (int | None)
enable_tag_override (bool)
tagged_addresses (dict | None)
connect (dict[str, Any] | None)

deregister(service_id, token=None)[source]¶

Used to remove a service from the local agent. The agent will take care of deregistering the service with the Catalog. If there is an associated check, that is also deregistered.

Parameters:

service_id (str)
token (str | None)

maintenance(service_id, enable, reason=None, token=None)[source]¶

The service maintenance endpoint allows placing a given service into “maintenance mode”.

service_id is the id of the service that is to be targeted for maintenance.

enable is either ‘true’ or ‘false’. ‘true’ enables maintenance mode, ‘false’ disables maintenance mode.

reason is an optional string. This is simply to aid human operators.

Parameters:

service_id (str)
enable (bool)
reason (str | None)
token (str | None)

class Check(agent)[source]¶

Bases: object

register(name, check=None, check_id=None, notes=None, service_id=None, token=None, script=None, interval=None, ttl=None, http=None, timeout=None)[source]¶

name is the name of the check.

check is one of `Check.script`_, `Check.http`_, `Check.tcp`_ `Check.ttl`_ or `Check.docker`_ and is required.

If the optional check_id is not provided it is set to name. check_id must be unique for this agent.

notes is not used by Consul, and is meant to be human readable.

Optionally, a service_id can be specified to associate a registered check with an existing service.

token is an optional `ACL token`_ to apply to this request. Note this call will return successful even if the token doesn’t have permissions to register this check.

script, interval, ttl, http, and timeout arguments are deprecated. use check instead.

Returns True on success.

Parameters:

name (str)
token (str | None)
ttl (int | None)

deregister(check_id, token=None)[source]¶

Remove a check from the local agent.

Parameters:

check_id (str)
token (str | None)

ttl_pass(check_id, notes=None, token=None)[source]¶

Mark a ttl based check as passing. Optional notes can be attached to describe the status of the check.

Parameters:

check_id (str)
token (str | None)

ttl_fail(check_id, notes=None, token=None)[source]¶

Mark a ttl based check as failing. Optional notes can be attached to describe why check is failing. The status of the check will be set to critical and the ttl clock will be reset.

Parameters:

check_id (str)
token (str | None)

ttl_warn(check_id, notes=None, token=None)[source]¶

Mark a ttl based check with warning. Optional notes can be attached to describe the warning. The status of the check will be set to warn and the ttl clock will be reset.

Parameters: