使用 AKS 基础设施的微服务设置

• 前置条件
  • 安装和配置工具
• 步骤 1. 克隆 ThingsBoard CE K8S 脚本仓库
• 步骤 2. 定义环境变量
• 步骤 3. 配置并创建 AKS 集群
• 步骤 4. 更新 kubectl 的 context
• 步骤 5. 配置数据库
  • 5.3. 创建 Azure Database for PostgreSQL 服务器
  • 5.2. Cassandra
    • 预置附加节点池
    • 部署 Cassandra StatefulSet
    • 更新数据库设置
    • 创建 keyspace
• 步骤 6. Azure Cache for Valkey（可选）
• 步骤 7. 安装
• 步骤 8. 启动
• 步骤 9. 配置负载均衡器
  • 9.1. 配置 HTTP(S) 负载均衡器
  • HTTP 负载均衡器
  • HTTPS 负载均衡器
  • 9.2. 配置 MQTT 负载均衡器（可选）
    • MQTT over SSL
  • 9.3. 配置 CoAP 负载均衡器（可选）
    • CoAP over DTLS
  • 9.4. 配置 LwM2M 负载均衡器（可选）
    • LwM2M over DTLS
  • 9.5. 配置 Edge 负载均衡器（可选）
• 步骤 10. 使用
• 升级
• 下一步

本指南将帮助您在 Azure AKS 中以微服务模式搭建 ThingsBoard。

前置条件

安装和配置工具

要在 EKS 集群上部署 ThingsBoard，您需要安装 kubectl 和 az 工具。

安装完成后，需要使用 az login 命令在 CLI 中登录。

1
az login

步骤 1. 克隆 ThingsBoard CE K8S 脚本仓库

1
2
git clone -b release-4.3.0.1 https://github.com/thingsboard/thingsboard-ce-k8s.git
cd thingsboard-ce-k8s/azure/microservices

步骤 2. 定义环境变量

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

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

1
2
3
4
5
6
7
export AKS_RESOURCE_GROUP=ThingsBoardResources
export AKS_LOCATION=eastus
export AKS_GATEWAY=tb-gateway
export TB_CLUSTER_NAME=tb-cluster
export TB_DATABASE_NAME=tb-db
export TB_REDIS_NAME=tb-redis
echo "您的变量已就绪，可在 $AKS_LOCATION 创建资源组 $AKS_RESOURCE_GROUP，以及其中的集群 $TB_CLUSTER_NAME 和数据库 $TB_DATABASE_NAME"

其中：

• myResourceGroup - 用于部署和管理 Azure 资源的逻辑组。本指南后续将使用 AKS_RESOURCE_GROUP 引用；
• eastus - 要创建资源组的位置。本指南后续将使用 AKS_LOCATION 引用； 执行 az account list-locations 可查看所有位置列表；
• tb-gateway - Azure 应用程序网关名称；
• tb-cluster - 集群名称。本指南后续将使用 TB_CLUSTER_NAME 引用；
• tb-db - 数据库服务器名称。您可输入不同名称。本指南后续将使用 TB_DATABASE_NAME 引用；

步骤 3. 配置并创建 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.2.0.0/16" \
    --node-vm-size Standard_DS3_v2 \
    --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 磁盘类型：Ephemeral 或 Managed。在 VM 大小和 OS 磁盘大小允许的情况下默认为 ‘Ephemeral’。创建后可能无法更改；
• node-vm-size（或 -s） - 作为 Kubernetes 节点创建的虚拟机大小（默认值为 Standard_DS2_v2）；
• generate-ssh-keys - 如缺少则生成 SSH 公钥和私钥文件。密钥将存储在 ~/.ssh 目录。

上述命令中我们添加了 ApplicationGateway 的 AKS 附加组件。我们将使用此网关作为 ThingsBoard 基础设施的基于路径的负载均衡器。

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

您也可以按照此指南进行自定义集群设置。

