mirror of https://github.com/status-im/consul.git
56 lines
9.7 KiB
Plaintext
56 lines
9.7 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: Health check configuration reference
|
|
description: ->
|
|
Use the health checks to direct safety functions, such as removing failing nodes and replacing secondary services. Learn how to configure health checks.
|
|
---
|
|
|
|
# Health check configuration reference
|
|
|
|
This topic provides configuration reference information for health checks. For information about the different kinds of health checks and guidance on defining them, refer to [Define Health Checks].
|
|
|
|
## Introduction
|
|
Health checks perform several safety functions, such as allowing a web balancer to gracefully remove failing nodes and allowing a database to replace a failed secondary. You can configure health checks to monitor the health of the entire node. Refer to [Define Health Checks](/consul/docs/services/usage/checks) for information about how to define the different types of health checks available in Consul.
|
|
|
|
## Check block
|
|
Specify health check options in the `check` block. To register two or more heath checks in the same configuration, use the [`checks` block](#checks-block). The following table describes the configuration options contained in the `check` block.
|
|
|
|
| Parameter | Description | Check types |
|
|
| --- | --- | --- |
|
|
| `name` | Required string value that specifies the name of the check. Default is `service:<service-id>`. If multiple service checks are registered, the autogenerated default is appended with colon and incrementing number starting with `1`. | <li>Script </li> <li>HTTP </li> <li>TCP </li> <li>UDP </li> <li>OSService </li> <li>TTL </li> <li>Docker </li> <li>gRPC </li> <li>H2ping </li> <li>Alias </li> |
|
|
| `id` | A unique string value that specifies an ID for the check. Default to the `name` value. If `name` values conflict, specify a unique ID to avoid overwriting existing checks with same ID on the same node. Consul auto-generates an ID if the check is defined in a service definition file. | <li>Script </li> <li>HTTP </li> <li>TCP </li> <li>UDP </li> <li>OSService </li> <li>TTL </li> <li>Docker </li> <li>gRPC </li> <li>H2ping </li> <li>Alias </li> |
|
|
| `notes` | String value that provides a human-readable description of the check. The contents are not visible to Consul. | <li>Script </li> <li>HTTP </li> <li>TCP </li> <li>UDP </li> <li>OSService </li> <li>TTL </li> <li>Docker </li> <li>gRPC </li> <li>H2ping </li> <li>Alias </li> |
|
|
| `interval` | Required string value that specifies how frequently to run the check. The `interval` parameter is required for supported check types. The value is parsed by the golang [time package formatting specification](https://golang.org/pkg/time/#ParseDuration). | <li>Script </li> <li>HTTP </li> <li>TCP </li> <li>UDP </li> <li>OSService </li> <li>Docker </li> <li>gRPC </li> <li>H2ping</li> |
|
|
| `timeout` | String value that specifies how long unsuccessful requests take to end with a timeout. The `timeout` is optional for the supported check types and has the following defaults: <li> Script: `30s` </li> <li> HTTP: `10s` </li><li> TCP: `10s` </li><li> UDP: `10s` </li><li> gRPC: `10s` </li><li> H2ping: `10s` </li> | <li>Script </li> <li>HTTP </li> <li>TCP </li> <li>UDP </li> <li>gRPC </li> <li>H2ping </li> |
|
|
| `status` | Optional string value that specifies the initial status of the health check. You can specify the following values: <li>`critical` (default)</li><li>`warning`</li><li>`passing`</li> | <li>Script </li> <li>HTTP </li> <li>TCP </li> <li>UDP </li> <li>OSService </li> <li>TTL </li> <li>Docker </li> <li>gRPC </li> <li>H2ping </li> <li>Alias </li> |
|
|
| `deregister_critical_service_after` | String value that specifies how long a service and its associated checks are allowed to be in a `critical` state. Consul deregisters services if they are `critical` for the specified amount of time. The value is parsed by the golang [time package formatting specification](https://golang.org/pkg/time/#ParseDuration) | <li>Script </li> <li>HTTP </li> <li>TCP </li> <li>UDP </li> <li>OSService </li> <li>TTL </li> <li>Docker </li> <li>gRPC </li> <li>H2ping </li> <li>Alias </li> |
|
|
| `success_before_passing` | Integer value that specifies how many consecutive times the check must pass before Consul marks the service or node as `passing`. Default is `0`. | <li>Script </li> <li>HTTP </li> <li>TCP </li> <li>UDP </li> <li>OSService </li> <li>TTL </li> <li>Docker </li> <li>gRPC </li> <li>H2ping </li> <li>Alias </li> |
|
|
| `failures_before_warning` | Integer value that specifies how many consecutive times the check must fail before Consul marks the service or node as `warning`. The value cannot be more than `failures_before_critical`. Defaults to the value specified for `failures_before_critical`. | <li>Script </li> <li>HTTP </li> <li>TCP </li> <li>UDP </li> <li>OSService </li> <li>TTL </li> <li>Docker </li> <li>gRPC </li> <li>H2ping </li> <li>Alias </li> |
|
|
| `failures_before_critical` | Integer value that specifies how many consecutive times the check must fail before Consul marks the service or node as `critical`. Default is `0`. | <li>Script </li> <li>HTTP </li> <li>TCP </li> <li>UDP </li> <li>OSService </li> <li>TTL </li> <li>Docker </li> <li>gRPC </li> <li>H2ping </li> <li>Alias </li> |
|
|
| `args` | Specifies a list of arguments strings to pass to the command line. The list of values includes the path to a script file or external application to invoke and any additional parameters for running the script or application. | <li> Script </li><li> Docker </li> |
|
|
| `docker_container_id` | Specifies the Docker container ID in which to run an external health check application. Specify the external application with the `args` parameter. | <li> Docker </li> |
|
|
| `shell` | String value that specifies the type of command line shell to use for running the health check application. Specify the external application with the `args` parameter. | <li> Docker </li> |
|
|
| `grpc` | String value that specifies the gRPC endpoint, including port number, to send requests to. Append the endpoint with `:/` and a service identifier to check a specific service. The endpoint must support the [gRPC health checking protocol](https://github.com/grpc/grpc/blob/master/doc/health-checking.md). | <li>gRPC </li>|
|
|
| `grpc_use_tls` | Boolean value that enables TLS for gRPC checks when set to `true`. | <li>gRPC </li> |
|
|
| `h2ping` | String value that specifies the HTTP2 endpoint, including port number, to send HTTP2 requests to. | <li>H2ping</li> |
|
|
| `h2ping_use_tls` | Boolean value that enables TLS for H2ping checks when set to `true`. | <li>H2ping</li> |
|
|
| `http` | String value that specifies an HTTP endpoint to send requests to. | <li>HTTP</li> |
|
|
| `tls_server_name` | String value that specifies the server name used to verify the hostname on the returned certificates unless `tls_skip_verify` is given. Also included in the client's handshake to support SNI. It is recommended that this field be left unspecified. The TLS client will deduce the server name for SNI from the check address unless it's an IP ([RFC 6066, Section 3](https://tools.ietf.org/html/rfc6066#section-3)). There are two common circumstances where supplying a `tls_server_name` can be beneficial: <li>When the check address is an IP, `tls_server_name` can be specified for SNI. Note: setting `tls_server_name` will also override the hostname used to verify the certificate presented by the server being checked.</li><li>When the hostname in the check address won't be present in the SAN (Subject Alternative Name) field of the certificate presented by the server being checked. Note: setting `tls_server_name` will also override the hostname used for SNI.</li> | <li>HTTP </li> <li>H2Ping </li> <li>gRPC </li> |
|
|
| `tls_skip_verify` | Boolean value that determines if the check verifies the chain and hostname of the certificate that the server presents. Set to `true` to disable verification. We recommend setting to `false` for production use. Default is `false`. | <li>HTTP </li> <li>H2Ping </li> <li>gRPC </li> <li>TCP </li> |
|
|
| `method` | String value that specifies the request method to send during HTTP checks. Default is `GET`. | <li>HTTP</li> |
|
|
| `header` | Object that specifies header fields to send in HTTP check requests. Each header specified in `header` object contains a list of string values. | <li>HTTP</li> |
|
|
| `body` | String value that contains JSON attributes to send in HTTP check requests. You must escape the quotation marks around the keys and values for each attribute. | <li>HTTP</li> |
|
|
| `disable_redirects` | Boolean value that prevents HTTP checks from following redirects if set to `true`. Default is `false`. | <li>HTTP</li> |
|
|
| `os_service` | String value that specifies the name of the name of a service to check during an OSService check. | <li>OSService</li> |
|
|
| `service_id` | String value that specifies the ID of a service instance to associate with an OSService check. That service instance must be on the same node as the check. If not specified, the check verifies the health of the node. | <li>OSService</li> |
|
|
| `tcp` | String value that specifies an IP address or host and port number for the check establish a TCP connection with. | <li>TCP</li> |
|
|
| `tcp_use_tls` | Boolean value that enables TLS for TCP checks when set to `true`. | <li>TCP </li> |
|
|
| `udp` | String value that specifies an IP address or host and port number for the check to send UDP datagrams to. | <li>UDP</li> |
|
|
| `ttl` | String value that specifies how long to wait for an update from an external process during a TTL check. | <li>TTL</li> |
|
|
| `alias_service` | String value that specifies a service or node that the service associated with the health check aliases. | <li>Alias</li> |
|
|
|
|
|
|
|
|
## Checks block
|
|
You can define multiple health checks in a single `checks` block. The `checks` block is an array of objects that contain the configuration options described in the [`check` block configuration reference](#check-block).
|