在 EKS 上使用 Helm 部署 TBMQ 集群

• 前置要求
• 配置Kubernetes环境
  • 配置 AWS 工具
  • 配置概述
  • PostgreSQL 相关说明（可选节点组）
  • OIDC 与 AWS Load Balancer Controller 的 IAM 设置
  • 插件说明
  • 创建 EKS 集群
  • 创建 GP3 存储类并将其设为默认
  • 附加策略
  • 创建 AWS Load Balancer Controller
• 添加TBMQ集群Helm仓库
• 修改默认chart值
  • 更新Pod调度中的nodeSelector
  • 外部PostgreSQL
  • 负载均衡器配置
    • HTTPS 访问
    • MQTTS 访问
      • TLS 终止（单向 TLS）
      • Mutual TLS（双向 TLS 或 mTLS）
• 创建命名空间
• 安装TBMQ Helm chart
• 验证HTTP访问
• 验证MQTT访问
• 故障排除
• 升级
• 卸载TBMQ Helm chart
• 删除Kubernetes集群
• 下一步

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

前置要求

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

• helm
• kubectl
• eksctl
• awscli

此外，需配置 Access Key、Secret Key 和默认区域。 获取 Access Key 和 Secret Key 请参阅 此指南。 默认区域应为要部署集群的目标区域的 ID。

配置Kubernetes环境

配置 AWS 工具

1
aws configure

配置概述

要部署 EKS 集群，建议使用预定义的 EKS 集群配置文件。 请使用以下命令下载：

1
curl -o cluster.yml https://raw.githubusercontent.com/thingsboard/tbmq/release-2.2.0/k8s/helm/aws/cluster.yml

可根据需要修改以下字段：

• region - 集群所在的 AWS 区域（默认 us-east-1）
• availabilityZones - 区域可用区的具体 ID（默认 [ us-east-1a,us-east-1b,us-east-1c ]）
• instanceType - 节点组实例类型。可按工作负载（如 TBMQ、Redis、Kafka）分别调整。
• desiredCapacity - 每个节点组的节点数。默认值适用于测试。
• volumeType - EC2 节点的 EBS 卷类型。默认为 gp3。

请参阅 Amazon EC2 Instance types 为生产工作负载选择合适的实例类型。

PostgreSQL 相关说明（可选节点组）

TBMQ Helm chart 支持外部 PostgreSQL，因此可能不需要此节点组：

1
2
3
4
5
6
7
8
  - name: tbmq-postgresql
    instanceType: c7a.large
    desiredCapacity: 1
    maxSize: 1
    minSize: 0
    labels: { role: postgresql }
    volumeType: gp3
    volumeSize: 20

以下情况可安全移除此部分：

• 使用 Amazon RDS 或现有 PostgreSQL 服务。
• 希望将数据库置于 EKS 集群外部。

OIDC 与 AWS Load Balancer Controller 的 IAM 设置

在 cluster.yml 中包含以下块，将自动启用服务账户的 IAM 角色并为 AWS Load Balancer Controller 创建服务账户：

1
2
3
4
5
6
7
8
iam:
  withOIDC: true
  serviceAccounts:
    - metadata:
        name: aws-load-balancer-controller
        namespace: kube-system
      wellKnownPolicies:
        awsLoadBalancerController: true

此配置：

• 启用 OIDC 集成（服务账户 IAM 角色所需）。
• 自动创建具有 AWS Load Balancer Controller 适当 IAM 策略的服务账户。

使用 eksctl 时，这是最简单、最集成的方式。

若不愿在 cluster.yml 中管理 IAM，或组织要求手动创建 IAM 策略，可在集群创建后手动设置。

请遵循以下 AWS 官方指南：

• 为集群创建 IAM OIDC 提供程序
• 使用 AWS Load Balancer Controller 路由互联网流量

插件说明

cluster.yml 中的 addons 部分会自动安装并配置扩展 EKS 集群基础功能的必要组件。

