拓冰网站定制 
Coroot 使用指南为 ClickHouse 配置 S3 对象存储Tiered 与 S3-only 双模式【免费下载链接】corootCoroot is an open-source observability and APM tool with AI-powered Root Cause Analysis. It combines metrics, logs, traces, continuous profiling, and SLO-based alerting with predefined dashboards and inspections.项目地址: https://gitcode.com/GitHub_Trending/co/corootCoroot 使用 ClickHouse 存储日志Logs、链路Traces、性能剖析Profiles与可选指标Metrics默认情况下这些遥测数据全部落在本地磁盘上。本文基于 Using S3 Storage with ClickHouse 指南完整讲解如何通过 Coroot Kubernetes Operator 为 ClickHouse 接入 S3 兼容对象存储实现热数据本地、冷数据上云的分层存储架构。读完本文你将掌握 Tiered 与 S3-only 两种模式的配置方法、凭证注入方式、底层数据隔离与缓存原理以及一套可复用的故障排查 SQL。为什么要把 ClickHouse 数据放到 S3默认部署下ClickHouse 把全部遥测数据写入本地持久卷。启用 S3 对象存储后可以带来三方面收益降低存储成本把历史冷数据迁移到更便宜的对象存储本地只保留高性价比的 SSD存储与计算独立伸缩扩容存储只需扩大对象存储容量无需反复调整 PVC 大小、迁移数据突破本地磁盘容量限制可以保存更长周期的数据不再受单机本地盘容量约束。需要注意的是S3 存储面向的是由 Operator 托管的 ClickHouse 集群部署在 Kubernetes 上不是 Coroot 外部连接的外部 ClickHouseexternalClickhouse配置。两种 S3 存储模式Coroot Operator 支持两种 S3 存储模式按业务对查询性能与成本的取舍进行选择模式工作方式适用场景Tiered分层近期数据保存在本地 SSD本地磁盘空间不足时自动把最旧的数据移动到 S3对近期数据查询性能要求高同时希望长期数据低成本留存官方推荐S3-only纯 S3所有数据直接写入 S3本地磁盘仅用作读缓存与临时合并操作本地存储要求极低、追求极致成本优化的场景两种模式可以在同一份CorootCustom ResourceCR中配置只需切换mode字段并调整cacheSize与storage.size即可。前置条件开始之前需要确认以下条件已满足Coroot 已通过 Kubernetes Operator 部署Operator 负责创建和管理 ClickHouse StatefulSet拥有一个 S3 兼容的存储桶例如 AWS S3、MinIO、Ceph RGW 等具备 S3 凭证Access Key Secret Key或集群已配置 IAM Roles for Service AccountsIRSA/ Workload Identity。Step 1创建专用的 S3 存储桶为 ClickHouse 数据创建专用bucket不要与其他应用共用。ClickHouse 自己管理对象文件的生命周期外部的生命周期策略如自动过期删除可能导致数据丢失。aws s3 mb s3://my-coroot-clickhouse --region us-east-1使用 MinIO 等自建存储时可通过其管理控制台或mc mb命令创建对应 bucket。Step 2创建凭证 Secret用kubectl在 Coroot 所在命名空间创建静态凭证 Secret字段名需要与 CR 中的引用保持一致kubectl create secret generic clickhouse-s3-creds \ --from-literalaccess_key_idYOUR_ACCESS_KEY \ --from-literalsecret_access_keyYOUR_SECRET_KEY \ -n coroot:::tip 如果集群使用了IAM Roles for Service AccountsIRSA或Workload Identity可以完全跳过 Secret 的创建并在 CR 中省略credentials段落。此时 ClickHouse 会自动从环境变量与实例元数据服务中解析凭证。 :::Step 3在 Coroot CR 中配置 S3在 Coroot 自定义资源的spec.clickhouse下增加s3段落。下面是 Operator 支持的完整参数说明对应 k8s-operator.md 中clickhouse段落的注释定义参数默认值说明endpoint—S3 端点 URL若结尾缺少/会自动补齐region—S3 区域可选credentials.accessKeyId—Access Key 的 Secret 引用name keycredentials.secretAccessKey—Secret Key 的 Secret 引用name keycacheSize10Gi本地用于缓存 S3 读取的磁盘空间必须小于storage.sizemodetiered存储模式tiered或s3onlymoveFactor0.1Tiered 模式下本地磁盘可用空间低于总容量该比例时触发数据搬迁Tiered 模式推荐apiVersion: coroot.com/v1 kind: Coroot metadata: name: coroot namespace: coroot spec: communityEdition: nodeAgent: clusterAgent: clickhouse: shards: 1 replicas: 2 storage: size: 100Gi # local disk per replica s3: endpoint: https://s3.us-east-1.amazonaws.com/my-coroot-clickhouse/ region: us-east-1 credentials: accessKeyId: name: clickhouse-s3-creds key: access_key_id secretAccessKey: name: clickhouse-s3-creds key: secret_access_key cacheSize: 10Gi # local cache for S3 reads mode: tiered moveFactor: 0.1 # move data to S3 when 10% free space以上面 100Gi 本地盘为例ClickHouse 会在本地磁盘可用空间低于约 10Gi即moveFactor 0.1时自动把最旧的数据部分parts搬迁到 S3从而把本地占用控制在一个稳定的水位。整个搬迁由 ClickHouse 自身透明完成无需修改任何表的 TTL 配置保留策略TTL 周期内的数据都会被完整保留在 S3 上而不是被删除。S3-only 模式所有数据直接落 S3本地磁盘只承担读缓存与临时合并merge工作s3: endpoint: https://s3.us-east-1.amazonaws.com/my-coroot-clickhouse/ region: us-east-1 credentials: accessKeyId: name: clickhouse-s3-creds key: access_key_id secretAccessKey: name: clickhouse-s3-creds key: secret_access_key cacheSize: 20Gi # larger cache recommended for s3only mode mode: s3onlyS3-only 模式下可以放心缩小storage.size本地盘仅用于缓存与临时操作但建议同步调大cacheSize以缓解读放大官方示例给出 20Gi。Step 4应用配置kubectl apply -f coroot.yamlOperator 会监听 CR 变更将 S3 存储配置写入 ClickHouse StatefulSet随后滚动重启 ClickHouse Pod 使新配置生效。变更期间 ClickHouse 会短暂不可用属正常现象。工作原理数据隔离每个 Shard / Replica 独立的 S3 路径为避免多副本并发写同一批 S3 对象造成数据损坏每个 ClickHouse shard 与 replica 都使用独立的 S3 路径前缀路径遵循以下模式s3://my-coroot-clickhouse/{shard}/{replica}/以 2 shard × 2 replica 为例实际路径为s3://my-coroot-clickhouse/shard-0/coroot-clickhouse-shard-0-0/s3://my-coroot-clickhouse/shard-0/coroot-clickhouse-shard-0-1/s3://my-coroot-clickhouse/shard-1/coroot-clickhouse-shard-1-1/s3://my-coroot-clickhouse/shard-1/coroot-clickhouse-shard-1-1/ClickHouse 虽然提供 zero-copy replication零拷贝复制特性让副本共享 S3 对象但该特性自22.8 版本起默认关闭且仍处于实验阶段存在已知的数据损坏风险见 ClickHouse 官方 issue #45346。因此 Operator 会显式禁用该特性坚持每副本独立路径保证数据安全。本地缓存层ClickHouse 与 S3 之间有一层本地磁盘缓存频繁访问的数据会被缓存在本地显著降低 S3 API 调用次数与读取延迟同时缓存支持写入时预填充cache_on_write_operations新写入的数据立即可从缓存命中。这也是cacheSize参数存在的意义——它决定了这个缓存层能占用的本地磁盘上限。Space Manager 自动禁用启用 S3 后Coroot 的 Space Manager 会被自动禁用逻辑可以在 clickhouse/space_manager.go 中找到Coroot 通过system.disks读取磁盘信息一旦检测到存在type ObjectStorage的磁盘便打印storage manager is disabled for ClickHouse on S3并跳过清理逻辑。原因很清晰Space Manager 的职责是在磁盘写满时删除最旧分区来释放空间见 space_manager.go仅针对otel_%与profiling_%表执行ALTER TABLE ... DROP PARTITION而启用 S3 后磁盘压力由 ClickHouse 通过把数据搬到 S3来解决数据得以保留完整的 TTL 周期不再需要以牺牲数据为代价换取可用空间。这与 ClickHouse Cloud 场景下 Space Manager 自动禁用的处理方式一致。使用 MinIO 或其他 S3 兼容存储任意 S3 兼容存储MinIO、Ceph RGW、SeaweedFS 等都可以接入只需把endpoint指向你的存储服务地址s3: endpoint: https://minio.example.com/coroot-clickhouse/ credentials: accessKeyId: name: minio-creds key: access_key_id secretAccessKey: name: minio-creds key: secret_access_key注意endpoint需要包含 bucket 前缀路径如https://minio.example.com/coroot-clickhouse/凭证 Secret 的创建方式与 Step 2 完全一致。故障排查1. 验证 S3 磁盘已生效进入 ClickHouse Pod 执行kubectl exec -it clickhouse-pod -- clickhouse-clientSELECT name, path, type, free_space, total_space FROM system.disks预期输出中除了Local默认磁盘外还应看到类型为ObjectStorage的s3_disk与s3_cache两块磁盘。其中 S3 磁盘的free_space/total_space通常是一个极大的哨兵值math.MaxUint64Coroot 在读取时会将其归一化为 0见 clickhouse.go 的处理逻辑这一点在核对输出时需要注意。2. 验证存储策略SELECT * FROM system.storage_policies根据mode的不同可以看到名为s3_tiered或s3_s3only的策略。3. 检查数据在磁盘间的分布SELECT disk_name, sum(bytes_on_disk) as bytes FROM system.parts WHERE active 1 GROUP BY disk_name该查询可以直观看到本地盘与 S3 上分别承载了多少活跃数据。Tiered 模式下随着时间推移s3_disk上的字节数应持续增长、本地磁盘占用保持在水位附近这正是分层存储按预期工作的信号。常见注意事项bucket 专用不要为 ClickHouse 配置外部对象生命周期删除策略ClickHouse 自行管理对象生命周期cacheSize 约束本地缓存不能超过 ClickHouse 本地盘容量cacheSize storage.size否则配置无效空间回收预期Tiered 模式下数据搬迁是渐进式的只有本地可用空间低于moveFactor阈值后才会触发搬迁动作无需人工干预Operator 升级调整 S3 配置后如果 ClickHouse Pod 未按预期重启可检查 Operator 日志与 CR 状态必要时执行kubectl rollout status观察 StatefulSet 滚动进度。至此Coroot 的 ClickHouse 已经从单机本地盘演进为热冷分层的弹性存储架构近期遥测数据以全速查询历史数据以极低成本长期留存而这一切只需一份 CR 配置即可完成。【免费下载链接】corootCoroot is an open-source observability and APM tool with AI-powered Root Cause Analysis. It combines metrics, logs, traces, continuous profiling, and SLO-based alerting with predefined dashboards and inspections.项目地址: https://gitcode.com/GitHub_Trending/co/coroot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Coroot 使用指南：为 ClickHouse 配置 S3 对象存储（Tiered 与 S3-only 双模式）
Coroot 使用指南为 ClickHouse 配置 S3 对象存储Tiered 与 S3-only 双模式【免费下载链接】corootCoroot is an open-source observability and APM tool with AI-powered Root Cause Analysis. It combines metrics, logs, traces, continuous profiling, and SLO-based alerting with predefined dashboards and inspections.项目地址: https://gitcode.com/GitHub_Trending/co/corootCoroot 使用 ClickHouse 存储日志Logs、链路Traces、性能剖析Profiles与可选指标Metrics默认情况下这些遥测数据全部落在本地磁盘上。本文基于 Using S3 Storage with ClickHouse 指南完整讲解如何通过 Coroot Kubernetes Operator 为 ClickHouse 接入 S3 兼容对象存储实现热数据本地、冷数据上云的分层存储架构。读完本文你将掌握 Tiered 与 S3-only 两种模式的配置方法、凭证注入方式、底层数据隔离与缓存原理以及一套可复用的故障排查 SQL。为什么要把 ClickHouse 数据放到 S3默认部署下ClickHouse 把全部遥测数据写入本地持久卷。启用 S3 对象存储后可以带来三方面收益降低存储成本把历史冷数据迁移到更便宜的对象存储本地只保留高性价比的 SSD存储与计算独立伸缩扩容存储只需扩大对象存储容量无需反复调整 PVC 大小、迁移数据突破本地磁盘容量限制可以保存更长周期的数据不再受单机本地盘容量约束。需要注意的是S3 存储面向的是由 Operator 托管的 ClickHouse 集群部署在 Kubernetes 上不是 Coroot 外部连接的外部 ClickHouseexternalClickhouse配置。两种 S3 存储模式Coroot Operator 支持两种 S3 存储模式按业务对查询性能与成本的取舍进行选择模式工作方式适用场景Tiered分层近期数据保存在本地 SSD本地磁盘空间不足时自动把最旧的数据移动到 S3对近期数据查询性能要求高同时希望长期数据低成本留存官方推荐S3-only纯 S3所有数据直接写入 S3本地磁盘仅用作读缓存与临时合并操作本地存储要求极低、追求极致成本优化的场景两种模式可以在同一份CorootCustom ResourceCR中配置只需切换mode字段并调整cacheSize与storage.size即可。前置条件开始之前需要确认以下条件已满足Coroot 已通过 Kubernetes Operator 部署Operator 负责创建和管理 ClickHouse StatefulSet拥有一个 S3 兼容的存储桶例如 AWS S3、MinIO、Ceph RGW 等具备 S3 凭证Access Key Secret Key或集群已配置 IAM Roles for Service AccountsIRSA/ Workload Identity。Step 1创建专用的 S3 存储桶为 ClickHouse 数据创建专用bucket不要与其他应用共用。ClickHouse 自己管理对象文件的生命周期外部的生命周期策略如自动过期删除可能导致数据丢失。aws s3 mb s3://my-coroot-clickhouse --region us-east-1使用 MinIO 等自建存储时可通过其管理控制台或mc mb命令创建对应 bucket。Step 2创建凭证 Secret用kubectl在 Coroot 所在命名空间创建静态凭证 Secret字段名需要与 CR 中的引用保持一致kubectl create secret generic clickhouse-s3-creds \ --from-literalaccess_key_idYOUR_ACCESS_KEY \ --from-literalsecret_access_keyYOUR_SECRET_KEY \ -n coroot:::tip 如果集群使用了IAM Roles for Service AccountsIRSA或Workload Identity可以完全跳过 Secret 的创建并在 CR 中省略credentials段落。此时 ClickHouse 会自动从环境变量与实例元数据服务中解析凭证。 :::Step 3在 Coroot CR 中配置 S3在 Coroot 自定义资源的spec.clickhouse下增加s3段落。下面是 Operator 支持的完整参数说明对应 k8s-operator.md 中clickhouse段落的注释定义参数默认值说明endpoint—S3 端点 URL若结尾缺少/会自动补齐region—S3 区域可选credentials.accessKeyId—Access Key 的 Secret 引用name keycredentials.secretAccessKey—Secret Key 的 Secret 引用name keycacheSize10Gi本地用于缓存 S3 读取的磁盘空间必须小于storage.sizemodetiered存储模式tiered或s3onlymoveFactor0.1Tiered 模式下本地磁盘可用空间低于总容量该比例时触发数据搬迁Tiered 模式推荐apiVersion: coroot.com/v1 kind: Coroot metadata: name: coroot namespace: coroot spec: communityEdition: nodeAgent: clusterAgent: clickhouse: shards: 1 replicas: 2 storage: size: 100Gi # local disk per replica s3: endpoint: https://s3.us-east-1.amazonaws.com/my-coroot-clickhouse/ region: us-east-1 credentials: accessKeyId: name: clickhouse-s3-creds key: access_key_id secretAccessKey: name: clickhouse-s3-creds key: secret_access_key cacheSize: 10Gi # local cache for S3 reads mode: tiered moveFactor: 0.1 # move data to S3 when 10% free space以上面 100Gi 本地盘为例ClickHouse 会在本地磁盘可用空间低于约 10Gi即moveFactor 0.1时自动把最旧的数据部分parts搬迁到 S3从而把本地占用控制在一个稳定的水位。整个搬迁由 ClickHouse 自身透明完成无需修改任何表的 TTL 配置保留策略TTL 周期内的数据都会被完整保留在 S3 上而不是被删除。S3-only 模式所有数据直接落 S3本地磁盘只承担读缓存与临时合并merge工作s3: endpoint: https://s3.us-east-1.amazonaws.com/my-coroot-clickhouse/ region: us-east-1 credentials: accessKeyId: name: clickhouse-s3-creds key: access_key_id secretAccessKey: name: clickhouse-s3-creds key: secret_access_key cacheSize: 20Gi # larger cache recommended for s3only mode mode: s3onlyS3-only 模式下可以放心缩小storage.size本地盘仅用于缓存与临时操作但建议同步调大cacheSize以缓解读放大官方示例给出 20Gi。Step 4应用配置kubectl apply -f coroot.yamlOperator 会监听 CR 变更将 S3 存储配置写入 ClickHouse StatefulSet随后滚动重启 ClickHouse Pod 使新配置生效。变更期间 ClickHouse 会短暂不可用属正常现象。工作原理数据隔离每个 Shard / Replica 独立的 S3 路径为避免多副本并发写同一批 S3 对象造成数据损坏每个 ClickHouse shard 与 replica 都使用独立的 S3 路径前缀路径遵循以下模式s3://my-coroot-clickhouse/{shard}/{replica}/以 2 shard × 2 replica 为例实际路径为s3://my-coroot-clickhouse/shard-0/coroot-clickhouse-shard-0-0/s3://my-coroot-clickhouse/shard-0/coroot-clickhouse-shard-0-1/s3://my-coroot-clickhouse/shard-1/coroot-clickhouse-shard-1-1/s3://my-coroot-clickhouse/shard-1/coroot-clickhouse-shard-1-1/ClickHouse 虽然提供 zero-copy replication零拷贝复制特性让副本共享 S3 对象但该特性自22.8 版本起默认关闭且仍处于实验阶段存在已知的数据损坏风险见 ClickHouse 官方 issue #45346。因此 Operator 会显式禁用该特性坚持每副本独立路径保证数据安全。本地缓存层ClickHouse 与 S3 之间有一层本地磁盘缓存频繁访问的数据会被缓存在本地显著降低 S3 API 调用次数与读取延迟同时缓存支持写入时预填充cache_on_write_operations新写入的数据立即可从缓存命中。这也是cacheSize参数存在的意义——它决定了这个缓存层能占用的本地磁盘上限。Space Manager 自动禁用启用 S3 后Coroot 的 Space Manager 会被自动禁用逻辑可以在 clickhouse/space_manager.go 中找到Coroot 通过system.disks读取磁盘信息一旦检测到存在type ObjectStorage的磁盘便打印storage manager is disabled for ClickHouse on S3并跳过清理逻辑。原因很清晰Space Manager 的职责是在磁盘写满时删除最旧分区来释放空间见 space_manager.go仅针对otel_%与profiling_%表执行ALTER TABLE ... DROP PARTITION而启用 S3 后磁盘压力由 ClickHouse 通过把数据搬到 S3来解决数据得以保留完整的 TTL 周期不再需要以牺牲数据为代价换取可用空间。这与 ClickHouse Cloud 场景下 Space Manager 自动禁用的处理方式一致。使用 MinIO 或其他 S3 兼容存储任意 S3 兼容存储MinIO、Ceph RGW、SeaweedFS 等都可以接入只需把endpoint指向你的存储服务地址s3: endpoint: https://minio.example.com/coroot-clickhouse/ credentials: accessKeyId: name: minio-creds key: access_key_id secretAccessKey: name: minio-creds key: secret_access_key注意endpoint需要包含 bucket 前缀路径如https://minio.example.com/coroot-clickhouse/凭证 Secret 的创建方式与 Step 2 完全一致。故障排查1. 验证 S3 磁盘已生效进入 ClickHouse Pod 执行kubectl exec -it clickhouse-pod -- clickhouse-clientSELECT name, path, type, free_space, total_space FROM system.disks预期输出中除了Local默认磁盘外还应看到类型为ObjectStorage的s3_disk与s3_cache两块磁盘。其中 S3 磁盘的free_space/total_space通常是一个极大的哨兵值math.MaxUint64Coroot 在读取时会将其归一化为 0见 clickhouse.go 的处理逻辑这一点在核对输出时需要注意。2. 验证存储策略SELECT * FROM system.storage_policies根据mode的不同可以看到名为s3_tiered或s3_s3only的策略。3. 检查数据在磁盘间的分布SELECT disk_name, sum(bytes_on_disk) as bytes FROM system.parts WHERE active 1 GROUP BY disk_name该查询可以直观看到本地盘与 S3 上分别承载了多少活跃数据。Tiered 模式下随着时间推移s3_disk上的字节数应持续增长、本地磁盘占用保持在水位附近这正是分层存储按预期工作的信号。常见注意事项bucket 专用不要为 ClickHouse 配置外部对象生命周期删除策略ClickHouse 自行管理对象生命周期cacheSize 约束本地缓存不能超过 ClickHouse 本地盘容量cacheSize storage.size否则配置无效空间回收预期Tiered 模式下数据搬迁是渐进式的只有本地可用空间低于moveFactor阈值后才会触发搬迁动作无需人工干预Operator 升级调整 S3 配置后如果 ClickHouse Pod 未按预期重启可检查 Operator 日志与 CR 状态必要时执行kubectl rollout status观察 StatefulSet 滚动进度。至此Coroot 的 ClickHouse 已经从单机本地盘演进为热冷分层的弹性存储架构近期遥测数据以全速查询历史数据以极低成本长期留存而这一切只需一份 CR 配置即可完成。【免费下载链接】corootCoroot is an open-source observability and APM tool with AI-powered Root Cause Analysis. It combines metrics, logs, traces, continuous profiling, and SLO-based alerting with predefined dashboards and inspections.项目地址: https://gitcode.com/GitHub_Trending/co/coroot创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考