Agent

class consulate.api.agent.Agent(uri, adapter, datacenter=None, token=None)

The Consul agent is the core process of Consul. The agent maintains membership information, registers services, runs checks, responds to queries and more. The agent must run on every node that is part of a Consul cluster.

class Check(uri, adapter, datacenter=None, token=None)

One of the primary roles of the agent is the management of system and application level health checks. A health check is considered to be application level if it associated with a service. A check is defined in a configuration file, or added at runtime over the HTTP interface.

There are two different kinds of checks:

  • Script + Interval: These checks depend on invoking an external

    application which does the health check and exits with an appropriate exit code, potentially generating some output. A script is paired with an invocation interval (e.g. every 30 seconds). This is similar to the Nagios plugin system.

  • TTL: These checks retain their last known state for a given TTL.

    The state of the check must be updated periodically over the HTTP interface. If an external system fails to update the status within a given TTL, the check is set to the failed state. This mechanism is used to allow an application to directly report it’s health. For example, a web app can periodically curl the endpoint, and if the app fails, then the TTL will expire and the health check enters a critical state. This is conceptually similar to a dead man’s switch.

deregister(check_id)

Remove a check from the local agent. The agent will take care of deregistering the check with the Catalog.

Parameters:check_id (str) – The check id
register(name, script=None, check_id=None, interval=None, ttl=None, notes=None, http=None)

Add a new check to the local agent. Checks are either a script or TTL type. The agent is responsible for managing the status of the check and keeping the Catalog in sync.

The name field is mandatory, as is either script and interval, http and interval or ttl. Only one of script and interval, http and interval or ttl should be provided. If an check_id is not provided, it is set to name. You cannot have duplicate check_id entries per agent, so it may be necessary to provide a check_id. The notes field is not used by Consul, and is meant to be human readable.

If a script is provided, the check type is a script, and Consul will evaluate the script every interval to update the status. If a http URL is provided, Consul will poll the URL every interval to update the status - only 2xx results are considered healthy. If a ttl type is used, then the ttl update APIs must be used to periodically update the state of the check.

Parameters:
  • name (str) – The check name
  • http (str) – The URL to poll for health checks
  • script (str) – The path to the script to run
  • check_id (str) – The optional check id
  • interval (int) – The interval to run the check
  • ttl (int) – The ttl to specify for the check
  • notes (str) – Administrative notes.
Return type:

bool
Raises:

ValueError
ttl_fail(check_id)

This endpoint is used with a check that is of the TTL type. When this endpoint is accessed, the status of the check is set to “critical”, and the TTL clock is reset.

Parameters:check_id (str) – The check id
ttl_pass(check_id)

This endpoint is used with a check that is of the TTL type. When this endpoint is accessed, the status of the check is set to “passing”, and the TTL clock is reset.

Parameters:check_id (str) – The check id
ttl_warn(check_id)

This endpoint is used with a check that is of the TTL type. When this endpoint is accessed, the status of the check is set to “warning”, and the TTL clock is reset.

Parameters:check_id (str) – The check id
class Agent.Service(uri, adapter, datacenter=None, token=None)

One of the main goals of service discovery is to provide a catalog of available services. To that end, the agent provides a simple service definition format to declare the availability of a service, a nd to potentially associate it with a health check. A health check is considered to be application level if it associated with a service. A service is defined in a configuration file, or added at runtime over the HTTP interface.

deregister(service_id)

Deregister the 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) – The service id to deregister
Return type:bool
register(name, service_id=None, address=None, port=None, tags=None, check=None, interval=None, ttl=None, httpcheck=None)

Add a new service to the local agent.

Parameters:
  • name (str) – The name of the service
  • service_id (str) – The id for the service (optional)
  • address (str) – The service IP address
  • port (int) – The service port
  • tags (list) – A list of tags for the service
  • check (str) – The path to the check script to run
  • interval (str) – The check execution interval
  • ttl (str) – The TTL for external script check pings
  • httpcheck (str) – An URL to check every interval
Return type:

bool
Raises:

ValueError
Agent.__init__(uri, adapter, datacenter=None, token=None)

Create a new instance of the Agent class

Parameters:
  • uri (str) – Base URI
  • adapter (consul.adapters.Request) – Request adapter
  • datacenter (str) – datacenter
  • token (str) – Access Token
Agent.checks()

return the 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. It is important to note that 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:list
Agent.force_leave(node)

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 this state, Consul will attempt to reconnect, and additionally 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.

Agent.join(address, wan=False)

This endpoint is hit with a GET and is used to instruct the agent to attempt to connect to a given address. For agents running in server mode, setting wan=True causes the agent to attempt to join using the WAN pool.

Parameters:
  • address (str) – The address to join
  • wan (bool) – Join a WAN pool as a server
Return type:

bool
Agent.members()

Returns the members the agent sees in the cluster gossip pool. Due to the nature of gossip, this is eventually consistent and the results may differ by agent. The strongly consistent view of nodes is instead provided by Consulate.catalog.nodes.

Return type:list
Agent.services()

return the 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:list