• aws-ebs-csi-driver - 通过 EBS CSI driver 启用 Amazon EBS 卷动态配置。 Redis 和 Kafka 等 TBMQ 组件需要持久化存储。此驱动允许 Kubernetes 在创建 PersistentVolumeClaim 时按需配置 gp3 卷。
• aws-efs-csi-driver - 通过 EFS CSI driver 使工作负载可使用 Amazon EFS（Elastic File System）作为持久卷。 TBMQ 不需要 EFS，但若需多个 pods 共享同一卷（如共享日志、配置文件或支持水平扩展的有状态工作负载），则很有用。
• vpc-cni - 安装 Amazon VPC CNI 插件，使 Kubernetes pods 具备原生 VPC 网络能力。 为每个 pod 从 VPC 子网分配独立 IP 地址。对 pod 间及 pod 对外通信至关重要。
• coredns - 通过 CoreDNS 为 Kubernetes 服务提供内部 DNS 解析。
• kube-proxy - 通过 kube-proxy 管理各节点上的网络规则以处理服务路由。

创建 EKS 集群

1
eksctl create cluster -f cluster.yml

创建 GP3 存储类并将其设为默认

gp3 EBS 卷类型是 Amazon EKS 的推荐默认选项，相比 gp2 具有更好的性能、成本效益和灵活性。

请下载存储类配置文件：

1
curl -o gp3-def-sc.yml https://raw.githubusercontent.com/thingsboard/tbmq/release-2.2.0/k8s/helm/aws/gp3-def-sc.yml

应用配置：

1
kubectl apply -f gp3-def-sc.yml

若存在 gp2 StorageClass，可能与 gp3 冲突。可将 gp2 存储类设为非默认：

1
kubectl patch storageclass gp2 -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"false"}}}'

或删除 gp2 StorageClass（若未使用）：

1
kubectl delete storageclass gp2

检查 gp3 存储类是否可用并已标记为默认：

1
kubectl get sc

输出应类似：

1
2
NAME            PROVISIONER       RECLAIMPOLICY   VOLUMEBINDINGMODE      ALLOWVOLUMEEXPANSION   AGE
gp3 (default)   ebs.csi.aws.com   Delete          WaitForFirstConsumer   true                   30s

附加策略

若使用提供的 cluster.yml 创建了 EKS 集群，则以下内容已自动配置：

• 已启用 OIDC 提供程序（withOIDC: true）
• 已在 kube-system 命名空间中创建服务账户 aws-load-balancer-controller。
• 该账户已标注 IAM 访问权限并与 AWS 托管已知策略关联。

但您必须手动将 AWSLoadBalancerControllerIAMPolicy（或自定义策略）附加到 eksctl 创建的 IAM 角色。

• 查找 eksctl 创建的角色：

1
2
3
aws iam list-roles \
  --query "Roles[?contains(RoleName, 'eksctl-tbmq')].RoleName" \
  --output text

输出应类似：

1
eksctl-tbmq-addon-iamserviceaccount-kube-syst-Role1-J9l4M87BqmNu

• 附加策略：

将 YOUR_AWS_ACCOUNT_ID 和 ROLE_NAME 替换为实际 AWS 账户 ID 和上一步找到的 IAM 角色名称：

1
2
3
aws iam attach-role-policy \
--policy-arn arn:aws:iam::YOUR_AWS_ACCOUNT_ID:policy/AWSLoadBalancerControllerIAMPolicy \
--role-name ROLE_NAME

可使用以下命令验证附加结果：

1
aws iam list-attached-role-policies --role-name ROLE_NAME

输出应类似：

1
ATTACHEDPOLICIES        arn:aws:iam::YOUR_AWS_ACCOUNT_ID:policy/AWSLoadBalancerControllerIAMPolicy     AWSLoadBalancerControllerIAMPolicy

创建 AWS Load Balancer Controller

要支持通过 Kubernetes 注解配置 Network Load Balancer (NLB) 和 Application Load Balancer (ALB)， 需在 EKS 集群中部署 AWS Load Balancer Controller。

1
2
helm repo add eks https://aws.github.io/eks-charts
helm repo update

然后，将 controller 安装到 kube-system 命名空间并关联到您的集群：

1
2
3
4
5
helm install aws-load-balancer-controller eks/aws-load-balancer-controller \
--namespace kube-system \
--set clusterName=tbmq \
--set serviceAccount.create=false \
--set serviceAccount.name=aws-load-balancer-controller

验证 controller 是否已安装：

1
kubectl get deployment -n kube-system aws-load-balancer-controller

示例输出如下。

1
2
NAME                           READY   UP-TO-DATE   AVAILABLE   AGE
aws-load-balancer-controller   2/2     2            2           84s

