Consul
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 for information about how to define the differnet 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. 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. | |
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. | |
notes | String value that provides a human-readabiole description of the check. The contents are not visible to Consul. | |
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. | |
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: 30s 10s 10s 10s 10s 10s | |
status | Optional string value that specifies the initial status of the health check. You can specify the following values: critical (default)warningpassing | |
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 | |
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. | |
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. | |
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. | |
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. | |
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. | |
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. | |
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. | |
grpc_use_tls | Boolean value that enables TLS for gRPC checks when set to true. | |
h2ping | String value that specifies the HTTP2 endpoint, including port number, to send HTTP2 requests to. | |
h2ping_use_tls | Boolean value that enables TLS for H2ping checks when set to true. | |
http | String value that specifies an HTTP endpoint to send requests to. | |
tls_server_name | String value that specifies the name of the TLS server that issues certificates. Defaults to the SNI determined by the address specified in the http field. Set the tls_skip_verify to false to disable this field. | |
tls_skip_verify | Boolean value that disbles TLS for HTTP checks when set to true. Default is false. | |
method | String value that specifies the request method to send during HTTP checks. Default is GET. | |
header | Object that specifies header fields to send in HTTP check requests. Each header specified in header object contains a list of string values. | |
body | String value that contains JSON attributes to send in HTTP check requests. You must escap the quotation marks around the keys and values for each attribute. | |
disable_redirects | Boolean value that prevents HTTP checks from following redirects if set to true. Default is false. | |
os_service | String value that specifies the name of the name of a service to check during an OSService check. | |
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. | |
tcp | String value that specifies an IP address or host and port number for the check establish a TCP connection with. | |
udp | String value that specifies an IP address or host and port number for the check to send UDP datagrams to. | |
ttl | String value that specifies how long to wait for an update from an external process during a TTL check. | |
alias_service | String value that specifies a service or node that the service associated with the health check aliases. |
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.