apisix/docs/en/latest/health-check.md

title
Health Check

Health Checks for Upstream

Health Check of APISIX is based on lua-resty-healthcheck, you can use it for upstream.

Note:

• We only start the health check when the upstream is hit by a request. There won't be any health check if an upstream is configured but isn't in used.
• If there is no healthy node can be chosen, we will continue to access the upstream.
• We won't start the health check when the upstream only has one node, as we will access it whether this unique node is healthy or not.

The following is an example of health check:

curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "uri": "/index.html",
    "plugins": {
        "limit-count": {
            "count": 2,
            "time_window": 60,
            "rejected_code": 503,
            "key": "remote_addr"
        }
    },
    "upstream": {
         "nodes": {
            "127.0.0.1:1980": 1,
            "127.0.0.1:1970": 1
        },
        "type": "roundrobin",
        "retries": 2,
        "checks": {
            "active": {
                "timeout": 5,
                "http_path": "/status",
                "host": "foo.com",
                "healthy": {
                    "interval": 2,
                    "successes": 1
                },
                "unhealthy": {
                    "interval": 1,
                    "http_failures": 2
                },
                "req_headers": ["User-Agent: curl/7.29.0"]
            },
            "passive": {
                "healthy": {
                    "http_statuses": [200, 201],
                    "successes": 3
                },
                "unhealthy": {
                    "http_statuses": [500],
                    "http_failures": 3,
                    "tcp_failures": 3
                }
            }
        }
    }
}'

The configures in checks are belong to health check, the type of checks contains: active or passive.

• active: To enable active health checks, you need to specify the configuration items under checks.active in the Upstream object configuration.

  • active.timeout: Socket timeout for active checks (in seconds), support decimals. For example 1.01 means 1010 milliseconds, 2 means 2000 milliseconds.

  • active.http_path: The HTTP GET request path used to detect if the upstream is healthy.

  • active.host: The HTTP request host used to detect if the upstream is healthy.

  • active.port: The customize health check host port (optional), this will override the port in the upstream node.

  The threshold fields of healthy are:

  • active.healthy.interval: Interval between health checks for healthy targets (in seconds), the minimum is 1.
  • active.healthy.successes: The number of success times to determine the target is healthy, the minimum is 1.

  The threshold fields of unhealthy are:

  • active.unhealthy.interval: Interval between health checks for unhealthy targets (in seconds), the minimum is 1.
  • active.unhealthy.http_failures: The number of http failures times to determine the target is unhealthy, the minimum is 1.
  • active.req_headers: Additional request headers. Array format, so you can fill in multiple headers.

• passive: To enable passive health checks, you need to specify the configuration items under checks.passive in the Upstream object configuration.

  The threshold fields of healthy are:

  • passive.healthy.http_statuses: If the current response code is equal to any of these, set the upstream node to the healthy state. Otherwise ignore this request.
  • passive.healthy.successes: Number of successes in proxied traffic (as defined by passive.healthy.http_statuses) to consider a target healthy, as observed by passive health checks.

  The threshold fields of unhealthy are:

  • passive.unhealthy.http_statuses: If the current response code is equal to any of these, set the upstream node to the unhealthy state. Otherwise ignore this request.
  • passive.unhealthy.tcp_failures: Number of TCP failures in proxied traffic to consider a target unhealthy, as observed by passive health checks.
  • passive.unhealthy.timeouts: Number of timeouts in proxied traffic to consider a target unhealthy, as observed by passive health checks.
  • passive.unhealthy.http_failures: Number of HTTP failures in proxied traffic (as defined by passive.unhealthy.http_statuses) to consider a target unhealthy, as observed by passive health checks.

The health check status can be fetched via GET /v1/healthcheck in control API.