添加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 选项显式传入该参数。

更新Pod调度中的nodeSelector

为确保基于 EKS 的 TBMQ 集群高可用及正确调度， 必须使用 Helm values.yml 中的 nodeSelector 字段将 TBMQ 组件分配到特定节点组。

您的 cluster.yml 已定义带基于角色标签的专用节点组。 例如，tbmq-node 托管节点组为：

1
labels: { role: tbmq }

必须使用这些标签将各组件映射到相应节点组。

以下为显式分配各组件的示例：

• TBMQ Broker：

1
2
3
tbmq:
  nodeSelector:
    role: tbmq

• TBMQ Integration Executor：

1
2
3
tbmq-ie:
  nodeSelector:
    role: tbmq-ie

• Kafka Controller 节点：

1
2
3
4
kafka:
  controller:
    nodeSelector:
      role: kafka

• Redis 集群节点：

1
2
3
4
redis-cluster:
  redis:
    nodeSelector:
      role: redis

• PostgreSQL（若未使用外部数据库）：

1
2
3
4
5
6
7
8
9
postgresql:
  primary:
    nodeSelector:
      role: postgresql

  backup:
    cronjob:
      nodeSelector:
        role: postgresql

外部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"

若在Amazon EKS上部署并计划使用AWS RDS作为PostgreSQL，请按此指南配置并创建RDS实例。

负载均衡器配置

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

1
2
loadbalancer:
  type: "nginx"

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

1
2
loadbalancer:
  type: "aws"

这将自动配置：

• 通过 AWS Application Load Balancer (ALB) 暴露明文 HTTP 流量；
• 通过 AWS Network Load Balancer (NLB) 暴露明文 MQTT 流量。

HTTPS 访问

使用 AWS Certificate Manager 创建或导入 SSL 证书。记录证书 ARN。

接下来，需将 loadbalancer.http.ssl.enabled 设为 true， 并将 loadbalancer.http.ssl.certificateRef 更新为之前配置的 ACM 证书 ARN。

参见以下示例：

1
2
3
4
5
6
7
loadbalancer:
  type: "aws"
  http:
    enabled: true
    ssl:
      enabled: true
      certificateRef: "<your-acm-certificate-arn-for-alb>"

MQTTS 访问

TLS 终止（单向 TLS）

配置 MQTTS 的最简单方式是让 MQTT 负载均衡器（AWS NLB）充当 TLS 终止点。 这样可建立单向 TLS 连接：设备与负载均衡器之间的流量加密，负载均衡器与 TBMQ 之间的流量未加密。 由于 ALB/NLB 在您的 VPC 内运行，应无安全问题。 此方案的主要不足是无法使用「X.509 certificate」MQTT 客户端凭据， 因为客户端证书信息不会从负载均衡器传递到 TBMQ。

使用 AWS Certificate Manager 创建或导入 SSL 证书。记录证书 ARN。

接下来，需将 loadbalancer.mqtt.tlsTermination.enabled 设为 true， 并将 loadbalancer.mqtt.tlsTermination.certificateRef 更新为之前配置的 ACM 证书 ARN。

参见以下示例：

1
2
3
4
5
6
7
loadbalancer:
  type: "aws"
  mqtt:
    enabled: true
    tlsTermination:
      enabled: true
      certificateRef: "<your-acm-certificate-arn-for-nlb>"

Mutual TLS（双向 TLS 或 mTLS）

启用 MQTTS 的另一种更复杂方式是获取有效（已签名）TLS 证书并在 TBMQ 中配置。 此方案的主要优势是可以与「X.509 certificate」MQTT 客户端凭据结合使用。

有关配置双向 TLS 的详情，请参阅 TBMQ Helm chart 文档 此处。

若 loadbalancer.mqtt.mutualTls.enabled 设为 true，TLS 终止配置将被忽略。

创建命名空间

建议为 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>   *       k8s-tbmq-mytbmq-000aba1305-222186756.eu-west-1.elb.amazonaws.com   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   k8s-tbmq-mytbmq-b9f99d1ab6-1049a98ba4e28403.elb.eu-west-1.amazonaws.com                  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集群

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

1
eksctl delete cluster -r us-east-1 -n tbmq -w

若配置使用了不同值，请确保更新集群名称 -n 和区域 -r。

下一步

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

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

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

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

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