docs: refactor health check doc (apache#8129)

CHANGELOG.md

@@ -1222,7 +1222,7 @@ This release brings many new features such as health check and circuit breaker,
 
 ### Core
 
-- :sunrise: **[Health Check and Circuit Breaker](https://github.com/apache/incubator-apisix/blob/master/docs/en/latest/health-check.md)**: Enable health check on the upstream node, and will automatically filter unhealthy nodes during load balancing to ensure system stability. [#249](https://github.com/apache/incubator-apisix/pull/249)
+- :sunrise: **[Health Check and Circuit Breaker](https://github.com/apache/incubator-apisix/blob/master/docs/en/latest/tutorials/health-check.md)**: Enable health check on the upstream node, and will automatically filter unhealthy nodes during load balancing to ensure system stability. [#249](https://github.com/apache/incubator-apisix/pull/249)
 - Anti-ReDoS(Regular expression Denial of Service). [#252](https://github.com/apache/incubator-apisix/pull/250)
 - supported debug mode. [#319](https://github.com/apache/incubator-apisix/pull/319)
 - allowed to use different router. [#364](https://github.com/apache/incubator-apisix/pull/364)

README.md

@@ -80,7 +80,7 @@ A/B testing, canary release, blue-green deployment, limit rate, defense against
   - [Response Rewrite](docs/en/latest/plugins/response-rewrite.md): Set customized response status code, body and header to the client.
   - Dynamic Load Balancing: Round-robin load balancing with weight.
   - Hash-based Load Balancing: Load balance with consistent hashing sessions.
-  - [Health Checks](docs/en/latest/health-check.md): Enable health check on the upstream node and will automatically filter unhealthy nodes during load balancing to ensure system stability.
+  - [Health Checks](docs/en/latest/tutorials/health-check.md): Enable health check on the upstream node and will automatically filter unhealthy nodes during load balancing to ensure system stability.
   - Circuit-Breaker: Intelligent tracking of unhealthy upstream services.
   - [Proxy Mirror](docs/en/latest/plugins/proxy-mirror.md): Provides the ability to mirror client requests.
   - [Traffic Split](docs/en/latest/plugins/traffic-split.md): Allows users to incrementally direct percentages of traffic between various upstreams.

docs/en/latest/admin-api.md

@@ -651,7 +651,7 @@ In addition to the equalization algorithm selections, Upstream also supports pas
 | discovery_type              | required, if `service_name` is used         | The type of service [discovery](discovery.md).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `eureka`                                                                                                                                   |
 | hash_on                     | optional                                    | Only valid if the `type` is `chash`. Supports Nginx variables (`vars`), custom headers (`header`), `cookie` and `consumer`. Defaults to `vars`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |                                                                                                                                            |
 | key                         | optional                                    | Only valid if the `type` is `chash`. Finds the corresponding node `id` according to `hash_on` and `key` values. When `hash_on` is set to `vars`, `key` is a required parameter and it supports [Nginx variables](http://nginx.org/en/docs/varindex.html). When `hash_on` is set as `header`, `key` is a required parameter, and `header name` can be customized. When `hash_on` is set to `cookie`, `key` is also a required parameter, and `cookie name` can be customized. When `hash_on` is set to `consumer`, `key` need not be set and the `key` used by the hash algorithm would be the authenticated `consumer_name`. If the specified `hash_on` and `key` fail to fetch the values, it will default to `remote_address`. | `uri`, `server_name`, `server_addr`, `request_uri`, `remote_port`, `remote_addr`, `query_string`, `host`, `hostname`, `arg_***`, `arg_***` |
-| checks                      | optional                                    | Configures the parameters for the [health check](health-check.md).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |                                                                                                                                            |
+| checks                      | optional                                    | Configures the parameters for the [health check](./tutorials/health-check.md).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |                                                                                                                                            |
 | retries                     | optional                                    | Sets the number of retries while passing the request to Upstream using the underlying Nginx mechanism. Set according to the number of available backend nodes by default. Setting this to `0` disables retry.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |                                                                                                                                            |
 | retry_timeout               | optional                                    | Timeout to continue with retries. Setting this to `0` disables the retry timeout.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |                                                                                                                                            |
 | timeout                     | optional                                    | Sets the timeout (in seconds) for connecting to, and sending and receiving messages to and from the Upstream.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |                                                                                                                                            |

docs/en/latest/config.json

@@ -20,7 +20,8 @@
         "tutorials/expose-api",
         "tutorials/protect-api",
         "tutorials/observe-your-api",
-        "tutorials/cache-api-responses"
+        "tutorials/cache-api-responses",
+        "tutorials/health-check"
       ]
     },
     {
@@ -285,10 +286,6 @@
           "type": "doc",
           "id": "deployment-modes"
         },
-        {
-          "type": "doc",
-          "id": "health-check"
-        },
         {
           "type": "doc",
           "id": "router-radixtree"

docs/en/latest/control-api.md

@@ -94,7 +94,7 @@ Returns the JSON schema used by the APISIX instance:
 
 Introduced in [v2.3](https://github.com/apache/apisix/releases/tag/2.3).
 
-Returns a [health check](health-check.md) of the APISIX instance.
+Returns a [health check](./tutorials/health-check.md) of the APISIX instance.
 
 ```json
 [

docs/en/latest/terminology/upstream.md

@@ -124,7 +124,7 @@ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
 }'
 ```
 
-You can learn more about health checks [here](../health-check.md).
+You can learn more about health checks [here](../tutorials/health-check.md).
 
 The examples below show configurations that use different `hash_on` types.
 

docs/en/latest/health-check.md → docs/en/latest/tutorials/health-check.md

@@ -1,5 +1,10 @@
 ---
 title: Health Check
+keywords:
+  - APISIX
+  - API Gateway
+  - Health Check
+description: This article describes how to use the health check feature of API Gateway Apache APISIX to check the health status of upstream nodes.
 ---
 
 <!--
@@ -21,22 +26,39 @@ title: Health Check
 #
 -->
 
-## Health Checks for Upstream
+## Description
 
-Health Check of Apache APISIX is based on [lua-resty-healthcheck](https://github.com/api7/lua-resty-healthcheck).
+This article mainly introduces the health check function of Apache APISIX. The health check function can proxy requests to healthy nodes when the upstream node fails or migrates, avoiding the problem of service unavailability to the greatest extent. The health check function of APISIX is implemented using [lua-resty-healthcheck](https://github.com/api7/lua-resty-healthcheck), which is divided into active check and passive check.
 
-Note:
+## Active check
 
-* 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.
+Active health check mainly means that APISIX actively detects the survivability of upstream nodes through preset probe types. APISIX supports three probe types: `HTTP`, `HTTPS`, and `TCP`.
+
+When N consecutive probes sent to healthy node `A` fail, the node will be marked as unhealthy, and the unhealthy node will be ignored by APISIX's load balancer and cannot receive requests; if For an unhealthy node, if M consecutive probes are successful, the node will be re-marked as healthy and can be proxied.
+
+## Passive check
+
+Passive health check refers to judging whether the corresponding upstream node is healthy by judging the response status of the request forwarded from APISIX to the upstream node. Compared with the active health check, the passive health check method does not need to initiate additional probes, but it cannot sense the node status in advance, and there may be a certain amount of failed requests.
+
+If `N` consecutive requests to a healthy node A fail, the node will be marked as unhealthy.
+
+:::note
+
+Since unhealthy nodes cannot receive requests, nodes cannot be re-marked as healthy using the passive health check strategy alone, so combining the active health check strategy is usually necessary.
+
+:::
+
+:::tip
+
+- 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.
+
+:::
 
 ### Configuration instructions
 
-| Configuration item                              | Configuration type              | Value type | Value option         | Defaults                                                                                      | Description                                                                                                          |
+| Name                                      | Configuration type              | Value type | Valid values         | Default                                                                                      | Description                                                                                                          |
 | ----------------------------------------------- | ------------------------------- | ---------- | -------------------- | --------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
 | upstream.checks.active.type                     | Active check                    | string     | `http` `https` `tcp` | http                                                                                          | The type of active check.                                                                                            |
 | upstream.checks.active.timeout                  | Active check                    | integer    |                      | 1                                                                                             | The timeout period of the active check (unit: second).                                                               |
@@ -63,6 +85,8 @@ it whether this unique node is healthy or not.
 
 ### Configuration example
 
+You can enable health checks in routes via the Admin API:
+
 ```shell
 curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
 {
@@ -113,4 +137,26 @@ curl http://127.0.0.1:9180/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
 }'
 ```
 
+If APISIX detects an unhealthy node, the following logs will be output in the error log:
+
+```shell
+enabled healthcheck passive while logging request
+failed to receive status line from 'nil (127.0.0.1:1980)': closed
+unhealthy TCP increment (1/2) for '(127.0.0.1:1980)'
+failed to receive status line from 'nil (127.0.0.1:1980)': closed
+unhealthy TCP increment (2/2) for '(127.0.0.1:1980'
+```
+
+:::tip
+
+To observe the above log information, you need to adjust the error log level to `info`.
+
+:::
+
 The health check status can be fetched via `GET /v1/healthcheck` in [Control API](./control-api.md).
+
+```shell
+
+curl http://127.0.0.1:9090/v1/healthcheck/upstreams/healthycheck -s | jq .
+
+```

docs/zh/latest/CHANGELOG.md

@@ -1202,7 +1202,7 @@ title: CHANGELOG
 
 ### Core
 
-- :sunrise: **[健康检查和服务熔断](https://github.com/apache/incubator-apisix/blob/master/docs/zh/latest//health-check.md)**: 对上游节点开启健康检查，智能判断服务状态进行熔断和连接。[#249](https://github.com/apache/incubator-apisix/pull/249)
+- :sunrise: **[健康检查和服务熔断](https://github.com/apache/incubator-apisix/blob/master/docs/zh/latest/tutorials/health-check..md)**: 对上游节点开启健康检查，智能判断服务状态进行熔断和连接。[#249](https://github.com/apache/incubator-apisix/pull/249)
 - 阻止 ReDoS(Regular expression Denial of Service). [#252](https://github.com/apache/incubator-apisix/pull/250)
 - 支持 debug 模式。[#319](https://github.com/apache/incubator-apisix/pull/319)
 - 允许自定义路由。[#364](https://github.com/apache/incubator-apisix/pull/364)

docs/zh/latest/README.md

@@ -89,7 +89,7 @@ A/B 测试、金丝雀发布（灰度发布）、蓝绿部署、限流限速、
     - [Serverless](plugins/serverless.md)：在 APISIX 的每一个阶段，你都可以添加并调用自己编写的函数。
     - 动态负载均衡：动态支持有权重的 round-robin 负载平衡。
     - 支持一致性 hash 的负载均衡：动态支持一致性 hash 的负载均衡。
-    - [健康检查](health-check.md)：启用上游节点的健康检查，将在负载均衡期间自动过滤不健康的节点，以确保系统稳定性。
+    - [健康检查](./tutorials/health-check.md)：启用上游节点的健康检查，将在负载均衡期间自动过滤不健康的节点，以确保系统稳定性。
     - 熔断器：智能跟踪不健康上游服务。
     - [代理镜像](plugins/proxy-mirror.md)：提供镜像客户端请求的能力。
     - [流量拆分](plugins/traffic-split.md)：允许用户逐步控制各个上游之间的流量百分比。