ClickHouse Operator 配置指南

本指南介绍如何使用该 Operator 配置 ClickHouse 和 Keeper 集群。

ClickHouseCluster 配置

基本配置

apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
metadata:
  name: my-cluster
spec:
  replicas: 3           # 每个分片的副本数
  shards: 2             # 分片数量
  keeperClusterRef:
    name: my-keeper     # 引用 KeeperCluster
  dataVolumeClaimSpec:
    resources:
      requests:
        storage: 10Gi

副本和分片

副本：每个分片中的 ClickHouse 实例数 (用于高可用)
分片：水平分片的数量 (用于扩缩容)

spec:
  replicas: 3  # 默认值：3
  shards: 2    # 默认值：1

一个配置为 replicas: 3、shards: 2 的集群将总共创建 6 个 ClickHouse pod (容器组) 。

Keeper 集成

每个 ClickHouse 集群都必须引用一个 KeeperCluster，以进行协调：

spec:
  keeperClusterRef:
    name: my-keeper
    # namespace: keeper-system  # 可选，默认为 ClickHouseCluster 的命名空间

当设置了 keeperClusterRef.namespace 时，operator 必须同时监听这两个命名空间。如果配置了 WATCH_NAMESPACE，请将 ClickHouse 和 Keeper 所在的命名空间都包含在该列表中。

KeeperCluster 配置

apiVersion: clickhouse.com/v1alpha1
kind: KeeperCluster
metadata:
  name: my-keeper
spec:
  replicas: 3  # 必须为奇数：1、3、5、7、9、11、13 或 15
  dataVolumeClaimSpec:
    resources:
      requests:
        storage: 5Gi

存储配置

配置持久化存储：

spec:
  dataVolumeClaimSpec:
    storageClassName: fast-ssd  # 可选：根据已安装的 CSI 选择合适的存储类名称
    resources:
      requests:
        storage: 100Gi

仅当底层存储类支持卷扩容时，Operator 才能修改现有的 PVC。

pod (容器组) 配置

自动拓扑分散与亲和性

将 Pod (容器组) 分散到各可用区：

spec:
  podTemplate:
    topologyZoneKey: topology.kubernetes.io/zone
    nodeHostnameKey: kubernetes.io/hostname

确保您的 Kubernetes 集群在不同可用区中具备足够的节点，以满足分布约束要求。

手动配置

可以指定任意的 pod (容器组) 亲和性/反亲和性规则以及拓扑分布约束条件。

spec:
  podTemplate:
    affinity:
      <your-affinity-rules-here>
    topologySpreadConstraints:
      <your-topology-spread-constraints-here>

所有受支持的 pod (容器组) 模板选项，请参见 API 参考文档。

pod (容器组) 中断预算

Operator 会为每个集群创建一个 PodDisruptionBudget (PDB) ，以确保自愿中断 (如节点排空、滚动升级、自动扩缩容驱逐) 不会导致过多 pod (容器组) 下线，从而失去仲裁或影响可用性。对于拥有多个分片的 ClickHouse 集群，每个分片都会创建一个 PDB，这样一个分片中的中断就不会计入另一个分片。

默认值

operator 会根据集群规模选择安全的默认值，因此即使首次执行 apply，也能避免意外丢失仲裁。

资源	拓扑	默认 PDB
`ClickHouseCluster`	`replicas: 1` (单副本分片)	`maxUnavailable: 1` — 对于单节点集群，允许中断，这样不会阻塞节点排空
`ClickHouseCluster`	`replicas: 2+` (多副本分片)	`minAvailable: 1` — 每个分片至少必须保持 1 个副本在线
`KeeperCluster`	`replicas: 1`	`maxUnavailable: 1` — 对于单节点集群，允许中断，这样不会阻塞节点排空
`KeeperCluster`	`replicas: 3+`	`maxUnavailable: replicas/2` — 为 `2F+1` 集群保留 RAFT 仲裁 (3 个副本可容忍 1 个宕机，5 个副本可容忍 2 个宕机)

对于一个包含 3 个分片且 replicas: 3 的 ClickHouseCluster，operator 会创建 3 个 PDB，每个分片 1 个，且每个都设置为 minAvailable: 1。

