mqtt-proxy

Description

The plugin mqtt-proxy only works in stream model, it help you to dynamic load balance by client_id of MQTT.

And this plugin both support MQTT protocol 3.1.* and 5.0.

Attributes

NameTypeRequirementDefaultValidDescription
protocol_namestringrequiredName of protocol, should be MQTT in normal.
protocol_levelintegerrequiredLevel of protocol, it should be 4 for MQTT 3.1.*. it should be 5 for MQTT 5.0.
upstreamobjectdeprecatedUse separate upstream in the route instead.
upstream.hoststringrequiredthe IP or host of upstream, will forward current request to.
upstream.ipstringdeprecatedUse “host” instead. IP address of upstream, will forward current request to.
upstream.portnumberrequiredPort of upstream, will forward current request to.

How To Enable

To enable this plugin, we need to enable the stream_proxy configuration in conf/config.yaml first. For example, the following configuration represents listening on the 9100 TCP port.

  1.     ...
  2.     router:
  3.         http: 'radixtree_uri'
  4.         ssl: 'radixtree_sni'
  5.     stream_proxy:                 # TCP/UDP proxy
  6.       only: false                 # needed if HTTP and Stream Proxy should be enabled
  7.       tcp:                        # TCP proxy port list
  8.         - 9100
  9.     dns_resolver:
  10.     ...

Then send the MQTT request to port 9100.

Creates a stream route, and enable plugin mqtt-proxy.

  1. curl http://127.0.0.1:9080/apisix/admin/stream_routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  2. {
  3.     "plugins": {
  4.         "mqtt-proxy": {
  5.             "protocol_name": "MQTT",
  6.             "protocol_level": 4
  7.         }
  8.     },
  9.     "upstream": {
  10.         "type": "roundrobin",
  11.         "nodes": [{
  12.             "host": "127.0.0.1",
  13.             "port": 1980,
  14.             "weight": 1
  15.         }]
  16.     }
  17. }'

In case Docker is used in combination with MacOS host.docker.internal is the right parameter for host.

This plugin exposes a variable mqtt_client_id, and we can use it to load balance via the client id. For example:

  1. curl http://127.0.0.1:9080/apisix/admin/stream_routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
  2. {
  3.     "plugins": {
  4.         "mqtt-proxy": {
  5.             "protocol_name": "MQTT",
  6.             "protocol_level": 4
  7.         }
  8.     },
  9.     "upstream": {
  10.         "type": "chash",
  11.         "key": "mqtt_client_id",
  12.         "nodes": [
  13.         {
  14.             "host": "127.0.0.1",
  15.             "port": 1995,
  16.             "weight": 1
  17.         },
  18.         {
  19.             "host": "127.0.0.2",
  20.             "port": 1995,
  21.             "weight": 1
  22.         }
  23.         ]
  24.     }
  25. }'

MQTT connections with different client ID will be forwarded to different node via the consistent hash algorithm. If the client ID is missing, we will balance via client IP instead.

Delete Plugin

  1. $ curl http://127.0.0.1:9080/apisix/admin/stream_routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X DELETE

The mqtt-proxy plugin has been deleted now.