步骤 4. 更新 kubectl 的 context

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

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

进行验证可执行命令

1
kubectl get nodes

您应看到集群节点列表

步骤 5. 配置数据库

5.3. 创建 Azure Database for PostgreSQL 服务器

您需要在 Azure 上设置 PostgreSQL。ThingsBoard 将使用其作为主数据库来存储设备、仪表板、规则链和设备遥测数据。

您可以按照此指南操作，但需注意以下要求：

• 请妥善保管 postgresql 密码。本指南后续将使用 YOUR_RDS_PASSWORD 引用；
• 确保 Azure Database for PostgreSQL 版本为最新 16.x；
• 确保 Azure Database for PostgreSQL 实例可从 ThingsBoard 集群访问；
• 确保使用 “thingsboard” 作为初始数据库名称；

以及建议：

• 启用”高可用性”。默认启用多项有用设置；

另一种创建 Azure Database for PostgreSQL 的方式是使用 az 工具 （别忘了将 ‘POSTGRESS_USER’ 和 ‘POSTGRESS_PASS’ 替换为您的用户名和密码）：

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 12 -d thingsboard

az postgres flexible-server create 有许多参数，其中部分为：

• location - 位置。值来自：az account list-locations；
• resource-group（或 -g）- 资源组名称；
• name - 服务器名称。名称只能包含小写字母、数字和连字符 (-)。最少 3 个字符，最多 63 个字符；
• admin-user - 服务器管理员用户名。设置后无法更改；
• admin-password - 管理员密码。最少 8 个字符，最多 128 个字符。密码必须包含以下四类字符中的三类：英文字母大写、英文字母小写、数字和非字母数字字符；
• public-access - 确定公共访问。输入单个或 IP 地址范围以加入允许的 IP 列表。IP 地址范围必须以破折号分隔且不含空格。指定 0.0.0.0 允许 Azure 内部署的任何资源访问您的服务器。设置为 “None” 会将服务器置于公共访问模式但不创建防火墙规则；
• storage-size - 服务器存储容量。最小 32 GiB，最大 16 TiB；
• version - 服务器主版本。
• high-availability - 启用或禁用高可用性功能。默认值为 Disabled。高可用性只能在灵活服务器创建时设置（接受值：Disabled、Enabled。默认值：Disabled）；
• database-name（或 -d）- 配置数据库服务器时要创建的数据库名称。

完整参数列表请参阅此处。

响应示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
{
  "connectionString": "postgresql://postgres:postgres@$tb-db.postgres.database.azure.com/postgres?sslmode=require",
  "databaseName": "thingsboard",
  "firewallName": "AllowAllAzureServicesAndResourcesWithinAzureIps_2021-11-17_15-45-6",
  "host": "tb-db.postgres.database.azure.com",
  "id": "/subscriptions/daff3288-1d5d-47c7-abf0-bfb7b738a18c/resourceGroups/myResourceGroup/providers/Microsoft.DBforPostgreSQL/flexibleServers/thingsboard",
  "location": "East US",
  "password": "postgres",
  "resourceGroup": "myResourceGroup",
  "skuname": "Standard_D2s_v3",
  "username": "postgres",
  "version": "12"
}

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

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

1
nano tb-node-db-configmap.yml

5.2. Cassandra

使用 Cassandra 为可选步骤。 如计划每秒插入超过 5K 数据点或希望优化存储空间，建议使用 Cassandra。

预置附加节点池

预置将托管 Cassandra 实例的附加节点池。 您可以更改机器类型。建议至少 4 个 vCPU 和 16GB 内存。

我们将在三个可用区各创建 3 个独立节点池，每个 zone 1 个节点。 由于计划使用区域磁盘，我们不希望 k8s 在对应磁盘不可用的节点上启动 Pod。 这些 zone 将具有相同的节点标签。我们将使用此标签来定位 StatefulSet 的部署。

因此，为您所在位置在三个 zone 中定义 3 个节点池：

