Merge branch 'main' into support-nginx-conf

easegress-io · Nov 7, 2023 · 96f36eb · 96f36eb
2 parents 6d47267 + e98c986
commit 96f36eb
Show file tree

Hide file tree

Showing 13 changed files with 1,161 additions and 561 deletions.
diff --git a/.github/workflows/golangci.lint.yml b/.github/workflows/golangci.lint.yml
@@ -29,4 +29,4 @@ jobs:
       uses: golangci/golangci-lint-action@v3
       with:
         version: v1.54
-        args: --timeout=30m --disable=errcheck
+        args: --timeout=30m --disable=errcheck --exclude="SA1019"
diff --git a/docs/04.Cloud-Native/4.1.Kubernetes-Ingress-Controller.md b/docs/04.Cloud-Native/4.1.Kubernetes-Ingress-Controller.md
@@ -7,6 +7,7 @@
   - [Handle Ingresses within Specified K8s Namespaces](#handle-ingresses-within-specified-k8s-namespaces)
   - [Use a Customized Ingress Class](#use-a-customized-ingress-class)
   - [Deploy Outside of a K8s Cluster](#deploy-outside-of-a-k8s-cluster)
+  - [Additional Annotations](#additional-annotations)
 
 The IngressController is an implementation of [Kubernetes ingress controller](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/), it watches Kubernetes Ingress, Service, Endpoints, and Secrets then translates them to Easegress HTTP server and pipelines.
 
@@ -201,3 +202,53 @@ httpServer:
   keepAliveTimeout: 60s
   maxConnections: 10240
 ```
+
+### Additional Annotations
+
+When defining your `Ingress` configurations, you can use the following `easegress` specific annotations for added customization:
+
+- **Load Balancing**: `easegress.ingress.kubernetes.io/proxy-load-balance`
+- **Header Hash Key for Load Balancing**: `easegress.ingress.kubernetes.io/proxy-header-hash-key`
+- **Forwarding Key**: `easegress.ingress.kubernetes.io/proxy-forward-key`
+- **Server Response Maximum Size**: `easegress.ingress.kubernetes.io/proxy-server-max-size`
+- **Proxy Timeout**: `easegress.ingress.kubernetes.io/proxy-timeout`
+
+Please refer to the [Proxy Server Pool Spec](../07.Reference/7.02.Filters.md#proxyserverpoolspec) and [Load Balance Spec](../07.Reference/7.02.Filters.md#proxyloadbalancespec) to get the details of the corresponding annotations.
+
+These annotations provide additional configurations to optimize the behavior and performance of your ingress controllers in different scenario.
+
+```yaml
+apiVersion: networking.k8s.io/v1
+kind: Ingress
+metadata:
+  name: ingress-example
+  annotations:
+    easegress.ingress.kubernetes.io/proxy-load-balance: "ipHash"
+    easegress.ingress.kubernetes.io/proxy-header-hash-key: "X-User-Id"
+    easegress.ingress.kubernetes.io/proxy-forward-key: ""
+    easegress.ingress.kubernetes.io/proxy-server-max-size: "12400"
+    easegress.ingress.kubernetes.io/proxy-timeout: "10s"
+spec:
+  ingressClassName: easegress
+  rules:
+  - host: "www.example.com"
+    http:
+      paths:
+      - pathType: Prefix
+        path: /
+        backend:
+          service:
+            name: hello-service
+            port:
+              number: 60001
+  - host: "*.megaease.com"
+    http:
+      paths:
+      - pathType: Prefix
+        path: /
+        backend:
+          service:
+            name: hello-service
+            port:
+              number: 60002
+```
diff --git a/docs/04.Cloud-Native/4.2.Gateway-API.md b/docs/04.Cloud-Native/4.2.Gateway-API.md
@@ -239,12 +239,12 @@ spec:
 
 ### Deploy Gateway API Objects
 
-Please refer https://gateway-api.sigs.k8s.io/ for the detailed information
+Please refer [Kubernetes Gateway API](https://gateway-api.sigs.k8s.io/) for the detailed information
 of Gateway Class, Gateway and HTTPRoute configuration. Up to now, the Easegress
 GatewayController only support HTTP & HTTPS listeners.
 
 ```yaml
-apiVersion: gateway.networking.k8s.io/v1beta1
+apiVersion: gateway.networking.k8s.io/v1
 kind: GatewayClass
 metadata:
   name: example-gateway-class
@@ -253,7 +253,7 @@ spec:
 
 ---
 
-apiVersion: gateway.networking.k8s.io/v1beta1
+apiVersion: gateway.networking.k8s.io/v1
 kind: Gateway
 metadata:
   name: example-gateway
@@ -266,7 +266,7 @@ spec:
 
 ---
 
-apiVersion: gateway.networking.k8s.io/v1beta1
+apiVersion: gateway.networking.k8s.io/v1
 kind: HTTPRoute
 metadata:
   name: example-route
@@ -285,7 +285,7 @@ spec:
 
 ---
 
-apiVersion: gateway.networking.k8s.io/v1beta1
+apiVersion: gateway.networking.k8s.io/v1
 kind: HTTPRoute
 metadata:
   name: example-route-2

diff --git a/docs/07.Reference/7.02.Filters.md b/docs/07.Reference/7.02.Filters.md
@@ -70,9 +70,12 @@
 - [Redirector](#redirector)
   - [Configuration](#configuration-22)
   - [Results](#results-22)
-- [GRPCProxy](#grpcproxy)
+- [RedirectorV2](#redirectorv2)
   - [Configuration](#configuration-23)
   - [Results](#results-23)
+- [GRPCProxy](#grpcproxy)
+  - [Configuration](#configuration-24)
+  - [Results](#results-24)
 - [Common Types](#common-types)
   - [pathadaptor.Spec](#pathadaptorspec)
   - [pathadaptor.RegexpReplace](#pathadaptorregexpreplace)
@@ -983,7 +986,7 @@ HeaderLookup has no results.
 
 ## ResultBuilder
 
-ResultBuilder generates a string, which will be the result of the filter. 
+ResultBuilder generates a string, which will be the result of the filter.
 This filter exists to work with the [`jumpIf` mechanism](7.01.Controllers.md#pipeline) for conditional jumping.
 
 Currently, the result string can only be `result0` - `result9`, this will be
@@ -1139,10 +1142,10 @@ After OIDCAdaptor handled, following OIDC related information can be obtained fr
 
 
 ## OPAFilter
-The [Open Policy Agent (OPA)](https://www.openpolicyagent.org/docs/latest/) is an open source, 
-general-purpose policy engine that unifies policy enforcement across the stack. It provides a 
-high-level declarative language, which can be used to define and enforce policies in 
-Easegress API Gateway. Currently, there are 160+ built-in operators and functions we can use, 
+The [Open Policy Agent (OPA)](https://www.openpolicyagent.org/docs/latest/) is an open source,
+general-purpose policy engine that unifies policy enforcement across the stack. It provides a
+high-level declarative language, which can be used to define and enforce policies in
+Easegress API Gateway. Currently, there are 160+ built-in operators and functions we can use,
 for examples `net.cidr_contains` and `contains`.
 
 ```yaml
@@ -1163,8 +1166,8 @@ filters:
       allow {
          input.request.method == "POST"
          input.request.scheme == "https"
-         contains(input.request.path, "/")               
-         net.cidr_contains("127.0.0.0/24",input.request.realIP)          
+         contains(input.request.path, "/")
+         net.cidr_contains("127.0.0.0/24",input.request.realIP)
       }
 ```
 
@@ -1178,7 +1181,7 @@ The following table lists input request fields that can be used in an OPA policy
 | input.request.raw_query  | string | The current http request raw query                                    | "a=1&b=2&c=3"                        |
 | input.request.query      | map    | The current http request query map                                    | {"a":1,"b":2,"c":3}                  |
 | input.request.headers    | map    | The current http request header map targeted by<br/> includedHeaders  | {"Content-Type":"application/json"}  |
-| input.request.scheme     | string | The current http request scheme                                       | "https"                              | 
+| input.request.scheme     | string | The current http request scheme                                       | "https"                              |
 | input.request.realIP     | string | The current http request client real IP                               | "127.0.0.1"                          |
 | input.request.body       | string | The current http request body string data                             | {"data":"xxx"}                       |
 
@@ -1202,7 +1205,7 @@ The following table lists input request fields that can be used in an OPA policy
 
 The `Redirector` filter is used to do HTTP redirect. `Redirector` matches request url, do replacement, and return response with status code of `3xx` and put new path in response header with key of `Location`.
 
-Here a simple example: 
+Here a simple example:
 ```yaml
 name: demo-pipeline
 kind: Pipeline
@@ -1234,13 +1237,13 @@ filters:
   kind: Redirector
   match: "^/users/([0-9]+)"
   # by default, value of matchPart is uri, supported values: uri, path, full.
-  matchPart: "full" 
+  matchPart: "full"
   replacement: "http://example.com/display?user=$1"
 ```
 
 For request with URL of `https://example.com:8080/apis/v1/user?id=1`, URI part is `/apis/v1/user?id=1`, path part is `/apis/v1/user` and full part is `https://example.com:8080/apis/v1/user?id=1`.
 
-By default, we return status code of `301` "Moved Permanently". To return status code of `302` "Found" or other `3xx`, change `statusCode` in yaml. 
+By default, we return status code of `301` "Moved Permanently". To return status code of `302` "Found" or other `3xx`, change `statusCode` in yaml.
 
 ```yaml
 name: demo-pipeline
@@ -1256,7 +1259,7 @@ filters:
   replacement: "http://example.com/display?user=$1"
 ```
 
-Following are some common used examples: 
+Following are some common used examples:
 1. URI prefix redirect
 ```yaml
 name: demo-pipeline
@@ -1355,13 +1358,96 @@ output: https://example.com/api/user/123
 | ---- | ---- | ----------- | -------- |
 | match | string | Regular expression to match request path. The syntax of the regular expression is [RE2](https://golang.org/s/re2syntax) | Yes |
 | matchPart | string | Parameter to decide which part of url used to do match, supported values: uri, full, path. Default value is uri. | No |
-| replacement | string | Replacement when the match succeeds. Placeholders like `$1`, `$2` can be used to represent the sub-matches in `regexp` | Yes | 
-| statusCode | int | Status code of response. Supported values: 301, 302, 303, 304, 307, 308. Default: 301. | No | 
+| replacement | string | Replacement when the match succeeds. Placeholders like `$1`, `$2` can be used to represent the sub-matches in `regexp` | Yes |
+| statusCode | int | Status code of response. Supported values: 301, 302, 303, 304, 307, 308. Default: 301. | No |
 ### Results
 | Value | Description |
 | ----- | ----------- |
 | redirected | The request has been redirected |
 
+
+## RedirectorV2
+
+The `RedirectorV2` filter provides advanced HTTP redirection capabilities within the Kubernetes API Gateway. It offers fine-grained control over URL components such as scheme, hostname, and path. The specifications are consistent with the [Kubernetes Gateway API's `HTTPRequestRedirectFilter`](https://gateway-api.sigs.k8s.io/reference/spec/#gateway.networking.k8s.io/v1.HTTPRequestRedirectFilter).
+
+### Configuration
+
+| Name | Type | Description | Required |
+|------|------|-------------|----------|
+| scheme | string | The protocol for the redirected request (e.g., `http` or `https`). | No |
+| hostname | string | The domain name to which the request should be redirected. To specify a port, include it in the hostname (e.g., `example.com:8080`). Note: Explicit port configurations are currently unsupported due to complexities in specification. | No |
+| statusCode | int | The HTTP status code for the redirection response. | Yes |
+| path.type | string | Determines the type of redirection. Supported values: `ReplacePrefixMatch`, `ReplaceFullPath`. | Yes |
+| path.replacePrefixMatch | string | The new prefix for the redirection. Used only with `ReplacePrefixMatch`. | Conditional |
+| path.replaceFullPath | string | The new full path for the redirection. Used only with `ReplaceFullPath`. | Conditional |
+
+### Results
+
+| Value | Description |
+|-------|-------------|
+| redirected | Indicates that the request has been redirected based on the `RedirectorV2` configuration. |
+
+
+Commmon Use-Cases:
+
+1. Replace Prefix:
+
+Substitute a prefix with `/account` and return a `302 Found` status code.
+
+```yaml
+name: demo-pipeline
+kind: Pipeline
+flow:
+- filter: redirectorv2
+filters:
+- name: redirectorv2
+  kind: RedirectorV2
+  pathPrefix: /user
+  path:
+    type: ReplacePrefixMatch
+    replacePrefixMatch: /account
+  statusCode: 302
+```
+
+2. Replace Full Path:
+
+Redirect to an absolute path `/full-path`.
+
+```yaml
+name: demo-pipeline
+kind: Pipeline
+flow:
+- filter: redirectorv2
+filters:
+- name: redirectorv2
+  kind: RedirectorV2
+  path:
+    type: ReplaceFullPath
+    replaceFullPath: /full-path
+  statusCode: 302
+```
+
+3. Domain and Scheme Redirection:
+
+Redirect to a new domain using the HTTPS protocol.
+
+```yaml
+name: demo-pipeline
+kind: Pipeline
+flow:
+- filter: redirectorv2
+filters:
+- name: redirectorv2
+  kind: RedirectorV2
+  scheme: https
+  hostname: newdomain.com
+  pathPrefix: /user
+  path:
+    type: ReplacePrefixMatch
+    replacePrefixMatch: /account
+  statusCode: 302
+```
+
 ## GRPCProxy
 
 The `GRPCProxy` filter is a proxy for gRPC backend service. It supports both unary RPCs and streaming RPCs.
@@ -1389,7 +1475,7 @@ Same as the `Proxy` filter:
 * the servers of a pool can be configured dynamically via service discovery.
 * when there are multiple servers in a pool, the pool can do a load balance between them.
 
-Because gRPC does not support the http `Connect` method, it does not support tunneling mode, 
+Because gRPC does not support the http `Connect` method, it does not support tunneling mode,
 we provide a new [load balancer](#proxyloadbalancespec) `policy.forward` to achieve a similar effect.
 
 Note that each gRPC client establishes a connection with Easegress. However,