Define health checks

This topic describes how to create different types of health checks for your services.

Overview

Health checks are configurations that verifies the health of a service or node. Health checks configurations are nested in the service block. Refer to Define Services for information about specifying other service parameters.

You can define individual health checks for your service in separate check blocks or define multiple checks in a checks block. Refer to Define multiple checks for additional information.

You can create several different kinds of checks:

• Script checks invoke an external application that performs the health check, exits with an appropriate exit code, and potentially generates output. Script checks are one of the most common types of checks.
• HTTP checks make an HTTP GET request to the specified URL and wait for the specified amount of time. HTTP checks are one of the most common types of checks.
• TCP checks attempt to connect to an IP or hostname and port over TCP and wait for the specified amount of time.
• UDP checks send UDP datagrams to the specified IP or hostname and port and wait for the specified amount of time.
• Time-to-live (TTL) checks are passive checks that await updates from the service. If the check does not receive a status update before the specified duration, the health check enters a criticalstate.
• Docker checks are dependent on external applications packaged with a Docker container that are triggered by calls to the Docker exec API endpoint.
• gRPC checks probe applications that support the standard gRPC health checking protocol.
• H2ping checks test an endpoint that uses http2. The check connects to the endpoint and sends a ping frame.
• Alias checks represent the health state of another registered node or service.

If your network runs in a Kubernetes environment, you can sync service health information with Kubernetes health checks. Refer to Configure Health Checks for Consul on Kubernetes for details.

Registration

After defining health checks, you must register the service containing the checks with Consul. Refer to Register Services and Health Checks for additional information. If the service is already registered, you can reload the service configuration file to implement your health check. Refer to Reload for additional information.

Define multiple checks

You can define multiple checks for a service in a single checks block. The checks block contains an array of objects. The objects contain the configuration for each health check you want to implement. The following example includes two script checks named mem and cpu and an HTTP check that calls the /health API endpoint.

checks = [
  {
    id       = "chk1"
    name     = "mem"
    args     = ["/bin/check_mem", "-limit", "256MB"]
    interval = "5s"
  },
  {
    id       = "chk2"
    name     = "/health"
    http     = "http://localhost:5000/health"
    interval = "15s"
  },
  {
    id       = "chk3"
    name     = "cpu"
    args     = ["/bin/check_cpu"]
    interval = "10s"
  }
]

{
  "checks": [
    {
      "id": "chk1",
      "name": "mem",
      "args": ["/bin/check_mem", "-limit", "256MB"],
      "interval": "5s"
    },
    {
      "id": "chk2",
      "name": "/health",
      "http": "http://localhost:5000/health",
      "interval": "15s"
    },
    {
      "id": "chk3",
      "name": "cpu",
      "args": ["/bin/check_cpu"],
      "interval": "10s"
    }
  ]
}

Define initial health check status

When checks are registered against a Consul agent, they are assigned a critical status by default. This prevents services from registering as passing and entering the service pool before their health is verified. You can add the status parameter to the check definition to specify the initial state. In the following example, the check registers in a passing state:

check = {
  id = "mem"
  args = ["/bin/check_mem", "-limit", "256MB"]
  interval = "10s"