Apache IoTDB（4）：深度解析时序数据库 IoTDB 在Kubernetes 集群中的部署与实践指南

前言

Apache IoTDB 凭借其高吞吐量、低存储成本和灵活查询能力，在工业物联网、智能家居等领域得到广泛应用。本文将结合版本（IoTDB v1.3.3.2与Kubernetes 1.24），详细讲明白如何在Kubernetes集群中实现IoTDB的高可用部署，并分享实际的优化经验

虚拟机测试节点【单机版安装】和【集群版安装】和【Docker部署】学习之前文章

• 单机版安装：Apache IoTDB（1）：时序数据库介绍与单机版安装部署指南
• 集群版安装：Apache IoTDB（2）：时序数据库 IoTDB 集群安装部署的技术优势与适用场景分析
• Docker集群部署：Apache IoTDB（3）：时序数据库 IoTDB Docker部署从单机到集群的全场景部署与实践指南

一、Apache IoTDB产品解析

1.1 核心特性

• 极致时序数据处理：支持每秒百万级数据点写入，通过列式存储和时间分区技术实现5-10倍压缩率。
• 灵活查询能力：提供类SQL语法，支持时间窗口分析、降采样及多设备数据对齐。
• 边缘-云端协同：轻量级设计支持边缘设备部署，同时可通过分布式集群实现水平扩展。
• 生态集成：内置MQTT服务器、支持Kafka/Spark集成，提供Java/Python客户端。

1.2 架构设计

架构图

• 存储组（Storage Group）：逻辑隔离单元，类似传统数据库的"库"概念。
• 设备层（Device）：对应传统数据库的"表"，存储具体传感器数据。
• 时间序列（Timeseries）：最小数据单元，支持FLOAT、TEXT、VECTOR等数据类型。

二、版本要求

需要在本地有一个可用的 Kubernetes 集群，作为部署 IoTDB 集群的基础

组件	版本要求
Kubernetes	1.24 以上
IoTDB（点击下载）	v1.3.3.2 以上
存储类	local-storage
节点配置	4核8G起

三、Kubernetes 环境准备

3.1 创建命名空间

需注意：博主踩过的坑（在执行命名空间创建操作之前，需验证所指定的命名空间名称在 Kubernetes 集群中尚未被使用。如果命名空间已存在，创建命令将无法执行，可能导致部署过程中的错误）

创建命名空间命令：

kubectl create ns iotdb-ns

查看命名空间命令

kubectl get ns

3.2 创建 PV 配置文件

PV用于持久化存储IoTDB的ConfigNode 和 DataNode的数据，集群中有几个节点就要创建几个PV

需注意：1个ConfigNode和1个DataNode 也算2个节点，要2个PV

博主这边以 3ConfigNode、3DataNode 为例：

1. 创建 pv.yaml 文件，并复制六份，分别重命名为 pv01.yaml 到 pv06.yaml

新建文件夹放yaml文件

创建 pv.yaml 文件命令

touch pv.yaml

2. 修改每个文件中的 name 和 path 以确保一致性

举例 pv.yaml:

# pv.yaml
apiVersion: v1
kind: PersistentVolume
metadata:
  name: iotdb-pv-01
spec:
  capacity:
    storage: 10Gi # 存储容量
  accessModes: # 访问模式
    - ReadWriteOnce
  persistentVolumeReclaimPolicy: Retain # 回收策略
  # 存储类名称，如果使用本地静态存储storageClassName 不用配置，如果使用动态存储必需设置此项
  storageClassName: local-storage 
  # 根据你的存储类型添加相应的配置
  hostPath: # 如果是使用本地路径
    path: /data/k8s-data/iotdb-pv-01
    type: DirectoryOrCreate  # 这行不配置就要手动创建文件夹

3. 应用 PV 配置（pv-01.yaml 到 pv-06.yaml 都要应用）

配置命令：

kubectl apply -f pv-01.yaml
kubectl apply -f pv-02.yaml
# 这里一直到pv-06.yaml

4. 配置完成后进行查看

查看命令：

kubectl get pv

5. 手动创建文件夹
   如果yaml里的hostPath-type未配置，需要手动去创建对应的文件夹

需注意：要在所有 Kubernetes 节点上创建对应的文件夹

