Skip to content
Tutorials Center
My learning

Topics

Lesson 16 of 37 ยท Health Checks

Consul Health Check Types: HTTP, TCP, gRPC, Script, TTL, Alias

Learn every kind of Consul health check, how each one maps results to passing, warning or critical, and how to attach checks to services and nodes safely.

A registered service is only useful if callers can trust it. Health checks are how Consul learns whether an instance can really serve traffic. Each check ends in one of three states, passing, warning or critical, and Consul hides critical instances from DNS and from ?passing queries.

Checks run on the agent that owns the service, not on the servers. That keeps probing local and scalable. The definitions below are read-only on this site; the stand-ins model how results map to states and how a definition is validated.

Where checks come from

A check is attached either to a service (inside the service block, or with service_id) or to the node itself. Besides the checks you define, every node has a built-in serfHealth check that fails when the cluster's gossip decides the node is gone. Checks can be in a definition file, registered with PUT /v1/agent/check/register or with the CLI; once registered they live with the agent.

Every check has a name, optional id and notes, and settings that control timing (covered in the next lesson).

HTTP checks

The agent sends a request to a URL and looks at the response status code:

HCL
check {
  name     = "web http"
  http     = "http://127.0.0.1:8080/health"
  method   = "GET"
  header   = { Accept = ["application/json"] }
  interval = "10s"
  timeout  = "2s"
}
HTTP result Check state
Any 2xx passing
429 Too Many Requests warning
Anything else (3xx is followed unless disabled, 4xx, 5xx, timeout, connection error) critical

The first 4 KB of the response body is stored in the check output, which makes failures much easier to debug; return a short plain-text reason from your health endpoint. HTTPS targets use tls_skip_verify = true (avoid it in production) or a CA you configure. Add disable_redirects = true to stop the agent following redirects.

TCP and UDP checks

A TCP check tries to open a connection to host:port; success is passing, failure is critical. It proves that something listens, not that it works, so use it for databases and brokers with no HTTP endpoint:

HCL
check {
  name     = "postgres tcp"
  tcp      = "127.0.0.1:5432"
  interval = "10s"
  timeout  = "1s"
}

A UDP check (udp = "host:port") sends a packet and reports critical if it gets a connection-refused error; it is less reliable because silence also looks like success.

gRPC checks

For gRPC services that implement the standard health protocol:

HCL
check {
  name     = "api grpc"
  grpc     = "127.0.0.1:9090"
  grpc_use_tls = false
  interval = "10s"
}

Append /service-name to the address to ask about a particular service. A SERVING response is passing; anything else is critical.

Script checks

A script check runs a command and maps its exit code: 0 is passing, 1 is warning, any other value is critical.

HCL
check {
  name     = "disk space"
  args     = ["/usr/local/bin/check-disk.sh", "/var/lib/data"]
  interval = "30s"
  timeout  = "5s"
}

Scripts are disabled by default, because anyone who can register a check through the API could otherwise run commands as the agent's user. Enable them only with enable_local_script_checks = true (checks from config files only), which is safer than enable_script_checks = true (also API-registered ones). Use the args array form, which does not go through a shell, rather than a script string.

TTL checks

A TTL check is passive: Consul does not probe anything. Your application must call the API within the time limit, or the check turns critical:

Terminal
$ curl --request PUT http://127.0.0.1:8500/v1/agent/check/pass/service:web?note=ok
$ curl --request PUT http://127.0.0.1:8500/v1/agent/check/warn/service:web?note=slow
$ curl --request PUT http://127.0.0.1:8500/v1/agent/check/fail/service:web?note=db-down

This fits batch jobs and workers that have no port to probe: they report in, and silence means trouble. The next lesson covers TTL timing.

Alias checks

An alias check copies the state of another service or node:

HCL
check {
  name          = "alias to db"
  alias_service = "db"
}

Use it when one service's health is defined by another one on the same node, for example a sidecar that is only healthy when the main process is.

Other kinds

  • h2ping probes HTTP/2 endpoints with a ping.
  • docker runs a command inside a container through the Docker API (you must give the container ID and a shell); newer designs use an HTTP or TCP check against the container's published port.
  • os_service checks the state of an operating system service on supported platforms.

Stand-in 1: map results to states

The mapping rules of HTTP, TCP and script checks, written as plain functions. They model the table above.

Python Stand-in: status mapping

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Stand-in 2: validate a check definition

Consul requires that each check have exactly one probe type. This model enforces that plus the interval rule (every active check needs one, a TTL check needs a ttl).

Python Stand-in: validate check definitions

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Choosing a check type

Situation Check
Web service with a health endpoint HTTP
Database or broker TCP (or a script that runs a real query)
gRPC service gRPC
Batch job, worker, cron TTL
Sidecar tied to a main process Alias
Anything custom Script (with care)

Make health endpoints cheap and honest. They run every few seconds on every instance, so they should not trigger heavy work. They should fail when the service truly cannot do its job (for instance, it has lost its database connection) and not fail for unrelated problems, or one slow dependency will take all your instances out of rotation at once.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What check state does an HTTP 429 response produce?

    2xx is passing, 429 is warning and every other result is critical.
  2. 2. A script check exits with code 1. What state is it in?

    Exit 0 is passing, 1 is warning and anything else is critical.
  3. 3. Which check type suits a nightly batch worker that has no network port?

    A TTL check is passive: silence beyond the TTL turns it critical.
  4. 4. Why are script checks disabled by default?

    A script check executes arbitrary commands, so Consul requires an explicit opt-in.

Summary

  • Checks end in passing, warning or critical; critical instances disappear from healthy answers.
  • Agents run checks locally: HTTP, TCP, UDP, gRPC, script, TTL (passive), alias and a few others.
  • HTTP 2xx passes, 429 warns; script exit 0, 1, other map to passing, warning, critical.
  • Enable script checks only where needed, preferring enable_local_script_checks and args arrays.
  • Health endpoints should be cheap and should reflect the service's real ability to work.

Next: Check Timing, TTLs and Avoiding Flapping