使用 Kubernetes 在 GCP 上部署 TBMQ PE 集群

• 前置要求
  • 安装并配置工具
  • 启用 GCP 服务
• 克隆TBMQ PE K8S仓库
• 定义环境变量
• 配置并创建GKE集群
• 更新kubectl上下文
• 配置Google Cloud SQL（PostgreSQL）实例
  • 前提条件
  • 创建数据库服务器实例
  • 设置数据库密码
  • 创建数据库
  • 编辑数据库配置
• 创建命名空间
• 配置Valkey集群
• Installation
• 获取许可证密钥
• 配置许可证密钥
• Provision Kafka
  • 选项 1. 部署 Apache Kafka 集群
  • 选项 2. 使用 Strimzi Operator 部署 Kafka 集群
• Starting
• Configure Load Balancers
  • 配置HTTP(S) 负载均衡器
    • HTTP Load Balancer
    • HTTPS Load Balancer
  • 配置MQTT负载均衡器
    • MQTT over SSL
• Validate the setup
  • Validate MQTT access
  • 故障排查
• Upgrading
  • Backup and restore (Optional)
  • 从 TBMQ CE 升级到 TBMQ PE（v2.2.0）
• 删除集群
• 下一步

本指南将帮助你在GKE中部署TBMQ PE。

前置要求

安装并配置工具

要在 GKE 集群上部署 TBMQ PE，您需要安装 kubectl 和 gcloud 工具。 详见开始之前指南。

创建新的 Google Cloud Platform 项目（推荐）或选择现有项目。

执行以下命令确保已选择正确的项目：

1
gcloud init

启用 GCP 服务

执行以下命令为您的项目启用 GKE 和 SQL 服务：

1
gcloud services enable container.googleapis.com sql-component.googleapis.com sqladmin.googleapis.com

克隆TBMQ PE K8S仓库

1
2
git clone -b release-2.2.0 https://github.com/thingsboard/tbmq-pe-k8s.git
cd tbmq-pe-k8s/gcp

定义环境变量

定义您将在此指南后续各种命令中使用的环境变量。

假设您使用 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 是可用的计算区域之一。我们将在本指南后续内容中使用 $GCP_REGION 引用；
• default 是默认 GCP 网络名称；我们将在本指南后续内容中使用 $GCP_NETWORK 引用；
• tbmq-cluster 是您的集群名称。您可以输入不同的名称。我们将在本指南后续内容中使用 $TB_CLUSTER_NAME 引用；
• tbmq-db 是您的数据库服务器名称。您可以输入不同的名称。我们将在本指南后续内容中使用 $TB_DATABASE_NAME 引用。

配置并创建GKE集群

创建一个跨 3 个可用区分布的区域集群，节点使用您偏好的机器类型。 以下示例在每个可用区配置一个 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 --region $GCP_REGION

配置Google Cloud SQL（PostgreSQL）实例

前提条件

启用服务网络以使 K8S 集群连接至 DB 实例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
gcloud services enable servicenetworking.googleapis.com --project=$GCP_PROJECT

gcloud compute addresses create google-managed-services-$GCP_NETWORK \
--global \
--purpose=VPC_PEERING \
--prefix-length=16 \
--network=projects/$GCP_PROJECT/global/networks/$GCP_NETWORK

gcloud services vpc-peerings connect \
--service=servicenetworking.googleapis.com \
--ranges=google-managed-services-$GCP_NETWORK \
--network=$GCP_NETWORK \
--project=$GCP_PROJECT
    

创建数据库服务器实例

创建数据库版本为 “PostgreSQL 17” 的 PostgreSQL 实例，建议如下：

• 使用与 K8S 集群 GCP_REGION 相同区域；
• 使用与 K8S 集群 GCP_REGION 相同的 VPC 网络；
• 使用私有 IP 连接实例并禁用公网 IP；
• 生产环境使用高可用 DB 实例，开发集群使用单可用区实例；
• 至少使用 2 vCPU 和 7.5 GB 内存，可满足大多数负载，可按需扩展。

