ClickHouse Operator 配置指南 - ClickHouse Documentation

本指南介绍如何使用该 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 集群都需要一个 Keeper ensemble 来进行协调。keeperClusterRef 与 externalKeeper 必须且只能设置其中之一；同时设置两者或均未设置的集群都会被拒绝。将 keeperClusterRef 指向由该 operator 管理的 KeeperCluster：

spec:
  keeperClusterRef:
    name: my-keeper
    # namespace: keeper-system  # Optional, defaults to the ClickHouseCluster namespace

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

外部管理的 Keeper

使用 externalKeeper 可让 ClickHouse 连接到不受该 operator 管理的 Keeper ensemble—— 例如由其他 operator 管理、运行在另一个 Kubernetes 集群中、部署在虚拟机或裸金属服务器上，或由多个系统共享的 Keeper ensemble：

spec:
  externalKeeper:
    nodes:
      - host: keeper-1.example.internal
        port: 9181
      - host: keeper-2.example.internal
        port: 9181
      - host: keeper-3.example.internal
        port: 9181

port 默认为 9181。host 可以是 DNS 名称或 IP 地址；IPv6 地址需用方括号括起来。如需通过 TLS 连接，请设置 tls: Enabled，并将 port 设为 Keeper ensemble 用于安全连接的监听端口：

spec:
  externalKeeper:
    tls: Enabled
    nodes:
      - host: keeper-1.example.internal
        port: 9281

ClickHouse 会使用系统信任库以及您配置的 caBundle (如有) 来验证 Keeper 证书。请参阅 ClickHouse 与 Keeper 之间的 TLS 通信。当多个 ClickHouse 集群共用同一个 Keeper ensemble 时，应通过 settings.extraConfig 为每个集群指定独立的根 znode，以免各集群的复制元数据、通过 SQL 定义的用户以及命名集合相互冲突。请在 ClickHouse 启动之前创建该 znode，且创建后不要再更改：

spec:
  settings:
    extraConfig:
      zookeeper:
        root: /clickhouse/production

不要将 zookeeper.root 放在 settings.extraReloadableConfig 中：重新加载会切换正在运行的集群的根路径，导致其复制表变为只读。如果根 znode 配置了 ACL，则必须允许集群的 keeper-identity 创建子 znode。 operator 不会修改这些服务器，在 reconcile ClickHouse 之前也不会等待它们就绪。 Keeper ensemble 的可用性需由用户自行保障。身份验证方式与 operator 管理的 Keeper 相同：operator 从集群 Secret 中读取 keeper-identity 键，并将其传递给 ClickHouse。有关 Secret 的结构，请参阅外部 Secret。

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

终止时的 leader 身份移交

Keeper 容器带有一个默认的 preStop hook，它会在副本停止前要求其移交 Raft leader 身份，并等待移交完成后才允许容器终止。容器每次正常停止时都会执行该 hook，而不仅限于 operator 发起的滚动发布：descheduler 驱逐、节点排空或自动扩缩器操作都会触发同一个 hook，因为它是 kubelet 节点代理级别的 preStop handler，而不是调和循环中的逻辑。如果没有该 hook，重启当前 leader 会导致 ensemble 在新一轮选举完成之前处于无 leader 状态；在高负载下，选举可能需要数秒，在 ClickHouse 侧则表现为 Keeper 连接丢失以及查询延迟升高。该 hook 会要求副本让出 leader 身份 (通过 http_control 端口发送 Keeper 的 ydld 四字命令) ，然后轮询副本的状态，直到其不再是 leader 为止，而不是发出请求后立即让容器停止。在写入负载下，发出即忘式的请求仍可能在与 SIGTERM 的竞争中落败，因此正是这一等待过程确保了无 leader 窗口的时长可控。该 hook 无需任何配置，并且能够平稳降级：早于 26.3 的 Keeper 版本尚不支持此处使用的 leader 身份相关命令，此时该请求为空操作，容器会像没有该 hook 时一样停止。该 hook 运行的是 shell 脚本，因此要求镜像中包含 bash；如果您使用的是 distroless 或 scratch 类型的 Keeper 镜像，请通过 containerTemplate.lifecycle 覆盖或移除该 hook，详见 API 参考文档。

存储配置

使用 dataVolumeClaimSpec (标准 Kubernetes PersistentVolumeClaimSpec) 配置持久化存储。Operator 会将其转换为每个副本对应的 PersistentVolumeClaim，并将其挂载到数据路径 /var/lib/clickhouse：

spec:
  dataVolumeClaimSpec:
    storageClassName: fast-ssd  # Optional: consider your storage class based on the installed CSI
    resources:
      requests:
        storage: 100Gi

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

