diff --git a/docs/en/latest/plugins/mqtt-proxy.md b/docs/en/latest/plugins/mqtt-proxy.md index 64c4f92d2277..5782ceb7bf26 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 +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + + + -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 +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: + + + + + ```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 + + + + +```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. + + + + + + + + +:::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: + + + + +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 +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: + + + + ```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 } - ] + ] } -}' + }' +``` + + + + + +```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. + + + + + + + + +:::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 +``` + + + + -## 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`. +Open three terminal sessions. In the first one, subscribe to the test topic in the first MQTT broker: + +```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. + +## 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-mtls", "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": [ + { + "host": "127.0.0.1", + "port": 1980, + "weight": 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..b771b73e68c0 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 版本。 --- -## 描述 +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + + + -通过 `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`。 | +| 名称 | 类型 | 必选项 | 默认值 | 描述 | +|----------------|---------|--------|---------|-------------------------------------------------------------| +| protocol_name | string | 否 | "MQTT" | 协议名称。 | +| protocol_level | integer | 是 | | 协议级别。MQTT `3.1.*` 应设为 `4`，MQTT `5.0` 应设为 `5`。 | + +## 示例 -## 启用插件 +默认情况下，APISIX 仅代理 L7 流量。在操作前，请先确保在 APISIX 中启用了 L4 流量代理。 -为了启用该插件，需要先在配置文件（`./conf/config.yaml`）中加载 `stream_proxy` 相关配置。以下配置代表监听 `9100` TCP 端口： +按如下方式更新配置文件以启用 L4 流量代理： -```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: - ... +```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 +73,409 @@ 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 + } + ] } -}' + }' +``` + + + + + +```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 ``` -如果你在 macOS 中使用 Docker，则 `host.docker.internal` 是 `host` 的正确属性。 +应用配置： + +```shell +kubectl apply -f mqtt-proxy-ic.yaml +``` + + + + + + + + + +打开两个终端会话。在第一个终端中，订阅测试主题： + +```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 服务器： + + -该插件暴露了一个变量 `mqtt_client_id`，你可以使用它来通过客户端 ID 进行负载均衡。比如： + ```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 } - ] + ] } -}' + }' +``` + + + + + +```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 ``` -不同客户端 ID 的 MQTT 连接将通过一致性哈希算法被转发到不同的节点。如果客户端 ID 为空，将会通过客户端 IP 进行均衡。 +将配置同步到网关： -## 使用 mqtt-proxy 插件启用 mTLS +```shell +adc sync -f adc.yaml +``` + + -Stream 代理可以使用 TCP 连接并且支持 TLS。请参考 [如何通过 tcp 连接接受 tls](../stream-proxy.md/#accept-tls-over-tcp-connection) 打开启用了 TLS 的 stream 代理。 + -`mqtt-proxy` 插件通过 Stream 代理的指定端口的 TCP 通信启用，如果 `tls` 设置为 `true`，则还要求客户端通过 TLS 进行身份验证。 + -配置 `ssl` 提供 CA 证书和服务器证书，以及 SNI 列表。使用 `ssl` 保护 `stream_routes` 的步骤等同于 [protect Routes](../mtls.md/#protect-route)。 + -### 创建 stream_route 并配置 mqtt-proxy 插件和 mTLS +:::info -通过以下示例可以创建一个配置了 `mqtt-proxy` 插件的 `stream_route`，需要提供 CA 证书、客户端证书和客户端密钥（对于不受主机信任的自签名证书，请使用 -k 选项）： +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 -curl 127.0.0.1:9180/apisix/admin/stream_routes/1 \ --H "X-API-KEY: $admin_key" -X PUT -d ' -{ - "plugins": { - "mqtt-proxy": { - "protocol_name": "MQTT", - "protocol_level": 4 - } - }, - "sni": "${your_sni_name}", - "upstream": { - "nodes": { - "127.0.0.1:1980": 1 - }, - "type": "roundrobin" - } -}' +kubectl apply -f mqtt-proxy-ic.yaml ``` -:::note 注意 + -`sni` 名称必须与提供的 CA 和服务器证书创建的 SSL 对象的一个​​或多个 SNI 匹配。 + -::: + + + + +打开三个终端会话。在第一个终端中，订阅第一个 MQTT broker 的测试主题： -## 删除插件 +```shell +mosquitto_sub -h test.mosquitto.org -p 1883 -t "test/apisix" +``` -当你需要删除该插件时，可以通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务： +在第二个终端中，订阅第二个 MQTT broker 的相同主题： ```shell -curl http://127.0.0.1:9180/apisix/admin/stream_routes/1 \ --H "X-API-KEY: $admin_key" -X DELETE +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。 + +## 使用 mqtt-proxy 插件启用 mTLS + +流式代理使用 TCP 连接，可以支持 TLS。请参考[如何通过 TCP 连接接受 TLS](../stream-proxy.md/#accept-tls-over-tcp-connection)，打开启用了 TLS 的流式代理。 + +`mqtt-proxy` 插件通过流式代理指定端口上的 TCP 通信启用。如果 `tls` 设置为 `true`，还要求客户端通过 TLS 进行身份验证。 + +配置 `ssl` 以提供 CA 证书和服务器证书，以及 SNI 列表。使用 `ssl` 保护 `stream_routes` 的步骤等同于[保护路由](../mtls.md/#protect-route)。 + +### 创建使用 mqtt-proxy 插件和 mTLS 的 stream_route + +以下示例创建了一个使用 `mqtt-proxy` 插件的 stream_route，并提供 CA 证书、客户端证书和客户端密钥（对于不受主机信任的自签名证书，请使用 `-k` 选项）： + +```shell +curl "http://127.0.0.1:9180/apisix/admin/stream_routes" -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "mqtt-route-mtls", + "plugins": { + "mqtt-proxy": { + "protocol_name": "MQTT", + "protocol_level": 4 + } + }, + "sni": "${your_sni_name}", + "upstream": { + "type": "roundrobin", + "nodes": [ + { + "host": "127.0.0.1", + "port": 1980, + "weight": 1 + } + ] + } + }' +``` + +`sni` 名称必须与使用 CA 和服务器证书创建的 SSL 对象的一个或多个 SNI 匹配。