luxolus
/
open-consul
2
0
Fork 0
Code Issues 1 Pull Requests Packages Releases Wiki Activity
open-consul/website/content/api-docs/agent/check.mdx

534 lines
22 KiB
Plaintext
Raw Blame History

---
layout: api
page_title: Check - Agent - HTTP API
description: The /agent/check endpoints interact with checks on the local agent in Consul.
---
# Check - Agent HTTP API
Consul's health check capabilities are described in the
[health checks overview](/docs/discovery/checks).
The `/agent/check` endpoints interact with health checks
managed by the local agent in Consul.
These should not be confused with checks in the catalog.
## List Checks
This endpoint returns all 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 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](/docs/architecture/anti-entropy), so in most situations
everything will be in sync within a few seconds.
@include 'http_api_results_filtered_by_acls.mdx'
| Method | Path | Produces |
| ------ | --------------- | ------------------ |
| `GET` | `/agent/checks` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
[required ACLs](/api-docs#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | ------------------------ |
| `NO` | `none` | `none` | `node:read,service:read` |
### Query Parameters
- `filter` `(string: "")` - Specifies the expression used to filter the
queries results prior to returning the data.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Return only the checks in the specified namespace.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### Sample Request
```shell-session
$ curl \
http://127.0.0.1:8500/v1/agent/checks
```
### Sample Response
```json
{
"service:redis": {
"Node": "foobar",
"CheckID": "service:redis",
"Name": "Service 'redis' check",
"Status": "passing",
"Notes": "",
"Output": "",
"ServiceID": "redis",
"ServiceName": "redis",
"ServiceTags": ["primary"],
"Interval": "10s",
"Timeout": "1s"
"Type": "tcp",
"ExposedPort": 0,
"Definition": {},
"Namespace": "default",
"CreateIndex": 0,
"ModifyIndex": 0
}
}
```
### Filtering
The filter will be executed against each health check value in the results map with
the following selectors and filter operations being supported:
| Selector | Supported Operations |
| ------------- | -------------------------------------------------- |
| `CheckID` | Equal, Not Equal, In, Not In, Matches, Not Matches |
| `Name` | Equal, Not Equal, In, Not In, Matches, Not Matches |
| `Node` | Equal, Not Equal, In, Not In, Matches, Not Matches |
| `Notes` | Equal, Not Equal, In, Not In, Matches, Not Matches |
| `Output` | Equal, Not Equal, In, Not In, Matches, Not Matches |
| `ServiceID` | Equal, Not Equal, In, Not In, Matches, Not Matches |
| `ServiceName` | Equal, Not Equal, In, Not In, Matches, Not Matches |
| `ServiceTags` | In, Not In, Is Empty, Is Not Empty |
| `Status` | Equal, Not Equal, In, Not In, Matches, Not Matches |
## Register Check
This endpoint adds a new check to the local agent. Checks may be of script,
HTTP, TCP, UDP, or TTL type. The agent is responsible for managing the status of the
check and keeping the Catalog in sync.
| Method | Path | Produces |
| ------ | ----------------------- | ------------------ |
| `PUT` | `/agent/check/register` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
[required ACLs](/api-docs#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | -------------------------- |
| `NO` | `none` | `none` | `node:write,service:write` |
### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the check you register.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### JSON Request Body Schema
- `Name` `(string: <required>)` - Specifies the name of the check.
- `ID` `(string: "")` - Specifies a unique ID for this check on the node.
This defaults to the `"Name"` parameter, but it may be necessary to provide an
ID for uniqueness. This value will return in the response as `"CheckId"`.
- `Namespace` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the check you register.
This field takes precedence over the `ns` query parameter,
one of several [other methods to specify the namespace](#methods-to-specify-namespace).
- `Interval` `(string: "")` - Specifies the frequency at which to run this
check. This is required for HTTP, TCP, and UDP checks.
- `Notes` `(string: "")` - Specifies arbitrary information for humans. This is
not used by Consul internally.
- `DeregisterCriticalServiceAfter` `(string: "")` - Specifies that checks
associated with a service should deregister after this time. This is specified
as a time duration with suffix like "10m". If a check is in the critical state
for more than this configured value, then its associated service (and all of
its associated checks) will automatically be deregistered. The minimum timeout
is 1 minute, and the process that reaps critical services runs every 30
seconds, so it may take slightly longer than the configured timeout to trigger
the deregistration. This should generally be configured with a timeout that's
much, much longer than any expected recoverable outage for the given service.
- `Args` `(array<string>)` - Specifies command arguments to run to update the
status of the check. Prior to Consul 1.0, checks used a single `Script` field
to define the command to run, and would always run in a shell. In Consul
1.0, the `Args` array was added so that checks can be run without a shell. The
`Script` field is deprecated, and you should include the shell in the `Args` to
run under a shell, eg. `"args": ["sh", "-c", "..."]`.
-> **Note:** Consul 1.0 shipped with an issue where `Args` was erroneously named
`ScriptArgs` in this API. Please use `ScriptArgs` with Consul 1.0 (that will
continue to be accepted in future versions of Consul), and `Args` in Consul
1.0.1 and later.
- `AliasNode` `(string: "")` - Specifies the ID of the node for an alias check.
If no service is specified, the check will alias the health of the node.
If a service is specified, the check will alias the specified service on
this particular node.
- `AliasService` `(string: "")` - Specifies the ID of a service for an
alias check. If the service is not registered with the same agent,
`AliasNode` must also be specified. Note this is the service _ID_ and
not the service _name_ (though they are very often the same).
- `DockerContainerID` `(string: "")` - Specifies that the check is a Docker
check, and Consul will evaluate the script every `Interval` in the given
container using the specified `Shell`. Note that `Shell` is currently only
supported for Docker checks.
- `GRPC` `(string: "")` - Specifies a `gRPC` check's endpoint that supports the standard
[gRPC health checking protocol](https://github.com/grpc/grpc/blob/master/doc/health-checking.md).
The state of the check will be updated at the given `Interval` by probing the configured
endpoint. Add the service identifier after the `gRPC` check's endpoint in the following format to check for a specific service instead of the whole gRPC server `/:service_identifier`.
- `GRPCUseTLS` `(bool: false)` - Specifies whether to use TLS for this `gRPC` health check.
If TLS is enabled, then by default, a valid TLS certificate is expected. Certificate
verification can be turned off by setting `TLSSkipVerify` to `true`.
- `H2PING` `(string "")` - Specifies an address that uses http2 to run a ping check on.
At the specified `Interval`, a connection is made to the address, and a ping is sent.
If the ping is successful, the check will be classified as `passing`, otherwise it will be marked as `critical`.
TLS is used by default. To disable TLS and use h2c, set `H2PingUseTLS` to `false`.
If TLS is enabled, a valid SSL certificate is required by default, but verification can be removed with `TLSSkipVerify`.
- `H2PingUseTLS` `(bool: true)` - Specifies if TLS should be used for H2PING check.
If TLS is enabled, a valid SSL certificate is required by default, but verification can be removed with `TLSSkipVerify`.
- `HTTP` `(string: "")` - Specifies an `HTTP` check to perform a `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`. HTTP checks also support SSL. By default, a valid SSL certificate
is expected. Certificate verification can be controlled using the
`TLSSkipVerify`.
- `Method` `(string: "")` - Specifies a different HTTP method to be used
for an `HTTP` check. When no value is specified, `GET` is used.
- `Body` `(string: "")` - Specifies a body that should be sent with `HTTP` checks.
- `DisableRedirects` `(bool: false)` - Specifies whether to disable following HTTP
redirects when performing an HTTP check.
- `Header` `(map[string][]string: {})` - Specifies a set of headers that should
be set for `HTTP` checks. Each header can have multiple values.
- `Timeout` `(duration: 10s)` - Specifies a timeout for outgoing connections in the
case of a Script, HTTP, TCP, UDP, or gRPC check. Can be specified in the form of "10s"
or "5m" (i.e., 10 seconds or 5 minutes, respectively).
- `OutputMaxSize` `(positive int: 4096)` - Allow to put a maximum size of text
for the given check. This value must be greater than 0, by default, the value
is 4k.
The value can be further limited for all checks of a given agent using the
`check_output_max_size` flag in the agent.
- `TLSServerName` `(string: "")` - Specifies an optional string used to set the
SNI host when connecting via TLS.
For an `HTTP` check, this value is set automatically if the URL uses a hostname
(not an IP address).
- `TLSSkipVerify` `(bool: false)` - Specifies if the certificate for an HTTPS
check should not be verified.
- `TCP` `(string: "")` - Specifies a `TCP` to connect against the value of `TCP`
(expected to be an IP or hostname plus port combination) every `Interval`. If
the connection attempt is successful, the check is `passing`. If the
connection attempt is unsuccessful, the check is `critical`. In the case of a
hostname that resolves to both IPv4 and IPv6 addresses, an attempt will be
made to both addresses, and the first successful connection attempt will
result in a successful check.
- `UDP` `(string: "")` - Specifies a `UDP` IP address/hostname and port.
The check sends datagrams to the value specified at the interval specified in the `Interval` configuration.
If the datagram is sent successfully or a timeout is returned, the check is set to the `passing` state.
The check is logged as `critical` if the datagram is sent unsuccessfully.
- `OSService` `(string: "")` - Specifies the identifier of an OS-level service to check. You can specify either `Windows Services` on Windows or `SystemD` services on Unix.
- `TTL` `(duration: 10s)` - Specifies this is a TTL check, and the TTL endpoint
must be used periodically to update the state of the check. If the check is not
set to passing within the specified duration, then the check will be set to the failed state.
- `ServiceID` `(string: "")` - Specifies the ID of a service to associate the
registered check with an existing service provided by the agent.
- `Status` `(string: "")` - Specifies the initial status of the health check.
- `SuccessBeforePassing` `(int: 0)` - Specifies the number of consecutive successful
results required before check status transitions to passing. Available for HTTP,
TCP, gRPC, Docker & Monitor checks. Added in Consul 1.7.0.
- `FailuresBeforeWarning` `(int: 0)` - Specifies the number of consecutive unsuccessful
results required before check status transitions to warning. Defaults to the same value
as `FailuresBeforeCritical`. Values higher than `FailuresBeforeCritical` are invalid.
Available for HTTP, TCP, gRPC, Docker & Monitor checks. Added in Consul 1.11.0.
- `FailuresBeforeCritical` `(int: 0)` - Specifies the number of consecutive unsuccessful
results required before check status transitions to critical. Available for HTTP,
TCP, gRPC, Docker & Monitor checks. Added in Consul 1.7.0.
### Sample Payload
```json
{
"ID": "mem",
"Name": "Memory utilization",
"Namespace": "default",
"Notes": "Ensure we don't oversubscribe memory",
"DeregisterCriticalServiceAfter": "90m",
"Args": ["/usr/local/bin/check_mem.py"],
"DockerContainerID": "f972c95ebf0e",
"Shell": "/bin/bash",
"HTTP": "https://example.com",
"Method": "POST",
"Header": { "Content-Type": ["application/json"] },
"Body": "{\"check\":\"mem\"}",
"DisableRedirects": true,
"TCP": "example.com:22",
"Interval": "10s",
"Timeout": "5s",
"TLSSkipVerify": true
}
```
### Sample Request
```shell-session
$ curl \
--request PUT \
--data @payload.json \
http://127.0.0.1:8500/v1/agent/check/register
```
## Deregister Check
This endpoint remove a check from the local agent. The agent will take care of
deregistering the check from the catalog. If the check with the provided ID does
not exist, no action is taken.
| Method | Path | Produces |
| ------ | ----------------------------------- | ------------------ |
| `PUT` | `/agent/check/deregister/:check_id` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
[required ACLs](/api-docs#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | -------------------------- |
| `NO` | `none` | `none` | `node:write,service:write` |
### Path Parameters
- `check_id` `(string: "")` - Specifies the unique ID of the check to deregister.
### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the check you deregister.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### Sample Request
```shell-session
$ curl \
--request PUT \
http://127.0.0.1:8500/v1/agent/check/deregister/my-check-id
```
## TTL Check Pass
This endpoint is used with a TTL type check to set the status of the check to
`passing` and to reset the TTL clock.
| Method | Path | Produces |
| ------ | ----------------------------- | ------------------ |
| `PUT` | `/agent/check/pass/:check_id` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
[required ACLs](/api-docs#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | -------------------------- |
| `NO` | `none` | `none` | `node:write,service:write` |
### Path Parameters
- `check_id` `(string: "")` - Specifies the unique ID of the check to use.
### Query Parameters
- `note` `(string: "")` - Specifies a human-readable message. This will be
passed through to the check's `Output` field.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the check you update.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### Sample Request
```shell-session
$ curl \
--request PUT \
http://127.0.0.1:8500/v1/agent/check/pass/my-check-id
```
## TTL Check Warn
This endpoint is used with a TTL type check to set the status of the check to
`warning` and to reset the TTL clock.
| Method | Path | Produces |
| ------ | ----------------------------- | ------------------ |
| `PUT` | `/agent/check/warn/:check_id` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
[required ACLs](/api-docs#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | -------------------------- |
| `NO` | `none` | `none` | `node:write,service:write` |
### Path Parameters
- `check_id` `(string: "")` - Specifies the unique ID of the check to use.
### Query Parameters
- `note` `(string: "")` - Specifies a human-readable message. This will be
passed through to the check's `Output` field.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the check you update.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### Sample Request
```shell-session
$ curl \
http://127.0.0.1:8500/v1/agent/check/warn/my-check-id
```
## TTL Check Fail
This endpoint is used with a TTL type check to set the status of the check to
`critical` and to reset the TTL clock.
If you want to manually mark a service as unhealthy,
use [maintenance mode](/api-docs/agent#enable-maintenance-mode)
instead of defining a TTL health check and using this endpoint.
| Method | Path | Produces |
| ------ | ----------------------------- | ------------------ |
| `PUT` | `/agent/check/fail/:check_id` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
[required ACLs](/api-docs#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | -------------------------- |
| `NO` | `none` | `none` | `node:write,service:write` |
### Path Parameters
- `check_id` `(string: "")` - Specifies the unique ID of the check to use.
### Query Parameters
- `note` `(string: "")` - Specifies a human-readable message. This will be
passed through to the check's `Output` field.
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the check you update.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### Sample Request
```shell-session
$ curl \
http://127.0.0.1:8500/v1/agent/check/fail/my-check-id
```
## TTL Check Update
This endpoint is used with a TTL type check to set the status of the check and
to reset the TTL clock.
If you want to manually mark a service as unhealthy,
use [maintenance mode](/api-docs/agent#enable-maintenance-mode)
instead of defining a TTL health check and using this endpoint.
| Method | Path | Produces |
| ------ | ------------------------------- | ------------------ |
| `PUT` | `/agent/check/update/:check_id` | `application/json` |
The table below shows this endpoint's support for
[blocking queries](/api-docs/features/blocking),
[consistency modes](/api-docs/features/consistency),
[agent caching](/api-docs/features/caching), and
[required ACLs](/api-docs#authentication).
| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
| ---------------- | ----------------- | ------------- | -------------------------- |
| `NO` | `none` | `none` | `node:write,service:write` |
### Path Parameters
- `check_id` `(string: "")` - Specifies the unique ID of the check to use.
### Query Parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - Specifies the namespace of the check you update.
You can also [specify the namespace through other methods](#methods-to-specify-namespace).
### JSON Request Body Schema
- `Status` `(string: "")` - Specifies the status of the check. Valid values are
`"passing"`, `"warning"`, and `"critical"`.
- `Output` `(string: "")` - Specifies a human-readable message. This will be
passed through to the check's `Output` field.
<!-- Are we missing a Namespace field here? -->
### Sample Payload
```json
{
"Status": "passing",
"Output": "curl reported a failure:\n\n..."
}
```
### Sample Request
```shell-session
$ curl \
--request PUT \
--data @payload.json \
http://127.0.0.1:8500/v1/agent/check/update/my-check-id
```
## Methods to Specify Namespace <EnterpriseAlert inline />
Local agent health check endpoints
support several methods for specifying the namespace of the check resources
with the following order of precedence:
1. `Namespace` field of the JSON request body -
only applies to the [register](#register-check) endpoint
1. `ns` query parameter
1. `X-Consul-Namespace` request header
1. Namespace is inherited from the namespace of the request's ACL token (if any)
1. The `default` namespace
Reference in New Issue View Git Blame Copy Permalink