update doc

easegress-io · Dec 1, 2023 · 7df1107 · 7df1107
1 parent 6212010
commit 7df1107
Show file tree

Hide file tree

Showing 3 changed files with 250 additions and 12 deletions.
diff --git a/docs/02.Tutorials/2.3.Pipeline-Explained.md b/docs/02.Tutorials/2.3.Pipeline-Explained.md
@@ -17,6 +17,7 @@ Easegress offers a rich set of filters tailored for diverse use cases, including
   - [GlobalFilter](#globalfilter)
   - [Load Balancer](#load-balancer)
     - [Traffic Adaptor: Change Something of Two-Way Traffic](#traffic-adaptor-change-something-of-two-way-traffic)
+  - [Health Check](#health-check)
   - [API Aggregation](#api-aggregation)
     - [Example 1: Simple aggregation](#example-1-simple-aggregation)
     - [Example 2: Merge response body](#example-2-merge-response-body)
@@ -374,6 +375,49 @@ filters:
       loadBalance:
         policy: roundRobin
 ```
+
+### Health Check
+Perform a health check on the servers in the pool. If a server fails the check, it will be marked as unhealthy, and requests will be rerouted to other healthy servers until it regains health.
+
+More details config in [Proxy](../07.Reference/7.02.Filters.md#health-check).
+
+```yaml
+name: pipeline-reverse-proxy
+kind: Pipeline
+flow:
+  - filter: proxy
+filters:
+  - name: proxy
+    kind: Proxy
+    pools:
+    - servers:
+      - url: http://127.0.0.1:9095
+      - url: http://127.0.0.1:9096
+      - url: http://127.0.0.1:9097
+      loadBalance:
+        policy: roundRobin
+      healthCheck:
+        # interval between health checks (default: 60s)
+        interval: 60s
+
+        # uri for health check http request
+        uri: /health
+        # http request headers for health check
+        headers:
+          X-Health-Check: easegress
+        # username for basic authentication
+        username: admin
+        # password for basic authentication
+        password: xxxxxx
+
+        # response validation criteria (default: 2xx and 3xx status codes)
+        match:
+          # acceptable status code ranges 
+          statusCode:
+          - [200, 299] # 2xx
+          - [300, 399] # 3xx
+```
+
 ### API Aggregation
 
 API aggregation is a pattern to aggregate multiple individual requests into a single request. This pattern is useful when a client must make multiple calls to different backend systems to operate. Easegress provides filters [RequestBuilder](../07.Reference/7.02.Filters.md#requestbuilder) & [ResponseBuilder](../07.Reference/7.02.Filters.md#responsebuilder) for this powerful feature.

diff --git a/docs/02.Tutorials/2.6.Websocket.md b/docs/02.Tutorials/2.6.Websocket.md
@@ -2,6 +2,8 @@
 
 - [Background](#background)
 - [Design](#design)
+- [Health Check](#health-check)
+  - [Health Check](#health-check-1)
 - [Example](#example)
 - [References](#references)
 
@@ -79,6 +81,58 @@ headers that send to websocket backend.
   `Sec-Websocket-Version`, `Sec-Websocket-Extensions` and
   `Sec-Websocket-Protocol` in http headers to set connection.
 
+## Health Check
+
+### Health Check
+Perform a health check on the servers in the pool. If a server fails the check, it will be marked as unhealthy, and requests will be rerouted to other healthy servers until it regains health. Health check for websocket proxy contains both http way or websocket way. The HTTP check involves a request-response evaluation similar to a Proxy filter. In the WebSocket method, a successful connection yields a 101 status code. Additional headers can be set and evaluated in both methods. 
+If you send both two ways of health check, then a server passes both HTTP and WebSocket health checks, it will be considered healthy.
+
+More details in [WebSocketProxy](../07.Reference/7.02.Filters.md#health-check-1).
+
+```yaml
+kind: WebSocketProxy
+name: proxy-example-1
+pools:
+- servers:
+  - url: ws://127.0.0.1:9095
+  - url: ws://127.0.0.1:9096
+  - url: ws://127.0.0.1:9097
+  healthCheck:
+    # interval between health checks (default: 60s)
+    interval: 60s
+    # timeout for health check response (default: 3s)
+    timeout: 3s
+    # fail threshold to mark server as unhealthy (default: 1)
+    fails: 1
+    # success threshold to mark server as healthy (default: 1)
+    pass: 1
+
+    ws:
+      # health check request port (defaults to server's port, e.g., 9095)
+      port: 10080
+      # uri for health check
+      uri: /health/ws
+      # http request headers for health check
+      headers:
+        X-Health-Check: easegress
+
+      # response validation criteria (default: 101 Switching Protocols)
+      match:
+        # acceptable status code ranges 
+        statusCode:
+        - [101, 101] # 101
+        # response header validation
+        # name is header key.
+        # value is header value, can be empty. 
+        # type is type of value, can be "exact" or "regexp".
+        headers:
+        - name: X-Status
+          value: healthy
+          type: exact
+    http:
+      uri: /health
+```
+
 ## Example
 
 1. Send request

diff --git a/docs/07.Reference/7.02.Filters.md b/docs/07.Reference/7.02.Filters.md
@@ -2,12 +2,14 @@
 
 
 - [Proxy](#proxy)
+  - [Health Check](#health-check)
   - [Configuration](#configuration)
   - [Results](#results)
 - [SimpleHTTPProxy](#simplehttpproxy)
   - [Configuration](#configuration-1)
   - [Results](#results-1)
 - [WebSocketProxy](#websocketproxy)
+  - [Health Check](#health-check-1)
   - [Configuration](#configuration-2)
   - [Results](#results-2)
 - [CORSAdaptor](#corsadaptor)
@@ -127,14 +129,18 @@ or preceding filter needs to take extra action.
 The Proxy filter is a proxy of the backend service.
 
 Below is one of the simplest Proxy configurations, it forward requests
-to `http://127.0.0.1:9095`.
+to `http://127.0.0.1:9095` or `http://127.0.0.1:9096` or `http://127.0.0.1:9097` based on `roundRobin`.
 
 ```yaml
 kind: Proxy
 name: proxy-example-1
 pools:
 - servers:
   - url: http://127.0.0.1:9095
+  - url: http://127.0.0.1:9096
+  - url: http://127.0.0.1:9097
+  loadBalance:
+    policy: roundRobin
 maxRedirection: 10
 ```
 
@@ -177,22 +183,68 @@ pools:
 - serverTags: ["v2"]
   serviceName: service-001
   serviceRegistry: eureka-service-registry-example
+  loadBalance:
+    policy: roundRobin
 maxRedirection: 10
 ```
 
-When there are multiple servers in a pool, the Proxy can do a load balance
-between them:
+### Health Check
+
+Perform a health check on the servers in the pool. If a server fails the check, it will be marked as unhealthy, and requests will be rerouted to other healthy servers until it regains health.
 
 ```yaml
+name: proxy
 kind: Proxy
-name: proxy-example-4
 pools:
-- serverTags: ["v2"]
-  serviceName: service-001
-  serviceRegistry: eureka-service-registry-example
-  loadBalance:
-    policy: roundRobin
-maxRedirection: 10
+- servers:
+  - url: http://127.0.0.1:9095
+  - url: http://127.0.0.1:9096
+  - url: http://127.0.0.1:9097
+  healthCheck:
+    # interval between health checks (default: 60s)
+    interval: 60s
+    # timeout for health check response (default: 3s)
+    timeout: 3s
+    # fail threshold to mark server as unhealthy (default: 1)
+    fails: 1
+    # success threshold to mark server as healthy (default: 1)
+    pass: 1
+
+    # health check request port (defaults to server's port, e.g., 9095)
+    port: 10080
+    # uri for health check http request
+    uri: /health
+    # http method for health check
+    method: GET
+    # http request headers for health check
+    headers:
+      X-Health-Check: easegress
+    # http request body for health check
+    body: "you-body-here"
+    # username for basic authentication
+    username: admin
+    # password for basic authentication
+    password: xxxxxx
+
+    # response validation criteria (default: 2xx and 3xx status codes)
+    match:
+      # acceptable status code ranges 
+      statusCode:
+      - [200, 299] # 2xx
+      - [300, 399] # 3xx
+      # response header validation
+      # name is header key.
+      # value is header value, can be empty. 
+      # type is type of value, can be "exact" or "regexp".
+      headers:
+      - name: X-Status
+        value: healthy
+        type: exact
+      # response body validation
+      # type can be "contains" or "regexp".
+      body:
+        value: "healthy"
+        type: contains
 ```
 
 ### Configuration
@@ -299,14 +351,16 @@ https_proxy=http://127.0.0.1:8088 http_proxy=http://127.0.0.1:8088 curl https://
 The WebSocketProxy filter is a proxy of the websocket backend service.
 
 Below is one of the simplest WebSocketProxy configurations, it forwards
-the websocket connection to `ws://127.0.0.1:9095`.
+the websocket connection to `ws://127.0.0.1:9095` or `ws://127.0.0.1:9096` or `ws://127.0.0.1:9097`.
 
 ```yaml
 kind: WebSocketProxy
 name: proxy-example-1
 pools:
 - servers:
   - url: ws://127.0.0.1:9095
+  - url: ws://127.0.0.1:9096
+  - url: ws://127.0.0.1:9097
 ```
 
 Same as the `Proxy` filter:
@@ -330,6 +384,88 @@ rules:
   backend: websocket-pipeline
 ```
 
+### Health Check
+Perform a health check on the servers in the pool. If a server fails the check, it will be marked as unhealthy, and requests will be rerouted to other healthy servers until it regains health. Health check for websocket proxy contains both http way or websocket way. The HTTP check involves a request-response evaluation similar to a Proxy filter. In the WebSocket method, a successful connection yields a 101 status code. Additional headers can be set and evaluated in both methods. 
+If you send both two ways of health check, then a server passes both HTTP and WebSocket health checks, it will be considered healthy.
+
+```yaml
+kind: WebSocketProxy
+name: proxy-example-1
+pools:
+- servers:
+  - url: ws://127.0.0.1:9095
+  - url: ws://127.0.0.1:9096
+  - url: ws://127.0.0.1:9097
+  healthCheck:
+    # interval between health checks (default: 60s)
+    interval: 60s
+    # timeout for health check response (default: 3s)
+    timeout: 3s
+    # fail threshold to mark server as unhealthy (default: 1)
+    fails: 1
+    # success threshold to mark server as healthy (default: 1)
+    pass: 1
+
+    ws:
+      # health check request port (defaults to server's port, e.g., 9095)
+      port: 10080
+      # uri for health check
+      uri: /health/ws
+      # http request headers for health check
+      headers:
+        X-Health-Check: easegress
+
+      # response validation criteria (default: 101 Switching Protocols)
+      match:
+        # acceptable status code ranges 
+        statusCode:
+        - [101, 101] # 101
+        # response header validation
+        # name is header key.
+        # value is header value, can be empty. 
+        # type is type of value, can be "exact" or "regexp".
+        headers:
+        - name: X-Status
+          value: healthy
+          type: exact
+    http:
+      # health check request port (defaults to server's port, e.g., 9095)
+      port: 10080
+      # uri for health check http request
+      uri: /health
+      # http method for health check
+      method: GET
+      # http request headers for health check
+      headers:
+        X-Health-Check: easegress
+      # http request body for health check
+      body: "you-body-here"
+      # username for basic authentication
+      username: admin
+      # password for basic authentication
+      password: xxxxxx
+
+      # response validation criteria (default: 2xx and 3xx status codes)
+      match:
+        # acceptable status code ranges 
+        statusCode:
+        - [200, 299] # 2xx
+        - [300, 399] # 3xx
+        # response header validation
+        # name is header key.
+        # value is header value, can be empty. 
+        # type is type of value, can be "exact" or "regexp".
+        headers:
+        - name: X-Status
+          value: healthy
+          type: exact
+        # response body validation
+        # type can be "contains" or "regexp".
+        body:
+          value: "healthy"
+          type: contains
+```
+
 ### Configuration
 | Name | Type | Description | Required |
 | ---- | ---- | ----------- | -------- |
@@ -1585,6 +1721,7 @@ Rules to revise request header.
 | retryPolicy | string | Retry policy name | No |
 | circuitBreakerPolicy | string | CircuitBreaker policy name | No |
 | failureCodes | []int | Proxy return result of failureCode when backend resposne's status code in failureCodes. The default value is 5xx | No |
+| healthCheck | ProxyHealthCheckSpec | Health check. Full example with details in [Proxy Health Check](#health-check) | No |
 
 
 ### proxy.Server
@@ -1603,7 +1740,7 @@ Rules to revise request header.
 | policy        | string | Load balance policy, valid values are `roundRobin`, `random`, `weightedRandom`, `ipHash`, `headerHash`, `cookieHash` and `forward`, the last one is only used in `GRPCProxy`  | Yes      |
 | headerHashKey | string | When `policy` is `headerHash`, this option is the name of a header whose value is used for hash calculation | No       |
 | stickySession | [proxy.StickySession](#proxyStickySessionSpec) | Sticky session spec                                                 | No       |
-| healthCheck | [proxy.HealthCheck](#proxyHealthCheckSpec) | Health check spec, note that healthCheck is not needed if you are using service registry | No       |
+| healthCheck | [proxy.HealthCheck](#proxyHealthCheckSpec) | (Deprecated) Use [Proxy](#health-check) or [WebSocketProxy](#health-check-1) instead. | No       |
 | forwardKey | string | The value of this field is a header name of the incoming request, the value of this header is address of the target server (host:port), and the request will be sent to this address | No |
 
 ### proxy.StickySessionSpec
@@ -1617,6 +1754,8 @@ Rules to revise request header.
 
 ### proxy.HealthCheckSpec
 
+(Deprecated) Use [Proxy](#health-check) or [WebSocketProxy](#health-check-1) instead.
+
 | Name          | Type   | Description                                                                                                 | Required |
 | ------------- | ------ | ----------------------------------------------------------------------------------------------------------- | -------- |
 | interval | string | Interval duration for health check, default is 60s | Yes |
@@ -1743,6 +1882,7 @@ The relationship between `methods` and `url` is `AND`.
 | filter          | [proxy.RequestMatcherSpec](#proxyrequestmatcherspec)     | Filter options for candidate pools                                                         | No       |
 | insecureSkipVerify | bool                                | Disable origin verification when accepting client connections, default is `false`.                           | No       |
 | originPatterns  | []string                               | Host patterns for authorized origins, used to enable cross origin WebSockets.                                | No       |
+| healthCheck | WSProxyHealthCheckSpec | Health check for Websocket. Full example with details in [WebSocketProxy Health Check](#health-check-1) | No |
 
 ### mock.Rule