From 00a9d5ccb6e3c57b8a8cf5059ee57ff9f09bc7e3 Mon Sep 17 00:00:00 2001 From: Yilia Lin Date: Tue, 28 Apr 2026 11:00:05 +0800 Subject: [PATCH 1/4] docs: update mqtt-proxy plugin docs - Full port from API7 docs with 2 structured examples: * Proxy to a MQTT Broker * Load Balance MQTT Traffic - Add attributes table Default column with 'MQTT' for protocol_name - Fix description to describe L4 plugin with stream Route requirement - Rewrite examples to use PUT /stream_routes with id in body and admin_key - Consolidate config.yaml snippet into examples preamble - Keep existing mTLS section (APISIX-specific content) - Remove Delete Plugin section - Add canonical link --- docs/en/latest/plugins/mqtt-proxy.md | 196 ++++++++++++++---------- docs/zh/latest/plugins/mqtt-proxy.md | 213 +++++++++++++++------------ 2 files changed, 236 insertions(+), 173 deletions(-) diff --git a/docs/en/latest/plugins/mqtt-proxy.md b/docs/en/latest/plugins/mqtt-proxy.md index 64c4f92d2277..64568561b6ad 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. --- -## Description + + + -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 +70,135 @@ 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: + ```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", "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": { + "test.mosquitto.org:1883": 1 + } } -}' + }' ``` -:::note +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" +``` -If you are using Docker in macOS, then `host.docker.internal` is the right parameter for the `host` attribute. +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" +``` -This Plugin exposes a variable `mqtt_client_id` which can be used for load balancing as shown below: +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: ```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", "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 } - ] + ] } -}' + }' ``` -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. +Open three terminal sessions. In the first one, subscribe to the test topic in the first MQTT broker: -## Enabling mTLS with mqtt-proxy plugin +```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, run the following commands a few times to send sample messages to the Route: + +```shell +mosquitto_pub -h 127.0.0.1 -p 9100 -t "test/apisix" -m "Hello APISIX" +``` -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. +You should see the message `Hello APISIX` in both terminals, verifying the traffic was load balanced. -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`. +## 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", "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": { + "127.0.0.1:1980": 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 193a4b3966cc..5c37dcbb4d41 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 版本。 --- -## 描述 + + + -通过 `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`。 | - -## 启用插件 - -为了启用该插件，需要先在配置文件（`./conf/config.yaml`）中加载 `stream_proxy` 相关配置。以下配置代表监听 `9100` TCP 端口： - -```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: - ... +| 名称 | 类型 | 必选项 | 默认值 | 描述 | +|----------------|---------|--------|---------|-------------------------------------------------------------| +| protocol_name | string | 否 | "MQTT" | 协议名称。 | +| protocol_level | integer | 是 | | 协议级别。MQTT `3.1.*` 应设为 `4`，MQTT `5.0` 应设为 `5`。 | + +## 示例 + +默认情况下，APISIX 仅代理 L7 流量。在操作前，请先确保在 APISIX 中启用了 L4 流量代理。 + +按如下方式更新配置文件以启用 L4 流量代理： + +```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 +70,135 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"/ ::: +### 代理到 MQTT Broker + +以下示例演示如何配置流式路由，将流量代理到托管的 MQTT 服务器，并验证 APISIX 能够成功代理 MQTT 消息。 + +创建流式路由并配置 `mqtt-proxy` 插件： + ```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", "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": { + "test.mosquitto.org:1883": 1 + } } -}' + }' +``` + +打开两个终端会话。在第一个终端中，订阅测试主题： + +```shell +mosquitto_sub -h test.mosquitto.org -p 1883 -t "test/apisix" ``` -如果你在 macOS 中使用 Docker，则 `host.docker.internal` 是 `host` 的正确属性。 +在另一个终端中，向创建的路由发布示例消息： + +```shell +mosquitto_pub -h 127.0.0.1 -p 9100 -t "test/apisix" -m "Hello APISIX" +``` -该插件暴露了一个变量 `mqtt_client_id`，你可以使用它来通过客户端 ID 进行负载均衡。比如： +你应该在第一个终端中看到消息 `Hello APISIX`。 + +### 对 MQTT 流量进行负载均衡 + +以下示例演示如何配置流式路由，将 MQTT 流量负载均衡到不同的 MQTT 服务器。 + +启用该插件后，它会注册一个变量 `mqtt_client_id`，可用于负载均衡。不同客户端 ID 的 MQTT 连接将根据一致性哈希算法转发到不同的上游节点。如果客户端 ID 缺失，则使用客户端 IP 代替。 + +创建流式路由，并将 `mqtt-proxy` 插件配置为指向两个 MQTT 服务器： ```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", "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 } - ] + ] } -}' + }' ``` -不同客户端 ID 的 MQTT 连接将通过一致性哈希算法被转发到不同的节点。如果客户端 ID 为空，将会通过客户端 IP 进行均衡。 +打开三个终端会话。在第一个终端中，订阅第一个 MQTT broker 的测试主题： + +```shell +mosquitto_sub -h test.mosquitto.org -p 1883 -t "test/apisix" +``` + +在第二个终端中，订阅第二个 MQTT broker 的相同主题： + +```shell +mosquitto_sub -h broker.mqtt.cool -p 1883 -t "test/apisix" +``` + +在第三个终端中，多次运行以下命令向路由发送示例消息： + +```shell +mosquitto_pub -h 127.0.0.1 -p 9100 -t "test/apisix" -m "Hello APISIX" +``` + +你应该在两个终端中都看到消息 `Hello APISIX`，验证流量已被负载均衡。 ## 使用 mqtt-proxy 插件启用 mTLS -Stream 代理可以使用 TCP 连接并且支持 TLS。请参考 [如何通过 tcp 连接接受 tls](../stream-proxy.md/#accept-tls-over-tcp-connection) 打开启用了 TLS 的 stream 代理。 +流式代理使用 TCP 连接，可以支持 TLS。请参考[如何通过 TCP 连接接受 TLS](../stream-proxy.md/#accept-tls-over-tcp-connection)，打开启用了 TLS 的流式代理。 -`mqtt-proxy` 插件通过 Stream 代理的指定端口的 TCP 通信启用，如果 `tls` 设置为 `true`，则还要求客户端通过 TLS 进行身份验证。 +`mqtt-proxy` 插件通过流式代理指定端口上的 TCP 通信启用。如果 `tls` 设置为 `true`，还要求客户端通过 TLS 进行身份验证。 -配置 `ssl` 提供 CA 证书和服务器证书，以及 SNI 列表。使用 `ssl` 保护 `stream_routes` 的步骤等同于 [protect Routes](../mtls.md/#protect-route)。 +配置 `ssl` 以提供 CA 证书和服务器证书，以及 SNI 列表。使用 `ssl` 保护 `stream_routes` 的步骤等同于[保护路由](../mtls.md/#protect-route)。 -### 创建 stream_route 并配置 mqtt-proxy 插件和 mTLS +### 创建使用 mqtt-proxy 插件和 mTLS 的 stream_route -通过以下示例可以创建一个配置了 `mqtt-proxy` 插件的 `stream_route`，需要提供 CA 证书、客户端证书和客户端密钥（对于不受主机信任的自签名证书，请使用 -k 选项）： +以下示例创建了一个使用 `mqtt-proxy` 插件的 stream_route，并提供 CA 证书、客户端证书和客户端密钥（对于不受主机信任的自签名证书，请使用 `-k` 选项）： ```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", "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": { + "127.0.0.1:1980": 1 + } } -}' + }' ``` -:::note 注意 - -`sni` 名称必须与提供的 CA 和服务器证书创建的 SSL 对象的一个​​或多个 SNI 匹配。 - -::: - -## 删除插件 - -当你需要删除该插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务： - -```shell -curl http://127.0.0.1:9180/apisix/admin/stream_routes/1 \ --H "X-API-KEY: $admin_key" -X DELETE -``` +`sni` 名称必须与使用 CA 和服务器证书创建的 SSL 对象的一个或多个 SNI 匹配。 From b3852d48a25a6fe68d5bb22cf602b327cf546937 Mon Sep 17 00:00:00 2001 From: Yilia Lin Date: Tue, 28 Apr 2026 11:56:15 +0800 Subject: [PATCH 2/4] docs: fix mqtt-proxy review comments - nodes format, route IDs, lb example --- docs/en/latest/plugins/mqtt-proxy.md | 33 ++++++++++++++++++---------- docs/zh/latest/plugins/mqtt-proxy.md | 33 ++++++++++++++++++---------- 2 files changed, 42 insertions(+), 24 deletions(-) diff --git a/docs/en/latest/plugins/mqtt-proxy.md b/docs/en/latest/plugins/mqtt-proxy.md index 64568561b6ad..ade349c3bfd3 100644 --- a/docs/en/latest/plugins/mqtt-proxy.md +++ b/docs/en/latest/plugins/mqtt-proxy.md @@ -80,7 +80,7 @@ Create a stream Route to the MQTT server and configure the `mqtt-proxy` Plugin: curl "http://127.0.0.1:9180/apisix/admin/stream_routes" -X PUT \ -H "X-API-KEY: ${admin_key}" \ -d '{ - "id": "mqtt-route", + "id": "mqtt-route-proxy", "plugins": { "mqtt-proxy": { "protocol_name": "MQTT", @@ -89,9 +89,13 @@ curl "http://127.0.0.1:9180/apisix/admin/stream_routes" -X PUT \ }, "upstream": { "type": "roundrobin", - "nodes": { - "test.mosquitto.org:1883": 1 - } + "nodes": [ + { + "host": "test.mosquitto.org", + "port": 1883, + "weight": 1 + } + ] } }' ``` @@ -122,7 +126,7 @@ Create a stream Route to two MQTT servers and configure the `mqtt-proxy` Plugin: curl "http://127.0.0.1:9180/apisix/admin/stream_routes" -X PUT \ -H "X-API-KEY: ${admin_key}" \ -d '{ - "id": "mqtt-route", + "id": "mqtt-route-lb", "plugins": { "mqtt-proxy": { "protocol_name": "MQTT", @@ -160,13 +164,14 @@ In the second terminal, subscribe to the same topic in the second MQTT broker: mosquitto_sub -h broker.mqtt.cool -p 1883 -t "test/apisix" ``` -In the third terminal, run the following commands a few times to send sample messages to the Route: +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" +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" ``` -You should see the message `Hello APISIX` in both terminals, verifying the traffic was load balanced. +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 @@ -184,7 +189,7 @@ The following example creates a stream Route using the `mqtt-proxy` Plugin and c curl "http://127.0.0.1:9180/apisix/admin/stream_routes" -X PUT \ -H "X-API-KEY: ${admin_key}" \ -d '{ - "id": "mqtt-route", + "id": "mqtt-route-mtls", "plugins": { "mqtt-proxy": { "protocol_name": "MQTT", @@ -194,9 +199,13 @@ curl "http://127.0.0.1:9180/apisix/admin/stream_routes" -X PUT \ "sni": "${your_sni_name}", "upstream": { "type": "roundrobin", - "nodes": { - "127.0.0.1:1980": 1 - } + "nodes": [ + { + "host": "127.0.0.1", + "port": 1980, + "weight": 1 + } + ] } }' ``` diff --git a/docs/zh/latest/plugins/mqtt-proxy.md b/docs/zh/latest/plugins/mqtt-proxy.md index 5c37dcbb4d41..e6b973104e67 100644 --- a/docs/zh/latest/plugins/mqtt-proxy.md +++ b/docs/zh/latest/plugins/mqtt-proxy.md @@ -80,7 +80,7 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"/ curl "http://127.0.0.1:9180/apisix/admin/stream_routes" -X PUT \ -H "X-API-KEY: ${admin_key}" \ -d '{ - "id": "mqtt-route", + "id": "mqtt-route-proxy", "plugins": { "mqtt-proxy": { "protocol_name": "MQTT", @@ -89,9 +89,13 @@ curl "http://127.0.0.1:9180/apisix/admin/stream_routes" -X PUT \ }, "upstream": { "type": "roundrobin", - "nodes": { - "test.mosquitto.org:1883": 1 - } + "nodes": [ + { + "host": "test.mosquitto.org", + "port": 1883, + "weight": 1 + } + ] } }' ``` @@ -122,7 +126,7 @@ mosquitto_pub -h 127.0.0.1 -p 9100 -t "test/apisix" -m "Hello APISIX" curl "http://127.0.0.1:9180/apisix/admin/stream_routes" -X PUT \ -H "X-API-KEY: ${admin_key}" \ -d '{ - "id": "mqtt-route", + "id": "mqtt-route-lb", "plugins": { "mqtt-proxy": { "protocol_name": "MQTT", @@ -160,13 +164,14 @@ mosquitto_sub -h test.mosquitto.org -p 1883 -t "test/apisix" 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" +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" ``` -你应该在两个终端中都看到消息 `Hello APISIX`，验证流量已被负载均衡。 +由于负载均衡基于 MQTT 客户端 ID 的一致性哈希，每个客户端 ID 会被一致地路由到同一个 broker。你应该看到每条消息出现在两个订阅终端之一，从而验证流量已分发到两个 broker。 ## 使用 mqtt-proxy 插件启用 mTLS @@ -184,7 +189,7 @@ mosquitto_pub -h 127.0.0.1 -p 9100 -t "test/apisix" -m "Hello APISIX" curl "http://127.0.0.1:9180/apisix/admin/stream_routes" -X PUT \ -H "X-API-KEY: ${admin_key}" \ -d '{ - "id": "mqtt-route", + "id": "mqtt-route-mtls", "plugins": { "mqtt-proxy": { "protocol_name": "MQTT", @@ -194,9 +199,13 @@ curl "http://127.0.0.1:9180/apisix/admin/stream_routes" -X PUT \ "sni": "${your_sni_name}", "upstream": { "type": "roundrobin", - "nodes": { - "127.0.0.1:1980": 1 - } + "nodes": [ + { + "host": "127.0.0.1", + "port": 1980, + "weight": 1 + } + ] } }' ``` From e108e641ec4e7c73cafefbca8748aa19828668ac Mon Sep 17 00:00:00 2001 From: OpenCode Date: Thu, 7 May 2026 10:48:50 +0800 Subject: [PATCH 3/4] docs: add ADC and Ingress Controller examples to mqtt-proxy Add comprehensive configuration examples for different deployment methods: - Add ADC (API7 Declarative Config) configuration examples - Add Ingress Controller examples with Gateway API and APISIX CRD - Organize examples using multi-tab interface for better usability - Include both simple proxy and load balancing scenarios These examples help users configure mqtt-proxy in different deployment environments including standalone APISIX, ADC-managed deployments, and Kubernetes with Ingress Controller. Related: api7/docs#1554 --- docs/en/latest/plugins/mqtt-proxy.md | 268 +++++++++++++++++++++++++++ 1 file changed, 268 insertions(+) diff --git a/docs/en/latest/plugins/mqtt-proxy.md b/docs/en/latest/plugins/mqtt-proxy.md index ade349c3bfd3..5782ceb7bf26 100644 --- a/docs/en/latest/plugins/mqtt-proxy.md +++ b/docs/en/latest/plugins/mqtt-proxy.md @@ -27,6 +27,9 @@ description: The mqtt-proxy Plugin supports proxying and load balancing MQTT req # --> +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + @@ -76,6 +79,17 @@ The following example demonstrates how you can configure a stream Route to proxy Create a stream Route to the MQTT server and configure the `mqtt-proxy` Plugin: + + + + ```shell curl "http://127.0.0.1:9180/apisix/admin/stream_routes" -X PUT \ -H "X-API-KEY: ${admin_key}" \ @@ -100,6 +114,112 @@ curl "http://127.0.0.1:9180/apisix/admin/stream_routes" -X PUT \ }' ``` + + + + +```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 +``` + + + + + + + + + +:::info + +Attaching L4 plugins is currently not supported with Gateway API. At the moment, this example cannot be completed with Gateway API. + +::: + + + + + +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 +``` + + + + + + + + + Open two terminal sessions. In the first one, subscribe to the test topic: ```shell @@ -122,6 +242,17 @@ When the Plugin is enabled, it registers a variable `mqtt_client_id` which can b Create a stream Route to two MQTT servers and configure the `mqtt-proxy` Plugin: + + + + ```shell curl "http://127.0.0.1:9180/apisix/admin/stream_routes" -X PUT \ -H "X-API-KEY: ${admin_key}" \ @@ -152,6 +283,143 @@ curl "http://127.0.0.1:9180/apisix/admin/stream_routes" -X PUT \ }' ``` + + + + +```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 +``` + + + + + + + + + +:::info + +Attaching L4 plugins is currently not supported with Gateway API. At the moment, this example cannot be completed with Gateway API. + +::: + + + + + +```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 +``` + + + + + + + + + Open three terminal sessions. In the first one, subscribe to the test topic in the first MQTT broker: ```shell From d74136404a8b77ffb6e57b87a0762f4047ce0a7a Mon Sep 17 00:00:00 2001 From: OpenCode Date: Thu, 7 May 2026 11:32:32 +0800 Subject: [PATCH 4/4] docs: sync Chinese documentation with ADC and Ingress Controller examples Update Chinese documentation for mqtt-proxy plugin to match the English version updates: - Add ADC (API7 Declarative Config) configuration examples - Add Ingress Controller (Gateway API and APISIX CRD) examples - Add multi-tab interface for different configuration methods - Translate new example descriptions and instructions to Chinese - Keep code blocks and YAML configurations in English This ensures Chinese-speaking users have access to the same comprehensive configuration examples as English-speaking users. --- docs/zh/latest/plugins/mqtt-proxy.md | 268 +++++++++++++++++++++++++++ 1 file changed, 268 insertions(+) diff --git a/docs/zh/latest/plugins/mqtt-proxy.md b/docs/zh/latest/plugins/mqtt-proxy.md index e6b973104e67..b771b73e68c0 100644 --- a/docs/zh/latest/plugins/mqtt-proxy.md +++ b/docs/zh/latest/plugins/mqtt-proxy.md @@ -27,6 +27,9 @@ description: mqtt-proxy 插件支持将 MQTT 请求代理和负载均衡到 MQTT # --> +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + @@ -76,6 +79,17 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"/ 创建流式路由并配置 `mqtt-proxy` 插件： + + + + ```shell curl "http://127.0.0.1:9180/apisix/admin/stream_routes" -X PUT \ -H "X-API-KEY: ${admin_key}" \ @@ -100,6 +114,112 @@ curl "http://127.0.0.1:9180/apisix/admin/stream_routes" -X PUT \ }' ``` + + + + +```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 +``` + + + + + + + + + +:::info + +Gateway API 目前不支持配置 L4 插件。此示例暂时无法通过 Gateway API 完成。 + +::: + + + + + +使用 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 +``` + +应用配置： + +```shell +kubectl apply -f mqtt-proxy-ic.yaml +``` + + + + + + + + + 打开两个终端会话。在第一个终端中，订阅测试主题： ```shell @@ -122,6 +242,17 @@ mosquitto_pub -h 127.0.0.1 -p 9100 -t "test/apisix" -m "Hello APISIX" 创建流式路由，并将 `mqtt-proxy` 插件配置为指向两个 MQTT 服务器： + + + + ```shell curl "http://127.0.0.1:9180/apisix/admin/stream_routes" -X PUT \ -H "X-API-KEY: ${admin_key}" \ @@ -152,6 +283,143 @@ curl "http://127.0.0.1:9180/apisix/admin/stream_routes" -X PUT \ }' ``` + + + + +```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 +``` + +将配置同步到网关： + +```shell +adc sync -f adc.yaml +``` + + + + + + + + + +:::info + +Gateway API 目前不支持配置 L4 插件。此示例暂时无法通过 Gateway API 完成。 + +::: + + + + + +```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 +kubectl apply -f mqtt-proxy-ic.yaml +``` + + + + + + + + + 打开三个终端会话。在第一个终端中，订阅第一个 MQTT broker 的测试主题： ```shell