> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-detect-table-modification.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Introduction to the ClickHouse Operator
> This document provides an overview of key concepts and usage patterns for 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.
```yaml theme={null}
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).
```yaml theme={null}
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.
The Keeper cluster must be referenced 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.
One-to-One Keeper relationship
Each ClickHouseCluster must have its own dedicated KeeperCluster. You can't share a single KeeperCluster between multiple ClickHouseClusters.
**Why?** The operator automatically generates a unique authentication key for each ClickHouseCluster to access its Keeper. This key is stored in a Secret and can't be shared.
**Consequences**:
* Multiple ClickHouseClusters can't reference the same KeeperCluster
* Recreating a ClickHouseCluster requires recreating its KeeperCluster
Persistent Volumes aren't deleted automatically when ClickHouseCluster or KeeperCluster resources are deleted.
When recreating a cluster:
1. Delete the ClickHouseCluster resource
2. Delete the KeeperCluster resource
3. Wait for all pods to terminate
4. Optionally delete PersistentVolumeClaims if you want to start fresh
5. 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](/reference/engines/database-engines/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 practice**
Always use the [Replicated](/reference/engines/database-engines/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:
```sql theme={null}
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`:
```yaml theme={null}
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:
```bash theme={null}
# 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](/products/kubernetes-operator/guides/configuration) - Detailed configuration options
* [API Reference](/products/kubernetes-operator/reference/api-reference) - Complete API documentation