mqtt-proxy
Description#
The mqtt-proxy Plugin is used for dynamic load balancing with client_id of MQTT. It only works in stream model.
This Plugin supports both the protocols 3.1.* and 5.0.
Attributes#
| Name | Type | Required | Description |
|---|---|---|---|
| protocol_name | string | True | Name of the protocol. Generally MQTT. |
| protocol_level | integer | True | Level of the protocol. It should be 4 for MQTT 3.1.* and 5 for MQTT 5.0. |
| upstream | object | Deprecated | Use separate Upstream in the Route instead. |
| upstream.host | string | True | IP or host of the upstream to forward the current request to. |
| upstream.ip | string | Deprecated | Use host instead. IP address of the upstream to forward the current request to. |
| upstream.port | number | True | Port of the upstream to forward the current request to. |
Enabling the Plugin#
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:
... router: http: 'radixtree_uri' ssl: 'radixtree_sni' stream_proxy: # TCP/UDP proxy only: false # needed if HTTP and Stream Proxy should be enabled tcp: # TCP proxy port list - 9100 dns_resolver: ...You can now send the MQTT request to port 9100.
You can now create a stream Route and enable the mqtt-proxy Plugin:
curl http://127.0.0.1:9080/apisix/admin/stream_routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '{ "plugins": { "mqtt-proxy": { "protocol_name": "MQTT", "protocol_level": 4 } }, "upstream": { "type": "roundrobin", "nodes": [{ "host": "127.0.0.1", "port": 1980, "weight": 1 }] }}'note
If you are using Docker in macOS, then host.docker.internal is the right parameter for the host attribute.
This Plugin exposes a variable mqtt_client_id which can be used for load balancing as shown below:
curl http://127.0.0.1:9080/apisix/admin/stream_routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '{ "plugins": { "mqtt-proxy": { "protocol_name": "MQTT", "protocol_level": 4 } }, "upstream": { "type": "chash", "key": "mqtt_client_id", "nodes": [ { "host": "127.0.0.1", "port": 1995, "weight": 1 }, { "host": "127.0.0.2", "port": 1995, "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.
Disable Plugin#
To disable the mqtt-proxy Plugin you can remove the corresponding configuration as shown below:
curl http://127.0.0.1:9080/apisix/admin/stream_routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X DELETE