What is the best way to run ClickHouse on Kubernetes?

The recommended approach is to use the Altinity ClickHouse Operator (altinity/clickhouse-operator), which is the most mature and widely adopted Kubernetes operator for ClickHouse. It manages the full lifecycle of ClickHouse clusters including provisioning, scaling, schema management, and upgrades via ClickHouseInstallation custom resources. For simpler setups, Helm charts provide a quick start, but the operator is strongly recommended for production workloads because it handles shard and replica topology, ZooKeeper/ClickHouse Keeper coordination, and rolling updates automatically.

How does sharding and replication work for ClickHouse on Kubernetes?

ClickHouse on Kubernetes uses a sharded, replicated architecture defined declaratively in the ClickHouseInstallation custom resource. Each shard is a group of replicas that hold the same data, while data is distributed across shards using a sharding key. The Altinity Operator creates StatefulSets for each shard-replica combination and manages the underlying ZooKeeper or ClickHouse Keeper ensemble for replica coordination. Distributed tables route queries across all shards, and ReplicatedMergeTree engine handles automatic data replication within each shard.

What storage configuration is recommended for ClickHouse on Kubernetes?

ClickHouse is I/O intensive and benefits from high-throughput, low-latency storage. On cloud providers, use provisioned IOPS SSD volumes (gp3/io2 on AWS, pd-ssd on GCP, Premium SSD on Azure) via CSI drivers. Configure StorageClasses with volumeBindingMode: WaitForFirstConsumer for topology-aware scheduling. ClickHouse supports tiered storage policies, so you can define hot/warm/cold tiers using local NVMe for hot data and S3-compatible object storage for cold data, all configured through ClickHouse storage policies in the operator's custom resource.

How do backups work for ClickHouse running on Kubernetes?

The standard tool for ClickHouse backups on Kubernetes is clickhouse-backup, which can be deployed as a sidecar container alongside each ClickHouse pod. It supports full and incremental backups to S3, GCS, Azure Blob Storage, and other S3-compatible stores. The Altinity Operator can integrate backup schedules into the ClickHouseInstallation resource. Backups capture table schemas, data parts, and access control objects. For disaster recovery, we configure automated backup schedules, retention policies, and regularly validate restore procedures to meet your RPO and RTO targets.

How do you monitor ClickHouse on Kubernetes?

ClickHouse exposes rich observability through its system tables (system.metrics, system.events, system.query_log, system.parts). On Kubernetes, we deploy Prometheus with a ClickHouse exporter or the built-in Prometheus endpoint to scrape metrics, paired with purpose-built Grafana dashboards for query performance, merge operations, replication lag, and resource utilization. The Altinity Operator supports Prometheus ServiceMonitor integration out of the box. Alertmanager rules cover critical conditions like replication queue growth, high merge backlogs, and storage utilization thresholds.

Can ClickHouse on Kubernetes handle petabyte-scale analytics workloads?

Yes. ClickHouse is designed for petabyte-scale analytics and its columnar storage with aggressive compression achieves 10-40x compression ratios, significantly reducing storage costs. On Kubernetes, you scale horizontally by adding shards to distribute data across more nodes, and vertically by adjusting CPU and memory resources per pod. ClickHouse's vectorized query execution and SIMD optimizations deliver sub-second query performance even on large datasets. Companies like Uber, Cloudflare, and eBay run ClickHouse at petabyte scale, and Kubernetes operators make scaling operations declarative and automated.

ClickHouse on Kubernetes | Altinity & Operator

ClickHouse on Kubernetes

In short: Running ClickHouse on Kubernetes means using the Altinity ClickHouse Operator to define sharded, replicated clusters via ClickHouseInstallation custom resources, which it materializes as StatefulSets with PersistentVolumeClaims and tiered storage. It coordinates replicas through ZooKeeper or ClickHouse Keeper and automates rolling upgrades, backups, and Prometheus monitoring.

Deploy production-grade ClickHouse on Kubernetes with the Altinity Operator, sharded clusters, columnar storage optimization, and cloud-native scaling for real-time analytics at petabyte scale.

Get Started Today Explore Services

Executive Direct Answer · ClickHouse Kubernetes Engineering Heuristic

