Introduction to the ClickHouse Operator

This document provides an overview of key concepts and usage patterns for the ClickHouse Operator.

What is the ClickHouse Operator

The ClickHouse Operator is a Kubernetes operator that automates the deployment and management of ClickHouse clusters on Kubernetes. Built using the operator pattern, it extends the Kubernetes API with custom resources that represent ClickHouse clusters and their dependencies. The operator handles:

Cluster lifecycle management (creation, updates, scaling, deletion)
ClickHouse Keeper cluster coordination
Automatic configuration generation
Database schema synchronization
Rolling updates and upgrades
Storage provisioning

Custom resources

The operator provides two main custom resource definitions (CRDs):

ClickHouseCluster

Represents a ClickHouse database cluster with configurable replicas and shards.

apiVersion: clickhouse.com/v1alpha1
kind: ClickHouseCluster
metadata:
  name: sample-cluster
spec:
  replicas: 3
  shards: 2
  keeperClusterRef:
    name: sample-keeper
  dataVolumeClaimSpec:
    resources:
      requests:
        storage: 100Gi

KeeperCluster

Represents a ClickHouse Keeper cluster for distributed coordination (ZooKeeper replacement).

apiVersion: clickhouse.com/v1alpha1
kind: KeeperCluster
metadata:
  name: sample-keeper
spec:
  replicas: 3
  dataVolumeClaimSpec:
    resources:
      requests:
        storage: 10Gi

Coordination

ClickHouse Keeper is required

Every ClickHouseCluster requires a ClickHouse Keeper cluster for distributed coordination. Reference an operator-managed KeeperCluster in the ClickHouseCluster spec using keeperClusterRef. By default the operator looks in the ClickHouseCluster namespace, but you can also set keeperClusterRef.namespace to point at a KeeperCluster in another watched namespace. To use a Keeper ensemble the operator does not manage, list its servers in externalKeeper instead. See Externally managed Keeper.

One-to-One Keeper relationship

By default, each ClickHouseCluster needs its own dedicated KeeperCluster. Why? The operator automatically generates a unique authentication key for each ClickHouseCluster to access its Keeper. This key is stored in a Secret. Consequences:

Multiple ClickHouseClusters can’t reference the same KeeperCluster without the setup below
Recreating a ClickHouseCluster requires recreating its KeeperCluster

To share a single Keeper cluster, set a distinct zookeeper.root in settings.extraConfig for each ClickHouseCluster, and create that znode before ClickHouse starts. See Externally managed Keeper.

Persistent Volumes aren’t deleted automatically when ClickHouseCluster or KeeperCluster resources are deleted.

When recreating a cluster:

Delete the ClickHouseCluster resource
Delete the KeeperCluster resource
Wait for all pods to terminate
Optionally delete PersistentVolumeClaims if you want to start fresh
Recreate both KeeperCluster and ClickHouseCluster together

To avoid authentication errors, either delete the Persistent Volumes manually or recreate both clusters together with fresh storage.

Schema Replication

The ClickHouse Operator automatically replicates database definitions across all replicas in a cluster.

What Gets Replicated

The operator synchronizes:

Replicated database definitions
Integration database engines (PostgreSQL, MySQL, etc.)

The operator does not synchronize:

Non-replicated databases (Atomic, Ordinary, etc.)
Local tables in non-replicated databases
Table data (handled by ClickHouse replication)

Recommended: Use Replicated database engine

Best practiceAlways use the Replicated database engine for production deployments.

Benefits:

Automatic schema replication across all nodes
Simplified table management
Operator can sync to new replicas
Consistent schema across the cluster

Create databases with distributed DDL:

CREATE DATABASE my_database ON CLUSTER 'default' ENGINE = Replicated;

Avoid non-Replicated engines

Non-replicated database engines (Atomic, Lazy, SQLite, Ordinary) require manual schema management:

Tables must be created individually on each replica
Schema drift can occur between nodes
Operator can’t automatically sync new replicas

Disable schema replication

To disable automatic schema replication, set spec.settings.enableDatabaseSync to false in the ClickHouseCluster resource.

Storage management

The operator manages storage through Kubernetes PersistentVolumeClaims (PVCs).

Data volume configuration

Specify storage requirements in dataVolumeClaimSpec:

spec:
  dataVolumeClaimSpec:
    storageClassName: fast-ssd
    resources:
      requests:
        storage: 500Gi

Storage Lifecycle

Creation: PVCs are created automatically with the cluster
Expansion: Supported if StorageClass allows volume expansion
Retention: PVCs are not deleted automatically on cluster deletion
Reuse: Existing PVCs can be reused if cluster is recreated with same name

To completely remove storage:

# Delete cluster
kubectl delete clickhousecluster my-cluster

# Wait for pods to terminate
kubectl wait --for=delete pod -l app.kubernetes.io/instance=my-cluster-clickhouse

# Delete PVCs
kubectl delete pvc -l app.kubernetes.io/instance=my-cluster-clickhouse

Default configuration highlights

Pre-configured Cluster: Cluster named ‘default’ containing all ClickHouse nodes.
Default macros: Some useful macros are pre-defined:
- {cluster}: Cluster name (default)
- {shard}: Shard number
- {replica}: Replica number
Replicated storage for Role Based Access Control(RBAC) entities
Replicated storage for User Defined Functions(UDF)

Next steps

Configuration Guide - Detailed configuration options
API Reference - Complete API documentation

Install

Guides

Reference

What is the ClickHouse Operator

Custom resources

ClickHouseCluster

KeeperCluster

Coordination

ClickHouse Keeper is required

One-to-One Keeper relationship

Schema Replication

What Gets Replicated

Recommended: Use Replicated database engine

Avoid non-Replicated engines

Disable schema replication

Storage management

Data volume configuration

Storage Lifecycle

Default configuration highlights

Next steps

​What is the ClickHouse Operator

​Custom resources

​ClickHouseCluster

​KeeperCluster

​Coordination

​ClickHouse Keeper is required

​One-to-One Keeper relationship

​Schema Replication

​What Gets Replicated

​Recommended: Use Replicated database engine

​Avoid non-Replicated engines

​Disable schema replication

​Storage management

​Data volume configuration

​Storage Lifecycle

​Default configuration highlights

​Next steps

What is the ClickHouse Operator

Custom resources

ClickHouseCluster

KeeperCluster

Coordination

ClickHouse Keeper is required

One-to-One Keeper relationship

Schema Replication

What Gets Replicated

Recommended: Use Replicated database engine

Avoid non-Replicated engines

Disable schema replication

Storage management

Data volume configuration

Storage Lifecycle

Default configuration highlights

Next steps