This is an automated email from the ASF dual-hosted git repository.
Yilialinn 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 990847067 docs: update mqtt-proxy plugin docs (#13310)
990847067 is described below
commit 9908470677d2e9aa3519372353ae29aedb87659f
Author: Yilia Lin <[email protected]>
AuthorDate: Sat May 9 17:55:51 2026 +0800
docs: update mqtt-proxy plugin docs (#13310)
---
docs/en/latest/plugins/mqtt-proxy.md | 471 ++++++++++++++++++++++++++++------
docs/zh/latest/plugins/mqtt-proxy.md | 482 ++++++++++++++++++++++++++++-------
2 files changed, 785 insertions(+), 168 deletions(-)
diff --git a/docs/en/latest/plugins/mqtt-proxy.md
b/docs/en/latest/plugins/mqtt-proxy.md
index 64c4f92d2..5782ceb7b 100644
--- a/docs/en/latest/plugins/mqtt-proxy.md
+++ b/docs/en/latest/plugins/mqtt-proxy.md
@@ -5,7 +5,7 @@ keywords:
- API Gateway
- Plugin
- MQTT Proxy
-description: This document contains information about the Apache APISIX
mqtt-proxy Plugin. The `mqtt-proxy` Plugin is used for dynamic load balancing
with `client_id` of MQTT.
+description: The mqtt-proxy Plugin supports proxying and load balancing MQTT
requests to MQTT servers, supporting MQTT versions 3.1.x and 5.0.
---
<!--
@@ -27,41 +27,44 @@ description: This document contains information about the
Apache APISIX mqtt-pro
#
-->
-## Description
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/hub/mqtt-proxy"; />
+</head>
-The `mqtt-proxy` Plugin is used for dynamic load balancing with `client_id` of
MQTT. It only works in stream model.
+## Description
-This Plugin supports both the protocols
[3.1.*](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html) and
[5.0](https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html).
+The `mqtt-proxy` Plugin is an L4 Plugin that supports proxying and load
balancing MQTT requests to MQTT servers. It supports MQTT versions
[3.1.*](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html) and
[5.0](https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html). The Plugin
must be configured on a stream Route, and APISIX should enable L4 traffic
proxying.
## Attributes
-| Name | Type | Required | Description
|
-|----------------|---------|------------|-----------------------------------------------------------------------------------|
-| protocol_name | string | False | Name of the protocol. Defaults to
`MQTT`. |
-| protocol_level | integer | True | Level of the protocol. It should be
`4` for MQTT `3.1.*` and `5` for MQTT `5.0`. |
+| Name | Type | Required | Default | Description
|
+|----------------|---------|----------|---------|----------------------------------------------------------------------------------|
+| protocol_name | string | False | "MQTT" | Name of the protocol.
|
+| protocol_level | integer | True | | Level of the protocol. It
should be `4` for MQTT `3.1.*` and `5` for MQTT `5.0`. |
+
+## Examples
-## Enable Plugin
+By default, APISIX only proxies L7 traffic. Before proceeding to examples,
first ensure that you enable L4 traffic proxying in APISIX.
-To enable the Plugin, you need to first enable the `stream_proxy`
configuration in your configuration file (`conf/config.yaml`). The below
configuration represents listening on the `9100` TCP port:
+Update the configuration file as follows to enable L4 traffic proxying:
```yaml title="conf/config.yaml"
- ...
- router:
- http: 'radixtree_uri'
- ssl: 'radixtree_sni'
- proxy_mode: http&stream
- stream_proxy: # TCP/UDP proxy
- tcp: # TCP proxy port list
- - 9100
- dns_resolver:
- ...
+apisix:
+ proxy_mode: http&stream # Enable both L4 & L7 proxies
+ stream_proxy: # Configure L4 proxy
+ tcp:
+ - 9100 # Set TCP proxy listening port
```
-You can now send the MQTT request to port `9100`.
+Reload APISIX for changes to take effect. APISIX should now start listening
for L4 traffic on port `9100`.
-You can now create a stream Route and enable the `mqtt-proxy` Plugin:
+The examples below use a MQTT client from the Mosquitto project to publish and
subscribe to messages. You can download it
[here](https://mosquitto.org/download/) or use any other MQTT client of your
choice.
:::note
+
You can fetch the `admin_key` from `config.yaml` and save to an environment
variable with the following command:
```bash
@@ -70,101 +73,409 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key'
conf/config.yaml | sed 's/"/
:::
+### Proxy to a MQTT Broker
+
+The following example demonstrates how you can configure a stream Route to
proxy traffic to a hosted MQTT server and verify that APISIX can proxy MQTT
messages successfully.
+
+Create a stream Route to the MQTT server and configure the `mqtt-proxy` Plugin:
+
+<Tabs
+groupId="api"
+defaultValue="admin-api"
+values={[
+{label: 'Admin API', value: 'admin-api'},
+{label: 'ADC', value: 'adc'},
+{label: 'Ingress Controller', value: 'aic'}
+]}>
+
+<TabItem value="admin-api">
+
```shell
-curl http://127.0.0.1:9180/apisix/admin/stream_routes/1 -H "X-API-KEY:
$admin_key" -X PUT -d '
-{
+curl "http://127.0.0.1:9180/apisix/admin/stream_routes"; -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "mqtt-route-proxy",
"plugins": {
- "mqtt-proxy": {
- "protocol_name": "MQTT",
- "protocol_level": 4
- }
+ "mqtt-proxy": {
+ "protocol_name": "MQTT",
+ "protocol_level": 4
+ }
},
"upstream": {
- "type": "roundrobin",
- "nodes": [{
- "host": "127.0.0.1",
- "port": 1980,
- "weight": 1
- }]
+ "type": "roundrobin",
+ "nodes": [
+ {
+ "host": "test.mosquitto.org",
+ "port": 1883,
+ "weight": 1
+ }
+ ]
}
-}'
+ }'
```
-:::note
+</TabItem>
+
+<TabItem value="adc">
+
+```yaml title="adc.yaml"
+services:
+ - name: mqtt-service
+ upstream:
+ name: default
+ scheme: tcp
+ nodes:
+ - host: test.mosquitto.org
+ port: 1883
+ weight: 1
+ stream_routes:
+ - name: mqtt-route
+ server_port: 9100
+ plugins:
+ mqtt-proxy:
+ protocol_name: MQTT
+ protocol_level: 4
+```
+
+Synchronize the configuration to the gateway:
+
+```shell
+adc sync -f adc.yaml
+```
-If you are using Docker in macOS, then `host.docker.internal` is the right
parameter for the `host` attribute.
+</TabItem>
+
+<TabItem value="aic">
+
+<Tabs
+groupId="k8s-api"
+defaultValue="gateway-api"
+values={[
+{label: 'Gateway API', value: 'gateway-api'},
+{label: 'APISIX CRD', value: 'apisix-crd'}
+]}>
+
+<TabItem value="gateway-api">
+
+:::info
+
+Attaching L4 plugins is currently not supported with Gateway API. At the
moment, this example cannot be completed with Gateway API.
:::
-This Plugin exposes a variable `mqtt_client_id` which can be used for load
balancing as shown below:
+</TabItem>
+
+<TabItem value="apisix-crd">
+
+Use APISIX CRD to attach the `mqtt-proxy` Plugin to the stream Route:
+
+```yaml title="mqtt-proxy-ic.yaml"
+apiVersion: v1
+kind: Service
+metadata:
+ namespace: aic
+ name: mqtt-broker
+spec:
+ type: ExternalName
+ externalName: test.mosquitto.org
+ ports:
+ - name: mqtt
+ port: 1883
+ targetPort: 1883
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixRoute
+metadata:
+ namespace: aic
+ name: mqtt-route
+spec:
+ ingressClassName: apisix
+ stream:
+ - name: mqtt-route
+ protocol: TCP
+ match:
+ ingressPort: 9100
+ backend:
+ serviceName: mqtt-broker
+ servicePort: 1883
+ plugins:
+ - name: mqtt-proxy
+ enable: true
+ config:
+ protocol_name: MQTT
+ protocol_level: 4
+```
+
+Apply the configuration:
+
+```shell
+kubectl apply -f mqtt-proxy-ic.yaml
+```
+
+</TabItem>
+
+</Tabs>
+
+</TabItem>
+
+</Tabs>
+
+Open two terminal sessions. In the first one, subscribe to the test topic:
+
+```shell
+mosquitto_sub -h test.mosquitto.org -p 1883 -t "test/apisix"
+```
+
+In the other one, publish a sample message to the created Route:
+
+```shell
+mosquitto_pub -h 127.0.0.1 -p 9100 -t "test/apisix" -m "Hello APISIX"
+```
+
+You should see the message `Hello APISIX` in the first terminal.
+
+### Load Balance MQTT Traffic
+
+The following example demonstrates how you can configure a stream Route to
load balance MQTT traffic to different MQTT servers.
+
+When the Plugin is enabled, it registers a variable `mqtt_client_id` which can
be used for load balancing. MQTT connections with different client IDs will be
forwarded to different upstream nodes based on the consistent hash algorithm.
If the client ID is missing, the client IP will be used instead.
+
+Create a stream Route to two MQTT servers and configure the `mqtt-proxy`
Plugin:
+
+<Tabs
+groupId="api"
+defaultValue="admin-api"
+values={[
+{label: 'Admin API', value: 'admin-api'},
+{label: 'ADC', value: 'adc'},
+{label: 'Ingress Controller', value: 'aic'}
+]}>
+
+<TabItem value="admin-api">
```shell
-curl http://127.0.0.1:9180/apisix/admin/stream_routes/1 -H "X-API-KEY:
$admin_key" -X PUT -d '
-{
+curl "http://127.0.0.1:9180/apisix/admin/stream_routes"; -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "mqtt-route-lb",
"plugins": {
- "mqtt-proxy": {
- "protocol_name": "MQTT",
- "protocol_level": 4
- }
+ "mqtt-proxy": {
+ "protocol_name": "MQTT",
+ "protocol_level": 4
+ }
},
"upstream": {
- "type": "chash",
- "key": "mqtt_client_id",
- "nodes": [
+ "type": "chash",
+ "key": "mqtt_client_id",
+ "nodes": [
{
- "host": "127.0.0.1",
- "port": 1995,
- "weight": 1
+ "host": "test.mosquitto.org",
+ "port": 1883,
+ "weight": 1
},
{
- "host": "127.0.0.2",
- "port": 1995,
- "weight": 1
+ "host": "broker.mqtt.cool",
+ "port": 1883,
+ "weight": 1
}
- ]
+ ]
}
-}'
+ }'
+```
+
+</TabItem>
+
+<TabItem value="adc">
+
+```yaml title="adc.yaml"
+services:
+ - name: mqtt-service
+ upstream:
+ name: default
+ scheme: tcp
+ type: chash
+ key: mqtt_client_id
+ nodes:
+ - host: test.mosquitto.org
+ port: 1883
+ weight: 1
+ - host: broker.mqtt.cool
+ port: 1883
+ weight: 1
+ stream_routes:
+ - name: mqtt-route
+ server_port: 9100
+ plugins:
+ mqtt-proxy:
+ protocol_name: MQTT
+ protocol_level: 4
+```
+
+Synchronize the configuration to the gateway:
+
+```shell
+adc sync -f adc.yaml
```
-MQTT connections with different client ID will be forwarded to different nodes
based on the consistent hash algorithm. If client ID is missing, client IP is
used instead for load balancing.
+</TabItem>
+
+<TabItem value="aic">
+
+<Tabs
+groupId="k8s-api"
+defaultValue="gateway-api"
+values={[
+{label: 'Gateway API', value: 'gateway-api'},
+{label: 'APISIX CRD', value: 'apisix-crd'}
+]}>
+
+<TabItem value="gateway-api">
+
+:::info
+
+Attaching L4 plugins is currently not supported with Gateway API. At the
moment, this example cannot be completed with Gateway API.
+
+:::
+
+</TabItem>
+
+<TabItem value="apisix-crd">
+
+```yaml title="mqtt-proxy-ic.yaml"
+apiVersion: v1
+kind: Service
+metadata:
+ namespace: aic
+ name: mqtt-brokers
+spec:
+ ports:
+ - name: mqtt
+ port: 1883
+ protocol: TCP
+---
+apiVersion: discovery.k8s.io/v1
+kind: EndpointSlice
+metadata:
+ namespace: aic
+ name: mqtt-brokers-1
+ labels:
+ kubernetes.io/service-name: mqtt-brokers
+addressType: FQDN
+ports:
+ - name: mqtt
+ protocol: TCP
+ port: 1883
+endpoints:
+ - addresses:
+ - test.mosquitto.org
+ - addresses:
+ - broker.mqtt.cool
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixUpstream
+metadata:
+ namespace: aic
+ name: mqtt-brokers
+spec:
+ ingressClassName: apisix
+ loadbalancer:
+ type: chash
+ key: mqtt_client_id
+ hashOn: vars
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixRoute
+metadata:
+ namespace: aic
+ name: mqtt-route
+spec:
+ ingressClassName: apisix
+ stream:
+ - name: mqtt-route
+ protocol: TCP
+ match:
+ ingressPort: 9100
+ backend:
+ serviceName: mqtt-brokers
+ servicePort: 1883
+ plugins:
+ - name: mqtt-proxy
+ enable: true
+ config:
+ protocol_name: MQTT
+ protocol_level: 4
+```
+
+Apply the configuration:
+
+```shell
+kubectl apply -f mqtt-proxy-ic.yaml
+```
+
+</TabItem>
+
+</Tabs>
-## Enabling mTLS with mqtt-proxy plugin
+</TabItem>
-Stream proxies use TCP connections and can accept TLS. Follow the guide about
[how to accept tls over tcp
connections](../stream-proxy.md/#accept-tls-over-tcp-connection) to open a
stream proxy with enabled TLS.
+</Tabs>
-The `mqtt-proxy` plugin is enabled through TCP communications on the specified
port for the stream proxy, and will also require clients to authenticate via
TLS if `tls` is set to `true`.
+Open three terminal sessions. In the first one, subscribe to the test topic in
the first MQTT broker:
+
+```shell
+mosquitto_sub -h test.mosquitto.org -p 1883 -t "test/apisix"
+```
+
+In the second terminal, subscribe to the same topic in the second MQTT broker:
+
+```shell
+mosquitto_sub -h broker.mqtt.cool -p 1883 -t "test/apisix"
+```
+
+In the third terminal, send sample messages with two different client IDs to
verify load balancing:
+
+```shell
+mosquitto_pub -h 127.0.0.1 -p 9100 -t "test/apisix" -m "Hello APISIX" -i
"client-1"
+mosquitto_pub -h 127.0.0.1 -p 9100 -t "test/apisix" -m "Hello APISIX" -i
"client-2"
+```
+
+Because load balancing is based on a consistent hash of the MQTT client ID,
each client ID is consistently routed to one broker. You should see each
message appear in one of the two subscriber terminals, verifying that traffic
is distributed across both brokers.
+
+## Enabling mTLS with mqtt-proxy Plugin
+
+Stream proxies use TCP connections and can accept TLS. Follow the guide about
[how to accept TLS over TCP
connections](../stream-proxy.md/#accept-tls-over-tcp-connection) to open a
stream proxy with enabled TLS.
+
+The `mqtt-proxy` Plugin is enabled through TCP communications on the specified
port for the stream proxy, and will also require clients to authenticate via
TLS if `tls` is set to `true`.
Configure `ssl` providing the CA certificate and the server certificate,
together with a list of SNIs. Steps to protect `stream_routes` with `ssl` are
equivalent to the ones to [protect Routes](../mtls.md/#protect-route).
-### Create a stream_route using mqtt-proxy plugin and mTLS
+### Create a stream_route using mqtt-proxy Plugin and mTLS
-Here is an example of how create a stream_route which is using the
`mqtt-proxy` plugin, providing the CA certificate, the client certificate and
the client key (for self-signed certificates which are not trusted by your
host, use the `-k` flag):
+The following example creates a stream Route using the `mqtt-proxy` Plugin and
configures it with the CA certificate, the client certificate and the client
key (for self-signed certificates which are not trusted by your host, use the
`-k` flag):
```shell
-curl 127.0.0.1:9180/apisix/admin/stream_routes/1 -H "X-API-KEY: $admin_key" -X
PUT -d '
-{
+curl "http://127.0.0.1:9180/apisix/admin/stream_routes"; -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "mqtt-route-mtls",
"plugins": {
- "mqtt-proxy": {
- "protocol_name": "MQTT",
- "protocol_level": 4
- }
+ "mqtt-proxy": {
+ "protocol_name": "MQTT",
+ "protocol_level": 4
+ }
},
"sni": "${your_sni_name}",
"upstream": {
- "nodes": {
- "127.0.0.1:1980": 1
- },
- "type": "roundrobin"
+ "type": "roundrobin",
+ "nodes": [
+ {
+ "host": "127.0.0.1",
+ "port": 1980,
+ "weight": 1
+ }
+ ]
}
-}'
+ }'
```
The `sni` name must match one or more of the SNIs provided to the SSL object
that you created with the CA and server certificates.
-
-## Delete Plugin
-
-To remove the `mqtt-proxy` Plugin you can remove the corresponding
configuration as shown below:
-
-```shell
-curl http://127.0.0.1:9180/apisix/admin/stream_routes/1 -H "X-API-KEY:
$admin_key" -X DELETE
-```
diff --git a/docs/zh/latest/plugins/mqtt-proxy.md
b/docs/zh/latest/plugins/mqtt-proxy.md
index 193a4b396..b771b73e6 100644
--- a/docs/zh/latest/plugins/mqtt-proxy.md
+++ b/docs/zh/latest/plugins/mqtt-proxy.md
@@ -5,7 +5,7 @@ keywords:
- API 网关
- Plugin
- MQTT Proxy
-description: 本文档介绍了 Apache APISIX mqtt-proxy 插件的信息，通过 `mqtt-proxy` 插件可以使用 MQTT
的 `client_id` 进行动态负载平衡。
+description: mqtt-proxy 插件支持将 MQTT 请求代理和负载均衡到 MQTT 服务器，支持 MQTT 3.1.x 和 5.0 版本。
---
<!--
@@ -27,39 +27,41 @@ description: 本文档介绍了 Apache APISIX mqtt-proxy 插件的信息，通
#
-->
-## 描述
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/hub/mqtt-proxy"; />
+</head>
-通过 `mqtt-proxy` 插件可以使用 MQTT 的 `client_id` 进行动态负载平衡。它仅适用于 `stream` 模式。
+## 描述
-这个插件支持 MQTT
[3.1.*](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html) 及
[5.0]( https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html ) 两个协议。
+`mqtt-proxy` 插件是一个 L4 插件，支持将 MQTT 请求代理和负载均衡到 MQTT 服务器。它支持 MQTT
[3.1.*](http://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.html) 和
[5.0](https://docs.oasis-open.org/mqtt/mqtt/v5.0/mqtt-v5.0.html)
版本。该插件必须配置在流式路由上，且 APISIX 需要启用 L4 流量代理。
## 属性
-| 名称 | 类型 | 必选项 | 描述
|
-| -------------- | ------- | ----- |
--------------------------------------------------- |
-| protocol_name | string | 否 | 协议名称，默认为 `MQTT`。
|
-| protocol_level | integer | 是 | 协议级别，MQTT `3.1.*` 为 `4`，MQTT `5.0` 应是`5`。
|
+| 名称 | 类型 | 必选项 | 默认值 | 描述
|
+|----------------|---------|--------|---------|-------------------------------------------------------------|
+| protocol_name | string | 否 | "MQTT" | 协议名称。
|
+| protocol_level | integer | 是 | | 协议级别。MQTT `3.1.*` 应设为 `4`，MQTT
`5.0` 应设为 `5`。 |
+
+## 示例
-## 启用插件
+默认情况下，APISIX 仅代理 L7 流量。在操作前，请先确保在 APISIX 中启用了 L4 流量代理。
-为了启用该插件，需要先在配置文件（`./conf/config.yaml`）中加载 `stream_proxy` 相关配置。以下配置代表监听 `9100`
TCP 端口：
+按如下方式更新配置文件以启用 L4 流量代理：
-```yaml title="./conf/config.yaml"
- ...
- router:
- http: 'radixtree_uri'
- ssl: 'radixtree_sni'
- proxy_mode: http&stream
- stream_proxy: # TCP/UDP proxy
- tcp: # TCP proxy port list
- - 9100
- dns_resolver:
- ...
+```yaml title="conf/config.yaml"
+apisix:
+ proxy_mode: http&stream # 同时启用 L4 和 L7 代理
+ stream_proxy: # 配置 L4 代理
+ tcp:
+ - 9100 # 设置 TCP 代理监听端口
```
-现在你可以将请求发送到 `9100` 端口。
+重载 APISIX 使配置生效。APISIX 现在应开始在 `9100` 端口监听 L4 流量。
-你可以创建一个 stream 路由并启用 `mqtt-proxy` 插件。
+以下示例使用来自 Mosquitto 项目的 MQTT
客户端发布和订阅消息。你可以在[这里](https://mosquitto.org/download/)下载，或使用其他 MQTT 客户端。
:::note
@@ -71,105 +73,409 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key'
conf/config.yaml | sed 's/"/
:::
+### 代理到 MQTT Broker
+
+以下示例演示如何配置流式路由，将流量代理到托管的 MQTT 服务器，并验证 APISIX 能够成功代理 MQTT 消息。
+
+创建流式路由并配置 `mqtt-proxy` 插件：
+
+<Tabs
+groupId="api"
+defaultValue="admin-api"
+values={[
+{label: 'Admin API', value: 'admin-api'},
+{label: 'ADC', value: 'adc'},
+{label: 'Ingress Controller', value: 'aic'}
+]}>
+
+<TabItem value="admin-api">
+
```shell
-curl http://127.0.0.1:9180/apisix/admin/stream_routes/1 \
--H "X-API-KEY: $admin_key" -X PUT -d '
-{
+curl "http://127.0.0.1:9180/apisix/admin/stream_routes"; -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "mqtt-route-proxy",
"plugins": {
- "mqtt-proxy": {
- "protocol_name": "MQTT",
- "protocol_level": 4
- }
+ "mqtt-proxy": {
+ "protocol_name": "MQTT",
+ "protocol_level": 4
+ }
},
"upstream": {
- "type": "roundrobin",
- "nodes": [{
- "host": "127.0.0.1",
- "port": 1980,
- "weight": 1
- }]
+ "type": "roundrobin",
+ "nodes": [
+ {
+ "host": "test.mosquitto.org",
+ "port": 1883,
+ "weight": 1
+ }
+ ]
}
-}'
+ }'
+```
+
+</TabItem>
+
+<TabItem value="adc">
+
+```yaml title="adc.yaml"
+services:
+ - name: mqtt-service
+ upstream:
+ name: default
+ scheme: tcp
+ nodes:
+ - host: test.mosquitto.org
+ port: 1883
+ weight: 1
+ stream_routes:
+ - name: mqtt-route
+ server_port: 9100
+ plugins:
+ mqtt-proxy:
+ protocol_name: MQTT
+ protocol_level: 4
+```
+
+将配置同步到网关：
+
+```shell
+adc sync -f adc.yaml
+```
+
+</TabItem>
+
+<TabItem value="aic">
+
+<Tabs
+groupId="k8s-api"
+defaultValue="gateway-api"
+values={[
+{label: 'Gateway API', value: 'gateway-api'},
+{label: 'APISIX CRD', value: 'apisix-crd'}
+]}>
+
+<TabItem value="gateway-api">
+
+:::info
+
+Gateway API 目前不支持配置 L4 插件。此示例暂时无法通过 Gateway API 完成。
+
+:::
+
+</TabItem>
+
+<TabItem value="apisix-crd">
+
+使用 APISIX CRD 将 `mqtt-proxy` 插件配置到流式路由：
+
+```yaml title="mqtt-proxy-ic.yaml"
+apiVersion: v1
+kind: Service
+metadata:
+ namespace: aic
+ name: mqtt-broker
+spec:
+ type: ExternalName
+ externalName: test.mosquitto.org
+ ports:
+ - name: mqtt
+ port: 1883
+ targetPort: 1883
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixRoute
+metadata:
+ namespace: aic
+ name: mqtt-route
+spec:
+ ingressClassName: apisix
+ stream:
+ - name: mqtt-route
+ protocol: TCP
+ match:
+ ingressPort: 9100
+ backend:
+ serviceName: mqtt-broker
+ servicePort: 1883
+ plugins:
+ - name: mqtt-proxy
+ enable: true
+ config:
+ protocol_name: MQTT
+ protocol_level: 4
```
-如果你在 macOS 中使用 Docker，则 `host.docker.internal` 是 `host` 的正确属性。
+应用配置：
+
+```shell
+kubectl apply -f mqtt-proxy-ic.yaml
+```
+
+</TabItem>
+
+</Tabs>
+
+</TabItem>
+
+</Tabs>
+
+打开两个终端会话。在第一个终端中，订阅测试主题：
+
+```shell
+mosquitto_sub -h test.mosquitto.org -p 1883 -t "test/apisix"
+```
+
+在另一个终端中，向创建的路由发布示例消息：
+
+```shell
+mosquitto_pub -h 127.0.0.1 -p 9100 -t "test/apisix" -m "Hello APISIX"
+```
+
+你应该在第一个终端中看到消息 `Hello APISIX`。
+
+### 对 MQTT 流量进行负载均衡
+
+以下示例演示如何配置流式路由，将 MQTT 流量负载均衡到不同的 MQTT 服务器。
+
+启用该插件后，它会注册一个变量 `mqtt_client_id`，可用于负载均衡。不同客户端 ID 的 MQTT
连接将根据一致性哈希算法转发到不同的上游节点。如果客户端 ID 缺失，则使用客户端 IP 代替。
+
+创建流式路由，并将 `mqtt-proxy` 插件配置为指向两个 MQTT 服务器：
+
+<Tabs
+groupId="api"
+defaultValue="admin-api"
+values={[
+{label: 'Admin API', value: 'admin-api'},
+{label: 'ADC', value: 'adc'},
+{label: 'Ingress Controller', value: 'aic'}
+]}>
-该插件暴露了一个变量 `mqtt_client_id`，你可以使用它来通过客户端 ID 进行负载均衡。比如：
+<TabItem value="admin-api">
```shell
-curl http://127.0.0.1:9180/apisix/admin/stream_routes/1 \
--H "X-API-KEY: $admin_key" -X PUT -d '
-{
+curl "http://127.0.0.1:9180/apisix/admin/stream_routes"; -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "mqtt-route-lb",
"plugins": {
- "mqtt-proxy": {
- "protocol_name": "MQTT",
- "protocol_level": 4
- }
+ "mqtt-proxy": {
+ "protocol_name": "MQTT",
+ "protocol_level": 4
+ }
},
"upstream": {
- "type": "chash",
- "key": "mqtt_client_id",
- "nodes": [
+ "type": "chash",
+ "key": "mqtt_client_id",
+ "nodes": [
{
- "host": "127.0.0.1",
- "port": 1995,
- "weight": 1
+ "host": "test.mosquitto.org",
+ "port": 1883,
+ "weight": 1
},
{
- "host": "127.0.0.2",
- "port": 1995,
- "weight": 1
+ "host": "broker.mqtt.cool",
+ "port": 1883,
+ "weight": 1
}
- ]
+ ]
}
-}'
+ }'
+```
+
+</TabItem>
+
+<TabItem value="adc">
+
+```yaml title="adc.yaml"
+services:
+ - name: mqtt-service
+ upstream:
+ name: default
+ scheme: tcp
+ type: chash
+ key: mqtt_client_id
+ nodes:
+ - host: test.mosquitto.org
+ port: 1883
+ weight: 1
+ - host: broker.mqtt.cool
+ port: 1883
+ weight: 1
+ stream_routes:
+ - name: mqtt-route
+ server_port: 9100
+ plugins:
+ mqtt-proxy:
+ protocol_name: MQTT
+ protocol_level: 4
```
-不同客户端 ID 的 MQTT 连接将通过一致性哈希算法被转发到不同的节点。如果客户端 ID 为空，将会通过客户端 IP 进行均衡。
+将配置同步到网关：
-## 使用 mqtt-proxy 插件启用 mTLS
+```shell
+adc sync -f adc.yaml
+```
+
+</TabItem>
-Stream 代理可以使用 TCP 连接并且支持 TLS。请参考 [如何通过 tcp 连接接受
tls](../stream-proxy.md/#accept-tls-over-tcp-connection) 打开启用了 TLS 的 stream 代理。
+<TabItem value="aic">
-`mqtt-proxy` 插件通过 Stream 代理的指定端口的 TCP 通信启用，如果 `tls` 设置为 `true`，则还要求客户端通过 TLS
进行身份验证。
+<Tabs
+groupId="k8s-api"
+defaultValue="gateway-api"
+values={[
+{label: 'Gateway API', value: 'gateway-api'},
+{label: 'APISIX CRD', value: 'apisix-crd'}
+]}>
-配置 `ssl` 提供 CA 证书和服务器证书，以及 SNI 列表。使用 `ssl` 保护 `stream_routes` 的步骤等同于 [protect
Routes](../mtls.md/#protect-route)。
+<TabItem value="gateway-api">
-### 创建 stream_route 并配置 mqtt-proxy 插件和 mTLS
+:::info
-通过以下示例可以创建一个配置了 `mqtt-proxy` 插件的 `stream_route`，需要提供 CA
证书、客户端证书和客户端密钥（对于不受主机信任的自签名证书，请使用 -k 选项）：
+Gateway API 目前不支持配置 L4 插件。此示例暂时无法通过 Gateway API 完成。
+
+:::
+
+</TabItem>
+
+<TabItem value="apisix-crd">
+
+```yaml title="mqtt-proxy-ic.yaml"
+apiVersion: v1
+kind: Service
+metadata:
+ namespace: aic
+ name: mqtt-brokers
+spec:
+ ports:
+ - name: mqtt
+ port: 1883
+ protocol: TCP
+---
+apiVersion: discovery.k8s.io/v1
+kind: EndpointSlice
+metadata:
+ namespace: aic
+ name: mqtt-brokers-1
+ labels:
+ kubernetes.io/service-name: mqtt-brokers
+addressType: FQDN
+ports:
+ - name: mqtt
+ protocol: TCP
+ port: 1883
+endpoints:
+ - addresses:
+ - test.mosquitto.org
+ - addresses:
+ - broker.mqtt.cool
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixUpstream
+metadata:
+ namespace: aic
+ name: mqtt-brokers
+spec:
+ ingressClassName: apisix
+ loadbalancer:
+ type: chash
+ key: mqtt_client_id
+ hashOn: vars
+---
+apiVersion: apisix.apache.org/v2
+kind: ApisixRoute
+metadata:
+ namespace: aic
+ name: mqtt-route
+spec:
+ ingressClassName: apisix
+ stream:
+ - name: mqtt-route
+ protocol: TCP
+ match:
+ ingressPort: 9100
+ backend:
+ serviceName: mqtt-brokers
+ servicePort: 1883
+ plugins:
+ - name: mqtt-proxy
+ enable: true
+ config:
+ protocol_name: MQTT
+ protocol_level: 4
+```
+
+应用配置：
```shell
-curl 127.0.0.1:9180/apisix/admin/stream_routes/1 \
--H "X-API-KEY: $admin_key" -X PUT -d '
-{
- "plugins": {
- "mqtt-proxy": {
- "protocol_name": "MQTT",
- "protocol_level": 4
- }
- },
- "sni": "${your_sni_name}",
- "upstream": {
- "nodes": {
- "127.0.0.1:1980": 1
- },
- "type": "roundrobin"
- }
-}'
+kubectl apply -f mqtt-proxy-ic.yaml
```
-:::note 注意
+</TabItem>
-`sni` 名称必须与提供的 CA 和服务器证书创建的 SSL 对象的一个或多个 SNI 匹配。
+</Tabs>
-:::
+</TabItem>
+
+</Tabs>
+
+打开三个终端会话。在第一个终端中，订阅第一个 MQTT broker 的测试主题：
-## 删除插件
+```shell
+mosquitto_sub -h test.mosquitto.org -p 1883 -t "test/apisix"
+```
-当你需要删除该插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：
+在第二个终端中，订阅第二个 MQTT broker 的相同主题：
```shell
-curl http://127.0.0.1:9180/apisix/admin/stream_routes/1 \
--H "X-API-KEY: $admin_key" -X DELETE
+mosquitto_sub -h broker.mqtt.cool -p 1883 -t "test/apisix"
```
+
+在第三个终端中，使用两个不同的客户端 ID 发送示例消息以验证负载均衡：
+
+```shell
+mosquitto_pub -h 127.0.0.1 -p 9100 -t "test/apisix" -m "Hello APISIX" -i
"client-1"
+mosquitto_pub -h 127.0.0.1 -p 9100 -t "test/apisix" -m "Hello APISIX" -i
"client-2"
+```
+
+由于负载均衡基于 MQTT 客户端 ID 的一致性哈希，每个客户端 ID 会被一致地路由到同一个
broker。你应该看到每条消息出现在两个订阅终端之一，从而验证流量已分发到两个 broker。
+
+## 使用 mqtt-proxy 插件启用 mTLS
+
+流式代理使用 TCP 连接，可以支持 TLS。请参考[如何通过 TCP 连接接受
TLS](../stream-proxy.md/#accept-tls-over-tcp-connection)，打开启用了 TLS 的流式代理。
+
+`mqtt-proxy` 插件通过流式代理指定端口上的 TCP 通信启用。如果 `tls` 设置为 `true`，还要求客户端通过 TLS 进行身份验证。
+
+配置 `ssl` 以提供 CA 证书和服务器证书，以及 SNI 列表。使用 `ssl` 保护 `stream_routes`
的步骤等同于[保护路由](../mtls.md/#protect-route)。
+
+### 创建使用 mqtt-proxy 插件和 mTLS 的 stream_route
+
+以下示例创建了一个使用 `mqtt-proxy` 插件的 stream_route，并提供 CA
证书、客户端证书和客户端密钥（对于不受主机信任的自签名证书，请使用 `-k` 选项）：
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/stream_routes"; -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "mqtt-route-mtls",
+ "plugins": {
+ "mqtt-proxy": {
+ "protocol_name": "MQTT",
+ "protocol_level": 4
+ }
+ },
+ "sni": "${your_sni_name}",
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": [
+ {
+ "host": "127.0.0.1",
+ "port": 1980,
+ "weight": 1
+ }
+ ]
+ }
+ }'
+```
+
+`sni` 名称必须与使用 CA 和服务器证书创建的 SSL 对象的一个或多个 SNI 匹配。