创建命令：

mkdir -p /data/k8s-data/iotdb-pv-01
mkdir -p /data/k8s-data/iotdb-pv-02
# 这里一直到pv-06.yaml

3.3 安装 Helm

需要参考Helm官网，此处不做过多叙述了

Helm 官方安装链接（点击进入）

四、IoTDB的Helm Chart 的配置

4.1 克隆 IoTDB Kubernetes 部署代码

需要联系工作人员获取IoTDB的Helm Chart

如果谁遇到代理问题，可以取消代理设置来解决：

git clone报错如下，说明是配置了代理，需要把代理关掉 fatal: unable to access ‘https://gitlab.timecho.com/r-d/db/iotdb-cluster-k8s.git/’: gnutls_handshake() failed: The TLS connection was non-properly terminated.

取消代理命令：

unset HTTPS_PROXY

4.2 修改 YAML 文件

跟随博主一步步操作，一文就可以完成配置，下面来看文件的配置

values.yaml 文件示例：

nameOverride: "iotdb"  
fullnameOverride: "iotdb"   #软件安装后的名称

image:
  repository: nexus.infra.timecho.com:8143/timecho/iotdb-enterprise
  pullPolicy: IfNotPresent
  tag: 1.3.3.2-standalone    #软件所用的仓库和版本

storage:
# 存储类名称，如果使用本地静态存储storageClassName 不用配置，如果使用动态存储必需设置此项
  className: local-storage

datanode:
  name: datanode
  nodeCount: 3        #datanode的节点数量
  enableRestService: true
  storageCapacity: 10Gi       #datanode的可用空间大小
  resources:
    requests:
      memory: 2Gi    #datanode的内存初始化大小
      cpu: 1000m     #datanode的CPU初始化大小
    limits:
      memory: 4Gi    #datanode的最大内存大小
      cpu: 1000m     #datanode的最大CPU大小

confignode:
  name: confignode
  nodeCount: 3      #confignode的节点数量
  storageCapacity: 10Gi      #confignode的可用空间大小
  resources:
    requests:
      memory: 512Mi    #confignode的内存初始化大小
      cpu: 1000m      #confignode的CPU初始化大小
    limits:
      memory: 1024Mi   #confignode的最大内存大小
      cpu: 2000m     #confignode的最大CPU大小
  configNodeConsensusProtocolClass: org.apache.iotdb.consensus.ratis.RatisConsensus
  schemaReplicationFactor: 3
  schemaRegionConsensusProtocolClass: org.apache.iotdb.consensus.ratis.RatisConsensus
  dataReplicationFactor: 2
  dataRegionConsensusProtocolClass: org.apache.iotdb.consensus.iot.IoTConsensus

4.3. 配置私库信息

1. 创建secret 使k8s可访问iotdb-helm的私有仓库

“xxxxxx”是IoTDB私有仓库的账号、密码、邮箱。

kubectl create secret docker-registry timecho-nexus \
  --docker-server='nexus.infra.timecho.com:8143' \
  --docker-username='xxxxxx' \
  --docker-password='xxxxxx' \
  --docker-email='xxxxxx' \
  -n iotdb-ns

查看secret

kubectl get secret timecho-nexus -n iotdb-ns

查看并输出为yaml

kubectl get secret timecho-nexus --output=yaml -n iotdb-ns

查看并解密

kubectl get secret timecho-nexus --output="jsonpath={.data.\.dockerconfigjson}" -n iotdb-ns | base64 --decode

2. 加载到命名空间iotdb-ns

添加一个patch，使该命名空间增加登陆nexus的登陆信息

kubectl patch serviceaccount default -n iotdb-ns -p '{"imagePullSecrets": [{"name": "timecho-nexus"}]}'

查看命名空间的该条信息

kubectl get serviceaccounts -n iotdb-ns -o yaml

五、安装 IoTDB

5.1 安装步骤

进入文件夹

cd iotdb-cluster-k8s/helm

安装iotdb

helm install iotdb ./ -n iotdb-ns

5.2 查看 Helm 安装列表

helm list -n iotdb-ns

5.3 查看 Pods

查看 iotdb的pods

kubectl get pods -n iotdb-ns -o wide

