在 AKS 上使用 Helm 部署 TBMQ 集群

• 前置要求
• 配置Kubernetes环境
  • 配置 Azure 工具
  • 定义环境变量
  • 配置并创建 AKS 集群
  • 更新 kubectl 上下文
• 添加TBMQ集群Helm仓库
• 修改默认chart值
  • External PostgreSQL
  • 负载均衡器配置
    • HTTPS 访问
    • MQTTS 访问
• 创建命名空间
• 安装TBMQ Helm chart
• 验证HTTP访问
• 验证MQTT访问
• 故障排除
• 升级
• 卸载TBMQ Helm chart
• 删除Kubernetes集群
• 下一步

本指南将帮助你在Azure Kubernetes Service (AKS) 上使用官方Helm chart 部署TBMQ集群。

前置要求

要在 AKS 集群上使用 Helm 部署 TBMQ 集群，需在本地机器上安装以下工具：

• helm
• kubectl
• az

配置Kubernetes环境

配置 Azure 工具

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

1
az login

定义环境变量

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

假设您使用 Linux，请执行以下命令：

1
2
3
4
5
6
7
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
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 Application Gateway 的名称；
• tbmq-cluster - 集群名称，本指南后续以 $TB_CLUSTER_NAME 引用；

配置并创建 AKS 集群

创建 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 的完整选项请参阅此处。

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

更新 kubectl 上下文

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

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

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

1
kubectl get nodes

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

添加TBMQ集群Helm仓库

安装 chart 前，请将 TBMQ Helm 仓库添加到本地 Helm 客户端：

1
2
helm repo add tbmq-helm-chart https://helm.thingsboard.io/tbmq
helm repo update

修改默认chart值

要自定义 TBMQ 部署，请先从 chart 下载默认 values.yaml 文件：

1
helm show values tbmq-helm-chart/tbmq-cluster > values.yaml

请勿直接在 values.yaml 中修改 installation.installDbSchema。 此参数仅在首次安装时用于初始化 TBMQ 数据库 schema。 我们将在 helm install 命令中通过 --set 选项显式传入该参数。

External PostgreSQL

默认情况下，chart 会安装 Bitnami PostgreSQL 作为子 chart：

1
2
3
4
5
# 此部分将引入 bitnami/postgresql (https://artifacthub.io/packages/helm/bitnami/postgresql)。
# 若要添加额外配置参数，可将其放在 `postgresql` 键下，将传递给 bitnami/postgresql chart
postgresql:
  # @param enabled 若 enabled 为 true，将忽略 externalPostgresql 配置
  enabled: true

该 chart 将配置单节点实例，支持可配置的存储、备份和监控选项。 若已有 PostgreSQL 实例，可将 TBMQ 配置为外部连接。 为此，请将 postgresql.enabled 设为 false 以禁用内置 PostgreSQL，并在 externalPostgresql 部分指定连接详情。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# 若在外部部署 PostgreSQL，请在此部分配置
externalPostgresql:
  # @param host - 外部 PostgreSQL 服务器 host
  host: ""
  # @param port - 外部 PostgreSQL 服务器端口
  ##
  port: 5432
  # @param username - PostgreSQL 用户
  ##
  username: "postgres"
  # @param password - PostgreSQL 用户密码
  ##
  password: "postgres"
  # @param database - TBMQ 使用的 PostgreSQL 数据库名
  ##
  database: "thingsboard_mqtt_broker"

若在Azure AKS上部署并计划使用Azure Database for PostgreSQL，请按此指南配置并创建PostgreSQL实例。

负载均衡器配置

默认情况下，在 Kubernetes 上安装 TBMQ 时，Helm chart 会为标准 NGINX Ingress Controller 部署 HTTP 和 MQTT 流量配置。

1
2
loadbalancer:
  type: "nginx"

由于您在 Azure AKS 上部署 TBMQ 集群，需将此值改为：

1
2
loadbalancer:
  type: "azure"

这将自动配置：

• 通过 Azure Application Gateway 暴露明文 HTTP 流量；
• 通过 Azure Load Balancer 暴露明文 MQTT 流量。

HTTPS 访问