1
2
3
az aks nodepool add --resource-group $AKS_RESOURCE_GROUP --cluster-name $TB_CLUSTER_NAME --name tbcassandra1 --node-count 1 --zones 1 --labels role=cassandra
az aks nodepool add --resource-group $AKS_RESOURCE_GROUP --cluster-name $TB_CLUSTER_NAME --name tbcassandra2 --node-count 1 --zones 2 --labels role=cassandra
az aks nodepool add --resource-group $AKS_RESOURCE_GROUP --cluster-name $TB_CLUSTER_NAME --name tbcassandra3 --node-count 1 --zones 3 --labels role=cassandra

部署 Cassandra StatefulSet

创建 ThingsBoard 命名空间：

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

将 Cassandra 部署到新节点组：

1
kubectl apply -f receipts/cassandra.yml

Cassandra 集群启动可能需要几分钟。可使用以下命令监控进程：

1
kubectl get pods

更新数据库设置

编辑 ThingsBoard 数据库设置文件并添加 Cassandra 设置：

1
2
3
echo "  DATABASE_TS_TYPE: cassandra" >> tb-node-db-configmap.yml
echo "  CASSANDRA_URL: cassandra:9042" >> tb-node-db-configmap.yml
echo "  CASSANDRA_LOCAL_DATACENTER: dc1"  >> tb-node-db-configmap.yml

检查设置是否已更新：

1
cat tb-node-db-configmap.yml | grep DATABASE_TS_TYPE

预期输出：

1
  DATABASE_TS_TYPE: cassandra

创建 keyspace

使用以下命令创建 thingsboard keyspace：

1
2
3
4
5
6
    kubectl exec -it cassandra-0 -- bash -c "cqlsh -e \
                    \"CREATE KEYSPACE IF NOT EXISTS thingsboard \
                    WITH replication = { \
                        'class' : 'NetworkTopologyStrategy', \
                        'dc1' : '3' \
                    };\""

步骤 6. Azure Cache for Valkey（可选）

ThingsBoard 使用缓存来提高性能并避免频繁的数据库读取。 默认情况下，部署已使用本地 Valkey 缓存。Azure 不提供托管 Valkey 集群，但您可以根据 Azure 文档 设置自己的 Valkey 集群，以替代默认部署。

自 ThingsBoard v4.0.0 起，Valkey 8.x 为官方支持版本。 Valkey 仍兼容 Redis 7.2.x，因此使用 Redis 的配置也可工作。 但 Redis 7.2.x 仅在 Enterprise 或 Enterprise Flash SKU 中可用。 Basic、Standard 和 Premium SKU 仍仅支持 Redis 6.x。 Redis Enterprise 安装指南请参阅： 创建 Redis Enterprise 缓存

编辑 thirdparty.yml 文件，找到名为 tb-valkey 的 StatefulSet 部分，将 spec.replicas 设置为 0。

Valkey 集群就绪后，需要在配置文件中替换端点。 若使用独立 Valkey，请编辑 tb-cache-configmap.yml，将 REDIS_HOST 值替换为 Redis 端点。 若以集群模式部署 Valkey，请将 REDIS_HOST 替换为：

1
2
REDIS_CONNECTION_TYPE: cluster
REDIS_NODES: (用于引导的 "host:port" 对的逗号分隔列表)

步骤 7. 安装

执行以下命令运行数据库的初始设置。该命令将启动短生命周期的 ThingsBoard Pod 以配置必要的数据库表、索引等。

1
 ./k8s-install-tb.sh --loadDemo

其中：

• --loadDemo - 可选参数。是否加载额外的演示数据。

此命令完成后，您应在控制台看到以下输出：

1
Installation finished successfully!

否则，请检查是否在 tb-node-db-configmap.yml 中正确设置了 PostgreSQL URL。

步骤 8. 启动

执行以下命令部署 ThingsBoard 服务：

