产品定价 立即试用
MQTT Broker
社区版 专业版 云平台 边缘 PE边缘 IoT网关 许可证服务器 Trendz Analytics 移动应用 PE移动应用 MQTT Broker PE MQTT Broker
安装 > Azure (Kubernetes) 集群
入门 文档
架构 API 常见问题
目录

在 Azure 上使用 Kubernetes 部署 TBMQ 集群

本指南将帮助您在Azure AKS上部署TBMQ。

前置条件

安装和配置工具

在 AKS 集群上部署 TBMQ 前，需安装 kubectl、helm 和 az 工具。

安装完成后，使用以下命令登录 CLI：

1

az login

步骤1. 打开TBMQ K8S脚本仓库

1
2

git clone -b release-2.2.0 https://github.com/thingsboard/tbmq.git
cd tbmq/k8s/azure

步骤2. 定义环境变量

定义本指南后续命令中将用到的环境变量。

假设您使用Linux，请执行：

1
2
3
4
5
6
7
8

export AKS_RESOURCE_GROUP=TBMQResources
export AKS_LOCATION=eastus
export AKS_GATEWAY=tbmq-gateway
export TB_CLUSTER_NAME=tbmq-cluster
export TB_DATABASE_NAME=tbmq-db
export TB_REDIS_NAME=tbmq-redis
echo "You variables ready to create resource group $AKS_RESOURCE_GROUP in location $AKS_LOCATION 
and cluster in it $TB_CLUSTER_NAME with database $TB_DATABASE_NAME"

其中：

  • TBMQResources-用于部署和管理Azure资源的逻辑组，下文中以 AKS_RESOURCE_GROUP 表示；
  • eastus-创建资源组所在区域，下文中以 AKS_LOCATION 表示，可执行 az account list-locations 查看所有区域；
  • tbmq-gateway-Azure应用程序网关名称；
  • tbmq-cluster-集群名称，下文中以 TB_CLUSTER_NAME 表示；
  • tbmq-db-数据库服务器名称，可自定义，下文中以 TB_DATABASE_NAME 表示。

Step 3. Configure and create AKS cluster

创建 AKS 集群前，需先创建 Azure 资源组。使用 Azure CLI 操作：

1

az group create --name $AKS_RESOURCE_GROUP --location $AKS_LOCATION

有关 az group 的更多信息请参阅此链接。

资源组创建后，可使用以下命令创建 AKS 集群：

1
2
3
4
5
6
7
8

az aks create --resource-group $AKS_RESOURCE_GROUP \
    --name $TB_CLUSTER_NAME \
    --generate-ssh-keys \
    --enable-addons ingress-appgw \
    --appgw-name $AKS_GATEWAY \
    --appgw-subnet-cidr "10.225.0.0/24" \
    --node-vm-size Standard_D4s_v6 \
    --node-count 3

az aks create 有两个必填参数：name 和 resource-group（使用先前设置的变量）， 以及多个可选参数（未设置时使用默认值）。其中部分参数如下：

  • node-count - Kubernetes 节点池中的节点数量。创建集群后，可用 az aks scale 调整节点池大小（默认值为 3）；
  • enable-addons - 以逗号分隔的 Kubernetes 附加组件列表（使用 az aks addon list 查看可用附加组件）；
  • node-osdisk-size - 给定代理池中机器的 OS 磁盘类型：临时或托管。在 VM 大小和 OS 磁盘大小满足条件时默认为 “Ephemeral”。创建后可能无法更改；
  • node-vm-size（或 -s） - 创建为 Kubernetes 节点的虚拟机大小（默认值为 Standard_DS2_v2）；
  • generate-ssh-keys - 若缺失则生成 SSH 公钥和私钥文件。密钥将存储在 ~/.ssh 目录中。

上述命令中添加了 ApplicationGateway 的 AKS 附加组件。 将使用该网关作为 TBMQ 的基于路径的负载均衡器。

az aks create 的完整选项请参阅此处。

您也可参考此指南进行自定义集群配置。

Step 4. Update the context of kubectl

集群创建后，可使用以下命令将 kubectl 连接到该集群：

1

az aks get-credentials --resource-group $AKS_RESOURCE_GROUP --name $TB_CLUSTER_NAME

为验证连接，可执行以下命令：

1

kubectl get nodes

您应能看到集群节点列表。

Step 5. Provision PostgreSQL DB

