Skip to main content
Version: 2.9

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.
  • Active health check is required so that the unhealthy node can recover.

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.