关于在多磁盘 (JBOD) 布局中挂载额外磁盘、在没有持久卷的情况下运行、扩展容量、自定义存储策略、静态数据加密，以及创建后哪些内容不能更改的规则，请参阅专门的存储和卷指南。

集群域

spec.clusterDomain 用于设置 operator 在构建并写入 ClickHouse server 配置的 pod (容器组) 完全限定主机名时所使用的 Kubernetes DNS 后缀。默认值为 cluster.local，并且在 ClickHouseCluster 和 KeeperCluster 中都可用。

spec:
  clusterDomain: cluster.local   # default; override only for a custom domain

对于 ClickHouse 副本，operator 会创建一个负责处理客户端流量的主无头 Service <cluster-name>-clickhouse-headless。并为每个副本创建 Service <cluster-name>-clickhouse-internal-<shard>-<index>，用于暴露尚未就绪的 Pod (容器组) ，以处理内部流量以及来自 operator 的管理请求。如果副本自身无法就绪，这可用于副本恢复。 Keeper 节点会通过其无头 Service 使用 pod 名称：<pod>.<headless-service>.<namespace>.svc.<clusterDomain>。

仅当你的集群中 kubelet 节点代理使用的 --cluster-domain 不是 cluster.local 时，才应覆盖此值。如果该值与实际的集群域不一致， ClickHouse 将无法解析 Keeper 和副本主机名——协调以及 Distributed 查询都会因 DNS 解析错误而失败。请在 ClickHouseCluster 及其引用的 KeeperCluster 中设置相同的值。

pod (容器组) 配置

自动拓扑分散与亲和性

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

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

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

在使用节点自动扩缩器 (Karpenter、Cluster Autoscaler) 时，仅靠拓扑分布约束条件无法为尚无节点的可用区置备节点——调度器只会在它能看到的可用区之间进行分配。将 topologyMinDomains 设置为可用区的数量，以强制分散：

spec:
  podTemplate:
    topologyZoneKey: topology.kubernetes.io/zone
    topologyMinDomains: 3   # number of availability zones

topologyMinDomains 需要配合 topologyZoneKey 使用。当可用的可用区数量少于所请求的数量时，Pod (容器组) 会持续处于 Pending 状态，因此请将其控制在集群实际能提供的可用区数量范围内。

手动配置

可以指定任意的 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 和内存：

# default values
spec:
  containerTemplate:
    resources:
      requests:
        cpu: "250m"
        memory: "512Mi"
      limits:
        cpu: "1"
        memory: "512Mi"

环境变量

添加自定义的环境变量：

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 会将所有已指定的挂载创建为一个投影卷。

健康探针

Operator 会为每个 ClickHouse 和 Keeper 容器配置存活探针 (存活) 和就绪探针 (就绪) 。默认不配置启动探针 (startup) 。

资源	探针	默认检查
`ClickHouseCluster`	存活	对服务器间端口 `9009` 执行 HTTP `GET /ping`
`ClickHouseCluster`	就绪	对管理 HTTP 端口 `9002` 执行 HTTP `GET /ping`
`KeeperCluster`	存活	通过 TCP 连接客户端端口 `2181` (当 `settings.tls.enabled` 和 `settings.tls.required` 均为 `true` 时为 `2281`)
`KeeperCluster`	就绪	对 `http_control` 端口 `9123` 执行 HTTP `GET /ready`

ClickHouse 和 Keeper 使用相同的默认时间设置：

探针	`initialDelaySeconds`	`periodSeconds`	`timeoutSeconds`	`successThreshold`	`failureThreshold`
存活	60	5	10	1	10
就绪	5	1	10	5	10

ClickHouse 会在加载表之前启动服务器间监听器，在加载完成后再启动客户端监听器。因此，即使表加载较慢，存活探针也不会失败；而就绪探针一旦通过，即表示该副本已能够处理查询。可在任一资源上通过 spec.containerTemplate 覆盖任意探针。例如，自定义 ClickHouse 的存活探针：

spec:
  containerTemplate:
    livenessProbe:
      httpGet:
        path: /ping
        port: 9009
      initialDelaySeconds: 120
      periodSeconds: 10
      timeoutSeconds: 10
      failureThreshold: 10

您设置的探针会完全取代 operator 的默认配置，而不会逐字段合并。请指定处理程序 (httpGet、tcpSocket 或 exec) 以及所有需要的计时字段；未指定的字段将回退到 Kubernetes 默认值 (例如 timeoutSeconds: 1、failureThreshold: 3) ，而不是上文所述的 operator 配置值。

启动探针