You’ll need to set up PostgreSQL on Azure. You may follow this guide, but take into account the following requirements:

  • Keep your postgresql password in a safe place. We will refer to it later in this guide using YOUR_AZURE_POSTGRES_PASSWORD;
  • Make sure your Azure Database for PostgreSQL version is 16.x;
  • Make sure your Azure Database for PostgreSQL instance is accessible from the TBMQ cluster;
  • Make sure you use “thingsboard_mqtt_broker” as the initial database name.

Note: Use “High availability” enabled. It enables a lot of useful settings by default.

Another way by which you can create Azure Database for PostgreSQL is using az tool (don’t forget to replace ‘POSTGRESS_USER’ and ‘POSTGRESS_PASS’ with your username and password):

1
2
3
4

az postgres flexible-server create --location $AKS_LOCATION --resource-group $AKS_RESOURCE_GROUP \
  --name $TB_DATABASE_NAME --admin-user POSTGRESS_USER --admin-password POSTGRESS_PASS \
  --public-access 0.0.0.0 --storage-size 32 \
  --version 16 -d thingsboard_mqtt_broker

az postgres flexible-server create has a lot of parameters, a few of them are:

  • location-Location. Values from: az account list-locations;
  • resource-group (or -g)-Name of resource group;
  • name-Name of the server. The name can contain only lowercase letters, numbers, and the hyphen (-) character. Minimum 3 characters and maximum 63 characters;
  • admin-user-Administrator username for the server. Once set, it cannot be changed;
  • admin-password-The password of the administrator. Minimum 8 characters and maximum 128 characters. Password must contain characters from three of the following categories: English uppercase letters, English lowercase letters, numbers, and non-alphanumeric characters;
  • public-access-Determines the public access. Enter single or range of IP addresses to be included in the allowed list of IPs. IP address ranges must be dash-separated and not contain any spaces. Specifying 0.0.0.0 allows public access from any resources deployed within Azure to access your server. Setting it to “None” sets the server in public access mode but does not create a firewall rule;
  • storage-size-The storage capacity of the server. Minimum is 32 GiB and maximum is 16 TiB;
  • version-Server major version;
  • high-availability-enable or disable high availability feature. High availability can only be set during flexible server creation (accepted values: Disabled, Enabled. Default value: Disabled);
  • database-name (or -d)-The name of the database to be created when provisioning the database server.

You can see full parameters list here.

Example of response:

1
2
3
4
5
6
7
8
9
10
11
12
13

{
  "connectionString": "postgresql://postgres:postgres@$tbmq-db.postgres.database.azure.com/postgres?sslmode=require",
  "databaseName": "thingsboard_mqtt_broker",
  "firewallName": "AllowAllAzureServicesAndResourcesWithinAzureIps_2021-11-17_15-45-6",
  "host": "tbmq-db.postgres.database.azure.com",
  "id": "/subscriptions/daff3288-1d5d-47c7-abf0-bfb7b738a18c/resourceGroups/myResourceGroup/providers/Microsoft.DBforPostgreSQL/flexibleServers/thingsboard_mqtt_broker",
  "location": "East US",
  "password": "postgres",
  "resourceGroup": "TBMQResources",
  "skuname": "Standard_D2s_v3",
  "username": "postgres",
  "version": "16"
}

请记下命令输出中的host值（本例为 tbmq-db.postgres.database.azure.com），以及用户名和密码（postgres）。

编辑数据库配置文件，将YOUR_AZURE_POSTGRES_ENDPOINT_URL替换为host值，YOUR_AZURE_POSTGRES_USER和YOUR_AZURE_POSTGRES_PASSWORD替换为正确值：

1

nano tb-broker-db-configmap.yml

步骤6. Azure Cache for Redis您需要配置Azure Cache for Redis。TBMQ使用缓存为 设备持久化客户端 存储消息，

以提升性能并减少频繁读库（详见下文）。

在启用认证且客户端连接TBMQ时，每次连接都会请求查找可认证该客户端的MQTT客户端凭据， 因此大量客户端同时连接时可能产生大量请求。

文档信息图标

注意： 自 TBMQ v2.1.0 起，第三方Redis部署的官方支持版本为Redis7.2.5。 目前仅Azure Cache for Redis的 Enterprise 和 Enterprise Flash SKU支持Redis7.2.x。 Basic、Standard和Premium SKU仍仅支持至 Redis6.x。为确保完全兼容，建议使用Enterprise级SKU，以与TBMQ所需的Redis7.2.5特性与行为一致。

要配置Redis，请参考以下任一指南：

针对开源（传统）Redis缓存，我们提供基于官方Azure文档、使用 az 工具的替代步骤：

