kayx23 commented on code in PR #13310:
URL: https://github.com/apache/apisix/pull/13310#discussion_r3198848229
##########
docs/en/latest/plugins/mqtt-proxy.md:
##########
@@ -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
+```
Review Comment:
This conclusion 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
demonstrate sticky routing by client ID, but it does not reliably verify
distribution across both brokers on every run. Please soften the wording here
(same issue in the ZH file).
--
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]
