ClickHouse Operator 存储指南PersistentVolume、StorageClass 与 PVC 的 Kubernetes 持久化实战【免费下载链接】clickhouse-operatorAltinity Kubernetes Operator for ClickHouse creates, configures and manages ClickHouse® clusters running on Kubernetes项目地址: https://gitcode.com/GitHub_Trending/cl/clickhouse-operator导读本指南是 ClickHouse Operator 存储体系的入门与实战参考系统讲解 Kubernetes 中PersistentVolumePV、PersistentVolumeClaimPVC与StorageClass三者如何协作为 ClickHouse 集群提供持久化数据卷。你将掌握如何通过storageClassName精确或省心地选择存储、如何在 Pod 与 StatefulSet 中挂载 PVC、如何为 AWS gp2 创建加密卷以及如何用 ClickHouse Operator 的volumeClaimTemplates、dataVolumeClaimTemplate/logVolumeClaimTemplate声明数据卷与日志卷。文章末尾以 docs/storage.md 对应的 chi-examples 目录下的真实示例为依托给出可直接复制的 CHI 配置。一、Kubernetes 持久化存储的三个核心对象在进入 ClickHouse 配置之前先厘清 Kubernetes 存储的抽象层次。管理员或云平台提供存储应用消费存储二者通过 PVC 解耦对象角色说明PersistentVolumePV集群级存储资源由管理员预置手动或由 provisioner 动态创建PersistentVolumeClaimPVC命名空间级存储申请应用申领存储的入口与 Pod 同命名空间StorageClass动态供给模板抽象底层存储介质类型、磁盘类型、回收策略等参数1.1 手动供给Manual Provisioning集群管理员先向云/存储厂商申请真实磁盘再以PersistentVolume对象把它注册进 Kubernetes用户随后创建PersistentVolumeClaim与之绑定。这种方式完全可控但需要管理员事先精确规划容量与存储位置。1.2 动态供给Dynamic Provisioning当 PVC 指定了storageClassName时Kubernetes 会调用该StorageClass中声明的 provisioner 插件按需创建底层存储并自动生成 PV 完成绑定无需管理员预置。StorageClass正是抽象底层存储提供商的关键——同一套 PVC 清单换一个云环境只需更换storageClassName。二、StorageClass 与 storageClassName 的三态行为2.1 如何在 PVC 中引用 StorageClass应用在 PVC 的spec.storageClassName字段中按名字引用StorageClassapiVersion: v1 kind: PersistentVolumeClaim metadata: name: mypvc namespace: mytestns spec: storageClassName: my-storage-class accessModes: - ReadWriteOnce resources: requests: storage: 100Gi示例中的my-storage-class由集群管理员定义并对外公布具体名字因集群而异。为了避免应用方必须知道环境里有哪些存储类管理员可以指定一个defaultStorageClass让用户省略该字段。2.2 storageClassName 三态语义务必记牢字段不指定使用集群的defaultStorageClass进行动态供给要求管理员已设置默认存储类字段为空字符串不使用任何StorageClass即对该 PVC 禁用动态供给只与不带storageClassName的既有 PV 绑定字段为具体名字使用与该名字匹配的StorageClass进行动态供给。这一三态语义是理解后续所有示例包括 ClickHouse Operator 默认存储行为的基础。三、AWS 实战用 kubectl 观察与选择 StorageClass以kops创建的 AWS 集群为例可以这样查看可用的StorageClasskubectl get storageclasses.storage.k8s.io输出示例NAME PROVISIONER AGE default kubernetes.io/aws-ebs 1d gp2 (default) kubernetes.io/aws-ebs 1d可以看到两个存储类名为default的存储类以及被标记为集群默认(default)的gp2。进一步查看其内部定义kubectl get storageclasses.storage.k8s.io default -o yaml kubectl get storageclasses.storage.k8s.io gp2 -o yaml两个存储类的内容几乎一致metadata: labels: k8s-addon: storage-aws.addons.k8s.io name: gp2 provisioner: kubernetes.io/aws-ebs parameters: type: gp2 reclaimPolicy: Delete volumeBindingMode: Immediatemetadata: labels: k8s-addon: storage-aws.addons.k8s.io name: default provisioner: kubernetes.io/aws-ebs parameters: type: gp2 reclaimPolicy: Delete volumeBindingMode: Immediate结论在kubernetes.io/aws-ebsprovisioner 下default与gp2参数完全相同磁盘类型均为gp2只是gp2被标记为系统默认。因此指定 PVC 时有两种等效写法省略storageClassName字段自动命中默认的gp2显式指定storageClassName: default两种方式结果一致但显式指定更利于阅读清单时的可读性。四、Pod 中的持久卷挂载4.1 volume 与 volumeMount 的对应关系Pod 通过volumes定义卷来源通过containers[].volumeMounts把卷挂载进容器文件系统# Pod 或 Pod Template 清单节选 containers: - name: myclickhouse image: clickhouse volumeMounts: - mountPath: /var/lib/clickhouse name: my-volumevolumeMounts[].name与volumes[].name一一对应。卷的类型有多种常见三类emptyDir临时目录# 清单节选 volumes: - name: my-volume emptyDir: {}hostPath节点本地路径# StatefulSet 清单节选 volumes: - name: my-volume hostPath: path: /local/path/persistentVolumeClaim引用 PVC# 清单节选 volumes: - name: my-volume persistentVolumeClaim: claimName: my-claim4.2 最小 PVC 与完整 Pod 示例最精简的 PVC 可省略storageClassName自动使用默认存储类apiVersion: v1 kind: PersistentVolumeClaim metadata: name: my-pvc spec: accessModes: - ReadWriteOnce resources: requests: storage: 1Gi把它放进完整 Pod 中使用apiVersion: v1 kind: Pod metadata: name: nginx spec: volumes: - name: www persistentVolumeClaim: claimName: my-pvc containers: - name: nginx image: k8s.gcr.io/nginx-slim:0.8 ports: - containerPort: 80 name: web volumeMounts: - name: www mountPath: /usr/share/nginx/html注意事项PVC 必须与使用它的 Pod 位于同一命名空间Kubernetes 根据 PVC 找到匹配的 PV 并挂载到mountPath关于storageClassName的更多语义可参考 Kubernetes 官方 Persistent Volumes 文档中的 Class 一节关于 PVC 的更多细节可查阅 PersistentVolumeClaims 章节。以上概念同时适用于 ClickHouse Pod——例如 ClickHouse 的默认数据目录/var/lib/clickhouse通常就应挂载持久卷。五、StatefulSetvolumeClaimTemplates 的快捷方式StatefulSet为有状态应用提供了一种更简捷的持久化方式省略volumes直接从volumeMounts跳到volumeClaimTemplates。每个 Pod 副本会自动获得一个由模板生成的独立 PVC命名规则为volumeClaimTemplate-name-statefulset-name-ordinal。标准示例apiVersion: v1 kind: Service metadata: name: nginx labels: app: nginx spec: ports: - port: 80 name: web clusterIP: None selector: app: nginx --- apiVersion: apps/v1 kind: StatefulSet metadata: name: web spec: serviceName: nginx replicas: 2 selector: matchLabels: app: nginx template: metadata: labels: app: nginx spec: containers: - name: nginx image: k8s.gcr.io/nginx-slim:0.8 ports: - containerPort: 80 name: web volumeMounts: - name: www mountPath: /usr/share/nginx/html volumeClaimTemplates: - metadata: name: www spec: accessModes: [ ReadWriteOnce ] resources: requests: storage: 1Gi注意.spec.template.spec.containers.volumeMounts直接引用volumeClaimTemplates的metadata.namevolumeMounts: - name: www mountPath: /usr/share/nginx/htmlvolumeClaimTemplates: - metadata: name: www spec: accessModes: [ ReadWriteOnce ] resources: requests: storage: 1GiClickHouse Operator 的对应物Operator 内部正是围绕这一机制建模的。CHI CRD 中的VolumeClaimTemplate结构定义见 type_volume_claim_template.go封装了Name与标准 KubernetesPersistentVolumeClaimSpec并附带PVCProvisionerStatefulSet/Operator两种取值与PVCReclaimPolicyRetain/Delete两个管理字段同文件 type_volume_claim_template.go、type_volume_claim_template.go。也就是说Operator 会把你在 CHI 中声明的卷模板翻译为 StatefulSet 的volumeClaimTemplates由 StatefulSet 为每个 ClickHouse Pod 生成专属 PVC。六、AWS 加密卷基于 gp2 的 encrypted-gp2默认的gp2卷不加密。要使用加密卷需要先定义一个带encrypted: true参数的专用StorageClassapiVersion: storage.k8s.io/v1 kind: StorageClass metadata: name: encrypted-gp2 provisioner: kubernetes.io/aws-ebs parameters: type: gp2 fsType: ext4 encrypted: true reclaimPolicy: Delete volumeBindingMode: Immediate再在 PVC 中引用它apiVersion: v1 kind: PersistentVolumeClaim metadata: name: encrypted-pvc spec: storageClassName: encrypted-gp2 accessModes: - ReadWriteOnce volumeMode: Block resources: requests: storage: 1Gi要点加密参数位于StorageClass.parameters中对使用该存储类的所有 PVC 生效该示例还展示了volumeMode: Block——以块设备而非文件系统方式消费卷适用于 ClickHouse 对块设备有特殊性能要求的场景对于更复杂的 ClickHouse 加密与安全需求可参考仓库中的 21-secure-cluster-secret 系列示例 与 22-secure-ssl 系列示例。七、ClickHouse Operator 实战在 CHI 中声明持久卷以上 Kubernetes 原语最终要落到 ClickHouse Operator 的ClickHouseInstallationCHI自定义资源中。CHI 通过spec.templates.volumeClaimTemplates定义卷模板并在 Pod 模板或defaults中引用。7.1 方式一defaults 中声明数据卷与日志卷03-persistent-volume-01-default-volume.yaml 展示了最简洁的用法——通过defaults.templates全局指定数据卷与日志卷apiVersion: clickhouse.altinity.com/v1 kind: ClickHouseInstallation metadata: name: pv-simple spec: defaults: templates: dataVolumeClaimTemplate:>apiVersion: clickhouse.altinity.com/v1 kind: ClickHouseInstallation metadata: name: pv-log spec: configuration: clusters: - name: deployment-pv # Templates are specified for this cluster explicitly templates: podTemplate: pod-template-with-volumes layout: shardsCount: 2 replicasCount: 2 templates: podTemplates: - name: pod-template-with-volumes spec: containers: - name: clickhouse image: clickhouse/clickhouse-server:24.8 volumeMounts: - name:>apiVersion: clickhouse.altinity.com/v1 kind: ClickHouseInstallation metadata: name: repl-03 spec: configuration: zookeeper: nodes: - host: zookeeper.zoo1ns port: 2181 clusters: - name: replcluster templates: podTemplate: clickhouse-with-volume-template layout: shardsCount: 1 replicasCount: 2 templates: podTemplates: - name: clickhouse-with-volume-template spec: containers: - name: clickhouse-pod image: clickhouse/clickhouse-server:24.8 volumeMounts: - name: clickhouse-storage-template mountPath: /var/lib/clickhouse volumeClaimTemplates: - name: clickhouse-storage-template spec: # no storageClassName - means use default storageClassName #storageClassName: default accessModes: - ReadWriteOnce resources: requests: storage: 50Gi而 04-replication-zookeeper-04-medium-AWS-persistent-volume.yaml 则把 Zookeeper 扩展为 3 节点数据卷调整为 900Mi适合中等规模验证apiVersion: clickhouse.altinity.com/v1 kind: ClickHouseInstallation metadata: name: repl-04 spec: configuration: zookeeper: nodes: - host: zookeeper-0.zookeepers.zoo3ns port: 2181 - host: zookeeper-1.zookeepers.zoo3ns port: 2181 - host: zookeeper-2.zookeepers.zoo3ns port: 2181 clusters: - name: replcluster templates: podTemplate: clickhouse-with-volume-template layout: shardsCount: 1 replicasCount: 2 templates: podTemplates: - name: clickhouse-with-volume-template spec: containers: - name: clickhouse-pod image: clickhouse/clickhouse-server:24.8 volumeMounts: - name: clickhouse-storage-template mountPath: /var/lib/clickhouse volumeClaimTemplates: - name: clickhouse-storage-template spec: # no storageClassName - means use default storageClassName #storageClassName: default accessModes: - ReadWriteOnce resources: requests: storage: 900Mi要点配置中刻意注释掉了storageClassName: default意在提醒读者省略该字段即使用集群默认存储类复制表ReplicatedMergeTree 等依赖 Zookeeper 协调而每个副本的本地数据则落在各自的 PVC 上——这正是存储与复制两类能力的组合使用方式完整的复制与 Zookeeper 配置方法可参考 replication_setup.md 与 zookeeper_setup.md。7.4 进阶storageManagement 与 PVC 生命周期管理除spec之外CHI 的卷模板还支持storageManagement字段用于控制 PVC 的供给方式与回收策略。在 99-clickhouseinstallation-max.yaml 的defaults中有完整示范defaults: replicasUseFQDN: no distributedDDL: profile: default storageManagement: # Specify PVC provisioner. # 1. StatefulSet. PVC would be provisioned by the StatefulSet # 2. Operator. PVC would be provisioned by the operator provisioner: StatefulSet # Specify PVC reclaim policy. # 1. Retain. Keep PVC from being deleted # Retaining PVC will also keep backing PV from deletion. This is useful in case we need to keep data intact. # 2. Delete reclaimPolicy: Retain对应到源码type_storage_management.goprovisioner取值StatefulSet或Operator。StatefulSet表示 PVC 由 StatefulSet 控制器自动创建Operator表示由 Operator 自行创建并管理 PVC合法取值定义见 type_volume_claim_template.goreclaimPolicy取值Retain或Delete。Retain在删除 PVC 时保留数据底层 PV 也不会被回收适合需要保护数据完整性的生产场景Delete则随 PVC 删除一并回收合法取值见 type_volume_claim_template.go。StorageManagement支持从默认值到具体集群的逐级合并MergeFrom逻辑见 type_storage_management.go即defaults中设置的provisioner/reclaimPolicy可被更下层的集群或模板覆盖实现默认一致、个别定制的管理模式。八、示例索引与延伸阅读8.1 本文涉及的示例文件示例相对路径核心看点默认数据/日志卷03-persistent-volume-01-default-volume.yamldefaults.templates全局指定 data/log 卷模板Pod 模板挂多卷03-persistent-volume-02-pod-template.yamlvolumeMounts与volumeClaimTemplates关联2×2 集群AWS 最小复制 PV04-replication-zookeeper-03-minimal-AWS-persistent-volume.yaml1×2 复制、单 Zookeeper、50Gi 数据卷AWS 中等复制 PV04-replication-zookeeper-04-medium-AWS-persistent-volume.yaml1×2 复制、3 节点 Zookeeper、900Mi 数据卷全量字段参考99-clickhouseinstallation-max.yamlstorageManagement完整字段与注释8.2 更多存储相关示例与文档存储体系进阶storage.md 的配套示例均在 docs/chi-examples 目录可按编号阅读03-persistent-volume-03-custom-labels-and-annotations.yaml自定义标签与注解03-persistent-volume-04-encrypted-volume.yaml加密卷03-persistent-volume-05-resizeable-volume-1.yaml 与 03-persistent-volume-05-resizeable-volume-2.yaml卷扩容03-persistent-volume-06-add-log-volume-1.yaml 与 03-persistent-volume-06-add-log-volume-2.yaml为运行中的集群新增日志卷03-persistent-volume-07-multiple-resizable-volumes-1.yaml 至 03-persistent-volume-07-multiple-resizable-volumes-3.yaml多卷可扩容组合03-persistent-volume-08-tiered-s3.yamlS3 分层存储03-persistent-volume-09-with-template-emptydir.yamlemptyDir 模板03-persistent-volume-10-log-volume-local.yaml本地日志卷相关文档operator_configuration.mdOperator 全局配置含存储相关默认值custom_resource_explained.mdCHI 自定义资源逐字段讲解replication_setup.md / zookeeper_setup.md复制与协调服务配置deploy/openebs/lvm/README基于 OpenEBS LVM 的本地存储方案含 clickhouse-installation-with-openebs.yaml 示例源码参考CRD 卷模板结构type_volume_claim_template.godata/log 卷模板字段与废弃兼容type_templates_list.go存储管理合并逻辑type_storage_management.go模板应用与 PVC 资源请求合并volumeClaimTemplate.go总结本文完整覆盖了 ClickHouse Operator 持久化存储的完整链路从 Kubernetes 的PersistentVolume/PersistentVolumeClaim/StorageClass基础概念到storageClassName三态语义、AWS gp2 与加密卷实战再到 CHI 中通过volumeClaimTemplates声明数据卷与日志卷、通过storageManagement控制 PVC 供给与回收。实际部署时推荐从 03-persistent-volume-01-default-volume.yaml 起步验证默认存储再按需升级为 Pod 模板多卷、加密卷或复制 持久卷组合。唯一需要记住的原则是省略storageClassName即使用集群默认存储类显式指定则精确控制存储后端——这一选择直接决定了 ClickHouse 数据卷的最终落盘位置。【免费下载链接】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），仅供参考 ClickHouse Operator 存储指南：PersistentVolume、StorageClass 与 PVC 的 Kubernetes 持久化实战
ClickHouse Operator 存储指南PersistentVolume、StorageClass 与 PVC 的 Kubernetes 持久化实战【免费下载链接】clickhouse-operatorAltinity Kubernetes Operator for ClickHouse creates, configures and manages ClickHouse® clusters running on Kubernetes项目地址: https://gitcode.com/GitHub_Trending/cl/clickhouse-operator导读本指南是 ClickHouse Operator 存储体系的入门与实战参考系统讲解 Kubernetes 中PersistentVolumePV、PersistentVolumeClaimPVC与StorageClass三者如何协作为 ClickHouse 集群提供持久化数据卷。你将掌握如何通过storageClassName精确或省心地选择存储、如何在 Pod 与 StatefulSet 中挂载 PVC、如何为 AWS gp2 创建加密卷以及如何用 ClickHouse Operator 的volumeClaimTemplates、dataVolumeClaimTemplate/logVolumeClaimTemplate声明数据卷与日志卷。文章末尾以 docs/storage.md 对应的 chi-examples 目录下的真实示例为依托给出可直接复制的 CHI 配置。一、Kubernetes 持久化存储的三个核心对象在进入 ClickHouse 配置之前先厘清 Kubernetes 存储的抽象层次。管理员或云平台提供存储应用消费存储二者通过 PVC 解耦对象角色说明PersistentVolumePV集群级存储资源由管理员预置手动或由 provisioner 动态创建PersistentVolumeClaimPVC命名空间级存储申请应用申领存储的入口与 Pod 同命名空间StorageClass动态供给模板抽象底层存储介质类型、磁盘类型、回收策略等参数1.1 手动供给Manual Provisioning集群管理员先向云/存储厂商申请真实磁盘再以PersistentVolume对象把它注册进 Kubernetes用户随后创建PersistentVolumeClaim与之绑定。这种方式完全可控但需要管理员事先精确规划容量与存储位置。1.2 动态供给Dynamic Provisioning当 PVC 指定了storageClassName时Kubernetes 会调用该StorageClass中声明的 provisioner 插件按需创建底层存储并自动生成 PV 完成绑定无需管理员预置。StorageClass正是抽象底层存储提供商的关键——同一套 PVC 清单换一个云环境只需更换storageClassName。二、StorageClass 与 storageClassName 的三态行为2.1 如何在 PVC 中引用 StorageClass应用在 PVC 的spec.storageClassName字段中按名字引用StorageClassapiVersion: v1 kind: PersistentVolumeClaim metadata: name: mypvc namespace: mytestns spec: storageClassName: my-storage-class accessModes: - ReadWriteOnce resources: requests: storage: 100Gi示例中的my-storage-class由集群管理员定义并对外公布具体名字因集群而异。为了避免应用方必须知道环境里有哪些存储类管理员可以指定一个defaultStorageClass让用户省略该字段。2.2 storageClassName 三态语义务必记牢字段不指定使用集群的defaultStorageClass进行动态供给要求管理员已设置默认存储类字段为空字符串不使用任何StorageClass即对该 PVC 禁用动态供给只与不带storageClassName的既有 PV 绑定字段为具体名字使用与该名字匹配的StorageClass进行动态供给。这一三态语义是理解后续所有示例包括 ClickHouse Operator 默认存储行为的基础。三、AWS 实战用 kubectl 观察与选择 StorageClass以kops创建的 AWS 集群为例可以这样查看可用的StorageClasskubectl get storageclasses.storage.k8s.io输出示例NAME PROVISIONER AGE default kubernetes.io/aws-ebs 1d gp2 (default) kubernetes.io/aws-ebs 1d可以看到两个存储类名为default的存储类以及被标记为集群默认(default)的gp2。进一步查看其内部定义kubectl get storageclasses.storage.k8s.io default -o yaml kubectl get storageclasses.storage.k8s.io gp2 -o yaml两个存储类的内容几乎一致metadata: labels: k8s-addon: storage-aws.addons.k8s.io name: gp2 provisioner: kubernetes.io/aws-ebs parameters: type: gp2 reclaimPolicy: Delete volumeBindingMode: Immediatemetadata: labels: k8s-addon: storage-aws.addons.k8s.io name: default provisioner: kubernetes.io/aws-ebs parameters: type: gp2 reclaimPolicy: Delete volumeBindingMode: Immediate结论在kubernetes.io/aws-ebsprovisioner 下default与gp2参数完全相同磁盘类型均为gp2只是gp2被标记为系统默认。因此指定 PVC 时有两种等效写法省略storageClassName字段自动命中默认的gp2显式指定storageClassName: default两种方式结果一致但显式指定更利于阅读清单时的可读性。四、Pod 中的持久卷挂载4.1 volume 与 volumeMount 的对应关系Pod 通过volumes定义卷来源通过containers[].volumeMounts把卷挂载进容器文件系统# Pod 或 Pod Template 清单节选 containers: - name: myclickhouse image: clickhouse volumeMounts: - mountPath: /var/lib/clickhouse name: my-volumevolumeMounts[].name与volumes[].name一一对应。卷的类型有多种常见三类emptyDir临时目录# 清单节选 volumes: - name: my-volume emptyDir: {}hostPath节点本地路径# StatefulSet 清单节选 volumes: - name: my-volume hostPath: path: /local/path/persistentVolumeClaim引用 PVC# 清单节选 volumes: - name: my-volume persistentVolumeClaim: claimName: my-claim4.2 最小 PVC 与完整 Pod 示例最精简的 PVC 可省略storageClassName自动使用默认存储类apiVersion: v1 kind: PersistentVolumeClaim metadata: name: my-pvc spec: accessModes: - ReadWriteOnce resources: requests: storage: 1Gi把它放进完整 Pod 中使用apiVersion: v1 kind: Pod metadata: name: nginx spec: volumes: - name: www persistentVolumeClaim: claimName: my-pvc containers: - name: nginx image: k8s.gcr.io/nginx-slim:0.8 ports: - containerPort: 80 name: web volumeMounts: - name: www mountPath: /usr/share/nginx/html注意事项PVC 必须与使用它的 Pod 位于同一命名空间Kubernetes 根据 PVC 找到匹配的 PV 并挂载到mountPath关于storageClassName的更多语义可参考 Kubernetes 官方 Persistent Volumes 文档中的 Class 一节关于 PVC 的更多细节可查阅 PersistentVolumeClaims 章节。以上概念同时适用于 ClickHouse Pod——例如 ClickHouse 的默认数据目录/var/lib/clickhouse通常就应挂载持久卷。五、StatefulSetvolumeClaimTemplates 的快捷方式StatefulSet为有状态应用提供了一种更简捷的持久化方式省略volumes直接从volumeMounts跳到volumeClaimTemplates。每个 Pod 副本会自动获得一个由模板生成的独立 PVC命名规则为volumeClaimTemplate-name-statefulset-name-ordinal。标准示例apiVersion: v1 kind: Service metadata: name: nginx labels: app: nginx spec: ports: - port: 80 name: web clusterIP: None selector: app: nginx --- apiVersion: apps/v1 kind: StatefulSet metadata: name: web spec: serviceName: nginx replicas: 2 selector: matchLabels: app: nginx template: metadata: labels: app: nginx spec: containers: - name: nginx image: k8s.gcr.io/nginx-slim:0.8 ports: - containerPort: 80 name: web volumeMounts: - name: www mountPath: /usr/share/nginx/html volumeClaimTemplates: - metadata: name: www spec: accessModes: [ ReadWriteOnce ] resources: requests: storage: 1Gi注意.spec.template.spec.containers.volumeMounts直接引用volumeClaimTemplates的metadata.namevolumeMounts: - name: www mountPath: /usr/share/nginx/htmlvolumeClaimTemplates: - metadata: name: www spec: accessModes: [ ReadWriteOnce ] resources: requests: storage: 1GiClickHouse Operator 的对应物Operator 内部正是围绕这一机制建模的。CHI CRD 中的VolumeClaimTemplate结构定义见 type_volume_claim_template.go封装了Name与标准 KubernetesPersistentVolumeClaimSpec并附带PVCProvisionerStatefulSet/Operator两种取值与PVCReclaimPolicyRetain/Delete两个管理字段同文件 type_volume_claim_template.go、type_volume_claim_template.go。也就是说Operator 会把你在 CHI 中声明的卷模板翻译为 StatefulSet 的volumeClaimTemplates由 StatefulSet 为每个 ClickHouse Pod 生成专属 PVC。六、AWS 加密卷基于 gp2 的 encrypted-gp2默认的gp2卷不加密。要使用加密卷需要先定义一个带encrypted: true参数的专用StorageClassapiVersion: storage.k8s.io/v1 kind: StorageClass metadata: name: encrypted-gp2 provisioner: kubernetes.io/aws-ebs parameters: type: gp2 fsType: ext4 encrypted: true reclaimPolicy: Delete volumeBindingMode: Immediate再在 PVC 中引用它apiVersion: v1 kind: PersistentVolumeClaim metadata: name: encrypted-pvc spec: storageClassName: encrypted-gp2 accessModes: - ReadWriteOnce volumeMode: Block resources: requests: storage: 1Gi要点加密参数位于StorageClass.parameters中对使用该存储类的所有 PVC 生效该示例还展示了volumeMode: Block——以块设备而非文件系统方式消费卷适用于 ClickHouse 对块设备有特殊性能要求的场景对于更复杂的 ClickHouse 加密与安全需求可参考仓库中的 21-secure-cluster-secret 系列示例 与 22-secure-ssl 系列示例。七、ClickHouse Operator 实战在 CHI 中声明持久卷以上 Kubernetes 原语最终要落到 ClickHouse Operator 的ClickHouseInstallationCHI自定义资源中。CHI 通过spec.templates.volumeClaimTemplates定义卷模板并在 Pod 模板或defaults中引用。7.1 方式一defaults 中声明数据卷与日志卷03-persistent-volume-01-default-volume.yaml 展示了最简洁的用法——通过defaults.templates全局指定数据卷与日志卷apiVersion: clickhouse.altinity.com/v1 kind: ClickHouseInstallation metadata: name: pv-simple spec: defaults: templates: dataVolumeClaimTemplate:>apiVersion: clickhouse.altinity.com/v1 kind: ClickHouseInstallation metadata: name: pv-log spec: configuration: clusters: - name: deployment-pv # Templates are specified for this cluster explicitly templates: podTemplate: pod-template-with-volumes layout: shardsCount: 2 replicasCount: 2 templates: podTemplates: - name: pod-template-with-volumes spec: containers: - name: clickhouse image: clickhouse/clickhouse-server:24.8 volumeMounts: - name:>apiVersion: clickhouse.altinity.com/v1 kind: ClickHouseInstallation metadata: name: repl-03 spec: configuration: zookeeper: nodes: - host: zookeeper.zoo1ns port: 2181 clusters: - name: replcluster templates: podTemplate: clickhouse-with-volume-template layout: shardsCount: 1 replicasCount: 2 templates: podTemplates: - name: clickhouse-with-volume-template spec: containers: - name: clickhouse-pod image: clickhouse/clickhouse-server:24.8 volumeMounts: - name: clickhouse-storage-template mountPath: /var/lib/clickhouse volumeClaimTemplates: - name: clickhouse-storage-template spec: # no storageClassName - means use default storageClassName #storageClassName: default accessModes: - ReadWriteOnce resources: requests: storage: 50Gi而 04-replication-zookeeper-04-medium-AWS-persistent-volume.yaml 则把 Zookeeper 扩展为 3 节点数据卷调整为 900Mi适合中等规模验证apiVersion: clickhouse.altinity.com/v1 kind: ClickHouseInstallation metadata: name: repl-04 spec: configuration: zookeeper: nodes: - host: zookeeper-0.zookeepers.zoo3ns port: 2181 - host: zookeeper-1.zookeepers.zoo3ns port: 2181 - host: zookeeper-2.zookeepers.zoo3ns port: 2181 clusters: - name: replcluster templates: podTemplate: clickhouse-with-volume-template layout: shardsCount: 1 replicasCount: 2 templates: podTemplates: - name: clickhouse-with-volume-template spec: containers: - name: clickhouse-pod image: clickhouse/clickhouse-server:24.8 volumeMounts: - name: clickhouse-storage-template mountPath: /var/lib/clickhouse volumeClaimTemplates: - name: clickhouse-storage-template spec: # no storageClassName - means use default storageClassName #storageClassName: default accessModes: - ReadWriteOnce resources: requests: storage: 900Mi要点配置中刻意注释掉了storageClassName: default意在提醒读者省略该字段即使用集群默认存储类复制表ReplicatedMergeTree 等依赖 Zookeeper 协调而每个副本的本地数据则落在各自的 PVC 上——这正是存储与复制两类能力的组合使用方式完整的复制与 Zookeeper 配置方法可参考 replication_setup.md 与 zookeeper_setup.md。7.4 进阶storageManagement 与 PVC 生命周期管理除spec之外CHI 的卷模板还支持storageManagement字段用于控制 PVC 的供给方式与回收策略。在 99-clickhouseinstallation-max.yaml 的defaults中有完整示范defaults: replicasUseFQDN: no distributedDDL: profile: default storageManagement: # Specify PVC provisioner. # 1. StatefulSet. PVC would be provisioned by the StatefulSet # 2. Operator. PVC would be provisioned by the operator provisioner: StatefulSet # Specify PVC reclaim policy. # 1. Retain. Keep PVC from being deleted # Retaining PVC will also keep backing PV from deletion. This is useful in case we need to keep data intact. # 2. Delete reclaimPolicy: Retain对应到源码type_storage_management.goprovisioner取值StatefulSet或Operator。StatefulSet表示 PVC 由 StatefulSet 控制器自动创建Operator表示由 Operator 自行创建并管理 PVC合法取值定义见 type_volume_claim_template.goreclaimPolicy取值Retain或Delete。Retain在删除 PVC 时保留数据底层 PV 也不会被回收适合需要保护数据完整性的生产场景Delete则随 PVC 删除一并回收合法取值见 type_volume_claim_template.go。StorageManagement支持从默认值到具体集群的逐级合并MergeFrom逻辑见 type_storage_management.go即defaults中设置的provisioner/reclaimPolicy可被更下层的集群或模板覆盖实现默认一致、个别定制的管理模式。八、示例索引与延伸阅读8.1 本文涉及的示例文件示例相对路径核心看点默认数据/日志卷03-persistent-volume-01-default-volume.yamldefaults.templates全局指定 data/log 卷模板Pod 模板挂多卷03-persistent-volume-02-pod-template.yamlvolumeMounts与volumeClaimTemplates关联2×2 集群AWS 最小复制 PV04-replication-zookeeper-03-minimal-AWS-persistent-volume.yaml1×2 复制、单 Zookeeper、50Gi 数据卷AWS 中等复制 PV04-replication-zookeeper-04-medium-AWS-persistent-volume.yaml1×2 复制、3 节点 Zookeeper、900Mi 数据卷全量字段参考99-clickhouseinstallation-max.yamlstorageManagement完整字段与注释8.2 更多存储相关示例与文档存储体系进阶storage.md 的配套示例均在 docs/chi-examples 目录可按编号阅读03-persistent-volume-03-custom-labels-and-annotations.yaml自定义标签与注解03-persistent-volume-04-encrypted-volume.yaml加密卷03-persistent-volume-05-resizeable-volume-1.yaml 与 03-persistent-volume-05-resizeable-volume-2.yaml卷扩容03-persistent-volume-06-add-log-volume-1.yaml 与 03-persistent-volume-06-add-log-volume-2.yaml为运行中的集群新增日志卷03-persistent-volume-07-multiple-resizable-volumes-1.yaml 至 03-persistent-volume-07-multiple-resizable-volumes-3.yaml多卷可扩容组合03-persistent-volume-08-tiered-s3.yamlS3 分层存储03-persistent-volume-09-with-template-emptydir.yamlemptyDir 模板03-persistent-volume-10-log-volume-local.yaml本地日志卷相关文档operator_configuration.mdOperator 全局配置含存储相关默认值custom_resource_explained.mdCHI 自定义资源逐字段讲解replication_setup.md / zookeeper_setup.md复制与协调服务配置deploy/openebs/lvm/README基于 OpenEBS LVM 的本地存储方案含 clickhouse-installation-with-openebs.yaml 示例源码参考CRD 卷模板结构type_volume_claim_template.godata/log 卷模板字段与废弃兼容type_templates_list.go存储管理合并逻辑type_storage_management.go模板应用与 PVC 资源请求合并volumeClaimTemplate.go总结本文完整覆盖了 ClickHouse Operator 持久化存储的完整链路从 Kubernetes 的PersistentVolume/PersistentVolumeClaim/StorageClass基础概念到storageClassName三态语义、AWS gp2 与加密卷实战再到 CHI 中通过volumeClaimTemplates声明数据卷与日志卷、通过storageManagement控制 PVC 供给与回收。实际部署时推荐从 03-persistent-volume-01-default-volume.yaml 起步验证默认存储再按需升级为 Pod 模板多卷、加密卷或复制 持久卷组合。唯一需要记住的原则是省略storageClassName即使用集群默认存储类显式指定则精确控制存储后端——这一选择直接决定了 ClickHouse 数据卷的最终落盘位置。【免费下载链接】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），仅供参考