1

az redis create --name $TB_REDIS_NAME --location $AKS_LOCATION --resource-group $AKS_RESOURCE_GROUP --sku basic --vm-size C0 --enable-non-ssl-port

az redis create 的常用选项包括：

  • name（或 -n）- Redis缓存名称；
  • resource-group（或 -g）- 资源组名称；
  • sku-Redis缓存类型（取值：Basic、Premium、Standard）；
  • vm-size-要部署的Redis缓存规格，Basic/Standard以C开头，Premium以P开头（如c0–c6、p1–p5）；
  • location（或 -l）- 区域，取值参见：az account list-locations。

完整参数列表见 此页。

响应示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47

{
  "accessKeys": null,
  "enableNonSslPort": true,
  "hostName": "tbmq-redis.redis.cache.windows.net",
  "id": "/subscriptions/daff3288-1d5d-47c7-abf0-bfb7b738a18c/resourceGroups/myResourceGroup/providers/Microsoft.Cache/Redis/tbmq-redis",
  "instances": [
    {
      "isMaster": false,
      "isPrimary": false,
      "nonSslPort": 13000,
      "shardId": null,
      "sslPort": 15000,
      "zone": null
    }
  ],
  "linkedServers": [],
  "location": "East US",
  "minimumTlsVersion": null,
  "name": "tbmq-redis",
  "port": 6379,
  "privateEndpointConnections": null,
  "provisioningState": "Creating",
  "publicNetworkAccess": "Enabled",
  "redisConfiguration": {
    "maxclients": "256",
    "maxfragmentationmemory-reserved": "12",
    "maxmemory-delta": "2",
    "maxmemory-reserved": "2"
  },
  "redisVersion": "6.0.20",
  "replicasPerMaster": null,
  "replicasPerPrimary": null,
  "resourceGroup": "myResourceGroup",
  "shardCount": null,
  "sku": {
    "capacity": 0,
    "family": "C",
    "name": "Basic"
  },
  "sslPort": 6380,
  "staticIp": null,
  "subnetId": null,
  "tags": {},
  "tenantSettings": {},
  "type": "Microsoft.Cache/Redis",
  "zones": null
}

请取 hostName 参数，在 tb-broker-cache-configmap.yml 文件中将 YOUR_REDIS_ENDPOINT_URL_WITHOUT_PORT 替换为该值。

然后获取Redis连接密钥，执行：

1

az redis list-keys --name $TB_REDIS_NAME --resource-group $AKS_RESOURCE_GROUP

将 “primary” 复制到 tb-broker-cache-configmap.yml 中，替换 YOUR_REDIS_PASSWORD。

更多说明请参阅 此脚本。

步骤7. 安装

执行以下命令完成数据库的初始配置。 该命令会启动短期运行的TBMQ pod，以创建所需数据库表、索引等。

1

./k8s-install-tbmq.sh

命令结束后，控制台应出现：

1

INFO  o.t.m.b.i.ThingsboardMqttBrokerInstallService-Installation finished successfully!
文档信息图标

否则请检查是否在 tb-broker-db-configmap.yml 中正确设置了PostgreSQL URL和PostgreSQL密码。

步骤8. 配置Kafka

建议使用 Helm 部署 Bitnami Kafka。请先查看 kafka 目录。

1

ls kafka/

其中可找到 default-values-kafka.yml 文件——从 Bitnami artifactHub 下载的默认值。以及修改后的 values-kafka.yml 文件。 建议保持第一个文件不变，仅修改第二个文件。这样升级到下一版本时更容易通过 diff 看出变更。

添加 Bitnami helm 仓库：

1
2

helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update

安装 Bitnami Kafka 时执行以下命令：

1

helm install kafka -f kafka/values-kafka.yml bitnami/kafka --version 29.3.4

等待几分钟直至 Kafka Pod 启动并运行。

步骤9. 启动

执行以下命令部署Broker：

1

./k8s-deploy-tbmq.sh

数分钟后可执行以下命令查看所有Pod状态：

1

kubectl get pods

若一切正常，应能看到 tb-broker-0 和 tb-broker-1，且均为 READY 状态。

步骤10. 配置负载均衡器

10.1配置HTTP(S) 负载均衡器

配置HTTP(S) 负载均衡器以访问TBMQ实例的Web界面。主要有两种配置方式：

  • http-不支持HTTPS的负载均衡器，建议用于 开发，配置简单、成本低，适合开发环境，不适合生产。
  • https-支持HTTPS的负载均衡器，建议用于 生产，作为SSL终止点，可方便配置与维护有效SSL证书，并将非安全 (HTTP) 流量重定向到安全 (HTTPS) 端口。

