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 eitherscript
andinterval
,http
andinterval
orttl
. Only one ofscript
andinterval
,http
andinterval
orttl
should be provided. If ancheck_id
is not provided, it is set toname
. You cannot have duplicatecheck_id
entries per agent, so it may be necessary to provide acheck_id
. Thenotes
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 everyinterval
to update the status. If ahttp
URL is provided, Consul will poll the URL everyinterval
to update the status - only 2xx results are considered healthy. If attl
type is used, then thettl
update APIs must be used to periodically update the state of the check.Parameters: Return type: 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
-
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: Raises: ValueError
-
-
Agent.
__init__
(uri, adapter, datacenter=None, token=None)¶ Create a new instance of the Agent class
Parameters:
-
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: Return type:
-
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
-
class