如果容器启动所需的时间超过存活探针所允许的时长，请使用 startupProbe。按默认配置，存活探针允许的时长约为 60 秒初始延迟，外加 10 次间隔 5 秒的失败检查。在启动探针成功之前，Kubernetes 会暂缓执行存活探针和就绪探针，因此启动缓慢不会导致重启循环。例如，某个 Keeper 副本需要重放大型快照，可为其预留最多 10 分钟来开始接受连接：

apiVersion: clickhouse.com/v1alpha1
kind: KeeperCluster
metadata:
  name: sample
spec:
  replicas: 3
  containerTemplate:
    startupProbe:
      tcpSocket:
        port: 2181
      periodSeconds: 10
      failureThreshold: 60

启动探针成功后，将由常规的存活和就绪探针接管。

有关所有受支持的容器模板选项，请参见 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 编码的私钥

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

通过 TLS 进行 ClickHouse-Keeper 通信

如果 keeperClusterRef 引用的 KeeperCluster 启用了 TLS，ClickHouseCluster 会自动使用与 Keeper 节点的安全连接。如果使用 externalKeeper，则应改为设置 tls: Enabled，并将每个节点的 port 设置为该 Keeper ensemble 的安全客户端端口 (例如 9281) 。 ClickHouseCluster 会根据系统信任库以及你配置的任何 caBundle 来验证 Keeper 节点证书。要信任私有 CA (例如自签名 CA 或内部 CA) ，请提供自定义 CA 证书包引用：

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

外部 Secret

默认情况下，operator 会创建并管理一个 Secret，其中包含集群的内部凭据 (interserver 密码、管理密码、Keeper 身份、集群 secret、named-collections 密钥) 。该 Secret 以集群名称命名，并位于集群所在的命名空间中。如果你想自行管理这些凭据——例如从 HashiCorp Vault、AWS Secrets Manager 或 External Secrets Operator 获取——可以使用 spec.externalSecret 将 operator 指向一个预先创建的 Secret：

apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
metadata:
  name: sample
spec:
  replicas: 2
  keeperClusterRef:
    name: sample
  dataVolumeClaimSpec:
    resources:
      requests:
        storage: 10Gi
  externalSecret:
    name: my-clickhouse-credentials
    policy: Observe

这里引用的 Secret 必须与 ClickHouseCluster 位于同一命名空间。该 operator 绝不会删除并非由其创建的 Secret。

必需的键

Secret 必须包含以下键：

Key	Format	When required
`interserver-password`	明文密码	始终需要
`management-password`	明文密码	始终需要
`keeper-identity`	`clickhouse:<password>`	始终需要
`cluster-secret`	明文密码	始终需要
`named-collections-key`	以十六进制编码的 16 字节 AES 密钥 (32 个十六进制字符)	仅适用于 ClickHouse `>= 25.12`
`disk-encryption-key`	以十六进制编码的 16 字节 AES 密钥 (32 个十六进制字符)	仅当设置了 `settings.encryption` 时

一个完整的 Secret 如下所示：

apiVersion: v1
kind: Secret
metadata:
  name: my-clickhouse-credentials
  namespace: sample
type: Opaque
stringData:
  interserver-password: "a-strong-random-password"
  management-password: "another-strong-password"
  keeper-identity: "clickhouse:keeper-auth-password"
  cluster-secret: "cluster-internal-secret"
  named-collections-key: "0123456789abcdef0123456789abcdef"   # 32 hex chars = 16 bytes
  disk-encryption-key: "00112233445566778899aabbccddeeff"     # only when settings.encryption is set

策略：Observe 与 Manage

spec.externalSecret.policy 用于控制 Operator 如何处理缺失的必需键：

Policy	键缺失时的行为
`Observe` (默认)	在所有必需键都存在之前，协调会被阻塞。Operator 会通过 `ExternalSecretValid` 条件 (reason 为 `ExternalSecretInvalid`) 和一个 `Warning` 事件，报告每个缺失的键及其对应的格式提示。
`Manage`	Operator 会生成所有缺失的必需键，并将它们写回同一个 Secret。适用于引导场景：先创建一个空 Secret，让 Operator 将其补齐，然后再按需收紧访问权限。Operator 仍然绝不会删除该 Secret。

即使设置了 policy: Manage，该 Secret 也必须已存在于命名空间中——Operator 绝不会自行创建 Secret，它只会将生成的键写入现有的 Secret。如果引用的 Secret 不存在，则无论采用哪种 policy，协调都会因 ExternalSecretNotFound 而被阻塞。