请按下方链接/说明配置相应选项。

HTTP负载均衡器

执行以下命令部署纯HTTP负载均衡器：

1

kubectl apply -f receipts/http-load-balancer.yml

负载均衡器创建可能需一定时间，可用以下命令定期查看状态：

1

kubectl get ingress

创建完成后，输出应类似：

1
2

NAME                          CLASS    HOSTS   ADDRESS         PORTS   AGE
tb-broker-http-loadbalancer   <none>   *       34.111.24.134   80      7m25s

HTTPS负载均衡器

要使用SSL证书，可在Azure Application Gateway中直接添加证书，执行：

1
2
3
4
5
6

az network application-gateway ssl-cert create \
   --resource-group $(az aks show --name $TB_CLUSTER_NAME --resource-group $AKS_RESOURCE_GROUP --query nodeResourceGroup | tr -d '"') \
   --gateway-name $AKS_GATEWAY\
   --name TBMQHTTPSCert \
   --cert-file YOUR_CERT \
   --cert-password YOUR_CERT_PASS

执行以下命令部署纯HTTPS负载均衡器：

1

kubectl apply -f receipts/https-load-balancer.yml

10.2配置MQTT负载均衡器

配置MQTT负载均衡器以支持使用MQTT协议连接设备。

Create TCP load balancer using following command:

1

kubectl apply -f receipts/mqtt-load-balancer.yml

The load balancer will forward all TCP traffic for ports 1883 and 8883.

MQTT over SSL按 本指南 创建包含SSL证书的 .pem文件，并以 server.pem 保存到工作目录。

您需要创建包含PEM文件的config-map，可执行：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

kubectl create configmap tbmq-mqtts-config \
 --from-file=server.pem=YOUR_PEM_FILENAME \
 --from-file=mqttserver_key.pem=YOUR_PEM_KEY_FILENAME \
 -o yaml --dry-run=client | kubectl apply -f-```
{: .copy-code}

* **YOUR_PEM_FILENAME** 为 **服务器证书文件** 名称。
* **YOUR_PEM_KEY_FILENAME** 为 **服务器证书私钥文件** 名称。

然后，取消注释 'tb-broker.yml' 文件中所有标有“Uncomment the following lines to enable two-way MQTTS”的段落。

执行以下命令使更改生效：

```bash
kubectl apply -f tb-broker.yml

步骤 11. 验证部署

现在可使用负载均衡器的 DNS名称在浏览器中打开TBMQ Web界面。

获取负载均衡器 DNS名称可执行：

1

kubectl get ingress

输出应类似：

1
2

NAME                          CLASS    HOSTS   ADDRESS         PORTS   AGE
tb-broker-http-loadbalancer   <none>   *       34.111.24.134   80      3d1h

使用 tb-broker-http-loadbalancer 的 ADDRESS 字段连接集群。

您将看到TBMQ登录页面。请使用以下 System Administrator（系统管理员）默认凭据：

用户名：

1

sysadmin@thingsboard.org

密码：

1

sysadmin

首次登录时，系统将要求您将默认密码修改为自定义密码，然后使用新凭据重新登录。

验证 MQTT访问

要通过 MQTT连接集群，需获取对应服务IP，可执行：

1

kubectl get services

输出应类似：

1
2

NAME                          TYPE           CLUSTER-IP       EXTERNAL-IP              PORT(S)                         AGE
tb-broker-mqtt-loadbalancer   LoadBalancer   10.100.119.170   *******                  1883:30308/TCP,8883:31609/TCP6m58s

使用负载均衡器的 EXTERNAL-IP 字段通过 MQTT协议连接集群。

故障排查

若遇问题可查看服务日志。例如查看 TBMQ日志可执行：

1

kubectl logs -f tb-broker-0

使用以下命令查看所有 StatefulSet状态：

1

kubectl get statefulsets

更多命令说明请参阅 kubectl 速查表。

升级

查看 release notes 和 升级说明 了解最新变更详情。

若您当前版本无 Upgrade to x.x.x 说明，可直接按升级说明执行。

若文档未涵盖您的升级场景，请联系我们以获取进一步指导。

备份与恢复（可选）

强烈建议在升级前备份 PostgreSQL数据库，但此为可选步骤。 更多说明请参阅 后续说明。

升级至 2.2.0

