Health check configuration reference

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`.	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-readabiole 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 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.	HTTP
`tls_skip_verify`	Boolean value that disbles TLS for HTTP checks when set to `true`. Default is `false`.	HTTP
`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 escap 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
`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.