Health Checks

Meridian supports active health checking to detect unhealthy endpoints before they receive traffic. When an endpoint fails enough consecutive checks, it’s removed from the load balancer rotation.

Configuration

[[clusters]]
name = "api-backend"
lb_policy = "round_robin"
connect_timeout_ms = 5000
endpoints = [
  { address = "10.0.1.1:8080", weight = 1 },
  { address = "10.0.1.2:8080", weight = 1 },
]

[clusters.health_check]
interval_ms = 5000
timeout_ms = 2000
healthy_threshold = 2
unhealthy_threshold = 3
http_path = "/health"

Fields

Field	Type	Required	Default	Description
`interval_ms`	integer	yes	—	Time between health checks
`timeout_ms`	integer	yes	—	Timeout for a single check
`healthy_threshold`	integer	no	2	Consecutive successes to mark healthy
`unhealthy_threshold`	integer	no	3	Consecutive failures to mark unhealthy
`http_path`	string	no	—	HTTP path to probe. If absent, uses TCP connect check

Check Types

TCP check (when http_path is not set): Success if a TCP connection can be established within the timeout.

HTTP check (when http_path is set): Connects, sends GET <path> HTTP/1.1, and checks for a 200 status code.

Threshold Hysteresis

Health status uses threshold hysteresis to prevent flapping:

An unhealthy endpoint must pass healthy_threshold consecutive checks to become healthy again
A healthy endpoint must fail unhealthy_threshold consecutive checks to be marked unhealthy
A single success resets the failure counter (and vice versa)

This prevents an intermittently failing endpoint from rapidly toggling between healthy and unhealthy states.

Behavior When All Endpoints Are Unhealthy

If all endpoints in a cluster are marked unhealthy, the load balancer returns no endpoints and the proxy responds with 502 Bad Gateway. A future “panic mode” feature will allow routing to all endpoints regardless of health when no healthy endpoints exist.