1. 执行命令后，输出了带有confignode和datanode标识的各3个Pods，，总共6个Pods，即表明安装成功；
2. 需要注意的是，并非所有Pods都处于Running状态，未激活的datanode可能会持续重启，但在激活后将恢复正常

5.4 排查问题方式

1. 查看k8s的创建log

kubectl get events -n iotdb-ns 
watch kubectl get events -n iotdb-ns

2. 获取详细信息

kubectl describe pod confignode-0 -n iotdb-ns
kubectl describe pod datanode-0 -n iotdb-ns

3. 查看confignode日志

kubectl logs -n iotdb-ns confignode-0 -f

5.5 三种方案激活 IoTDB

方案1：直接在 Pod 中激活（最简单）

拿到机器码后进行激活

kubectl exec -it -n iotdb-ns confignode-0 -- /iotdb/sbin/start-activate.sh
kubectl exec -it -n iotdb-ns confignode-1 -- /iotdb/sbin/start-activate.sh
kubectl exec -it -n iotdb-ns confignode-2 -- /iotdb/sbin/start-activate.sh

方案2：进入confignode的容器中激活

拿到机器码后进行激活

kubectl exec -it -n iotdb-ns confignode-0 -- /bin/bash
cd /iotdb/sbin
/bin/bash start-activate.sh

方案3：手动激活（博主采用的这个方案）

1. 查看 ConfigNode 详细信息，确定所在节点：

kubectl describe pod confignode-0 -n iotdb-ns | grep -e "Node:" -e "Path:"

结果示例：

Node:          a87/172.20.31.87
Path:          /data/k8s-data/env/confignode/.env

2. 查看 PVC 并找到 ConfigNode 对应的 Volume，确定所在路径：

kubectl get pvc -n iotdb-ns | grep "confignode-0"

也可以查看多个confignode

for i in {0..2}; do echo confignode-$i;kubectl describe pod confignode-${i} -n iotdb-ns | grep -e "Node:" -e "Path:"; echo "----"; done

3. 查看对应 Volume 的详细信息，确定物理目录的位置：

kubectl describe pv iotdb-pv-04 | grep "Path:"

结果示例：

Path:          /data/k8s-data/iotdb-pv-04

4. 从对应节点的对应目录下找到 system-info 文件，使用该 system-info 作为机器码生成激活码，并在同级目录新建文件 license，将激活码写入到文件里面

5.6 验证 IoTDB

1. 查看命名空间内的 Pods 状态

查看iotdb-ns命名空间内的IP、状态等信息，确定全部运行正常

kubectl get pods -n iotdb-ns -o wide

结果示例：

# NAME           READY   STATUS    RESTARTS         AGE   IP             NODE   NOMINATED NODE   READINESS GATES
# confignode-0   1/1     Running   0                75m   10.20.187.14   a87    <none>           <none>
# confignode-1   1/1     Running   0                75m   10.20.191.75   a88    <none>           <none>
# confignode-2   1/1     Running   0                75m   10.20.187.16   a87    <none>           <none>
# datanode-0     1/1     Running   10 (5m54s ago)   75m   10.20.191.74   a88    <none>           <none>
# datanode-1     1/1     Running   10 (5m42s ago)   75m   10.20.187.15   a87    <none>           <none>
# datanode-2     1/1     Running   10 (5m55s ago)   75m   10.20.191.76   a88    <none>           <none>

2. 查看命名空间内的端口映射情况

kubectl get svc -n iotdb-ns

3. 在任意服务器启动 CLI 脚本验证 IoTDB 集群状态
   端口就是jdbc-balancer的端口，服务器为k8s任意节点的IP都可以

start-cli.sh -h 172.20.31.86 -p 31895
start-cli.sh -h 172.20.31.87 -p 31895
start-cli.sh -h 172.20.31.88 -p 31895

结果示例：

通过以上任意一种验证，出现博主这种结果样例的就已经部署完成了~

六、结语

本文详细介绍了Kubernetes与IoTDB数据库的集成部署，跟着博主一步步做，有问题可以联系博主帮忙，可以远程帮小伙伴解决问题的！通过Kubernetes的容器编排能力，IoTDB可以快速部署，并实现高可用性

官方获取：👉Apache IoTDB 下载地址👈（点击下载）