1
 ./k8s-deploy-resources.sh

几分钟后，您可调用 kubectl get pods。若一切正常，您应能看到 tb-node-0 pod 处于 READY 状态。

几分钟后，可执行 kubectl get pods。若一切正常，您应能看到 tb-node-0 Pod 处于 READY 状态。

您还应部署传输微服务。为节省资源，可省略不使用的协议：

HTTP 传输（可选）

1
kubectl apply -f transports/tb-http-transport.yml

MQTT 传输（可选）

1
kubectl apply -f transports/tb-mqtt-transport.yml

CoAP 传输（可选）

1
kubectl apply -f transports/tb-coap-transport.yml

LwM2M 传输（可选）

1
kubectl apply -f transports/tb-lwm2m-transport.yml

SNMP 传输（可选）

1
kubectl apply -f transports/tb-snmp-transport.yml

步骤 9. 配置负载均衡器

9.1. 配置 HTTP(S) 负载均衡器

配置 HTTP(S) 负载均衡器以访问 ThingsBoard 实例的 Web 界面。主要有 3 种配置选项：

• 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-http-loadbalancer   <none>   *       34.111.24.134   80      7m25s

现在，您可以使用该地址（命令输出中替代 34.111.24.134 的地址）通过端口 80 访问 HTTP Web UI，并通过 HTTP API 连接设备。使用以下默认凭据：

• 系统管理员：sysadmin@thingsboard.org / sysadmin
• 租户管理员：tenant@thingsboard.org / tenant
• 客户用户：customer@thingsboard.org / customer

HTTPS 负载均衡器

使用 SSL 证书时，可通过以下命令直接在 Azure ApplicationGateWay 中添加证书：

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 ThingsBoardHTTPCert \
   --cert-file YOUR_CERT \
   --cert-password YOUR_CERT_PASS

将证书添加到应用程序负载均衡器后可执行：

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

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

1
kubectl get ingress

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

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

注意：负载均衡器会将所有 HTTP 流量重定向到 HTTPS。不支持 HTTPS 的设备将无法连接 ThingsBoard。 如需支持此类设备，您可以部署单独的 HTTP 传输负载均衡器（推荐） 或在 https-load-balancer.yml 文件中修改 appgw.ingress.kubernetes.io/ssl-redirect 设置以禁用重定向行为。

9.2. 配置 MQTT 负载均衡器（可选）

如计划使用 MQTT 协议连接设备，请配置 MQTT 负载均衡器。

使用以下命令创建 TCP 负载均衡器：

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

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

MQTT over SSL

此类型负载均衡器需要您自行预置和维护有效的 SSL 证书。 请按照通用 MQTT over SSL 指南 在 transport/tb-mqtt-transport.yml 文件中配置所需环境变量。

9.3. 配置 CoAP 负载均衡器（可选）

如计划使用 CoAP 协议连接设备，请配置 CoAP 负载均衡器。

使用以下命令创建 CoAP 负载均衡器：

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

该负载均衡器将转发以下端口的全部 UDP 流量：

• 5683 - CoAP 服务器非安全端口
• 5684 - CoAP 服务器安全 DTLS 端口。

CoAP over DTLS

此类型负载均衡器需要您自行预置和维护有效的 SSL 证书。 请按照通用 CoAP over DTLS 指南 在 transport/tb-coap-transport.yml 文件中配置所需环境变量。

9.4. 配置 LwM2M 负载均衡器（可选）

如计划使用 LwM2M 协议连接设备，请配置 LwM2M 负载均衡器。

使用以下命令创建 LwM2M UDP 负载均衡器：

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

该负载均衡器将转发以下端口的全部 UDP 流量：

• 5685 - LwM2M 服务器非安全端口。
• 5686 - LwM2M 服务器安全 DTLS 端口。
• 5687 - LwM2M 引导服务器 DTLS 端口。
• 5688 - LwM2M 引导服务器安全 DTLS 端口。

