ClickHouse Operator 简介 - ClickHouse Documentation

本文档概述了 ClickHouse Operator 的关键概念和使用方式。

什么是 ClickHouse Operator

ClickHouse Operator 是一个 Kubernetes Operator，用于在 Kubernetes 上自动部署和管理 ClickHouse 集群。它采用 operator 模式构建，通过自定义资源扩展 Kubernetes API，以表示 ClickHouse 集群及其依赖项。该 operator 负责：

集群生命周期管理 (创建、更新、扩缩容、删除)
ClickHouse Keeper 集群协调
自动生成配置
数据库 schema 同步
滚动更新和升级
存储预配

自定义资源

该 Operator 提供两个主要的自定义资源定义 (CRD) ：

ClickHouseCluster

表示一个副本数和分片方式均可配置的 ClickHouse 数据库集群。

apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
metadata:
  name: sample-cluster
spec:
  replicas: 3
  shards: 2
  keeperClusterRef:
    name: sample-keeper
  dataVolumeClaimSpec:
    resources:
      requests:
        storage: 100Gi

KeeperCluster

表示用于分布式协调的 ClickHouse Keeper 集群 (可替代 ZooKeeper) 。

apiVersion: clickhouse.com/v1alpha1
kind: KeeperCluster
metadata:
  name: sample-keeper
spec:
  replicas: 3
  dataVolumeClaimSpec:
    resources:
      requests:
        storage: 10Gi

协调

需要 ClickHouse Keeper

每个 ClickHouseCluster 都需要一个 ClickHouse Keeper 集群来提供分布式协调。在 ClickHouseCluster 规范中使用 keeperClusterRef 引用由 operator 管理的 KeeperCluster。默认情况下，operator 会在 ClickHouseCluster 所在的命名空间中查找，但你也可以设置 keeperClusterRef.namespace，使其指向另一个受监视命名空间中的 KeeperCluster。如需使用不由 operator 管理的 Keeper 集群，请改为在 externalKeeper 中列出其服务器。请参阅外部管理的 Keeper。

Keeper 的一对一关系

默认情况下，每个 ClickHouseCluster 都需要有自己专用的 KeeperCluster。 为什么？ operator 会自动为每个 ClickHouseCluster 生成一个唯一的身份验证密钥，用于访问其 Keeper。该密钥存储在 Secret 中。后果：

若未完成下述配置，多个 ClickHouseCluster 不能引用同一个 KeeperCluster
重新创建 ClickHouseCluster 时，必须同时重新创建其 KeeperCluster

如需共享同一个 Keeper 集群，请在每个 ClickHouseCluster 的 settings.extraConfig 中分别设置不同的 zookeeper.root，并在 ClickHouse 启动前创建对应的 znode。请参阅外部管理的 Keeper。

删除 ClickHouseCluster 或 KeeperCluster 资源时，Persistent Volumes 不会自动删除。

重新创建集群时：

删除 ClickHouseCluster 资源
删除 KeeperCluster 资源
等待所有 pod (容器组) 终止
如果希望重新开始，可选择删除 PersistentVolumeClaims
同时重新创建 KeeperCluster 和 ClickHouseCluster

为避免身份验证错误，请手动删除 Persistent Volumes，或者使用全新的存储同时重建这两个集群。

Schema 复制

ClickHouse Operator 会自动将数据库定义复制到集群中的所有副本。

会复制哪些内容

operator 会同步以下内容：

Replicated 数据库定义
集成型数据库引擎 (PostgreSQL、MySQL 等)

operator 不会同步以下内容：

非复制数据库 (Atomic、Ordinary 等)
非复制数据库中的本地表
表数据 (由 ClickHouse 复制机制处理)

推荐：使用 Replicated 数据库引擎

最佳实践在生产环境部署中，始终使用 Replicated 数据库引擎。

优点：

在所有节点之间自动复制 schema
简化表管理
Operator 可与新副本同步
在整个集群中保持 schema 一致

使用分布式 DDL 创建数据库：

CREATE DATABASE my_database ON CLUSTER 'default' ENGINE = Replicated;

避免使用非 Replicated 引擎

非复制数据库引擎 (Atomic、Lazy、SQLite、Ordinary) 需要手动管理 schema：

必须在每个副本上单独创建表
节点之间可能出现 schema 漂移
Operator 无法自动同步新增副本

禁用 schema 复制

如需禁用自动 schema 复制，请在 ClickHouseCluster 资源中将 spec.settings.enableDatabaseSync 设置为 false。

存储管理

ClickHouse Operator 通过 Kubernetes 的 PersistentVolumeClaim (PVC) 管理存储。

数据卷配置

在 dataVolumeClaimSpec 中指定存储要求：

spec:
  dataVolumeClaimSpec:
    storageClassName: fast-ssd
    resources:
      requests:
        storage: 500Gi

存储生命周期

创建：PVC 会随集群自动创建
扩容：如果 StorageClass 允许卷扩容，则支持扩容
保留：删除集群时，PVC 不会自动删除
复用：如果使用相同名称重新创建集群，则可复用现有 PVC

如需彻底删除存储：

# Delete cluster
kubectl delete clickhousecluster my-cluster

# Wait for pods to terminate
kubectl wait --for=delete pod -l app.kubernetes.io/instance=my-cluster-clickhouse

# Delete PVCs
kubectl delete pvc -l app.kubernetes.io/instance=my-cluster-clickhouse

默认配置亮点

预配置集群： 名为 default 的集群，包含所有 ClickHouse 节点。
默认宏： 预定义了一些实用的宏：
- {cluster}：集群名称 (default)
- {shard}：分片编号
- {replica}：副本编号
RBAC 实体采用复制存储
用户自定义函数 (UDF) 采用复制存储

后续步骤

配置指南 - 详细配置选项
API 参考文档 - 完整的 API 文档

​什么是 ClickHouse Operator

​自定义资源

​ClickHouseCluster

​KeeperCluster

​协调

​需要 ClickHouse Keeper

​Keeper 的一对一关系

​Schema 复制

​会复制哪些内容

​推荐：使用 Replicated 数据库引擎

​避免使用非 Replicated 引擎

​禁用 schema 复制

​存储管理

​数据卷配置

​存储生命周期

​默认配置亮点

​后续步骤

什么是 ClickHouse Operator

自定义资源

ClickHouseCluster

KeeperCluster

协调

需要 ClickHouse Keeper

Keeper 的一对一关系

Schema 复制

会复制哪些内容

推荐：使用 Replicated 数据库引擎

避免使用非 Replicated 引擎

禁用 schema 复制

存储管理

数据卷配置

存储生命周期

默认配置亮点

后续步骤