Health Checks for Upstream

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

The following is a example of health check:

  1. curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  2. {
  3.     "uri": "/index.html",
  4.     "plugins": {
  5.         "limit-count": {
  6.             "count": 2,
  7.             "time_window": 60,
  8.             "rejected_code": 503,
  9.             "key": "remote_addr"
  10.         }
  11.     },
  12.     "upstream": {
  13.          "nodes": {
  14.             "127.0.0.1:1980": 1,
  15.             "127.0.0.1:1970": 1
  16.         },
  17.         "type": "roundrobin",
  18.         "retries": 2,
  19.         "checks": {
  20.             "active": {
  21.                 "http_path": "/status",
  22.                 "host": "foo.com",
  23.                 "healthy": {
  24.                     "interval": 2,
  25.                     "successes": 1
  26.                 },
  27.                 "unhealthy": {
  28.                     "interval": 1,
  29.                     "http_failures": 2
  30.                 },
  31.                 "req_headers": ["User-Agent: curl/7.29.0"]
  32.             },
  33.             "passive": {
  34.                 "healthy": {
  35.                     "http_statuses": [200, 201],
  36.                     "successes": 3
  37.                 },
  38.                 "unhealthy": {
  39.                     "http_statuses": [500],
  40.                     "http_failures": 3,
  41.                     "tcp_failures": 3
  42.                 }
  43.             }
  44.         }
  45.     }
  46. }'

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.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.

    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.