The /agent endpoints are used to interact with the local Consul agent.
Usually, services and checks are registered with an agent which then takes on
the burden of keeping that data synchronized with the cluster. For example, the
agent registers services and checks with the Catalog and performs
anti-entropy to recover from outages.
In addition to these endpoints, additional endpoints are grouped in the
navigation for Checks and Services.
This endpoint returns the members the agent sees in the cluster gossip pool. Due
to the nature of gossip, this is eventually consistent: the results may differ
by agent. The strongly consistent view of nodes is instead provided by
wan(bool: false) - Specifies to list WAN members instead of the LAN
members (which is the default). This is only eligible for agents running in
server mode. This is specified as part of the URL as a query parameter.
- Specifies the segment to list members for.
If left blank, this will query for the default segment when connecting to a server and
the agent's own segment when connecting to a client (clients can only be part of one
network segment). When querying a server, setting this to the special string _all
will show members in all segments.
This endpoint returns the configuration and member information of the local
agent. The Config element contains a subset of the configuration and its
format will not change in a backwards incompatible way between releases.
DebugConfig contains the full runtime configuration but its format is subject
to change without notice or deprecation.
... full runtime configuration ...
... format subject to change ...
enable(bool: <required>) - Specifies whether to enable or disable
maintenance mode. This is specified as part of the URL as a query string
reason(string: "") - Specifies a text string explaining the reason for
placing the node into maintenance mode. This is simply to aid human operators.
If no reason is provided, a default value will be used instead. This is
specified as part of the URL as a query string parameter, and, as such, must
Since Consul 1.7.2 this endpoint will also automatically switch output format if
the request contains an Accept header with a compatible MIME type such as
application/openmetrics-text. Prometheus v2.5.0 and newer pass this header in scraping
queries, and so will get a compatible format by default. Older versions of Prometheus may
work by default as several previously used MIME types are also detected, but the ?format
query parameter may also be used to specify the output format manually if needed.
simplifying scrape configuration.
Note: If using the default format and your metric includes labels that use the same key
name multiple times (i.e. tag=tag2 and tag=tag1), only the sorted last value (tag=tag2)
will be visible on this endpoint due to a display issue. The complete label set is correctly
applied and passed to external metrics providers even though it is not visible through this
This endpoint triggers a graceful leave and shutdown of the agent. It is used to
ensure other nodes see the agent as "left" instead of "failed". Nodes that leave
will not attempt to re-join the cluster on restarting with a snapshot.
For nodes in server mode, the node is removed from the Raft peer set in a
graceful manner. This is critical, as in certain situations a non-graceful leave
can affect cluster availability.
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.
Additionally, by specifying the prune flag, a node can be forcibly removed from
the list of members entirely.
This endpoint updates the ACL tokens currently in use by the agent. It can be
used to introduce ACL tokens to the agent for the first time, or to update
tokens that were initially loaded from the agent's configuration. Tokens will be persisted
only if the acl.enable_token_persistence
configuration is true. When not being persisted, they will need to be reset if the agent