kayx23 commented on code in PR #13310: URL: https://github.com/apache/apisix/pull/13310#discussion_r3152038869
########## docs/zh/latest/plugins/mqtt-proxy.md: ########## @@ -71,105 +70,144 @@ 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-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 + } + ] } -}' + }' ``` -如果你在 macOS 中使用 Docker，则 `host.docker.internal` 是 `host` 的正确属性。 +打开两个终端会话。在第一个终端中，订阅测试主题： -该插件暴露了一个变量 `mqtt_client_id`，你可以使用它来通过客户端 ID 进行负载均衡。比如： +```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 服务器： ```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 } - ] + ] } -}' + }' ``` -不同客户端 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" +``` + +在第三个终端中，使用两个不同的客户端 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。 Review Comment: 这里的验证表述比示例实际能证明的内容更强。对 `mqtt_client_id` 使用 `chash` 时，每个固定的 client ID 都会稳定地命中同一个 broker。用 `client-1` 和 `client-2` 各发一条消息，最多只能说明不同 client ID 可能映射到不同 broker，但不能在每次运行中都可靠地证明消息一定会分布到两个 broker。建议将这里的结论写得更保守一些，例如说明它展示的是基于 client ID 的粘性路由；如果想观察到两个 broker，都可能需要再尝试更多不同的 client ID。 ########## docs/en/latest/plugins/mqtt-proxy.md: ########## @@ -70,101 +70,144 @@ 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-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 +Open two terminal sessions. In the first one, subscribe to the test topic: -If you are using Docker in macOS, then `host.docker.internal` is the right parameter for the `host` attribute. +```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" +``` -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-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 } - ] + ] } -}' + }' ``` -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, 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. Review Comment: This verification wording is stronger than what the example actually proves. With `chash` on `mqtt_client_id`, each fixed client ID deterministically sticks to one broker. Sending one message with `client-1` and one with `client-2` can show that different client IDs may map to different brokers, but it does not reliably verify distribution across both brokers in every run. Please soften the claim here (for example: it demonstrates sticky routing by client ID, and readers may need to try additional client IDs to observe both brokers). -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
