Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add filter RedirectorV2 #1116

Merged
merged 1 commit into from
Oct 31, 2023
Merged

Add filter RedirectorV2 #1116

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
118 changes: 102 additions & 16 deletions docs/07.Reference/7.02.Filters.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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)
}
```

Expand All @@ -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"} |

Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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,
Expand Down
Loading
Loading