This is an automated email from the ASF dual-hosted git repository.
spacewander 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 34ab8c6 docs: improve stream proxy filtering with example (#5783)
34ab8c6 is described below
commit 34ab8c6218e8a5679b58eb9473744f5216492ec2
Author: Bisakh <[email protected]>
AuthorDate: Tue Dec 14 06:33:12 2021 +0530
docs: improve stream proxy filtering with example (#5783)
---
docs/en/latest/admin-api.md | 10 +++---
docs/en/latest/stream-proxy.md | 71 ++++++++++++++++++++++++++++++++++++++++--
2 files changed, 75 insertions(+), 6 deletions(-)
diff --git a/docs/en/latest/admin-api.md b/docs/en/latest/admin-api.md
index 20c0933..b0fa7f9 100644
--- a/docs/en/latest/admin-api.md
+++ b/docs/en/latest/admin-api.md
@@ -977,11 +977,13 @@ By default, this API only returns the http plugins. If
you need stream plugins,
| Parameter | Required | Type | Description | Example |
| ---------------- | ------| -------- | ------| -----|
-| remote_addr | False | IP/CIDR | client IP | "127.0.0.1/32" or
"127.0.0.1" |
-| server_addr | False | IP/CIDR | server IP | "127.0.0.1/32" or
"127.0.0.1" |
-| server_port | False | Integer | server port | 9090 |
-| sni | False | Host | server name indication | "test.com" |
| upstream | False | Upstream | Upstream configuration, see
[Upstream](architecture-design/upstream.md) for more details | |
| upstream_id | False | Upstream | specify the upstream id, see
[Upstream](architecture-design/upstream.md) for more details | |
+| remote_addr | False | IP/CIDR | Filter option: forward to upstream if
client IP matches | "127.0.0.1/32" or "127.0.0.1" |
+| server_addr | False | IP/CIDR | Filter option: forward to upstream if
APISIX server IP matches with server_addr | "127.0.0.1/32" or "127.0.0.1" |
+| server_port | False | Integer | Filter option: forward to upstream if
APISIX server port matches with server_port | 9090 |
+| sni | False | Host | server name indication | "test.com" |
+
+To know more about how the filter works, see the documentation
[here](./stream-proxy.md#more-route-match-options)
[Back to TOC](#table-of-contents)
diff --git a/docs/en/latest/stream-proxy.md b/docs/en/latest/stream-proxy.md
index 291b9c4..4b32a00 100644
--- a/docs/en/latest/stream-proxy.md
+++ b/docs/en/latest/stream-proxy.md
@@ -74,7 +74,11 @@ For more use cases, please take a look at [test
case](https://github.com/apache/
## More route match options
-And we can add more options to match a route.
+And we can add more options to match a route. Currently stream route
configuration supports 3 fields for filtering:
+
+- 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:
@@ -92,7 +96,70 @@ 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
address is `127.0.0.1` and the server port is equal to `2000`.
+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:
+
+1. Put this config inside `config.yaml`
+
+ ```yaml
+ apisix:
+ stream_proxy: # TCP/UDP proxy
+ tcp: # TCP proxy address list
+ - 9100 # by default uses 0.0.0.0
+ - "127.0.0.10:9101"
+ ```
+
+2. Now run a mysql docker container and expose port 3306 to the host
+
+ ```shell
+ $ docker run --name mysql -e MYSQL_ROOT_PASSWORD=toor -p 3306:3306 -d mysql
+ # check it using a mysql client that it works
+ $ mysql --host=127.0.0.1 --port=3306 -u root -p
+ Enter password:
+ Welcome to the MySQL monitor. Commands end with ; or \g.
+ Your MySQL connection id is 25
+ ...
+ mysql>
+ ```
+
+3. Now we are going to create a stream route with server filtering:
+
+ ```shell
+ curl http://127.0.0.1:9080/apisix/admin/stream_routes/1 -H 'X-API-KEY:
edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+ {
+ "server_addr": "127.0.0.10",
+ "server_port": 9101,
+ "upstream": {
+ "nodes": {
+ "127.0.0.1:3306": 1
+ },
+ "type": "roundrobin"
+ }
+ }'
+ ```
+
+ It only forwards the request to the mysql upstream whenever a connection is
received at APISIX server `127.0.0.10` and port `9101`. Let's test that
behaviour:
+
+4. Making a request to 9100 (stream proxy port enabled inside config.yaml),
filter matching fails.
+
+ ```shell
+ $ mysql --host=127.0.0.1 --port=9100 -u root -p
+ Enter password:
+ ERROR 2013 (HY000): Lost connection to MySQL server at 'reading initial
communication packet', system error: 2
+
+ ```
+
+ Instead making a request to the APISIX host and port where the filter
matching succeeds:
+
+ ```shell
+ mysql --host=127.0.0.10 --port=9101 -u root -p
+ Enter password:
+ Welcome to the MySQL monitor. Commands end with ; or \g.
+ Your MySQL connection id is 26
+ ...
+ mysql>
+ ```
Read [Admin API's Stream Route section](./admin-api.md#stream-route) for the
complete options list.