当外部系统 (Vault、ESO、sealed-secrets、GitOps) 是事实来源，且你希望 Operator 在配置错误时明确报错时，请选择 Observe。当你希望实现自给自足的引导，同时仍保留对 Secret 对象本身的所有权 (例如为了备份) 时，请选择 Manage。

状态条件和故障排查

Operator 会在 ClickHouseCluster.status.conditions 中暴露 ExternalSecretValid 条件。协调过程看起来卡住时，请检查它：

# Plain kubectl — works out of the box
kubectl describe clickhousecluster sample | sed -n '/Conditions:/,$p'

# Same data as YAML
kubectl get clickhousecluster sample -o yaml | sed -n '/conditions:/,/^[^ ]/p'

# Pretty-printed JSON (requires jq)
kubectl get clickhousecluster sample -o jsonpath='{.status.conditions}' | jq

可能的原因：

`reason`	含义	处理方式
`ExternalSecretNotFound`	被引用的 Secret 在该命名空间中不存在。	创建该 Secret，或修正 `spec.externalSecret.name`。
`ExternalSecretInvalid`	Secret 存在，但缺少必需的键 (仅在使用 `Observe` 时) 。消息会列出每个缺失的键及其预期格式。	添加缺失的键，或切换为 `policy: Manage`。
`ExternalSecretValid`	所有必需的键都已存在，并且 operator 正在使用该 Secret。	—

当 Secret 无效时，operator 会将协调重新入队，因此一旦补齐缺失的键，下一次协调就会自动生效——无需重启 Pod (容器组) 。

所需键的集合取决于当前运行的 ClickHouse 版本。只有在 operator 的版本探测检测到 ClickHouse 25.12 或更高版本后，才会校验 named-collections-key。在较旧版本中，Secret 可以不包含该键。仅当设置了 spec.settings.encryption 时，才需要 disk-encryption-key。

附加端口

该 Operator 会在每个 ClickHouse pod (容器组) 及其公网无头 Service 上暴露一组固定端口：8123 HTTP、9000 native、9009 interserver、9001/9002 management、9363 Prometheus 指标，以及启用 TLS 时对应的 8443/9440 TLS 端口变体。interserver 和 management 端口还会通过每个副本的内部 Service 暴露，以便副本和 operator 能够在副本就绪前进行通信。若要让 ClickHouse 监听更多协议 (如 MySQL、PostgreSQL、gRPC 或其他自定义端口) ，请在 spec.additionalPorts 中声明：

spec:
  additionalPorts:
    - name: mysql
      port: 9004
    - name: postgres
      port: 9005
    - name: grpc
      port: 9100

operator 会将这些端口添加到 Pod 的 containerPorts 和公网无头 Service 中。完整示例见 examples/custom_protocols.yaml。

additionalPorts 只会在 Kubernetes 这一侧开放端口。它不会配置 ClickHouse 服务器在这些端口上监听。你还需要在 spec.settings.extraConfig.protocols 中启用对应的协议。否则，虽然 Service 上的端口已开放，但 pod (容器组) 内部不会有任何程序响应。

端到端示例：MySQL wire 协议

要通过 MySQL wire 协议在端口 9004 上对外暴露 ClickHouse：

apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
metadata:
  name: sample
spec:
  replicas: 1
  keeperClusterRef:
    name: sample
  dataVolumeClaimSpec:
    resources:
      requests:
        storage: 2Gi

  # 1) Open the port on the Pod and the public headless Service.
  additionalPorts:
    - name: mysql
      port: 9004

  # 2) Tell ClickHouse server to actually listen on it.
  settings:
    extraConfig:
      protocols:
        mysql:
          type: mysql
          port: 9004
          description: "MySQL wire protocol"

应用完成后，在集群内部验证：

kubectl exec sample-clickhouse-0-0-0 -- \
  clickhouse-client --port 9004 --query "SELECT 1"

字段约束

字段	规则
`name`	必须匹配 DNS_LABEL 模式 `^[a-z]([-a-z0-9]*[a-z0-9])?$`，最长 63 个字符。CRD 会将其作为 list-map 键来强制保证唯一性。
`port`	`[1, 65535]` 范围内的整数。webhook 会拒绝列表中重复的端口号。

保留端口和名称

validating webhook 会拒绝与 operator 自身绑定端口发生冲突的 additionalPorts 条目。所有与 TLS 相关的端口都会被无条件保留，以确保后续切换 spec.settings.tls.enabled 时，不会破坏原本有效的集群。

Port	保留用途
`8123`	HTTP
`8443`	HTTPS
`9000`	native TCP
`9440`	native TLS
`9009`	interserver
`9001`	management
`9363`	Prometheus 指标

