从 CHANGELOG 读懂 Altinity ClickHouse Operator核心机制、关键能力与版本演进全解析【免费下载链接】clickhouse-operatorAltinity Kubernetes Operator for ClickHouse creates, configures and manages ClickHouse® clusters running on Kubernetes项目地址: https://gitcode.com/GitHub_Trending/cl/clickhouse-operator导读CHANGELOG.md 记录了 Altinity ClickHouse Operator一个在 Kubernetes 上创建、配置并管理 ClickHouse 集群的 Operator从 0.15.0 到 0.23.4 的核心演进脉络。本文以该变更记录为骨架结合仓库源码pkg/、config/、docs/、deploy/逐条印证每个重要特性的实现位置与工作原理帮助读者系统理解Operator 如何决定一次配置变更是否需要重启 ClickHouse、如何通过 Kubernetes Secret 注入密码与配置、如何并发调和大规模分片集群、如何度量自身运行状态以及升级到新版本时需要注意哪些兼容性红线。读完本文你将能把某个版本改了什么与底层代码如何实现一一对应起来从而更安全地规划自己的升级与排障路径。一、CHANGELOG 的组织方式与版本节奏该文件遵循 Keep a Changelog 规范、采用语义化版本Semantic Versioning按Added / Changed / Fixed三类归并每个版本的行为变更。从版本号跨度0.15.0 → 0.23.4可以看出这是一个持续高频迭代的项目每个小版本通常包含数个到数十个 PR 的合并成果。值得注意的版本节奏特点0.x 阶段主版本号仍为 0意味着 0.21.0、0.23.0 这类次版本号跃迁往往携带行为级变化例如 0.21.0 重写了设置应用方式、0.23.0 引入 Kubernetes Secret 支持与实验性 Keeper 支持升级时务必阅读对应小节。部分版本带升级提示例如 0.16.1 明确标注CRD needs to be updated with this release0.19.3 提示 ClickHouseInstallation 自定义资源类型发生变化make sure you deploy full installation manifest when upgrading。仓库中 deploy/operatorhub/ 目录按 0.18.1 起逐版本存放 CSV 与 CRD 清单CHANGELOG.md 中记录的许多变更都能在其中找到对应的发布产物。下文按主题而非按版本顺序重组这些变更让每个机制都能讲透是什么、为什么、源码在哪。二、配置重启决策引擎configurationRestartPolicy2.1 问题背景设置变更 ≠ 必须重启在 0.21.0 之前Operator 应用 ClickHouse 设置的唯一方式是通过重建 StatefulSet 触发重启——任何 settings 变更都会导致所有 Pod 滚动重启代价高昂。0.21.0 彻底改变了这一行为不再重建 StatefulSet而是维护一套决策逻辑判断 ClickHouse 是否需要重启才能让某条设置生效需要重启时采用将 StatefulSet 缩容再扩容scale down and up的方式执行。这套逻辑由configurationRestartPolicy配置项控制其默认规则集在 config/config.yaml 与 CHANGELOG 中均有记录configurationRestartPolicy: rules: - version: * rules: - settings/*: yes - settings/dictionaries_config: no - settings/logger: no - settings/macros/*: no - settings/max_server_memory_*: no - settings/max_*_to_drop: no - settings/max_concurrent_queries: no - settings/models_config: no - settings/user_defined_executable_functions_config: no - zookeeper/*: yes - files/config.d/*.xml: yes - files/config.d/*dict*.xml: no - profiles/default/background_*_pool_size: yes - profiles/default/max_*_for_server: yes - version: 21.* rules: - settings/logger: yes规则语义按版本匹配version支持通配*作为兜底默认版本对每个配置路径前缀给出yes需重启或no热生效即可的结论同一路径命中多条规则时取最后一条匹配。2.2 源码实现谁在执行这条决策决策入口在 pkg/model/chop_config.go 的IsConfigurationChangeRequiresReboot(host)它分别对 ZooKeeper、全局 Profiles、全局 Quotas、Settings、Files 等区块逐一调用isSettingsChangeRequiresReboot判断。路径前缀常量定义于同一文件configurationRestartPolicyRulesSectionProfiles/Quotas/Settings/Files/Zookeeper对应配置文件中profiles/*、settings/*、files/*、zookeeper/*等前缀。注释中特别强调了一个工程细节pkg/model/chop_config.go*默认版本必须满足所有 ClickHouse 版本且当 ClickHouse 版本未知例如 host 因配置错误而无法启动时也会回退到该默认规则。2.3 结构化设置的特殊处理0.23.40.23.4 修复了logger/*这类结构化设置的重启规则此前修改它们会错误地触发 Pod 重启现在已修正。这正体现了该决策引擎的价值——把能否热加载的判断精确到路径级别避免无谓的集群抖动。与此相关的配套默认配置可见 config/chi/config.d/01-clickhouse-02-logger.xml 等文件Operator 正是通过生成这类配置片段来管理 ClickHouse 的日志、查询日志与 trace 日志。三、Kubernetes Secret 集成密码、设置与文件的注入3.1 三种标准注入位置0.23.0 起0.23.0 是 Secret 支持的重要里程碑CHI 中用户密码、配置设置项、配置文件三类内容都可以用 Kubernetes 标准语法从 Secret 取值users: user1/password: valueFrom: secretKeyRef: name: clickhouse_secret key: pwduser1 settings: s3/my_bucket/access_key: valueFrom: secretKeyRef: name: s3-credentials key: AWS_ACCESS_KEY_ID files: server.key: valueFrom: secretKeyRef: name: clickhouse-certs key: server.keyusers用户密码可从 Secret 注入如上面的user1/password避免明文写在 CHI 中。settings配置设置项的值可引用 Secret典型场景是 S3 存储的access_key/secret_key等凭据。files完整文件内容可来自 Secret典型场景是 TLS 证书server.key。仓库中完整的实战示例包括 docs/chi-examples/05-settings-01-overview.yaml用户/设置/文件综合示例、docs/chi-examples/22-secure-ssl-02-files-secret-ref.yamlSSL 文件引用 Secret、docs/chi-examples/22-secure-ssl-03-files-multi-secrets-ref.yaml多 Secret 引用详见 docs/security_hardening.md 的 Securing ClickHouse server settings 一节。3.2 更早的铺垫与源码落点Secret 能力并非一蹴而就0.16.0 就为settings区块增加了通过 Kubernetes Secret 提供 ClickHouse 用户/密码的能力。0.18.0 允许在定义用户时指定access_management并支持在用户密码中引用 k8s secret。0.20.0 起 Operator 与 ClickHouse 之间使用的clickhouse_operator凭据默认也来自 Secret见 config/secret.yaml 的生成模板思路。源码层面Secret 引用的数据结构定义在 pkg/apis/clickhouse.altinity.com/v1/type_cluster_secret.goSecret 值在配置模板中的替换逻辑在 pkg/model/common/normalizer/subst/settings.go 中完成CHI 的规范器normalizer在 pkg/model/chi/normalizer/normalizer.go 中处理这些引用。相关的单元测试见 pkg/controller/chi/worker-reconciler-chi_test.go。3.3 相关修复与配套能力0.23.2修复了某些情况下 Secret 相关环境变量生成可能偏离预期的问题issue #1344并升级到 Go 1.20 以关闭依赖库中的 CVE。0.23.1修复了在某些场景下用户users生成可能出错的问题issue #1324、#1332以及 metrics-exporter 在部分情况下无法导出指标的问题issue #1336。0.20.1修复了 Secret 相关的 RBAC 权限issue #1051Operator 需要具备读取 Secret 的权限才能在运行时解析这些引用。四、调和Reconcile机制并发控制、等待策略与状态可见性4.1 分片级并发调和0.21.1 → 0.22.0 定型0.21.1 引入可配置的分片级并发调和PR #11240.22.0 将参数正式化为reconcile.runtime区块。从 config/config.yaml 可以看到当前完整默认配置reconcile: runtime: # Max number of concurrent CHI reconciles in progress reconcileCHIsThreadsNumber: 10 # The operator reconciles shards concurrently in each CHI with the following limitations: # 1. Number of shards being reconciled (and thus having hosts down) in each CHI concurrently # can not be greater than reconcileShardsThreadsNumber. # 2. Percentage of shards being reconciled (and thus having hosts down) in each CHI concurrently # can not be greater than reconcileShardsMaxConcurrencyPercent. # 3. The first shard is always reconciled alone. Concurrency starts from the second shard and onward. # Max number of concurrent shard reconciles within one CHI in progress reconcileShardsThreadsNumber: 5 # Max percentage of concurrent shard reconciles within one CHI in progress reconcileShardsMaxConcurrencyPercent: 50设计要点注释中已写明并能在代码常量中得到印证reconcileShardsThreadsNumber与reconcileShardsMaxConcurrencyPercent同时约束并行分片数——数量上限与百分比上限取更严格者。第一个分片总是单独调和并发从第二个分片才开始避免首片尚未就绪就滚动后续分片。代码层面的默认值定义在 pkg/apis/clickhouse.altinity.com/v1/type_configuration_chop.godefaultReconcileCHIsThreadsNumber 1、defaultReconcileShardsThreadsNumber 11 表示严格串行、defaultReconcileShardsMaxConcurrencyPercent 50。也就是说CHANGELOG 与 config.yaml 中的示例值10/5/50是生产调优推荐值而非代码内建默认值未配置时 Operator 会按串行方式安全运行。0.22.0 还提到当变更应用到分片很多的集群时先在第一个节点上探针式验证成功后推广到 50% 分片——这一先验证后推广的节奏同样是保护大规模集群稳定性的关键设计。4.2 等待策略等待查询结束与nowait0.22.0 新增关闭等待运行中查询完成的能力可在 Operator 配置中全局设置spec: reconcile: host: wait: queries: false也可在 CHI 中按集群覆盖spec: reconciling: policy: nowait这延续了 0.16.0 引入的Pod 维护期间等待查询完成最长 5 分钟的思路把是否等待变成用户可调的策略。4.3 状态可见性演进CHI.status的演进贯穿多个版本0.20.2 / 0.20.1引入hostsCompletedstatus.hostsCompleted用于跟踪调和进度。0.21.3新增.status.useTemplates反映 CHI 中实际使用手动或自动的所有模板。0.22.1新增Aborted状态——当 Operator 中止一次调和时CHI 被标记为Aborted而不是停留在中间状态。0.23.3在 CHI status 中引入未变化 host 数量number of unchanged hosts并修复了调和中途重启时hosts-completed可能误报的问题。状态字段的开合可在 config/config.yaml 的status.fields区块控制如error: true、errors: true默认开启。4.4 自动恢复Aborted 后的处理config/config.yaml 中还记录了与 Aborted 状态配套的自动恢复配置reconcile: recovery: from: aborted: onPodReady: retry # retry (default) — re-enqueue the CHI for reconcile # none — do nothing, CHI stays Aborted即默认情况下当被中止的 CHI 的某个 Pod 变为 Ready 时Operator 会重新入队调和也可改为none保持 Aborted。对应的clickhouse_operator_chi_auto_recoveries_triggered指标在 pkg/controller/chi/metrics/metrics.go 中登记后续 4.5 节详述。4.5 Operator 自身指标从 0.22.0 到 0.23.40.22.0 起 Operator 暴露一批自监控指标0.23.4 又补充了clickhouse_operator_chi_reconciles_aborted。CHANGELOG 中列出的完整指标清单在 pkg/controller/chi/metrics/metrics.go 中可逐条对应到 OTel Meter 的注册代码clickhouse_operator_chi_reconciles_started clickhouse_operator_chi_reconciles_completed clickhouse_operator_chi_reconciles_timings clickhouse_operator_host_reconciles_started clickhouse_operator_host_reconciles_completed clickhouse_operator_host_reconciles_restarts clickhouse_operator_host_reconciles_errors clickhouse_operator_host_reconciles_timings clickhouse_operator_pod_add_events clickhouse_operator_pod_update_events clickhouse_operator_pod_delete_events此外 0.23.4 新增的clickhouse_operator_chi_reconciles_aborted统计被显式中止的调和次数在源码中也有明确注释它不包含因外部原因如 Operator 重启而未完成的调和语义非常精确。0.23.0 还让 CHI 的 labels 随指标一并导出方便在 Prometheus 中按集群维度聚合config/config.yaml 的metrics.labels.exclude可控制是否排除部分 label。指标收集与抓取的另一半是 metrics-exporter入口在 cmd/metrics_exporter0.22.0 起它并行采集所有 host 与查询0.23.1 修复了其偶发无法导出指标的问题0.21.0 起支持采集system.errors并允许通过配置禁用 metrics exporter。五、实验性 ClickHouse Keeper 支持0.23.00.23.0 通过 PR #1218 引入了实验性的 ClickHouse Keeper 支持CRD 类型为ClickHouseKeeperInstallationkind: ClickHouseKeeperInstallationCHANGELOG 明确列出了尚未完成的两件事如实呈现了该功能的实验性质动态重配置——这是支持动态增删 Keeper 副本的前提与 ClickHouseInstallation 的集成——理想情况下 CHI 应通过引用reference而非服务名来关联 Keeper。同时 0.23.4 提到 Keeper 相关代码有大量内部重构但无功能变化功能增强留待下一大版本。CHANGELOG 还注明如果集群中不存在ClickHouseKeeperInstallation资源类型Operator 也不会因此失败0.23.4这为混合环境提供了兼容性保障。仓库中可找到的配套产物示例清单配置与部署示例集中在 docs/chk-examples/含 1 节点、3 节点、test-only、私有镜像 Secret 等场景部署目录见 deploy/clickhouse-keeper/。默认 Keeper 配置Operator 生成 Keeper 配置时使用的模板在 config/chk/keeper_config.d/如 01-keeper-01-default-config.xml、02-keeper-readiness.xml。调谐逻辑pkg/controller/chk/目录34 个 Go 文件对应 CHK 的控制器实现模型层在 pkg/model/chk/。六、存储与数据安全卷重供应、PV 管理与数据恢复6.1 卷重供应0.22.00.22.0 支持卷重供应volume re-provisioning当卷损坏、PVC 判定其丢失lost时Operator 会重新供应卷。这对自管存储Local PV 等场景尤为重要——损坏的卷不应导致集群永久不可用。6.2 Operator 托管的 PV 供应0.20.00.20.0 引入 Operator 管理的 PV provisioning受 PR #947 启发允许无停机调整卷大小。启用方式是在 CHI 中设置defaults: storageManagement: provisioner: Operator启用后卷的创建与扩容由 Operator 接管从而避免调整 PVC 大小必须重建 Pod的经典约束。仓库中与之配套的卷管理示例见 docs/chi-examples/03-persistent-volume-05-resizeable-volume-1.yaml 与 03-persistent-volume-07-multiple-resizable-volumes-1.yaml存储设计文档见 docs/storage.md。6.3 数据恢复与误删保护0.23.0修复了用户删除 PVC 后的数据恢复问题issue #1310。0.18.0删除 CRD 时 Operator 保留所有依赖对象StatefulSet、卷防止误删导致整个集群数据丢失。0.16.1 / 0.16.0修复了 PVC 在 Operator 外部被修改后调和时被重建的 bugissue #730以及缩容时副本未从 ZooKeeper 删除的问题issue #735。6.4 对象存储指标修正0.23.30.23.3 将对象存储磁盘S3 等从DiskTotal/Free指标中移除——对对象存储而言总容量/剩余容量没有实际意义保留只会误导监控。七、安全加固演进网络、用户、TLS安全相关的变更贯穿多个版本核心脉络如下0.19.0clickhouse_operator用户被限制为只能从 Operator Pod 的 IP 访问default用户除了hostRegexp外还被限制为仅接受 CHI Pod 的 IP修复 GKE 下分片间连接问题interserver_http_host设为服务名并与remote_servers匹配可通过replicasUseFQDN改为全限定名支持为 Operator 到 ClickHouse 的连接添加自定义 CA。0.20.0支持 ClickHouse 实例之间安全通信配套示例见 docs/chi-examples/21-secure-cluster-secret-01-auto.yaml自动生成 Secret、21-secure-cluster-secret-02-plaintext.yaml明文 Secret、21-secure-cluster-secret-03-secret-ref.yaml引用 K8s Secret。0.20.2集群级别新增secure标志用于启用分布式查询的 TLS注意其数据类型从 boolean 改为 String接受true、yes、1等升级时需留意写法。0.21.0ZooKeeper 连接新增secure选项新增insecure标志可关闭不安全的 TCP/HTTP ClickHouse 端口详见 docs/security_hardening.md 的 Disabling insecure connections。0.21.2Operator 与 metrics-exporter 会根据集群配置自动选择 http 或 https连接无需手工指定。基础镜像层面0.16.0 切到 RedHat UBI0.20.3 又改为 alpine 基础镜像多个版本0.18.4/0.18.5/0.20.2/0.20.1/0.23.2持续处理依赖库 CVE。八、网络与服务治理Service 类型、PDB 与健康检查8.1 Service 类型变更与重建0.23.4 / 0.23.00.23.4默认 Service 类型从LoadBalancer改为ClusterIP——对多数内部使用场景ClusterIP更符合最小暴露原则需要对外暴露时再显式指定LoadBalancer。0.23.0当 ServiceType 被修改时Service 会被重建以规避 Kubernetes 的已知问题kubernetes/kubernetes#24040Service 类型变更后负载均衡器不生效。0.20.2调整 LB Service 的创建顺序避免出现Service 已存在但没有可用 endpoints的窗口期。0.19.1为副本 Service 增加clickhouse.altinity.com/ready: yes|no注解供外部负载均衡器判断就绪状态。8.2 PodDisruptionBudget0.16.0 → 0.20.10.16.0 起自动配置 PDB防止 k8s 同时关闭多个 Pod。0.20.1 将 cluster 加入 PDB selectorissue #996注意该特性要求 Kubernetes 1.21 及以上。0.21.0 修复了 PDB 可能被误删的 bugissue #1139。0.19.1 更新了 PDB 的 API 版本。8.3 健康检查与探针0.18.4健康检查支持 HTTPSPR #912。0.23.0检查节点是否在线时Operator 会等待 ClickHouse Service 的 endpoints 响应避免Pod 在但服务不可达的误判。0.15.0引入troubleshooting 模式spec.troubleshootClickHouse 启动失败时允许 Pod 照常启动、移除 liveness 检查并注入额外 sleep便于现场排障。九、模板与元数据管理0.21.3CHITemplate 支持selector——可以定义只应用于特定 CHI的模板示例见 docs/chi-examples/50-CHIT-04-auto-template-volume-with-selector.yaml同时新增.status.useTemplates反映实际使用的模板。0.23.0CHI 模板CHITemplate改为自动热加载——此前只在 Operator 启动时加载现在模板变更后只需触发一次 CHI 更新即可生效0.21.3 已为 CHITemplate 本身实现免重启重载。0.17.0自动模板的 labels/annotations 得到支持宏macros可用于 service annotations与 generateName 用法一致。0.23.4Helm chart 支持在 chart 中直接添加 Pod labelsPR #1369满足通过 Helm 安装时统一打标的诉求对应 deploy/helm/clickhouse-operator/values.yaml。十、Schema 传播、迁移与分布式表0.19.0schema 传播策略由两个集群级设置控制CRD 定义见 deploy/operator/parts/crd.yamlschemaPolicy: replica: None | All (default) shard: None | All (default) | DistributedTablesOnly此前新增分片时只创建分布式表及依赖对象即DistributedTablesOnly现在可配置为全量传播。0.17.0 / 0.19.1修复 Atomic 数据库、{uuid}宏、materialized view 在 ClickHouse 22.6 的迁移问题0.18.0 从 schema 传播中移除 INFORMATION_SCHEMA。0.21.2新增分片/副本时支持SQL UDF 的复制issue #1174。0.23.0 / 0.23.3修复 ClickHouse 23.11 新副本的 schema 传播0.23.3 起支持参数化数据库传播到分片与副本ClickHouse 22.12包括 Replicated 与 MySQL 数据库引擎issue #1076。0.22.0修复了新节点启动过慢时 schema 无法创建的问题。0.16.0DDL 操作超时提高到 60 秒缓解慢集群上的 schema 管理问题。十一、升级与兼容性检查清单综合 CHANGELOG 中所有带标注的注意点升级时建议逐项核对CRD 必须同步更新0.16.1Status CRD 定义修改、0.19.3ClickHouseInstallation 资源类型变化都明确要求部署完整安装清单。0.22.1 起允许 CRD status 及部分字段为空方便先升 Operator、后升 CRD的过渡迁移issue #842、#890。默认值变化可能引发重启0.16.0 将terminationGracePeriod提到 60 秒0.16.1 又改回 30 秒并移入 Operator 配置见 config/config.yaml 的pod.terminationGracePeriod。0.15.0 → 0.16.x 的升级会触发 ClickHouse 重启0.16.0 → 0.16.1 如需保留 60 秒需在 Operator 配置中显式设置。Service 类型默认值0.23.4 起默认ClusterIP依赖LoadBalancer的环境需显式配置。类型语义变化0.20.2 中secure标志从 boolean 改为 String0.18.0 起 Operator 配置文件格式调整旧格式仍向后兼容新格式参见 config/config.yaml 与 docs/chi-examples/70-chop-config.yaml。行为变化0.23.0 起 Operator 配置无法解析时直接崩溃而非回退到默认值——这要求配置必须经过校验可用 docs/operator_configuration.md 核对全部可选项0.21.2 起 StatefulSet 更新失败会中止更新以保护集群其余部分。故障容忍0.18.0 起删除 CRD 不再级联删除 StatefulSet 与卷避免误删0.19.2/0.19.3 修复了重启时 remote-servers.xml 被重建导致分布式查询异常的问题。调度与亲和0.16.0 使topologyKey可配置issue #7720.15.0 引入spec.reconciling.configMapPropagationTimeout默认 90 秒消除 ConfigMap 更新与 StatefulSet 重启之间的竞态。十二、总结把 CHANGELOG.md 与源码对照阅读可以得到几条清晰的演进主线从无脑重启到智能决策configurationRestartPolicy让设置变更的重启决策精确到路径级是 0.21.0 以来最值得关注的架构改进从明文配置到Secret 优先用户密码、设置项、文件三路 Secret 注入配合secure/insecure/TLS 选项构成了完整的安全闭环从串行调和到受控并发reconcile.runtime的线程数与百分比双约束、首分片单独调和、探针式推广让大规模多分片集群的滚动更新既快又稳从黑盒运行到可观测CHI/host 两个层级的 reconcile 指标族与Aborted状态、自动恢复机制使 Operator 自身的健康与进度可监控、可恢复。对于计划升级或正在排障的用户建议以本文第二章重启策略、第四章调和与指标、第十一章兼容性清单作为优先阅读章节并将 config/config.yaml 作为核对配置的权威基准。【免费下载链接】clickhouse-operatorAltinity Kubernetes Operator for ClickHouse creates, configures and manages ClickHouse® clusters running on Kubernetes项目地址: https://gitcode.com/GitHub_Trending/cl/clickhouse-operator创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考