LwM2M over DTLS

此类型负载均衡器需要您自行预置和维护有效的 SSL 证书。 请按照通用 LwM2M over DTLS 指南 在 transport/tb-lwm2m-transport.yml 文件中配置所需环境变量。

9.5. 配置 Edge 负载均衡器（可选）

若计划将 Edge 实例连接到 ThingsBoard 服务器，需配置 Edge 负载均衡器。

要创建 TCP Edge 负载均衡器，使用以下命令应用提供的 YAML 文件：

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

负载均衡器将转发端口 7070 上的所有 TCP 流量。

Edge 负载均衡器配置完成后，可将 Edge 实例连接到 ThingsBoard 服务器。

连接 Edge 实例前，需获取 Edge 负载均衡器的外部 IP 地址。执行以下命令获取该 IP：

1
kubectl get services | grep "EXTERNAL-IP\|tb-edge-loadbalancer"

应看到类似以下输出：

1
2
NAME                   TYPE           CLUSTER-IP    EXTERNAL-IP      PORT(S)          AGE
tb-edge-loadbalancer   LoadBalancer   10.44.5.255   104.154.29.225   7070:30783/TCP   85m

记下外部 IP 地址，并在 Edge 连接参数中将 CLOUD_RPC_HOST 设为该地址。

步骤 10. 使用

现在您可以在浏览器中使用负载均衡器的 IP 地址打开 ThingsBoard Web 界面。

您可以使用以下命令查看 HTTP 负载均衡器的 DNS 名称（ADDRESS 列）：

1
kubectl get ingress

您应该看到类似的输出：

要通过 MQTT 或 COAP 连接集群，需要获取对应的服务，可使用以下命令：

1
kubectl get service

您应该看到类似的输出：

有两个负载均衡器：

• tb-mqtt-loadbalancer - 用于 TCP（MQTT）协议
• tb-udp-loadbalancer - 用于 UDP（COAP/LwM2M）协议

使用负载均衡器的 EXTERNAL-IP 字段连接集群。

使用以下默认凭据：

• 系统管理员：sysadmin@thingsboard.org / sysadmin

如果使用 --loadDemo 标志安装了带演示数据的数据库，您还可以使用以下凭据：

• 租户管理员：tenant@thingsboard.org / tenant
• 客户用户：customer@thingsboard.org / customer

如遇问题，可以检查服务日志以查找错误。例如，要查看 ThingsBoard 节点日志，请执行以下命令：

1
kubectl logs -f tb-node-0

或使用 kubectl get pods 查看 Pod 状态。 或使用 kubectl get services 查看所有服务状态。 或使用 kubectl get deployments 查看所有部署状态。 详见 kubectl 速查表 命令参考。

执行以下命令删除 tb-node 和负载均衡器：

1
./k8s-delete-resources.sh

执行以下命令删除所有数据（包括数据库）：

1
./k8s-delete-all.sh

升级

当需要升级数据库时，执行以下命令：

1
2
3
 ./k8s-delete-resources.sh
 ./k8s-upgrade-tb.sh --fromVersion=[FROM_VERSION]
 ./k8s-deploy-resources.sh

其中：

• FROM_VERSION - 升级起始版本。有关有效 fromVersion 值请参阅 升级说明。注意，必须逐个版本升级（例如 3.6.1 -> 3.6.2 -> 3.6.3 等）。

下一步

• 快速入门指南 - 快速了解ThingsBoard主要功能，约15-30分钟完成。

• 连接设备 - 根据连接技术或方案学习如何连接设备。

• 数据可视化 - 配置ThingsBoard复杂仪表盘的说明。

• 数据处理与操作 - 学习使用ThingsBoard规则引擎。

• IoT数据分析 - 学习使用规则引擎执行基本分析任务。

• 高级功能 - 了解ThingsBoard高级功能。

• 贡献与开发 - 了解ThingsBoard贡献与开发。