在 GKE 上使用 Helm 部署 TBMQ 集群

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

本指南将帮助你在Google Cloud Platform (GCP) 的Google Kubernetes Engine (GKE) 上使用官方Helm chart 部署TBMQ集群。

前置要求

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

• helm
• kubectl
• gcloud

配置Kubernetes环境

配置 GCP 工具

更多信息请参阅 开始前准备 指南。

创建新的 Google Cloud Platform 项目（推荐）或选择现有项目。执行以下命令确保已选择正确项目：

1
gcloud init

启用 GKE 服务

1
gcloud services enable container.googleapis.com

定义环境变量

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

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

1
2
3
4
5
6
7
8
9
10
export GCP_PROJECT=$(gcloud config get-value project)
export GCP_REGION=us-central1
export GCP_ZONE=us-central1
export GCP_ZONE1=us-central1-a
export GCP_ZONE2=us-central1-b
export GCP_ZONE3=us-central1-c
export GCP_NETWORK=default
export TB_CLUSTER_NAME=tbmq-cluster
export TB_DATABASE_NAME=tbmq-db
echo "You have selected project: $GCP_PROJECT, region: $GCP_REGION, gcp zones: $GCP_ZONE1,$GCP_ZONE2,$GCP_ZONE3, network: $GCP_NETWORK, cluster: $TB_CLUSTER_NAME, database: $TB_DATABASE_NAME"

参数说明：

• 第一行使用 gcloud 命令获取当前 GCP 项目 ID，本指南后续以 $GCP_PROJECT 引用；
• us-central1 为可用计算 regions 之一，本指南后续以 $GCP_REGION 引用；
• default 为默认 GCP 网络名称，本指南后续以 $GCP_NETWORK 引用；
• tbmq-cluster 为集群名称，可改为其他名称，本指南后续以 $TB_CLUSTER_NAME 引用；

配置并创建 GKE 集群

在 3 个可用区内创建分布式的区域集群，使用您偏好的机器类型。 以下示例在每个可用区预置 1 个 e2-standard-4 节点（共三个节点），但您可以根据工作负载需求修改 --machine-type 和 --num-nodes。 有关可用机器类型及其规格的完整列表，请参阅 GCP 机器类型文档。

执行以下命令（推荐）：

1
2
3
4
5
6
7
8
9
gcloud container clusters create $TB_CLUSTER_NAME \
--release-channel stable \
--region $GCP_REGION \
--network=$GCP_NETWORK \
--node-locations $GCP_ZONE1,$GCP_ZONE2,$GCP_ZONE3 \
--enable-ip-alias \
--num-nodes=1 \
--node-labels=role=main \
--machine-type=e2-standard-4

或者，您可以使用此指南进行自定义集群设置。

更新 kubectl 上下文

使用以下命令更新 kubectl 的上下文：

1
gcloud container clusters get-credentials $TB_CLUSTER_NAME --zone $GCP_ZONE

添加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"

若在GCP GKE上部署并计划使用Google Cloud SQL (PostgreSQL) 实例，请先启用所需 GCP服务，再按此说明配置并创建PostgreSQL实例。

负载均衡器配置

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

1
2
loadbalancer:
  type: "nginx"

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

1
2
loadbalancer:
  type: "gcp"

这将自动配置：

• 通过 HTTP Load Balancer 暴露明文 HTTP 流量；
• 通过 TCP Load Balancer 暴露明文 MQTT 流量。

HTTPS 访问

使用 Google 托管 SSL 证书配置负载均衡器的过程请参阅官方 文档页面。 以下说明摘自官方文档。继续前请仔细阅读前置条件。

• 预留静态全局 IP 地址：

1
gcloud compute addresses create tbmq-http-lb-address --global

• 获取预留的静态 IP 地址：

1
gcloud compute addresses describe tbmq-http-lb-address --global --format="get(address)"

• 配置 DNS：

必须至少配置一个完全限定域名（FQDN）指向预留的静态 IP 地址。 这是托管证书成功颁发的必要条件。

• 更新 values.yaml 文件：

1
2
3
4
5
6
7
8
9
10
11
12
13
loadbalancer:
  type: "gcp"
  http:
    enabled: true
    ssl:
      enabled: true
      # 这将是由 Helm chart 自动创建的 ManagedCertificate 资源的名称
      certificateRef: "<your-managed-certificate-resource-name>"
      domains:
      # 必须指向预留的静态 IP
      - <your-domain-name> 
      # GCP HTTP(S) 负载均衡器的静态 IP 地址
      staticIP: "tbmq-http-lb-address"

这将通过 Helm chart 创建的 ManagedCertificate 资源自动颁发并管理 SSL 证书，并通过 HTTPS 安全暴露 TBMQ。

MQTTS 访问

GCP 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>   *       <your-domain-name>   80      3d1h

使用 my-tbmq-cluster-http-lb 的 ADDRESS 字段连接集群。

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

用户名：

1
sysadmin@thingsboard.org

密码：

1
sysadmin

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

验证 HTTPS 访问（若已配置）

使用 dig 检查域名是否正确配置：

1
dig <your-domain-name>

示例输出：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
; <<>> DiG 9.11.3-1ubuntu1.16-Ubuntu <<>> <your-domain-name>
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 12513
;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1

;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 65494
;; QUESTION SECTION:
;YOUR_DOMAIN_NAME.	IN	A

;; ANSWER SECTION:
YOUR_DOMAIN_NAME. 36 IN	A	34.111.24.134

;; Query time: 0 msec
;; SERVER: 127.0.0.53#53(127.0.0.53)
;; WHEN: Fri Nov 19 13:00:00 EET 2021
;; MSG SIZE  rcvd: 74

分配完成后，等待 Google 托管证书完成配置，可能需要最多 60 分钟。可使用以下命令查看证书状态：

1
kubectl describe managedcertificate <your-managed-certificate-resource-name>

若域名记录已正确配置，证书最终将完成配置。使用 <your-domain-name> 连接集群。

验证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集群

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

1
gcloud container clusters delete $TB_CLUSTER_NAME --region=$GCP_REGION

下一步

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

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

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

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

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