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

docs: improve stream route/proxy #4389

Merged
merged 1 commit into from
Jun 9, 2021
Merged

docs: improve stream route/proxy #4389

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
29 changes: 28 additions & 1 deletion docs/en/latest/admin-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,9 +30,10 @@ title: Admin API
- [Upstream](#upstream)
- [SSL](#ssl)
- [Global Rule](#global-rule)
- [Plugin config](#plugin-config)
- [Plugin Config](#plugin-config)
- [Plugin Metadata](#plugin-metadata)
- [Plugin](#plugin)
- [Stream Route](#stream-route)

## Description

Expand Down Expand Up @@ -938,3 +939,29 @@ $ curl "http://127.0.0.1:9080/apisix/admin/plugins/key-auth" -H 'X-API-KEY:
| GET | /apisix/admin/plugins?all=true | NULL | Fetch resource |

[Back to TOC](#table-of-contents)

## Stream Route

*API*：/apisix/admin/stream_routes/{id}

*Description*：Stream Route is the route used in the stream proxy. See [Stream Proxy](./stream-proxy.md) for the details.

### Request Methods

| Method | Request URI | Request Body | Description |
| ------ | -------------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | /apisix/admin/stream_routes | NULL | Fetch resource list |
| GET | /apisix/admin/stream_routes/{id} | NULL | Fetch resource |
| PUT | /apisix/admin/stream_routes/{id} | {...} | Create resource by ID |
| POST | /apisix/admin/stream_routes | {...} | Create resource, and ID is generated by server |
| DELETE | /apisix/admin/stream_routes/{id} | NULL | Remove resource |

### Request Body Parameters

| Parameter | Required | Type | Description | Example |
| ---------------- | ------| -------- | ------| -----|
| remote_addr | False | IP | client IP | "127.0.0.1" |
| server_addr | False | IP | server IP | "127.0.0.1" |
| server_port | False | Integer | server port | 9090 |

[Back to TOC](#table-of-contents)
12 changes: 8 additions & 4 deletions docs/en/latest/stream-proxy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ TCP is the protocol for many popular applications and services, such as LDAP, My

APISIX can dynamic load balancing TCP/UDP proxy. In Nginx world, we call TCP/UDP proxy to stream proxy, we followed this statement.

## How to enable Stream proxy?
## How to enable stream proxy?

Setting the `stream_proxy` option in `conf/config.yaml`, specify a list of addresses that require dynamic proxy.
By default, no any stream proxy is enabled.
Expand Down Expand Up @@ -62,9 +62,11 @@ It means APISIX will proxy the request to `127.0.0.1:1995` which the client remo

For more use cases, please take a look at [test case](https://github.com/apache/apisix/blob/master/t/stream-node/sanity.t).

## More Limit Options
## More route match options

And we can add more limit options to match a route, here is an example:
And we can add more options to match a route.

Here is an example:

```shell
curl http://127.0.0.1:9080/apisix/admin/stream_routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
Expand All @@ -80,4 +82,6 @@ curl http://127.0.0.1:9080/apisix/admin/stream_routes/1 -H 'X-API-KEY: edd1c9f03
}'
```

It means APISIX will proxy the request to `127.0.0.1:1995` which the server remote address is `127.0.0.1` and the server port is equal `2000`.
It means APISIX will proxy the request to `127.0.0.1:1995` which the server address is `127.0.0.1` and the server port is equal `2000`.

Read [Admin API's Stream Route section](./admin-api.md#stream-route) for the complete options list.
27 changes: 27 additions & 0 deletions docs/zh/latest/admin-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@ title: Admin API
- [Plugin Config](#plugin-config)
- [Plugin Metadata](#plugin-metadata)
- [Plugin](#plugin)
- [Stream Route](#stream-route)

## Description

Expand Down Expand Up @@ -945,3 +946,29 @@ $ curl "http://127.0.0.1:9080/apisix/admin/plugins/key-auth" -H 'X-API-KEY:
| GET | /apisix/admin/plugins?all=true | 无 | 获取资源 |

[Back to TOC](#目录)

## Stream Route

*API*：/apisix/admin/stream_routes/{id}

*Description*：Stream Route 是用于 TCP/UDP 动态代理的路由。参见 [TCP/UDP 动态代理](./stream-proxy.md) 一节.

### 请求方法

| 名字 | 请求 uri | 请求 body | 说明 |
| ------ | -------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GET | /apisix/admin/stream_routes | 无 | 获取资源列表 |
| GET | /apisix/admin/stream_routes/{id} | 无 | 获取资源 |
| PUT | /apisix/admin/stream_routes/{id} | {...} | 根据 id 创建资源 |
| POST | /apisix/admin/stream_routes | {...} | 创建资源，id 由后台服务自动生成 |
| DELETE | /apisix/admin/stream_routes/{id} | 无 | 删除资源 |

### body 请求参数

| 名字 | 可选项| 类型 | 说明 | 示例 |
| ---------------- | ------| -------- | ------| -----|
| remote_addr | 可选 | IP | 客户端 IP 地址 | "127.0.0.1" |
| server_addr | 可选 | IP | 服务端 IP 地址 | "127.0.0.1" |
| server_port | 可选 | 整数 | 服务端端口 | 9090 |

[Back to TOC](#目录)
10 changes: 7 additions & 3 deletions docs/zh/latest/stream-proxy.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,9 +60,11 @@ curl http://127.0.0.1:9080/apisix/admin/stream_routes/1 -H 'X-API-KEY: edd1c9f03
例子中 APISIX 对客户端 IP 为 `127.0.0.1` 的请求代理转发到上游主机 `127.0.0.1:1995`。
更多用例，请参照 [test case](../../../t/stream-node/sanity.t).

## 更多限制选项
## 更多 route 匹配选项

我们可以添加更多的选项来匹配 route ，例如
我们可以添加更多的选项来匹配 route 。

例如

```shell
curl http://127.0.0.1:9080/apisix/admin/stream_routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
Expand All @@ -78,4 +80,6 @@ curl http://127.0.0.1:9080/apisix/admin/stream_routes/1 -H 'X-API-KEY: edd1c9f03
}'
```

例子中 APISIX 把上游地址 `127.0.0.1:1995` 代理成地址为 `127.0.0.1`, 端口为 `2000`
例子中 APISIX 会把服务器地址为 `127.0.0.1`, 端口为 `2000` 代理到上游地址 `127.0.0.1:1995`。

完整的匹配选项列表参见 [Admin API 的 Stream Route](./admin-api.md#stream-route)。