Health

Gateway uses two signals.

Active health checksCopy Anchor Link

When a target group has health checks, Gateway probes each server on a schedule.

Passive failure trackingCopy Anchor Link

Failed connections and requests count against a server. After 3 consecutive failures the server is taken out of rotation. Once 30 seconds have passed since its last failure, it becomes eligible for traffic again, without waiting for a successful health check.

How the two signals combineCopy Anchor Link

• Active check results are applied periodically, not on every request. A server can keep receiving requests for a short time after a probe marks it unhealthy.
• A server marked unhealthy by active checks can become eligible again through the 30-second passive window before the next probe result is applied. Requests to it then count as failures again.
• Backup servers receive traffic only while no primary server is eligible.
• If no server in the target group is eligible, Gateway returns 502 without forwarding the request.

Do not rely on health checks alone to keep traffic away from a failing server. Keep your targets able to reject work they cannot do.

Make your health endpoint honestCopy Anchor Link

Return 200 only when the server can do real work, such as reach its database. A health endpoint that always succeeds hides failures from Gateway.

ExampleCopy Anchor Link

In the current Gateway configuration format, health checks and failure tracking are set on the target group and its servers.

{
  "upstreams": [
    {
      "name": "api",
      "servers": [
        { "address": "10.0.0.1", "port": 8080, "max_fails": 3, "fail_timeout_ms": 30000 },
        { "address": "10.0.0.2", "port": 8080, "backup": true }
      ],
      "health_check": {
        "path": "/health",
        "interval_ms": 5000,
        "timeout_ms": 2000,
        "expected_status": 200,
        "healthy_threshold": 2,
        "unhealthy_threshold": 3
      }
    }
  ]
}