在此版本中，MQTT认证机制已从YAML/环境变量配置迁移到数据库。 升级时，TBMQ需要知道当前部署启用了哪些认证提供方。 该信息通过传入 升级 pod 的环境变量提供。

升级脚本要求存在名为 database-setup.yml 的文件并在此文件中显式定义这些变量。 升级过程中不会使用 tb-broker.yml 中的环境变量，仅使用 database-setup.yml 中的值。

提示 若仅使用 Basic认证，请设置 SECURITY_MQTT_SSL_ENABLED=false。 若仅使用X.509 认证，请设置 SECURITY_MQTT_BASIC_ENABLED=false 和 SECURITY_MQTT_SSL_ENABLED=true。

支持的变量

  • SECURITY_MQTT_BASIC_ENABLED（true|false）
  • SECURITY_MQTT_SSL_ENABLED（true|false）
  • SECURITY_MQTT_SSL_SKIP_VALIDITY_CHECK_FOR_CLIENT_CERT（true|false）— 通常为 false。

准备好该文件并确认取值后，请按 升级流程 执行。

升级至 2.1.0

TBMQ v2.1.0 引入多项改进，包括新的 Integration Executor 微服务及第三方服务版本升级。

添加 Integration Executor 微服务

本版本通过新的 Integration Executor 微服务支持外部集成。

要获取包括 Integration Executor 在内的最新配置文件，请从release分支拉取更新。 按照 运行升级说明 中的步骤操作，直至执行升级脚本前（暂不执行 .sh 命令）。

更新第三方服务

v2.1.0 中，TBMQ 更新了关键第三方依赖版本，包括 Redis、PostgreSQL 和 Kafka。 可通过以下 链接 查看变更详情。

服务 更新前版本 更新后版本
Redis 7.0 7.2.5
PostgreSQL 15.x 16.x
Kafka 3.5.1 3.7.0

建议 将环境中的第三方版本与上述更新版本对齐，以确保与本版本完全兼容。 也可选择不升级，但兼容性仅在推荐版本下得到保证。

文档信息图标

我们不为第三方服务提供逐步升级说明。 此类操作请参阅各平台的官方文档，或在使用托管服务时查阅服务提供商的资源。 注意： 仅更改镜像标签不足以完成升级，且可能并非正确或安全的升级方式。

若选择跳过第三方服务版本更新，请仔细检查前一步合并过程是否修改了其版本。 如有必要，请撤销这些更改。

按需处理第三方服务版本后，可继续 升级流程 的剩余步骤。

升级至 2.0.0

升级到TBMQ v2.0.0 时，若尚未安装 Redis，请先按 步骤 6 完成安装后再执行 升级。

执行升级

若要升级，请从最新发布分支拉取最近更改：

1

git pull origin release-2.2.0
文档信息图标

如需升级到特定版本（如 TBMQ v2.0.0），将上述命令中的 release 分支替换为目标分支名，例如 release-2.0.0。

注意：请确保在合并过程中不丢失您的自定义修改。

若合并过程中出现与您修改无关的冲突， 建议接受远程分支的所有新变更。

可通过执行以下命令撤销合并操作：

1

git merge --abort

然后通过接受 theirs 变更重新执行合并：

1

git pull origin release-2.2.0 -X theirs

默认合并策略的常用选项：

  • -X ours - 此选项强制以我方版本自动解决冲突块。
  • -X theirs - 与 ours 相反。更多详情请参阅 此处。

然后执行以下命令：

1

./k8s-upgrade-tbmq.sh

1

./k8s-upgrade-tbmq.sh --fromVersion=FROM_VERSION

其中 FROM_VERSION 表示升级的起始版本。参见 升级说明 了解有效的 fromVersion 取值。


说明： 升级数据库时，可选择使用以下命令停止 TBMQ pods：

1

./k8s-delete-tbmq.sh

这将导致服务中断，但可确保更新后 DB 状态一致。 多数更新不需要停止 TBMQ。

完成后，再次执行资源部署。这将触发 TBMQ 使用最新版本进行 rollout restart。

1

./k8s-deploy-tbmq.sh

删除集群

执行以下命令删除 TBMQ节点：

1

./k8s-delete-tbmq.sh

执行以下命令删除所有 TBMQ节点及 configmap、负载均衡器等：

1

./k8s-delete-all.sh

执行以下命令删除 AKS集群：

1

az aks delete --resource-group $AKS_RESOURCE_GROUP --name $TB_CLUSTER_NAME

后续步骤