Apache IoTDB 在 Kubernetes 集群中的部署与实践指南

一、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 为例：

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

新建文件夹放 yaml 文件

创建 pv.yaml 文件命令：

touch pv.yaml

修改每个文件中的 name 和 path 以确保一致性。举例 pv.yaml:

apiVersion: v1
kind: PersistentVolume
metadata:
  name: iotdb-pv-01
spec:
  capacity:
    storage: 10Gi
  accessModes:
    - ReadWriteOnce
  persistentVolumeReclaimPolicy: Retain
  storageClassName: local-storage
  hostPath:
    path: /data/k8s-data/iotdb-pv-01
    type: DirectoryOrCreate

应用 PV 配置（pv-01.yaml 到 pv-06.yaml 都要应用）。配置命令：

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

配置完成后进行查看。查看命令：

kubectl get pv

手动创建文件夹。如果 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:
  className: local-storage
datanode:
  name: datanode
  nodeCount: 3
  enableRestService: true
  storageCapacity: 10Gi
  resources:
    requests:
      memory: 2Gi
      cpu: 1000m
    limits:
      memory: 4Gi
      cpu: 1000m
confignode:
  name: confignode
  nodeCount: 3
  storageCapacity: 10Gi
  resources:
    requests:
      memory: 512Mi
      cpu: 1000m
    limits:
      memory: 1024Mi
      cpu: 2000m
configNodeConsensusProtocolClass:

4.3 配置私库信息

创建 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

加载到命名空间 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

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

5.4 排查问题方式

查看 k8s 的创建 log：

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

获取详细信息：

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

查看 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：手动激活

查看 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

查看 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

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

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

结果示例：

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

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

5.6 验证 IoTDB

查看命名空间内的 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 (m55s ago) m  a88 <> <>

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

kubectl get svc -n iotdb-ns

在任意服务器启动 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 下载地址

Apache IoTDB 在 Kubernetes 集群中的部署与实践指南