覆盖默认设置

使用 spec.podDisruptionBudget 覆盖 minAvailable 或 maxUnavailable (两者只能指定一个) ：

spec:
  replicas: 3
  shards: 2
  podDisruptionBudget:
    minAvailable: 2   # 中断期间，每个分片中至少保持 3 个副本中的 2 个正常运行

或者使用按百分比设置的 maxUnavailable 形式：

spec:
  replicas: 5
  podDisruptionBudget:
    maxUnavailable: 40%

同时设置 minAvailable 和 maxUnavailable 会被验证 webhook 拒绝。请选择其一——Kubernetes 本身也不允许同时设置这两项。

你也可以将 unhealthyPodEvictionPolicy 字段传递到生成的 PDB 中——当你需要允许仍处于 NotReady 状态的 pod (容器组) 被驱逐时，这会很有用：

spec:
  podDisruptionBudget:
    minAvailable: 2
    unhealthyPodEvictionPolicy: AlwaysAllow

策略

spec.podDisruptionBudget.policy 允许你选择 operator 以多大力度管理 PDB：

Policy	Behavior
`Enabled` (default)	operator 会在每次 reconcile 时创建并更新 PDB。这是适用于生产环境的安全默认设置。
`Disabled`	operator 不会创建 PDB，并会删除所有带有匹配标签的现有 PDB。这适用于开发集群，因为这类集群通常应允许所有自愿中断。
`Ignored`	operator 既不创建也不删除 PDB。现有 PDB 会保持不变。当 PDB 管理由其他系统 (例如策略准入、GitOps 工具) 接管时，请使用此选项。

示例——在开发集群上完全禁用 PDB 管理：

spec:
  podDisruptionBudget:
    policy: Disabled

示例 — 将你手动编写的 PDB 与集群放在一起，并阻止 operator 触碰它：

spec:
  podDisruptionBudget:
    policy: Ignored

集群范围内停用

也可以通过 operator 的 ENABLE_PDB 环境变量，在整个集群范围内停用 PDB 管理。设置 ENABLE_PDB=false 后，无论 spec.podDisruptionBudget.policy 如何，operator 都会跳过所有 ClickHouseCluster 和 KeeperCluster 的 PDB reconcile 步骤，并且完全不监视 PodDisruptionBudget 资源。因此，operator 的 ServiceAccount 无需具备 poddisruptionbudgets.policy/v1 的 RBAC 权限；当 operator 以受限的 ServiceAccount 运行，且该账户刻意不包含这些权限时，这一点尤其有用。

# 在 operator 的 Deployment 规格中
env:
- name: ENABLE_PDB
  value: "false"

这适用于自行实施中断策略 (例如通过 Gatekeeper / Kyverno) 的环境，并希望将 operator 完全排除在外。

容器配置

自定义镜像

使用指定的 ClickHouse 镜像：

spec:
  containerTemplate:
    image:
      repository: clickhouse/clickhouse-server
      tag: "25.12"
    imagePullPolicy: IfNotPresent

容器资源

为 ClickHouse 容器配置 CPU 和内存：

# 默认值
spec:
  containerTemplate:
    resources:
      requests:
        cpu: "250m"
        memory: "256Mi"
      limits:
        cpu: "1"
        memory: "1Gi"

环境变量

添加自定义的环境变量：

spec:
  containerTemplate:
    env:
    - name: CUSTOM_ENV_VAR
      value: "1"

卷挂载

添加更多卷挂载：

spec:
  containerTemplate:
    volumeMounts:
    - name: custom-config
      mountPath: /etc/clickhouse-server/config.d/custom.xml
      subPath: custom.xml

可以为同一个 mountPath 指定多个卷挂载。 Operator 会将所有已指定的挂载创建为一个投影卷。

有关所有受支持的容器模板选项，请参见 API 参考文档。

TLS/SSL 配置

配置安全端点

引用包含 TLS 证书的 Kubernetes Secret，以启用安全端点

spec:
  settings:
    tls:
      enabled: true
      required: true # 设置此项后，非安全端口将被禁用
      serverCertSecret:
        name: <certificate-secret-name>

