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.

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

docs: updated Stream Proxy doc #9367

Merged
merged 7 commits into from
May 6, 2023
Merged
Changes from all commits
Commits
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
53 changes: 30 additions & 23 deletions docs/en/latest/stream-proxy.md
Original file line number Diff line number Diff line change
Expand Up @@ -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"
```

Expand All @@ -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:

Expand All @@ -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`

Expand Down