This is an automated email from the ASF dual-hosted git repository.
juzhiyuan pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new fd24f3c50 docs: updated Stream Proxy doc (#9367)
fd24f3c50 is described below
commit fd24f3c504c79fe641191f5f5ce79081cadb32cf
Author: Traky Deng <trakyd...@gmail.com>
AuthorDate: Sat May 6 16:13:40 2023 +0800
docs: updated Stream Proxy doc (#9367)
---
docs/en/latest/stream-proxy.md | 53 ++++++++++++++++++++++++------------------
1 file changed, 30 insertions(+), 23 deletions(-)
diff --git a/docs/en/latest/stream-proxy.md b/docs/en/latest/stream-proxy.md
index 0ab87b8df..c68173d09 100644
--- a/docs/en/latest/stream-proxy.md
+++ b/docs/en/latest/stream-proxy.md
@@ -21,23 +21,24 @@ title: Stream Proxy
#
-->
-TCP is the protocol for many popular applications and services, such as LDAP,
MySQL, and RTMP. UDP (User Datagram Protocol) is the protocol for many popular
non-transactional applications, such as DNS, syslog, and RADIUS.
+A stream proxy operates at the transport layer, handling stream-oriented
traffic based on TCP and UDP protocols. TCP is used for many applications and
services, such as LDAP, MySQL, and RTMP. UDP is used for many popular
non-transactional applications, such as DNS, syslog, and RADIUS.
-APISIX can dynamically load balancing TCP/UDP proxy. In Nginx world, we call
TCP/UDP proxy to stream proxy, we followed this statement.
+APISIX can serve as a stream proxy, in addition to being an application layer
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 stream proxy is enabled.
+By default, stream proxy is disabled.
+
+To enable the option, add the `apisix.stream_proxy` option in
`conf/config.yaml` and specify a list of addresses which APISIX should act as a
stream proxy and listen for incoming requests.
```yaml
apisix:
- stream_proxy: # TCP/UDP proxy
- tcp: # TCP proxy address list
- - 9100
+ stream_proxy:
+ tcp:
+ - 9100 # listen on 9100 ports of all network interfaces for TCP requests
- "127.0.0.1:9101"
- udp: # UDP proxy address list
- - 9200
+ udp:
+ - 9200 # listen on 9200 ports of all network interfaces for UDP requests
- "127.0.0.1:9211"
```
@@ -48,40 +49,46 @@ If you have set the `enable_admin` to false, and need to
enable both HTTP and st
```yaml
apisix:
enable_admin: false
- stream_proxy: # TCP/UDP proxy
+ stream_proxy:
only: false
- tcp: # TCP proxy address list
+ tcp:
- 9100
```
-## How to set route?
+If `apisix.stream_proxy` is undefined in `conf/config.yaml`, you will
encounter an error similar to the following and not be able to add a stream
route:
-Here is a mini example:
+```
+{"error_msg":"stream mode is disabled, can not add stream routes"}
+```
+
+## How to set a route?
+
+You can create a stream route using the Admin API `/stream_routes` endpoint.
For example:
```shell
curl http://127.0.0.1:9180/apisix/admin/stream_routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
- "remote_addr": "127.0.0.1",
+ "remote_addr": "192.168.5.3",
"upstream": {
"nodes": {
- "127.0.0.1:1995": 1
+ "192.168.4.10:1995": 1
},
"type": "roundrobin"
}
}'
```
-It means APISIX will proxy the request to `127.0.0.1:1995` which the client
remote address is `127.0.0.1`.
+With this configuration, APISIX would only forward the request to the upstream
service at `192.168.4.10:1995` if and only if the request is sent from
`192.168.5.3`. See the next section to learn more about filtering options.
-For more use cases, please take a look at [test
case](https://github.com/apache/apisix/blob/master/t/stream-node/sanity.t).
+More examples can be found in [test
cases](https://github.com/apache/apisix/blob/master/t/stream-node/sanity.t).
-## More route match options
+## More stream route filtering options
-And we can add more options to match a route. Currently stream route
configuration supports 3 fields for filtering:
+Currently there are three attributes in stream routes that can be used for
filtering requests:
-- server_addr: The address of the APISIX server that accepts the L4 stream
connection.
-- server_port: The port of the APISIX server that accepts the L4 stream
connection.
-- remote_addr: The address of client from which the request has been made.
+- `server_addr`: The address of the APISIX server that accepts the L4 stream
connection.
+- `server_port`: The port of the APISIX server that accepts the L4 stream
connection.
+- `remote_addr`: The address of client from which the request has been made.
Here is an example:
@@ -101,7 +108,7 @@ curl http://127.0.0.1:9180/apisix/admin/stream_routes/1 -H
'X-API-KEY: edd1c9f03
It means APISIX will proxy the request to `127.0.0.1:1995` when the server
address is `127.0.0.1` and the server port is equal to `2000`.
-Let's take another real world example:
+Here is an example with MySQL:
1. Put this config inside `config.yaml`