SSL 证书 Secret 格式

该 Secret 应包含以下键：

tls.crt - PEM 编码的服务器证书
tls.key - PEM 编码的私钥
ca.crt - PEM 编码的 CA 证书链

此格式兼容由 cert-manager 生成的证书。

通过 TLS 进行 ClickHouse-Keeper 通信

如果 KeeperCluster 启用了 TLS，ClickHouseCluster 会自动使用与 Keeper 节点的安全连接。 ClickHouseCluster 应能够验证 Keeper 节点的证书。如果 ClickHouseCluster 启用了 TLS，则会使用 ca.crt 证书包进行验证；否则，将使用默认的 CA 证书包。用户可以提供自定义 CA 证书包引用：

spec:
    settings:
        tls:
          caBundle:
            name: <ca-certificate-secret-name>
            key: <ca-certificate-key>

ClickHouse 设置

默认用户密码

设置默认用户的密码：

spec:
  settings:
    defaultUserPassword:
      passwordType: <password-type> # 默认值：password
      <secret|configMap>:
        name: <resource name>
        key: <password>

不建议使用 ConfigMap 存储明文密码。

创建 secret：

kubectl create secret generic clickhouse-password --from-literal=password='your-secure-password'

使用 ConfigMap 配置用户密码

您也可以使用 ConfigMap 来设置非敏感的默认密码：

spec:
  settings:
    defaultUserPassword:
      passwordType: password_sha256_hex
      configMap:
        name: clickhouse-config
        key: default_password

配置中的自定义用户

在配置文件中添加其他用户。为该用户创建 ConfigMap 和 Secret：

apiVersion: v1
kind: ConfigMap
metadata:
  name: user-config
data:
  reader.yaml: |
    users:
      reader:
        password:
          - '@from_env': READER_PASSWORD
        profile: default
        grants:
          - query: "GRANT SELECT ON *.*"
---
apiVersion: v1
kind: Secret
metadata:
  name: reader-password
data:
  password: "c2VjcmV0LXBhc3N3b3Jk"  # base64("secret-password")

向 ClickHouseCluster 添加自定义配置：

spec:
  podTemplate:
    volumes:
      - name: reader-user
        configMap:
          name: user-config
  containerTemplate:
    env:
      - name: READER_PASSWORD
        valueFrom:
          secretKeyRef:
            name: reader-password
            key: password
    volumeMounts:
      - mountPath: /etc/clickhouse-server/users.d/
        name: reader-user
        readOnly: true

数据库同步

为新副本启用数据库自动同步：

spec:
  settings:
    enableDatabaseSync: true  # 默认值：true

启用后，该 Operator 会将 Replicated 表和集成表同步到新副本。

自定义配置

内嵌额外配置

无需挂载自定义配置文件，也可以直接指定额外的 ClickHouse 配置选项。使用 extraConfig 添加自定义的 ClickHouse 配置：

spec:
  settings:
    extraConfig:
      background_pool_size: 20

有用链接：

嵌入式附加用户配置

你也可以使用 extraUsersConfig 指定额外的 ClickHouse 用户配置。这对于直接在集群规范中定义用户、profile、配额和授权非常有用。

spec:
  settings:
    extraUsersConfig:
      users:
        analyst:
          password:
            - '@from_env': ANALYST_PASSWORD
          profile: "readonly"
          quota: "default"
      profiles:
        readonly:
          readonly: 1
          max_memory_usage: 10000000000
      quotas:
        default:
          interval:
            duration: 3600
            queries: 1000
            errors: 100

extraUsersConfig 存储在 k8s 的 ConfigMap 对象中。请避免在其中以明文形式存放 secret。

有关所有受支持的 ClickHouse 用户配置选项，请参阅文档。

配置示例

完整配置示例：

apiVersion: clickhouse.com/v1alpha1
kind: KeeperCluster
metadata:
  name: sample