JusDB delivers enterprise ClickHouse on Kubernetes engineering utilizing the Altinity operator and official cloud-native patterns. Certified Database Reliability Engineers architect multi-pod Keeper consensus, configure local NVMe persistent volumes, orchestrate zero-downtime rolling stateful upgrades, and automate Prometheus and Grafana observability pipelines backed by contractual 15-minute Sev-1 response SLAs and SOC 2 compliance.

Uptime: 99.99% Availability SLA·Operator: Altinity & Official Cloud-Native·Storage: Local NVMe & S3 Tiering·Failover: Sub-30s Automated Recovery·Compliance: ISO 27001 & SOC 2

Petabyte

Scale

Real-Time

Analytics

Column

Oriented

ClickHouse K8s Architecture

Altinity Operator

Custom Controller

Sharded Clusters

ClickHouse Pods

Columnar Storage

PVC / Tiered Storage

ClickHouse Keeper

Coordination Service

Cloud-Native, Operator-Managed OLAP Architecture

Services

Comprehensive ClickHouse on Kubernetes Services

From operator deployment to production monitoring, we provide end-to-end ClickHouse on Kubernetes solutions for cloud-native analytics environments.

ClickHouse Operator Deployment

Altinity ClickHouse Operator setup and configuration for automated ClickHouse lifecycle management on Kubernetes

Altinity ClickHouse Operator installation
ClickHouseInstallation CRD configuration
RBAC and namespace isolation
Operator upgrades and version management

Helm Chart Management

Chart customization, values tuning, and upgrade strategies for reproducible ClickHouse deployments

Helm chart customization and templating
Values file tuning for production
Chart version upgrade strategies
GitOps integration with ArgoCD / Flux

Sharded Cluster on K8s

Multi-shard, multi-replica ClickHouse clusters with ZooKeeper or ClickHouse Keeper coordination

Shard and replica topology design
ZooKeeper / ClickHouse Keeper setup
Distributed table configuration
Sharding key and partition strategy

Storage & Persistence

PVCs, StorageClasses, tiered storage policies, and volume optimization for ClickHouse columnar data

PVC and StorageClass configuration
CSI driver setup (EBS, PD, Ceph)
Hot/warm/cold tiered storage policies
S3-backed cold storage integration

Monitoring & Observability

System tables, Prometheus exporters, and Grafana dashboards for full ClickHouse observability on K8s

Prometheus exporter and ServiceMonitor
Grafana dashboard provisioning
system.query_log and system.parts analysis
Alertmanager rules for replication lag

Backup & Disaster Recovery

clickhouse-backup sidecar, S3 snapshots, and cross-region restore for ClickHouse data protection

clickhouse-backup sidecar deployment
S3-compatible snapshot storage
Scheduled and on-demand backups
Cross-region restore testing

Why Kubernetes

Why Run ClickHouse on Kubernetes?

Cloud-native ClickHouse with operator-managed lifecycle, horizontal sharding, columnar compression, and infrastructure-as-code for consistent, repeatable analytics deployments. To squeeze more from query and merge throughput, see our ClickHouse performance tuning service.

Cloud-Native OLAP

Run ClickHouse as a first-class Kubernetes workload with declarative configuration, self-healing, and seamless integration with your cloud-native infrastructure and CI/CD pipelines.

Operator-Managed Lifecycle

The Altinity ClickHouse Operator encodes expert knowledge into automated controllers that handle provisioning, shard topology, schema management, and rolling upgrades without manual intervention.

Columnar Compression

ClickHouse's column-oriented storage with LZ4, ZSTD, and Delta codecs achieves 10-40x compression ratios, dramatically reducing storage costs for large-scale analytics workloads on Kubernetes.

Horizontal Sharding

Scale ClickHouse horizontally by adding shards to distribute data across more nodes. The operator manages shard topology declaratively, and Distributed tables route queries across the cluster.

ClickHouse on K8s Key Metrics

Compression(Columnar codecs)

10-40x

Query Speed(Vectorized execution)

Sub-second

Scaling(Shard-based expansion)

Horizontal

Backup(clickhouse-backup to S3)

