Introduction to the ClickHouse Operator

[Edit this page](https://github.com/ClickHouse/clickhouse-docs/blob/main/docs/kubernetes-operator/03_guides/01_introduction.mdx)

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

## What is the ClickHouse Operator[​](#what-is-the-clickhouse-operator "Direct link to 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[​](#custom-resources "Direct link to Custom resources")

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

### ClickHouseCluster[​](#clickhousecluster "Direct link to 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[​](#keepercluster "Direct link to 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[​](#coordination "Direct link to Coordination")

### ClickHouse Keeper is required[​](#clickhouse-keeper-is-required "Direct link to 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`.

### One-to-One Keeper relationship[​](#one-to-one-keeper-relationship "Direct link to 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

Note

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[​](#schema-replication "Direct link to Schema Replication")

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

### What Gets Replicated[​](#what-gets-replicated "Direct link to What Gets Replicated")

The operator synchronizes:

- [Replicated](/docs/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[​](#recommended-use-replicated-database-engine "Direct link to Recommended: Use Replicated database engine")

Best practice

Always use the [Replicated](/docs/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:

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

### Avoid non-Replicated engines[​](#avoid-non-replicated-engines "Direct link to 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[​](#disable-schema-replication "Direct link to Disable schema replication")

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

## Storage management[​](#storage-management "Direct link to Storage management")

The operator manages storage through Kubernetes PersistentVolumeClaims (PVCs).

### Data volume configuration[​](#data-volume-configuration "Direct link to Data volume configuration")

Specify storage requirements in `dataVolumeClaimSpec`:

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

### Storage Lifecycle[​](#storage-lifecycle "Direct link to 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

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

## Default configuration highlights[​](#default-configuration-highlights "Direct link to 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[​](#next-steps "Direct link to Next steps")

- [Configuration Guide](/docs/clickhouse-operator/guides/configuration) - Detailed configuration options
- [API Reference](/docs/clickhouse-operator/reference/api-reference) - Complete API documentation

- [What is the ClickHouse Operator](#what-is-the-clickhouse-operator)- [Custom resources](#custom-resources)
    - [ClickHouseCluster](#clickhousecluster)- [KeeperCluster](#keepercluster)- [Coordination](#coordination)
      - [ClickHouse Keeper is required](#clickhouse-keeper-is-required)- [One-to-One Keeper relationship](#one-to-one-keeper-relationship)- [Schema Replication](#schema-replication)
        - [What Gets Replicated](#what-gets-replicated)- [Recommended: Use Replicated database engine](#recommended-use-replicated-database-engine)- [Avoid non-Replicated engines](#avoid-non-replicated-engines)- [Disable schema replication](#disable-schema-replication)- [Storage management](#storage-management)
          - [Data volume configuration](#data-volume-configuration)- [Storage Lifecycle](#storage-lifecycle)- [Default configuration highlights](#default-configuration-highlights)- [Next steps](#next-steps)

Was this page helpful?