Health Check

Health Checks for Upstream

Health Check of Apache APISIX is based on lua-resty-healthcheck.

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.

Configuration instructions

Configuration itemConfiguration typeValue typeValue optionDefaultsDescription
upstream.checks.active.typeActive checkstringhttp https tcphttpThe type of active check.
upstream.checks.active.timeoutActive checkinteger1The timeout period of the active check (unit: second).
upstream.checks.active.concurrencyActive checkinteger10The number of targets to be checked at the same time during the active check.
upstream.checks.active.http_pathActive checkstring/The HTTP request path that is actively checked.
upstream.checks.active.hostActive checkstring${upstream.node.host}The hostname of the HTTP request actively checked.
upstream.checks.active.portActive checkinteger1 to 65535${upstream.node.port}The host port of the HTTP request that is actively checked.
upstream.checks.active.https_verify_certificateActive checkbooleantrueActive check whether to check the SSL certificate of the remote host when HTTPS type checking is used.
upstream.checks.active.req_headersActive checkarray[]Active check When using HTTP or HTTPS type checking, set additional request header information.
upstream.checks.active.healthy.intervalActive check (healthy node)integer>= 11Active check (healthy node) check interval (unit: second)
upstream.checks.active.healthy.http_statusesActive check (healthy node)array200 to 599[200, 302]Active check (healthy node) HTTP or HTTPS type check, the HTTP status code of the healthy node.
upstream.checks.active.healthy.successesActive check (healthy node)integer1 to 2542Active check (healthy node) determine the number of times a node is healthy.
upstream.checks.active.unhealthy.intervalActive check (unhealthy node)integer>= 11Active check (unhealthy node) check interval (unit: second)
upstream.checks.active.unhealthy.http_statusesActive check (unhealthy node)array200 to 599[429, 404, 500, 501, 502, 503, 504, 505]Active check (unhealthy node) HTTP or HTTPS type check, the HTTP status code of the non-healthy node.
upstream.checks.active.unhealthy.http_failuresActive check (unhealthy node)integer1 to 2545Active check (unhealthy node) HTTP or HTTPS type check, determine the number of times that the node is not healthy.
upstream.checks.active.unhealthy.tcp_failuresActive check (unhealthy node)integer1 to 2542Active check (unhealthy node) TCP type check, determine the number of times that the node is not healthy.
upstream.checks.active.unhealthy.timeoutsActive check (unhealthy node)integer1 to 2543Active check (unhealthy node) to determine the number of timeouts for unhealthy nodes.
upstream.checks.passive.healthy.http_statusesPassive check (healthy node)array200 to 599[200, 201, 202, 203, 204, 205, 206, 207, 208, 226, 300, 301, 302, 303, 304, 305, 306, 307, 308]Passive check (healthy node) HTTP or HTTPS type check, the HTTP status code of the healthy node.
upstream.checks.passive.healthy.successesPassive check (healthy node)integer0 to 2545Passive checks (healthy node) determine the number of times a node is healthy.
upstream.checks.passive.unhealthy.http_statusesPassive check (unhealthy node)array200 to 599[429, 500, 503]Passive check (unhealthy node) HTTP or HTTPS type check, the HTTP status code of the non-healthy node.
upstream.checks.passive.unhealthy.tcp_failuresPassive check (unhealthy node)integer0 to 2542Passive check (unhealthy node) When TCP type is checked, determine the number of times that the node is not healthy.
upstream.checks.passive.unhealthy.timeoutsPassive check (unhealthy node)integer0 to 2547Passive checks (unhealthy node) determine the number of timeouts for unhealthy nodes.
upstream.checks.passive.unhealthy.http_failuresPassive check (unhealthy node)integer0 to 2545Passive check (unhealthy node) The number of times that the node is not healthy during HTTP or HTTPS type checking.

Configuration example

  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.                 "timeout": 5,
  22.                 "http_path": "/status",
  23.                 "host": "foo.com",
  24.                 "healthy": {
  25.                     "interval": 2,
  26.                     "successes": 1
  27.                 },
  28.                 "unhealthy": {
  29.                     "interval": 1,
  30.                     "http_failures": 2
  31.                 },
  32.                 "req_headers": ["User-Agent: curl/7.29.0"]
  33.             },
  34.             "passive": {
  35.                 "healthy": {
  36.                     "http_statuses": [200, 201],
  37.                     "successes": 3
  38.                 },
  39.                 "unhealthy": {
  40.                     "http_statuses": [500],
  41.                     "http_failures": 3,
  42.                     "tcp_failures": 3
  43.                 }
  44.             }
  45.         }
  46.     }
  47. }'

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