docs: improve stream route/proxy (#4389)

Signed-off-by: spacewander <spacewanderlzx@gmail.com>
apache · Oct 25, 2021 · 24bd8d6 · 24bd8d6
1 parent d134b93
commit 24bd8d6
Show file tree

Hide file tree

Showing 4 changed files with 70 additions and 8 deletions.
diff --git a/docs/en/latest/admin-api.md b/docs/en/latest/admin-api.md
@@ -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
 
@@ -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)
diff --git a/docs/en/latest/stream-proxy.md b/docs/en/latest/stream-proxy.md
@@ -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.
@@ -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 '
@@ -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.
diff --git a/docs/zh/latest/admin-api.md b/docs/zh/latest/admin-api.md
@@ -33,6 +33,7 @@ title: Admin API
 - [Plugin Config](#plugin-config)
 - [Plugin Metadata](#plugin-metadata)
 - [Plugin](#plugin)
+- [Stream Route](#stream-route)
 
 ## Description
 
@@ -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](#目录)
diff --git a/docs/zh/latest/stream-proxy.md b/docs/zh/latest/stream-proxy.md
@@ -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 '
@@ -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)。