spec:
  replicas: 3
  dataVolumeClaimSpec:
    storageClassName: <storage-class-name>
    resources:
      requests:
        storage: 10Gi
  podTemplate:
    topologyZoneKey: topology.kubernetes.io/zone
    nodeHostnameKey: kubernetes.io/hostname
  containerTemplate:
    resources:
      requests:
        cpu: "2"
        memory: "4Gi"
      limits:
        cpu: "4"
        memory: "8Gi"
  settings:
    tls:
      enabled: true
      required: true
      serverCertSecret:
        name: <keeper-certificate-secret>
---
apiVersion: v1
kind: ConfigMap
metadata:
  name: default-user-password
data:
  # 密钥密码
  password: "..." # 密码的 sha256 十六进制值
---
apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
metadata:
  name: sample
spec:
  replicas: 2
  dataVolumeClaimSpec:
    storageClassName: <storage-class-name>
    resources:
      requests:
        storage: 200Gi
  keeperClusterRef:
    name: sample
  podTemplate:
    topologyZoneKey: topology.kubernetes.io/zone
    nodeHostnameKey: kubernetes.io/hostname
  settings:
    tls:
      enabled: true
      required: true
      serverCertSecret:
        name: clickhouse-cert
    defaultUserPassword:
      passwordType: password_sha256_hex
      configMap:
        key: password
        name: default-password

Install

Guides

Reference

ClickHouseCluster 配置

基本配置

副本和分片

Keeper 集成

KeeperCluster 配置

存储配置

pod (容器组) 配置

自动拓扑分散与亲和性

手动配置

所有受支持的 pod (容器组) 模板选项，请参见 API 参考文档。

pod (容器组) 中断预算

默认值

覆盖默认设置

策略

集群范围内停用

容器配置

自定义镜像

容器资源

环境变量

卷挂载

有关所有受支持的容器模板选项，请参见 API 参考文档。

TLS/SSL 配置

配置安全端点

SSL 证书 Secret 格式

通过 TLS 进行 ClickHouse-Keeper 通信

ClickHouse 设置

默认用户密码

使用 ConfigMap 配置用户密码

配置中的自定义用户

数据库同步

自定义配置

内嵌额外配置

有用链接：

嵌入式附加用户配置

有关所有受支持的 ClickHouse 用户配置选项，请参阅文档。

配置示例

​ClickHouseCluster 配置

​基本配置

​副本和分片

​Keeper 集成

​KeeperCluster 配置

​存储配置

​pod (容器组) 配置

​自动拓扑分散与亲和性

​手动配置

​所有受支持的 pod (容器组) 模板选项，请参见 API 参考文档。

​pod (容器组) 中断预算

​默认值

​覆盖默认设置

​策略

​集群范围内停用

​容器配置

​自定义镜像

​容器资源

​环境变量

​卷挂载

​有关所有受支持的容器模板选项，请参见 API 参考文档。

​TLS/SSL 配置

​配置安全端点

​SSL 证书 Secret 格式

​通过 TLS 进行 ClickHouse-Keeper 通信

​ClickHouse 设置

​默认用户密码

​使用 ConfigMap 配置用户密码

​配置中的自定义用户

​数据库同步

​自定义配置

​内嵌额外配置

​有用链接：

​嵌入式附加用户配置

​有关所有受支持的 ClickHouse 用户配置选项，请参阅文档。

​配置示例

ClickHouseCluster 配置

基本配置

副本和分片

Keeper 集成

KeeperCluster 配置

存储配置

pod (容器组) 配置

自动拓扑分散与亲和性

手动配置

所有受支持的 pod (容器组) 模板选项，请参见 API 参考文档。

pod (容器组) 中断预算

默认值

覆盖默认设置

策略

集群范围内停用

容器配置

自定义镜像

容器资源

环境变量

卷挂载

有关所有受支持的容器模板选项，请参见 API 参考文档。

TLS/SSL 配置

配置安全端点

SSL 证书 Secret 格式

通过 TLS 进行 ClickHouse-Keeper 通信

ClickHouse 设置

默认用户密码

使用 ConfigMap 配置用户密码

配置中的自定义用户

数据库同步

自定义配置

内嵌额外配置

有用链接：

嵌入式附加用户配置

有关所有受支持的 ClickHouse 用户配置选项，请参阅文档。

配置示例