要为 HTTP 流量启用 TLS， 需将 loadbalancer.http.ssl.enabled 设为 true， 并将 loadbalancer.http.ssl.certificateRef 更新为已配置在 Azure Application Gateway 中的 SSL 证书名称。

参见以下示例：

1
2
3
4
5
6
7
loadbalancer:
  type: "azure"
  http:
    enabled: true
    ssl:
      enabled: true
      certificateRef: "<your-appgw-ssl-certificate-name>"

MQTTS 访问

Azure Load Balancer 不支持 MQTT 流量的 TLS 终止。 若要保护 MQTT 通信，必须在应用层（TBMQ 侧）直接配置双向 TLS（Mutual TLS 或 mTLS）。 有关配置双向 TLS 的详情，请参阅 TBMQ Helm chart 文档 此处。

创建命名空间

建议为 TBMQ 集群部署创建专用命名空间：

1
kubectl create namespace tbmq

1
kubectl config set-context --current --namespace=tbmq

这将把 tbmq 设为当前上下文的默认命名空间，因此您无需在每个命令中传递 –namespace 参数。

安装TBMQ Helm chart

现在可以使用 Helm chart 安装 TBMQ。 请确保当前目录与自定义的 values.yaml 文件所在目录一致。

1
2
3
helm install my-tbmq-cluster tbmq-helm-chart/tbmq-cluster \
  -f values.yaml \
  --set installation.installDbSchema=true

my-tbmq-cluster 为 Helm release 名称。可改为任意名称，后续 Helm 命令中将使用此名称引用该部署。

部署完成后，输出应类似以下内容：

1
2
3
4
5
6
7
8
9
10
NAME: my-tbmq-cluster
LAST DEPLOYED: Wed Mar 26 17:42:49 2025
NAMESPACE: tbmq
STATUS: deployed
REVISION: 1
TEST SUITE: None
NOTES:
TBMQ 集群 my-tbmq-cluster 将在数分钟内部署完成。
信息：
命名空间：tbmq

验证HTTP访问

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

可使用以下命令获取负载均衡器的 DNS 名称：

1
kubectl get ingress

输出应类似：

1
2
NAME                          CLASS    HOSTS   ADDRESS         PORTS   AGE
my-tbmq-cluster-http-lb       <none>   *       34.111.24.134   80      3d1h

使用 my-tbmq-cluster-http-lb 的 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
my-tbmq-cluster-mqtt-lb       LoadBalancer   10.100.119.170   *******                  1883:30308/TCP,8883:31609/TCP   6m58s

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

故障排除

如遇问题，可查看服务日志中的错误。例如，要查看 TBMQ 日志，请执行以下命令：

1
kubectl logs -f my-tbmq-cluster-tbmq-node-0

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

1
kubectl get statefulsets

更多详情请参阅 kubectl Cheat Sheet 命令参考。

升级

Helm 支持自 TBMQ 2.1.0 版本起引入。自 TBMQ 2.2.0 起， Helm chart 已更新至 1.1.0 版本，并引入了升级选项。 有关如何升级 TBMQ Helm 部署的详细说明，请参阅 Artifact Hub 上 TBMQ Helm Chart 文档的 Upgrading 部分。

卸载TBMQ Helm chart

要卸载 TBMQ Helm chart，请运行以下命令：

1
helm delete my-tbmq-cluster

此命令将从当前 Kubernetes 上下文中设置的命名空间内移除与该 release 关联的所有 TBMQ 组件。

helm delete 命令仅移除 TBMQ 集群的逻辑资源。 要完全清理所有持久化数据，卸载后可能还需手动删除关联的 Persistent Volume Claims (PVCs)：

1
kubectl delete pvc -l app.kubernetes.io/instance=my-tbmq-cluster

删除Kubernetes集群

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

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

下一步

• 快速入门指南 - 本指南提供 TBMQ 的快速概览。

• 安全指南 - 学习如何为 MQTT 客户端启用认证与授权。

• 配置指南 - 了解 TBMQ 配置文件和参数。

• MQTT 客户端类型指南 - 了解 TBMQ 客户端类型。

• 与 ThingsBoard 集成 - 了解如何将 TBMQ 与 ThingsBoard 集成。