Automated

Self-Healing(Pod restart & failover)

Yes

GitOps Ready(ArgoCD / Flux compatible)

Yes

Delivery

Our ClickHouse on Kubernetes Implementation Process

A proven methodology for deploying production-ready ClickHouse on Kubernetes with comprehensive testing and validation. For data cutover from existing systems, see our ClickHouse migration service.

Assessment & Planning

Evaluate your analytics workload requirements, data volumes, query patterns, and Kubernetes environment. Design the shard/replica topology, storage tiers, and ClickHouse Keeper ensemble.

Operator & Cluster Setup

Deploy the Altinity ClickHouse Operator via Helm. Configure ClickHouseInstallation custom resources, StatefulSets, persistent volumes, ZooKeeper/Keeper, and security contexts.

Migration & Validation

Migrate data from existing ClickHouse or analytics systems, validate schema and Distributed tables, perform query benchmarking, and test backup/restore procedures under load.

Production & Operations

Go live with full monitoring, alerting, automated backups, and runbooks. Provide team training on operator management, day-2 operations, and ongoing optimization support.

Comparative Matrix · ClickHouse on Kubernetes

How JusDB DBRE Kubernetes Engineering compares to alternative approaches.

Operating ClickHouse on Kubernetes requires strict alignment of operator CRDs, Keeper Raft consensus, and NVMe persistent volume lifecycles. Here is how our certified DBRE methodology compares across core evaluation vectors:

Evaluation Vector	JusDB DBRE	In-House DBA	Legacy Agency	Developer Generalist
Operator Selection (Altinity vs Official vs Helm)	Production Altinity ClickHouse Operator architecture with customized ClickHouseInstallation CRDs, multi-cluster templates, automated schema synchronization, and battle-tested lifecycle controllers.	Generic community Helm chart deployments without operator reconciliation, requiring manual pod interventions during schema or topology mutations.	Naked StatefulSet manifests lacking ClickHouse lifecycle awareness, causing configuration drift and broken shard definitions across environments.	Monolithic container deployments on standalone pods without Kubernetes CRD abstractions or horizontal scaling controllers.
Multi-Pod ClickHouse Keeper Raft Consensus	Dedicated 3-pod or 5-pod Keeper StatefulSet deployed with strict pod anti-affinity, isolated local NVMe storage, and tuned raft log compaction to eliminate election deadlocks.	Keeper co-located on analytical compute worker pods; heavy analytical queries starve Keeper CPU and trigger false quorum loss failovers.	External legacy ZooKeeper deployment with heavy JVM memory footprints and uncontrolled GC pauses freezing cluster coordination.	Single Keeper replica without quorum redundancy; any single node restart halts all distributed DDL queries cluster-wide.
Local NVMe vs EBS Volume Topology & S3 Tiering	Hybrid multi-tier storage policies combining high-IOPS local NVMe for hot partitions with automated background TTL offloading to Amazon S3 or Google Cloud Storage.	Standard EBS gp3 volumes without tiering, resulting in runaway cloud storage costs and I/O credit throttling during analytical queries.	Network-attached NFS or shared block volumes causing severe latency spikes and ClickHouse part locking corruptions.	Ephemeral hostPath storage without proper volume snapshots; node eviction permanently deletes active table parts.
Zero-Downtime Rolling Stateful Upgrades	Replicated table-aware rolling upgrade sequence (replica-by-replica), active query drain verification, system.replicas sync validation, and zero dropped connections.	Mass StatefulSet rolling restart that drops active analytical client queries and triggers concurrent replica resync network storms.	Full maintenance window cluster stops, incurring hours of analytical application outage during version upgrades.	Direct image tag updates in deployment manifests causing uncoordinated restarts, split-brain states, and corrupted table parts.
PodDisruptionBudget & Node Drain Resilience	Granular PodDisruptionBudgets enforcing maxUnavailable=1 per shard, graceful preStop lifecycle hooks, and automated cordon/drain safety gates during Kubernetes node upgrades.	Unrestricted node drains killing multiple replicas in the same shard concurrently, causing instantaneous analytical downtime.	Missing PDBs; automated Kubernetes cluster autoscaler node consolidations repeatedly terminate active ClickHouse merge threads.	No preStop hooks or termination grace period tuning; abrupt SIGKILL signals corrupt uncommitted part writes.
Cloud-Native Telemetry (Prometheus / Grafana)	Native Prometheus endpoint integration, custom Grafana dashboards for parts merging, replication queue lag, Keeper raft health, and Alertmanager alerts with automated runbooks.	Standard Kubernetes node-exporter without internal ClickHouse system table scraping, missing critical replication lag anomalies.	Generic third-party APM agents injected into containers, introducing CPU overhead without ClickHouse-specific query telemetry.	No metrics collection; relies on application HTTP 500 error logs to discover when ClickHouse pods run out of memory.

