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 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. 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`.	Script HTTP TCP UDP OSService TTL Docker gRPC H2ping Alias
`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.	Script HTTP TCP UDP OSService TTL Docker gRPC H2ping Alias
`notes`	String value that provides a human-readable description of the check. The contents are not visible to Consul.	Script HTTP TCP UDP OSService TTL Docker gRPC H2ping Alias
`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.	Script HTTP TCP UDP OSService Docker gRPC H2ping
`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: Script: `30s` HTTP: `10s` TCP: `10s` UDP: `10s` gRPC: `10s` H2ping: `10s`	Script HTTP TCP UDP gRPC H2ping
`status`	Optional string value that specifies the initial status of the health check. You can specify the following values: `critical` (default) `warning` `passing`	Script HTTP TCP UDP OSService TTL Docker gRPC H2ping Alias
`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	Script HTTP TCP UDP OSService TTL Docker gRPC H2ping Alias
`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`.	Script HTTP TCP UDP OSService TTL Docker gRPC H2ping Alias
`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`.	Script HTTP TCP UDP OSService TTL Docker gRPC H2ping Alias
`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`.	Script HTTP TCP UDP OSService TTL Docker gRPC H2ping Alias
`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.	Script Docker
`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.	Docker
`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.	Docker
`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
`grpc_use_tls`	Boolean value that enables TLS for gRPC checks when set to `true`.	gRPC
`h2ping`	String value that specifies the HTTP2 endpoint, including port number, to send HTTP2 requests to.	H2ping
`h2ping_use_tls`	Boolean value that enables TLS for H2ping checks when set to `true`.	H2ping
`http`	String value that specifies an HTTP endpoint to send requests to.	HTTP
`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). There are two common circumstances where supplying a `tls_server_name` can be beneficial: 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. 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.	HTTP H2Ping gRPC
`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`.	HTTP H2Ping gRPC TCP
`method`	String value that specifies the request method to send during HTTP checks. Default is `GET`.	HTTP
`header`	Object that specifies header fields to send in HTTP check requests. Each header specified in `header` object contains a list of string values.	HTTP
`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.	HTTP
`disable_redirects`	Boolean value that prevents HTTP checks from following redirects if set to `true`. Default is `false`.	HTTP
`os_service`	String value that specifies the name of the name of a service to check during an OSService check.	OSService
`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.	OSService
`tcp`	String value that specifies an IP address or host and port number for the check establish a TCP connection with.	TCP
`tcp_use_tls`	Boolean value that enables TLS for TCP checks when set to `true`.	TCP
`udp`	String value that specifies an IP address or host and port number for the check to send UDP datagrams to.	UDP
`ttl`	String value that specifies how long to wait for an update from an external process during a TTL check.	TTL
`alias_service`	String value that specifies a service or node that the service associated with the health check aliases.	Alias

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.