Merge pull request #678 from ryanbreen/agent
Cleanup for docs/agent/http/agent.
This commit is contained in:
Armon Dadgar
commit
07618766a8
|
|
@ -3,41 +3,41 @@ layout: "docs"
|
|||
page_title: "Agent (HTTP)"
|
||||
sidebar_current: "docs-agent-http-agent"
|
||||
description: >
|
||||
The Agent endpoints are used to interact with a local Consul agent.
|
||||
The Agent endpoints are used to interact with the local Consul agent.
|
||||
---
|
||||
|
||||
# Agent HTTP Endpoint
|
||||
|
||||
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. There are also various control APIs that can be used instead of the
|
||||
msgpack RPC protocol.
|
||||
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.
|
||||
|
||||
The following endpoints are supported:
|
||||
|
||||
* [`/v1/agent/checks`](#agent_checks) : Returns the checks the local agent is managing
|
||||
* [`/v1/agent/services`](#agent_services) : Returns the services local agent is managing
|
||||
* [`/v1/agent/services`](#agent_services) : Returns the services the local agent is managing
|
||||
* [`/v1/agent/members`](#agent_members) : Returns the members as seen by the local serf agent
|
||||
* [`/v1/agent/self`](#agent_self) : Returns the local node configuration
|
||||
* [`/v1/agent/maintenance`](#agent_maintenance) : Node maintenance mode
|
||||
* [`/v1/agent/join/<address>`](#agent_join) : Trigger local agent to join a node
|
||||
* [`/v1/agent/force-leave/<node>`](#agent_force_leave)>: Force remove node
|
||||
* [`/v1/agent/maintenance`](#agent_maintenance) : Manages node maintenance mode
|
||||
* [`/v1/agent/join/<address>`](#agent_join) : Triggers the local agent to join a node
|
||||
* [`/v1/agent/force-leave/<node>`](#agent_force_leave)>: Forces removal of a node
|
||||
* [`/v1/agent/check/register`](#agent_check_register) : Registers a new local check
|
||||
* [`/v1/agent/check/deregister/<checkID>`](#agent_check_deregister) : Deregister a local check
|
||||
* [`/v1/agent/check/pass/<checkID>`](#agent_check_pass) : Mark a local test as passing
|
||||
* [`/v1/agent/check/warn/<checkID>`](#agent_check_warn) : Mark a local test as warning
|
||||
* [`/v1/agent/check/fail/<checkID>`](#agent_check_fail) : Mark a local test as critical
|
||||
* [`/v1/agent/check/deregister/<checkID>`](#agent_check_deregister) : Deregisters a local check
|
||||
* [`/v1/agent/check/pass/<checkID>`](#agent_check_pass) : Marks a local test as passing
|
||||
* [`/v1/agent/check/warn/<checkID>`](#agent_check_warn) : Marks a local test as warning
|
||||
* [`/v1/agent/check/fail/<checkID>`](#agent_check_fail) : Marks a local test as critical
|
||||
* [`/v1/agent/service/register`](#agent_service_register) : Registers a new local service
|
||||
* [`/v1/agent/service/deregister/<serviceID>`](#agent_service_deregister) : Deregister a local service
|
||||
* [`/v1/agent/service/maintenance/<serviceID>`](#agent_service_maintenance) : Service maintenance mode
|
||||
* [`/v1/agent/service/deregister/<serviceID>`](#agent_service_deregister) : Deregisters a local service
|
||||
* [`/v1/agent/service/maintenance/<serviceID>`](#agent_service_maintenance) : Manages service maintenance mode
|
||||
|
||||
### <a name="agent_checks"></a> /v1/agent/checks
|
||||
|
||||
This endpoint is used to return the all the checks that are registered with
|
||||
the local agent. These checks were either provided through configuration files,
|
||||
This endpoint is used to return 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
|
||||
known by the agent may be different from 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.
|
||||
|
||||
|
|
@ -61,9 +61,9 @@ This endpoint is hit with a GET and returns a JSON body like this:
|
|||
### <a name="agent_services"></a> /v1/agent/services
|
||||
|
||||
This endpoint is used to return the all the services that are registered with
|
||||
the local agent. These services were either provided through configuration files,
|
||||
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
|
||||
known by the agent may be different from 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.
|
||||
|
||||
|
|
@ -83,15 +83,15 @@ This endpoint is hit with a GET and returns a JSON body like this:
|
|||
|
||||
### <a name="agent_members"></a> /v1/agent/members
|
||||
|
||||
This endpoint is hit with a GET and 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
|
||||
This endpoint is used to return 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 "/v1/catalog/nodes".
|
||||
|
||||
For agents running in server mode, providing a "?wan=1" query parameter returns
|
||||
the list of WAN members instead of the LAN members which is default.
|
||||
the list of WAN members instead of the LAN members returned by default.
|
||||
|
||||
This endpoint returns a JSON body like:
|
||||
This endpoint is hit with a GET and returns a JSON body like:
|
||||
|
||||
```javascript
|
||||
[
|
||||
|
|
@ -118,7 +118,7 @@ This endpoint returns a JSON body like:
|
|||
|
||||
### <a name="agent_self"></a> /v1/agent/self
|
||||
|
||||
This endpoint is used to return configuration of the local agent and member information.
|
||||
This endpoint is used to return the configuration and member information of the local agent.
|
||||
|
||||
It returns a JSON body like this:
|
||||
|
||||
|
|
@ -187,17 +187,17 @@ It returns a JSON body like this:
|
|||
|
||||
### <a name="agent_maintenance"></a> /v1/agent/maintenance
|
||||
|
||||
The node maintenance endpoint allows placing the agent into "maintenance mode".
|
||||
During maintenance mode, the node will be marked as unavailable, and will not be
|
||||
The node maintenance endpoint can place the agent into "maintenance mode".
|
||||
During maintenance mode, the node will be marked as unavailable and will not be
|
||||
present in DNS or API queries. This API call is idempotent. Maintenance mode is
|
||||
persistent and will be automatically restored on agent restart.
|
||||
|
||||
The `?enable` flag is required, and its value must be `true` (to enter
|
||||
maintenance mode), or `false` (to resume normal operation).
|
||||
The `?enable` flag is required. Acceptable values are either `true` (to enter
|
||||
maintenance mode) or `false` (to resume normal operation).
|
||||
|
||||
The `?reason` flag is optional, and can contain a text string explaining the
|
||||
reason for placing the node into maintenance mode. If no reason is provided,
|
||||
a default value will be used instead.
|
||||
The `?reason` flag is optional. If provided, its value should be 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.
|
||||
|
||||
The return code is 200 on success.
|
||||
|
||||
|
|
@ -207,14 +207,14 @@ 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, providing a "?wan=1"
|
||||
query parameter causes the agent to attempt to join using the WAN pool.
|
||||
|
||||
The endpoint returns 200 on successful join.
|
||||
The return code is 200 on success.
|
||||
|
||||
### <a name="agent_force_leave"></a> /v1/agent/force-leave/\<node\>
|
||||
|
||||
This endpoint is hit with a GET and is used to 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.
|
||||
This endpoint is hit with a GET and is used to instruct 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.
|
||||
|
||||
The endpoint always returns 200.
|
||||
|
||||
|
|
@ -222,7 +222,7 @@ The endpoint always returns 200.
|
|||
|
||||
The register endpoint is used to add a new check to the local agent.
|
||||
There is more documentation on checks [here](/docs/agent/checks.html).
|
||||
Checks are of script, HTTP, or TTL type. The agent is responsible for managing
|
||||
Checks may be of script, HTTP, or TTL type. The agent is responsible for managing
|
||||
the status of the check and keeping the Catalog in sync.
|
||||
|
||||
The register endpoint expects a JSON request body to be PUT. The request
|
||||
|
|
@ -244,66 +244,69 @@ The `Name` field is mandatory, as is one of `Script`, `HTTP` or `TTL`.
|
|||
`Script` and `HTTP` also require that `Interval` be set.
|
||||
|
||||
If an `ID` is not provided, it is set to `Name`. You cannot have duplicate
|
||||
`ID` entries per agent, so it may be necessary to provide an ID. The `Notes`
|
||||
field is not used by Consul, and is meant to be human readable.
|
||||
`ID` entries per agent, so it may be necessary to provide an `ID`.
|
||||
|
||||
The `Notes` field is not used internally 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.
|
||||
|
||||
An `HTTP` check will perform an HTTP GET request to the value of `HTTP` (expected to be a URL) every `Interval`. If the response is any `2xx` code the check is passing, if the response is `429 Too Many Requests` the check is warning, otherwise the check is critical.
|
||||
An `HTTP` check will perform an HTTP GET request against the value of `HTTP` (expected to
|
||||
be a URL) every `Interval`. If the response is any `2xx` code, the check is `passing`.
|
||||
If the response is `429 Too Many Requests`, the check is `warning`. Otherwise, the check
|
||||
is `critical`.
|
||||
|
||||
If a `TTL` type is used, then the TTL update APIs must be used to periodically update
|
||||
If a `TTL` type is used, then the TTL update endpoint must be used periodically to update
|
||||
the state of the check.
|
||||
|
||||
The return code is 200 on success.
|
||||
|
||||
### <a name="agent_check_deregister"></a> /v1/agent/check/deregister/\<checkId\>
|
||||
|
||||
The deregister endpoint is used to remove a check from the local agent.
|
||||
The CheckID must be passed after the slash. The agent will take care
|
||||
of deregistering the check with the Catalog.
|
||||
This endpoint is used to remove a check from the local agent.
|
||||
The `CheckID` must be passed on the path. The agent will take care
|
||||
of deregistering the check from the Catalog.
|
||||
|
||||
The return code is 200 on success.
|
||||
|
||||
### <a name="agent_check_pass"></a> /v1/agent/check/pass/\<checkId\>
|
||||
|
||||
This endpoint is used with a check that is of the [TTL type](/docs/agent/checks.html).
|
||||
When this endpoint is accessed via a GET, the status of the check is set to "passing",
|
||||
When this endpoint is accessed via a GET, the status of the check is set to `passing`
|
||||
and the TTL clock is reset.
|
||||
|
||||
The optional "?note=" query parameter can be used to associate output with
|
||||
the status of the check. This should be human readable for operators.
|
||||
The optional "?note=" query parameter can be used to associate a human-readable message
|
||||
with the status of the check.
|
||||
|
||||
The return code is 200 on success.
|
||||
|
||||
### <a name="agent_check_warn"></a> /v1/agent/check/warn/\<checkId\>
|
||||
|
||||
This endpoint is used with a check that is of the [TTL type](/docs/agent/checks.html).
|
||||
When this endpoint is accessed via a GET, the status of the check is set to "warning",
|
||||
When this endpoint is accessed via a GET, the status of the check is set to `warning`,
|
||||
and the TTL clock is reset.
|
||||
|
||||
The optional "?note=" query parameter can be used to associate output with
|
||||
the status of the check. This should be human readable for operators.
|
||||
The optional "?note=" query parameter can be used to associate a human-readable message
|
||||
with the status of the check.
|
||||
|
||||
The return code is 200 on success.
|
||||
|
||||
### <a name="agent_check_fail"></a> /v1/agent/check/fail/\<checkId\>
|
||||
|
||||
This endpoint is used with a check that is of the [TTL type](/docs/agent/checks.html).
|
||||
When this endpoint is accessed via a GET, the status of the check is set to "critical",
|
||||
When this endpoint is accessed via a GET, the status of the check is set to `critical`,
|
||||
and the TTL clock is reset.
|
||||
|
||||
The optional "?note=" query parameter can be used to associate output with
|
||||
the status of the check. This should be human readable for operators.
|
||||
The optional "?note=" query parameter can be used to associate a human-readable message
|
||||
with the status of the check.
|
||||
|
||||
The return code is 200 on success.
|
||||
|
||||
### <a name="agent_service_register"></a> /v1/agent/service/register
|
||||
|
||||
The register endpoint is used to add a new service to the local agent.
|
||||
There is more documentation on services [here](/docs/agent/services.html).
|
||||
Services may also provide a health check. The agent is responsible for managing
|
||||
the status of the check and keeping the Catalog in sync.
|
||||
The register endpoint is used to add a new service, with an optional health check,
|
||||
to the local agent. There is more documentation on services [here](/docs/agent/services.html).
|
||||
The agent is responsible for managing the status of the service and keeping the Catalog in sync.
|
||||
|
||||
The register endpoint expects a JSON request body to be PUT. The request
|
||||
body must look like:
|
||||
|
|
@ -328,14 +331,16 @@ body must look like:
|
|||
```
|
||||
|
||||
The `Name` field is mandatory, If an `ID` is not provided, it is set to `Name`.
|
||||
You cannot have duplicate `ID` entries per agent, so it may be necessary to provide an ID.
|
||||
`Tags`, `Address`, `Port` and `Check` are optional.
|
||||
If `Check` is provided, only one of `Script`, `HTTP` or `TTL` should be provided.
|
||||
`Script` and `HTTP` also require `Interval`.
|
||||
There is more information about checks [here](/docs/agent/checks.html).
|
||||
The `Address` will default to that of the agent if not provided.
|
||||
You cannot have duplicate `ID` entries per agent, so it may be necessary to provide an ID
|
||||
in the case of a collision.
|
||||
|
||||
The created check will be named "service:\<ServiceId\>".
|
||||
`Tags`, `Address`, `Port` and `Check` are optional.
|
||||
|
||||
`Address` will default to that of the agent if not provided.
|
||||
|
||||
If `Check` is provided, only one of `Script`, `HTTP`, or `TTL` should be specified.
|
||||
`Script` and `HTTP` also require `Interval`. The created check will be named "service:\<ServiceId\>".
|
||||
There is more information about checks [here](/docs/agent/checks.html).
|
||||
|
||||
The return code is 200 on success.
|
||||
|
||||
|
|
@ -352,15 +357,15 @@ The return code is 200 on success.
|
|||
|
||||
The service maintenance endpoint allows placing a given service into
|
||||
"maintenance mode". During maintenance mode, the service will be marked as
|
||||
unavailable, and will not be present in DNS or API queries. This API call is
|
||||
unavailable and will not be present in DNS or API queries. This API call is
|
||||
idempotent. Maintenance mode is persistent and will be automatically restored
|
||||
on agent restart.
|
||||
|
||||
The `?enable` flag is required, and its value must be `true` (to enter
|
||||
maintenance mode), or `false` (to resume normal operation).
|
||||
The `?enable` flag is required. Acceptable values are either `true` (to enter
|
||||
maintenance mode) or `false` (to resume normal operation).
|
||||
|
||||
The `?reason` flag is optional, and can contain a text string explaining the
|
||||
reason for placing the service into maintenance mode. If no reason is provided,
|
||||
a default value will be used instead.
|
||||
The `?reason` flag is optional. If provided, its value should be a text string
|
||||
explaining the reason for placing the service into maintenance mode. This is simply
|
||||
to aid human operators. If no reason is provided, a default value will be used instead.
|
||||
|
||||
The return code is 200 on success.
|
||||
|
|
|
|||
Loading…
Reference in New Issue