Kubernetes Failure Modes

Critical ClickHouse on Kubernetes Risks We Eliminate

Stateful OLAP clusters on Kubernetes fail when node drains breach shard quorum, storage drivers hang on volume re-attachment, or rapid rollouts split Raft consensus. We engineer operational resilience into every cluster:

P1 Critical

Node Eviction Triggering Uncoordinated Multi-Pod Replica Outage

Kubernetes cluster autoscalers or automated node upgrades drain nodes hosting multiple replicas in the same shard concurrently when PodDisruptionBudgets are missing. Shards lose quorum, resulting in total analytical query rejections and write stalls.

JusDB Engineering Mitigation:

JusDB DBREs enforce strict shard-aware PodDisruptionBudgets (maxUnavailable: 1 per shard), topologySpreadConstraints across availability zones, and pod anti-affinity policies.

P1 Critical

Persistent Volume Detachment Failure on Kubernetes Cloud Provider

When a ClickHouse pod crashes or is rescheduled to a new node, cloud provider CSI drivers (such as AWS EBS or GCP Persistent Disk) experience volume detachment timeouts (VolumeInUse). The rescheduled pod hangs indefinitely in ContainerCreating, preventing replica recovery.

JusDB Engineering Mitigation:

JusDB configures node-affinity storage classes, aggressive attach/detach timeouts, and automated CSI force-detach remediation controllers to restore pods within seconds.

P2 High

Keeper Raft Quorum Split During Rapid StatefulSet Rollout

Executing rapid sequential rollouts or rolling restarts of ClickHouse Keeper StatefulSets faster than Raft leader election and heartbeat catch-up windows causes split-brain or election deadlocks. ClickHouse nodes lose metadata synchronization and freeze DDL executions.

JusDB Engineering Mitigation:

JusDB deploys dedicated Keeper StatefulSets isolated from compute nodes, configures minReadySeconds, and enforces automated Raft quorum health checks before permitting subsequent pod updates.

Telemetry Runbooks · Non-Blocking Kubernetes Diagnostics

Our DBREs execute non-blocking pre-flight diagnostic commands to audit operator resources, pod scheduling states, and replica synchronization health across Kubernetes nodes:

Kubernetes: Altinity ClickHouse Installation & Pod Status Audit

CLI · Operator Status

Inspects the status, phase, replica distribution, and node assignment of Altinity ClickHouseInstallation resources and associated pods across the cluster.

# Audit Altinity ClickHouseInstallation resources and pod distribution
kubectl get chi,pods -n clickhouse -o wide

ClickHouse: Replicated Database Replica Sync & Queue Health

SQL · Replica Health

Queries system.replicas to verify active leader status, read-only flags, absolute replication delay, and pending queue size across all replicated tables.

SELECT
    database,
    table,
    is_leader,
    is_readonly,
    absolute_delay,
    queue_size
FROM system.replicas;

FAQ

ClickHouse on Kubernetes — Frequently Asked Questions

Common questions about running ClickHouse on Kubernetes in production environments.

Ready to Run ClickHouse on Kubernetes?

Let our experts deploy and manage production ClickHouse on Kubernetes with operator-driven automation, sharded clusters, and real-time analytics at petabyte scale.

Start Your Project Schedule Consultation

Related ClickHouse Services

Explore more ways our ClickHouse experts can help with your database infrastructure.

ClickHouse Consulting ClickHouse Migration ClickHouse Performance Tuning

View all ClickHouse services