以下名称也会被拒绝——它们是 operator 的内部协议类型标识符 (而非便于人工阅读的别名) ：

Name
`http`
`http-secure`
`tcp`
`tcp-secure`
`interserver`
`management`
`prometheus`

被拒绝的请求会产生如下错误：

spec.additionalPorts[0].port: 8123 is reserved for the operator-managed HTTP port
spec.additionalPorts[0].name: "http" is reserved by the operator

版本探测与升级通道

operator 会针对 cluster 版本执行两项彼此独立的操作：

版本报告 — 对于 ClickHouseCluster，一个 Kubernetes Job 会将容器镜像运行一次，以检测当前运行的 ClickHouse 版本；对于 KeeperCluster，operator 会从正在运行的副本中读取由 server 上报的版本。检测到的版本会记录到 .status.version 中，并用于其他协调步骤 (例如，名为 外部 Secret 的 named-collections key 仅在 ClickHouse 25.12 及以上版本中才需要) 。
升级通道 — 定期检查公开的 ClickHouse 发布源 (https://clickhouse.com/data/version_date.tsv) 。operator 会通过 VersionUpgraded status condition 报告是否有新版本可用。它绝不会自行升级 cluster——镜像标签始终由用户控制。

选择发布渠道

spec.upgradeChannel 用于指定 operator 要对照比较的上游发行版集合。ClickHouseCluster 和 KeeperCluster 都有这个相同的字段。

spec:
  upgradeChannel: lts   # or "stable", or "25.8", or omitted

允许的值 (由 CRD 按模式 ^(lts|stable|\d+\.\d+)?$ 验证) ：

Value	Behavior
empty (default)	Operator 只会在当前运行的 major.minor 版本线上提示次版本更新。运行 `25.8.3.1` 的集群会收到 `25.8.4.x` 的更新提示，但不会收到 `25.9.x`。
`stable`	跟踪上游 `stable` 通道——即 ClickHouse Inc. 在主发行线上标记为稳定版本的最新 release。与 `lts` 通道相比，它会更早接收 major 升级。
`lts`	跟踪上游 `lts` 通道——即长期支持发行版。接收 major 升级的频率较低，但支持周期更长。
`25.8` (or any `<major>.<minor>`)	将通道固定在特定的 major.minor 版本线上。即使上游已有更新版本，也不会提示超出该版本线的 major 升级。

对于生产环境，通常更建议将通道固定为明确的 <major>.<minor> (例如 25.8) 。这样可以把集群锁定在预期的 major 发行线上，并且当某个副本因某种原因漂移到其他 major 版本时，Operator 会显示 WrongReleaseChannel 警告——这一点在镜像通过摘要 (@sha256:...) 而不是便于人类阅读的标签引用时尤其重要。对于不担心 major 版本跳变的开发集群，默认的空值也完全适用。

状态条件

两个 conditions 会体现探测和升级检查的结果：

Condition	Reason	Meaning
`VersionInSync`	`VersionMatch`	所有副本报告的版本都相同
`VersionInSync`	`VersionMismatch`	各副本运行的版本不同。在计划内的滚动升级期间，此原因会被抑制。通常这会在可变镜像标签被固定时出现 (例如 `latest` 或仅指定主次版本的 `26.3`) ，且底层 registry 在多次拉取之间发生了变化，导致不同副本最终落在同一标签对应的不同补丁版本上。
`VersionInSync`	`VersionPending`	版本探测 Job 尚未完成，或者尚未观察到 Keeper 副本版本
`VersionInSync`	`VersionProbeFailed`	ClickHouse 探测 Job 失败；operator 无法确定当前运行的版本
`VersionUpgraded`	`UpToDate`	该集群使用的是所选通道中当前可用的最新版本
`VersionUpgraded`	`MinorUpdateAvailable`	同一 `major.minor` 系列中有更新的补丁版本可用
`VersionUpgraded`	`MajorUpdateAvailable`	所选通道中有更新的 `major.minor` 版本可用
`VersionUpgraded`	`VersionOutdated`	当前运行的版本已过时，不会再从所选通道接收修复——通常是因为该主版本系列已被上游从 `lts` 或 `stable` 中移除
`VersionUpgraded`	`WrongReleaseChannel`	当前运行的镜像不属于所选的 `upgradeChannel`。例如：某个运行 `26.5` 且设置了 `upgradeChannel: lts` 的集群，因为 `26.5` 不属于上游 `lts` 系列。
`VersionUpgraded`	`UpgradeCheckFailed`	operator 无法访问上游发布源

可使用以下方式检查它们：

kubectl get clickhousecluster sample -o yaml | sed -n '/conditions:/,/^[^ ]/p'

覆盖版本探测 Job

这仅适用于 ClickHouseCluster。KeeperCluster 不再运行版本探测 Job——它的版本会直接从正在运行的 Keeper 副本中读取——因此 spec.versionProbeTemplate 已弃用，在那里不会产生任何效果。该探测是通过一个常规的 Kubernetes Job 实现的。如果你的集群设置了准入策略，要求指定的 Tolerations、节点选择器或安全上下文，或者你想限制已完成的探测 Job 保留的时间，可以通过 spec.versionProbeTemplate 覆盖该模板：

spec:
  versionProbeTemplate:
    spec:
      ttlSecondsAfterFinished: 600   # delete completed probe Jobs 10 minutes after completion
      template:
        spec:
          nodeSelector:
            kubernetes.io/arch: amd64
          tolerations:
            - key: dedicated
              operator: Equal
              value: clickhouse
              effect: NoSchedule
          containers:
            - name: version-probe
              resources:
                requests:
                  cpu: 50m
                  memory: 64Mi

容器名称 version-probe 是 operator 的默认名称——containers: 下对应的条目会按名称与其匹配，因此 operator 会在默认配置的基础上，将用户提供的字段深度合并进去。

Operator 级别的控制

Operator 管理器上的两个标志可在全局范围内控制升级检查循环：

Flag	Default	Effect
`--version-update-interval`	`24h`	Operator 重新拉取上游版本列表的频率。启用版本更新检查时，该值必须大于零
`--disable-version-update-checks`	`false`	完全禁用升级检查器。不会设置 `VersionUpgraded` 条件，也不会产生任何发往 `clickhouse.com` 的出站 HTTP 流量

在隔离网络环境中，或者不允许访问 clickhouse.com 出站流量时，请设置 --disable-version-update-checks=true。

ClickHouse 设置

默认用户密码

spec.settings.defaultUserPassword 用于为内置 default 用户设置密码。请提供你创建的 Secret (推荐) 或 ConfigMap 中某个键的值，而不要直接将密码内联写在 CR 中：

spec:
  settings:
    defaultUserPassword:
      passwordType: password   # default; see "Password types" below
      secret:                  # exactly one of secret or configMap
        name: clickhouse-password   # name of the Secret/ConfigMap
        key: password               # the key inside it, not the password value

只能提供 secret 或 configMap 其中之一，并且两者都必须同时包含 name (对象) 和 key (保存密码的条目) 。

密码类型

passwordType 用于告知 ClickHouse 如何解析该值。其默认值为 password (明文) ；其他可选项为哈希形式，例如 password_sha256_hex 和 password_double_sha1_hex。建议优先使用哈希类型，以避免存储明文。完整列表请参见 ClickHouse user settings。

使用 Secret 的完整示例

先创建 Secret，再引用其中的键：

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

apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
metadata:
  name: my-cluster
spec:
  settings:
    defaultUserPassword:
      passwordType: password
      secret:
        name: clickhouse-password
        key: password

使用 passwordType: password 时，pod (容器组) 内的 clickhouse-client 会配置为使用该密码，这样在调试时会更方便。

对于哈希密码，请存储哈希值而非明文：

echo -n 'your-secure-password' | sha256sum   # use the hex digest as the value
kubectl create secret generic clickhouse-password \
  --from-literal=password='<sha256-hex-digest>'

spec:
  settings:
    defaultUserPassword:
      passwordType: password_sha256_hex
      secret:
        name: clickhouse-password
        key: password

使用 ConfigMap

ConfigMap 的作用方式与 Secret 相同，但其内容不像 Secret 那样受到保护。仅应用于非敏感或已哈希的值，例如 password_sha256_hex 摘要：

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

不要将明文密码放在 ConfigMap 中。任何明文 (passwordType: password) 值都应使用 Secret。

配置中的自定义用户

在配置文件中添加其他用户。为该用户创建 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  # Default: true

启用后，该 Operator 会将 Replicated 表和集成表同步到新副本。每个副本 pod (容器组) 都带有 clickhouse.com/ReplicaInitialized 就绪门控，因此只有在 Operator 完成初始化后，新副本才会通过公网无头 Service 对外发布：default 数据库会转换为 Replicated 引擎，并同步 schema。在此之前，Operator 和其他副本会通过其内部 Service 访问该副本。使用 enableDatabaseSync: false 时，Operator 会立即将副本标记为已初始化，因此就绪状态仅取决于容器探针。 Operator 绝不会删除已填充数据的非 Replicated default 数据库。此类副本在完成 schema 准备后仍会开始处理客户端流量，但在您自行解决该数据库的问题之前，集群会报告 SchemaInSync=False，原因为 DefaultDatabaseNotReplicated。在缩容移除副本之前，Operator 会先将客户端流量从该副本卸载，等待其停止对外发布，将其剩余数据复制到存活副本，然后才将其删除。

服务器日志

通过 spec.settings.logger 配置 ClickHouse 服务器日志。每个字段都是可选的，并且都有安全的默认值，因此即使你从未改动过，集群也会默认以 information 级别同时将日志输出到容器控制台和磁盘上的轮转文件。

spec:
  settings:
    logger:
      logToFile: true   # Default: true. Set false to log only to the console
      jsonLogs: false   # Default: false. Set true for structured JSON log lines
      level: information # Default: information
      size: 100M        # Default: 100M. Rotate a log file once it reaches this size
      count: 10         # Default: 10. Number of rotated files to keep

字段	默认值	描述
`logToFile`	`true`	当为 `false` 时，operator 会移除文件输出目标，服务器只向容器控制台输出日志。
`jsonLogs`	`false`	当为 `true` 时，operator 会添加 `formatting.type: json`，使每一行都成为一个 JSON 对象。
`level`	`information`	日志详细级别。可选值包括 `test`、`trace`、`debug`、`information`、`notice`、`warning`、`error`、`critical`、`fatal`。
`size`	`100M`	单个日志文件在轮转前的最大大小。
`count`	`10`	服务器保留的轮转后日志文件数量。

operator 始终会保持控制台日志开启，以确保 kubectl logs 可用；当 logToFile 为 true 时，还会额外启用文件日志。使用默认值的集群会生成如下 logger 块：

logger:
  console: true
  level: information
  log: /var/log/clickhouse-server/clickhouse-server.log
  errorlog: /var/log/clickhouse-server/clickhouse-server.err.log
  size: 100M
  count: 10

同样的 spec.settings.logger 块也适用于 KeeperCluster；不过，operator 会改为将日志文件写入 /var/log/clickhouse-keeper/，并将 Raft 日志记录器 (raft_logs_level) 设置为相同的 level。

无论 logToFile 如何设置，控制台日志始终保持开启，因此即使禁用文件日志，kubectl logs 仍可正常使用。将日志发送到可解析 JSON 的结构化日志存储时，请设置 jsonLogs: true。

系统日志表

Operator 会启用 query_log、part_log、text_log、metric_log 和 asynchronous_metric_log 系统表。由于这些表与您的数据位于同一个卷上，spec.settings.systemLogsTTLDays 会通过表生存时间 (TTL) 限制它们的保留时长。如果创建集群时未指定该字段，defaulting webhook 会将其设为 30。将其设为 0 可显式禁用生存时间 (TTL)。

spec:
  settings:
    systemLogsTTLDays: 14

默认值仅适用于新建集群。在 systemLogsTTLDays 引入之前创建的集群，其系统日志表不会自动设置生存时间 (TTL)，需要你手动设置该字段。

生存时间 (TTL) 会在服务器下次重启时生效。你可以通过 extraConfig 为各个表单独调整 TTL、调整其他系统日志设置，或使用 @remove 属性彻底禁用某个表：

spec:
  settings:
    extraConfig:
      text_log:
        ttl: event_date + INTERVAL 90 DAY DELETE
      metric_log:
        collect_interval_milliseconds: 60000
      part_log:
        "@remove": "1"

禁用表并不会删除该表：现有数据会一直保留在磁盘上，直到你手动删除该表。

系统表的生存时间 (TTL) 发生变化时，ClickHouse 会重新创建该系统表，并将旧数据保留在重命名后的表中，例如 system.text_log_0。不再需要历史数据时，请删除这些表。

自定义配置

内嵌额外配置

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

spec:
  settings:
    extraConfig:
      background_pool_size: 20

有用链接：

可重新加载的额外配置

对 extraConfig 的任何更改都会导致 ClickHouse Pod (容器组) 重启，因为 operator 无法确定哪些设置可在运行时重新加载。对于 ClickHouse 支持动态重新加载的设置 (常见的是 named_collections) ，请改用 extraReloadableConfig。operator 会通过重新加载配置来应用更改，无需重启 Pod (容器组) ：

spec:
  settings:
    extraReloadableConfig:
      named_collections:
        customers:
          url: "http://my-service.my-ns.svc:5400/Customers"
          format: "JSONEachRow"

确保每个顶层配置节只出现在 extraConfig 和 extraReloadableConfig 其中一处；如果两者包含相同的配置节，Operator 会发出警告。

使用 extraReloadableConfig 即表示你确认其中的设置可以安全地重新加载。若将必须重启才能生效的设置放在此处，该设置只会在下次重启后生效，且不会报错。

嵌入式附加用户配置

你也可以使用 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

定期重新同步

除了响应 Kubernetes 事件之外，operator 还会按固定时间间隔对每个集群重新执行协调。这样可以让 watch 无法观察到的状态 (如 ClickHouse 副本健康状况、Keeper quorum) 对应的状态条件保持最新，并重试诸如清理卡住的 pod (容器组) 等修复操作。该时间间隔由 operator 的 RESYNC_PERIOD environment variable 控制 (默认为 30s) 。它适用于 KeeperCluster 资源，设为 0 即可禁用定期重新同步。ClickHouseCluster 资源每 30 秒轮询一次 ClickHouse 的 system.warnings，这本身就会重新触发协调，因此 RESYNC_PERIOD 目前对其不起作用。

# in the operator Deployment spec
env:
- name: RESYNC_PERIOD
  value: "1m"

operator 会并发协调多个集群；每个控制器可并行执行的协调操作数量由 MAX_CONCURRENT_RECONCILES 设置 (默认为 4) 。

暂停协调

在 ClickHouseCluster 或 KeeperCluster 上设置 clickhouse.com/pause-reconciliation: "true" 注解，即可让 operator 停止对其进行协调。operator 会在已暂停的资源上报告 ReconcileSucceeded=False，原因为 ReconciliationPaused，除此之外不会对该资源做任何改动。如果 operator 会覆盖您的手动更改，可借此进行人工干预。暂停期间，operator 会将所有状态条件 (包括 Ready 和 Healthy) 报告为 Unknown，原因为 ReconciliationPaused，因为此时它不会观测该集群。移除该注解即可恢复协调；待处理的 spec 变更将在下一次协调时生效。

kubectl annotate clickhousecluster my-cluster clickhouse.com/pause-reconciliation=true
# ... manual surgery ...
kubectl annotate clickhousecluster my-cluster clickhouse.com/pause-reconciliation-

​ClickHouseCluster 配置

​基本配置

​副本和分片

​Keeper 集成

​外部管理的 Keeper

​KeeperCluster 配置

​终止时的 leader 身份移交

​存储配置

​集群域

​pod (容器组) 配置

​自动拓扑分散与亲和性

​手动配置

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

​pod (容器组) 中断预算

​默认值

​覆盖默认设置

​策略

​集群范围内停用

​容器配置

​自定义镜像

​容器资源

​环境变量

​卷挂载

​健康探针

​启动探针

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

​TLS/SSL 配置

​配置安全端点

​SSL 证书 Secret 格式

​通过 TLS 进行 ClickHouse-Keeper 通信

​外部 Secret

​必需的键

​策略：Observe 与 Manage

​状态条件和故障排查

​附加端口

​端到端示例：MySQL wire 协议

​字段约束

​保留端口和名称

​版本探测与升级通道

​选择发布渠道

​状态条件

​覆盖版本探测 Job

​Operator 级别的控制

​ClickHouse 设置

​默认用户密码

​密码类型

​使用 Secret 的完整示例

​使用 ConfigMap

​配置中的自定义用户

​数据库同步

​服务器日志

​系统日志表

​自定义配置

​内嵌额外配置

​有用链接：

​可重新加载的额外配置

​嵌入式附加用户配置

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

​配置示例

​定期重新同步

​暂停协调

ClickHouseCluster 配置

基本配置

副本和分片

Keeper 集成

外部管理的 Keeper

KeeperCluster 配置

终止时的 leader 身份移交

存储配置

集群域

pod (容器组) 配置

自动拓扑分散与亲和性

手动配置

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

pod (容器组) 中断预算

默认值

覆盖默认设置

策略

集群范围内停用

容器配置

自定义镜像

容器资源

环境变量

卷挂载

健康探针

启动探针

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

TLS/SSL 配置

配置安全端点

SSL 证书 Secret 格式

通过 TLS 进行 ClickHouse-Keeper 通信

外部 Secret

必需的键

策略：Observe 与 Manage

状态条件和故障排查

附加端口

端到端示例：MySQL wire 协议

字段约束

保留端口和名称

版本探测与升级通道

选择发布渠道

状态条件

覆盖版本探测 Job

Operator 级别的控制

ClickHouse 设置

默认用户密码

密码类型

使用 Secret 的完整示例

使用 ConfigMap

配置中的自定义用户

数据库同步

服务器日志

系统日志表

自定义配置

内嵌额外配置

有用链接：

可重新加载的额外配置

嵌入式附加用户配置

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

配置示例

定期重新同步

暂停协调