执行以下命令：

1
2
3
4
5
6
gcloud beta sql instances create $TB_DATABASE_NAME \
--database-version=POSTGRES_17 \
--region=$GCP_REGION --availability-type=regional \
--no-assign-ip --network=projects/$GCP_PROJECT/global/networks/$GCP_NETWORK \
--cpu=2 --memory=7680MB --edition=ENTERPRISE

也可参考 此 指南配置数据库。

从命令输出中记录 IP 地址（YOUR_DB_IP_ADDRESS）。成功执行后的输出类似：

1
2
3
Created [https://sqladmin.googleapis.com/sql/v1beta4/projects/YOUR_PROJECT_ID/instances/$TB_DATABASE_NAME].
NAME                        DATABASE_VERSION  LOCATION       TIER              PRIMARY_ADDRESS  PRIVATE_ADDRESS  STATUS
$TB_DATABASE_NAME           POSTGRES_17       us-central1-f  db-custom-2-7680  35.192.189.68    -                RUNNABLE

设置数据库密码

为新建数据库服务器实例设置密码：

1
2
3
gcloud sql users set-password postgres \
--instance=$TB_DATABASE_NAME \
--password=secret

其中：

• instance 为数据库服务器实例名称；
• secret 为密码。应使用不同密码。本指南后续以 YOUR_DB_PASSWORD 引用。

创建数据库

在 postgres 数据库服务器实例中创建 “thingsboard_mqtt_broker” 数据库：

1
gcloud sql databases create thingsboard_mqtt_broker --instance=$TB_DATABASE_NAME

其中 thingsboard_mqtt_broker 为数据库名称。可使用其他名称。本指南后续以 YOUR_DB_NAME 引用。

编辑数据库配置

将 YOUR_DB_IP_ADDRESS、YOUR_DB_PASSWORD 和 YOUR_DB_NAME 替换为正确值：

1
nano tbmq-db-configmap.yml

创建命名空间

为TBMQ集群部署创建专用命名空间，以提升资源隔离与管理效果。

1
2
kubectl apply -f tbmq-namespace.yml
kubectl config set-context $(kubectl config current-context) --namespace=thingsboard-mqtt-broker

配置Valkey集群

TBMQ 依赖 Valkey 存储设备持久化客户端的消息。 缓存还能减少直接数据库读取次数，提升性能，尤其是在启用认证且多客户端同时连接时。 若不使用缓存，每次新连接都会触发数据库查询以验证 MQTT 客户端凭据，在高连接率下可能导致不必要的负载。

在 Google Cloud 中配置 Valkey，请参阅 Valkey 的 Google Memorystore 文档：

• 创建 Memorystore for Valkey 实例： 预配启用集群模式和禁用集群模式实例的说明，包括服务连接策略和网络配置等前置条件。 (Google Cloud)

• 概述： 托管 Valkey 服务的详细信息、架构及分片、端点和支持的 Valkey 版本（含 8.0）等核心概念。 (Google Cloud)

• 网络要求： Private Service Connect 及服务连接策略设置的相关指导，用于建立安全连接。 (Google Cloud)

• 实例和节点 sizing： 根据工作负载（如 standard-small、highmem-medium）选择节点类型的建议、内存容量及性能特点。 (Google Cloud)

• 集群 vs 单机（启用 vs 禁用集群模式）： 水平扩展、吞吐量和功能支持的对比，有助于根据使用场景选择合适模式。 (Google Cloud)

• 高可用与副本： 多可用区部署、副本用于读扩展及生产环境弹性相关的最佳实践。 (Google Cloud)

• 最佳实践与扩展指南： 内存管理、淘汰策略、何时扩展及如何应对增长负载的建议。 (Google Cloud)

Valkey 集群就绪后，在 tbmq-cache-configmap.yml 中更新缓存配置，填入正确的端点值：

• Valkey 单机： 取消注释并设置以下值。请确保 REDIS_HOST 的值不包含端口（:6379）。

  1
  2
  3
  REDIS_CONNECTION_TYPE: "standalone"
  REDIS_HOST: "YOUR_VALKEY_ENDPOINT_URL_WITHOUT_PORT"
  #REDIS_PASSWORD: "YOUR_REDIS_PASSWORD"
  

• Valkey 集群： 提供以逗号分隔的 “host:port” 节点端点列表，用于引导。

  1
  2
  3
  4
  5
  6
  REDIS_CONNECTION_TYPE: "cluster"
  REDIS_NODES: "COMMA_SEPARATED_LIST_OF_NODES"
  #REDIS_PASSWORD: "YOUR_REDIS_PASSWORD"
  # Kubernetes 中处理动态 IP 和故障转移时建议启用：
  #REDIS_LETTUCE_CLUSTER_TOPOLOGY_REFRESH_ENABLED: "true"
  #REDIS_JEDIS_CLUSTER_TOPOLOGY_REFRESH_ENABLED: "true"
  

Installation

执行以下命令运行安装：

1
./k8s-install-tbmq.sh

此命令完成后，您应在控制台看到下一行：

1
安装已成功完成！

Otherwise, please check if you set the PostgreSQL URL and PostgreSQL password in the tbmq-db-configmap.yml correctly.

获取许可证密钥

在继续之前，请确保已选择订阅计划或购买永久许可证。 若尚未完成，请访问定价页面比较可用选项 并获取许可证密钥。

注意： 本指南中，我们将用 YOUR_LICENSE_KEY_HERE 表示您的许可证密钥。

配置许可证密钥

使用许可证密钥创建 k8s 密钥：

1
2
export TBMQ_LICENSE_KEY=YOUR_LICENSE_KEY_HERE 
kubectl create -n thingsboard-mqtt-broker secret generic tbmq-license --from-literal=license-key=$TBMQ_LICENSE_KEY

请勿忘记将 YOUR_LICENSE_KEY_HERE 替换为您的许可证密钥值。

Provision Kafka

TBMQ 需要运行中的 Kafka 集群。可通过两种方式部署 Kafka：

• 部署自管理的 Apache Kafka 集群
• 使用 Strimzi Operator 部署托管 Kafka 集群

根据环境与运维需求选择合适方案。

选项 1. 部署 Apache Kafka 集群

• 以 StatefulSet 运行，3 个 pod 处于 KRaft 双角色模式（每个节点同时充当 controller 和 broker）。

• 适用于轻量、自管的 Kafka 部署。

• 完整部署指南见此处.

快速步骤：

1
kubectl apply -f kafka/tbmq-kafka.yml

更新 TBMQ 配置文件（tbmq.yml 和 tbmq-ie.yml），并取消注释标记为以下内容的段落：

1
# Uncomment the following lines to connect to Apache Kafka

选项 2. 使用 Strimzi Operator 部署 Kafka 集群

• 使用 Kubernetes 的 Strimzi Cluster Operator 管理 Kafka。

• 便于升级、扩缩容和运维管理。

• 完整部署指南见此处.

快速步骤：

安装 Strimzi operator：

1
helm install tbmq-kafka -f kafka/operator/values-strimzi-kafka-operator.yaml oci://quay.io/strimzi-helm/strimzi-kafka-operator --version 0.47.0

部署 Kafka 集群：

1
kubectl apply -f kafka/operator/kafka-cluster.yaml

更新 TBMQ 配置文件（tbmq.yml 和 tbmq-ie.yml），并取消注释标记为以下内容的段落：

1
# Uncomment the following lines to connect to Strimzi

Starting

执行以下命令部署 broker：

1
./k8s-deploy-tbmq.sh

几分钟后，可执行以下命令检查所有 pod 状态。

1
kubectl get pods

若一切正常，应能看到 tbmq-0 和 tbmq-1 pod，且均处于 READY 状态。

Configure Load Balancers

配置HTTP(S) 负载均衡器

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

• http —— 不支持HTTPS的负载均衡器。适用于开发。优点是配置简单、成本最低。适合开发服务器，但不适合生产环境。
• https —— 支持HTTPS的负载均衡器。适用于生产。作为SSL终端，可方便地签发与维护有效SSL证书，自动将HTTP流量重定向到HTTPS。

下面提供各选项的配置链接/说明。

HTTP Load Balancer

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

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

负载均衡器配置可能需要一些时间。可使用以下命令定期检查负载均衡器状态：

1
kubectl get ingress

配置完成后，您应能看到类似输出：

1
2
NAME                     CLASS    HOSTS   ADDRESS         PORTS   AGE
tbmq-http-loadbalancer   <none>   *       34.111.24.134   80      7m25s

HTTPS Load Balancer

使用 Google 托管 SSL 证书配置负载均衡器的过程在官方文档页面中有描述。 以下说明摘自官方文档。请务必在继续操作前仔细阅读先决条件。

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

在 https-load-balancer.yml 文件中将 PUT_YOUR_DOMAIN_HERE 替换为有效域名：

1
nano receipts/https-load-balancer.yml

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

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

负载均衡器配置过程可能需要一些时间。您可以使用以下命令定期检查负载均衡器状态：

1
kubectl get ingress

配置完成后，您将看到类似的输出：

1
2
NAME                      CLASS    HOSTS   ADDRESS         PORTS   AGE
tbmq-https-loadbalancer   gce      *       34.111.24.134   80      7m25s

现在，将您使用的域名指向负载均衡器 IP 地址（即命令输出中替代 34.111.24.134 的地址）。

使用 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 managed-cert

如果您已正确配置域名解析记录，证书最终将配置完成。

配置完成后，可通过域名访问Web UI（https）。

配置MQTT负载均衡器

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

执行以下命令创建 TCP 负载均衡器：

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

负载均衡器将转发 1883 和 8883 端口的所有 TCP 流量。

MQTT over SSL

按照 此指南 创建包含 SSL 证书的 .pem 文件。将文件以 server.pem 保存在工作目录中。

需创建包含 PEM 文件的 config-map，可执行以下命令：

1
2
3
4
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 -

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

然后，取消 tbmq.yml 文件中标记为「Uncomment the following lines to enable two-way MQTTS」的所有节的注释。

执行以下命令应用更改：

1
kubectl apply -f tbmq.yml

Validate the setup

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

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

1
kubectl get ingress

输出应类似：

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

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

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

用户名：

1
sysadmin@thingsboard.org

密码：

1
sysadmin

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

Validate MQTT access

要通过 MQTT 连接集群，需获取对应服务的 IP。可执行以下命令：

1
kubectl get services

输出应类似：

1
2
NAME                     TYPE           CLUSTER-IP       EXTERNAL-IP              PORT(S)                         AGE
tbmq-mqtt-loadbalancer   LoadBalancer   10.100.119.170   *******                  1883:30308/TCP,8883:31609/TCP   6m58s

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

故障排查

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

1
kubectl logs -f tbmq-0

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

1
kubectl get statefulsets

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

Upgrading

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

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

Backup and restore (Optional)

While backing up your PostgreSQL database is highly recommended, it is optional before proceeding with the upgrade. For further guidance, follow the next instructions.

从 TBMQ CE 升级到 TBMQ PE（v2.2.0）

要将现有 TBMQ 社区版 (CE) 升级到 TBMQ 专业版 (PE)，请确保在开始前已运行最新的 TBMQ CE 2.2.0 版本。 将当前配置与最新的 TBMQ PE K8S 脚本 合并。 请勿忘记配置许可证密钥。

运行以下命令（包含升级脚本）以迁移 PostgreSQL 数据库数据（从 CE 到 PE）：

1
2
3
./k8s-delete-tbmq.sh
./k8s-upgrade-tbmq.sh --fromVersion=ce
./k8s-deploy-tbmq.sh

删除集群

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

1
./k8s-delete-tbmq.sh

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

1
./k8s-delete-all.sh

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

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

下一步

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

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

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

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

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