This is the fourth article in the series on running the ClickHouse® database on Kubernetes with the Altinity® Kubernetes Operator. The previous article deployed a single ClickHouse node by hand and made the manual cost of a real cluster obvious. This one introduces the tool that takes that cost away.
What is the Altinity Kubernetes Operator
The operator pattern from the first article applies directly here: an operator is a program that runs inside your cluster and teaches Kubernetes how to manage a specific application. The Altinity Kubernetes Operator does that for ClickHouse. It was the first database operator ever published, it is open source under the Apache 2.0 license, and it is the same engine behind Altinity.Cloud, so it has a long track record in production.
Rather than writing StatefulSets, Services, volume claims, and configuration by hand, you describe the cluster you want in a single short resource, and the operator builds and maintains everything beneath it. As of mid-2026 the current release is the 0.27 line: 0.27.0 landed on 8 May 2026, and 0.27.1, which adds FIPS support, on 4 June 2026. It supports ClickHouse 21.11 and newer, and Kubernetes 1.25 and newer.
The custom resources it adds
Installing the operator extends Kubernetes with new kinds of object, called Custom Resource Definitions. Two of them do most of the work in this series.
A ClickHouseInstallation, usually shortened to CHI, describes a ClickHouse cluster: how many shards and replicas, what storage, which users and settings. It is the resource you will write most often.
A ClickHouseKeeperInstallation, shortened to CHK, describes a ClickHouse Keeper ensemble, the coordination service that replication needs. It gets its own article shortly.
Two more advanced resources exist, a ClickHouseInstallationTemplate for reusable defaults and a ClickHouseOperatorConfiguration for operator-wide settings, but you can leave them aside while learning.
How the operator works: the reconcile loop
The operator watches for these resources. Create or change a CHI, and it compares the desired state you described against what actually exists in the cluster, then creates, updates, or deletes the underlying StatefulSets, Services, ConfigMaps, and volume claims until reality matches. It is the same reconcile loop Kubernetes runs on its own objects, applied to ClickHouse: you declare intent, and the operator handles the plumbing and keeps handling it.
Step 1: Install the operator with kubectl
The quickest install applies the official bundle straight from the project repository. It installs into the kube-system namespace:
kubectl apply -f https://raw.githubusercontent.com/Altinity/clickhouse-operator/master/deploy/operator/clickhouse-operator-install-bundle.yamlIt creates a CustomResourceDefinition, a ServiceAccount, a ClusterRoleBinding, and a Deployment. Confirm the operator pod is running:
kubectl get pods -n kube-system -l app=clickhouse-operatorNAME READY STATUS RESTARTS AGE
clickhouse-operator-5c46dfc7bd-7cz5l 1/1 Running 0 40sThat one running pod now watches the whole cluster for ClickHouse resources.
Step 1, alternative: install with Helm
If you prefer Helm, the project publishes an official chart (available since operator 0.20.1):
helm repo add clickhouse-operator https://helm.altinity.com
helm install clickhouse-operator clickhouse-operator/altinity-clickhouse-operatorEither route gives you the same operator. Use kubectl for the quickest start, or Helm if you already manage your cluster that way.
Step 2: Deploy your first cluster
Below is the entire description of a single-node ClickHouse cluster managed by the operator. Set its length against the hand-written StatefulSet from the previous article. Save it as first-cluster.yaml:
apiVersion: "clickhouse.altinity.com/v1"
kind: "ClickHouseInstallation"
metadata:
name: "demo"
spec:
configuration:
users:
# A demo user reachable from anywhere in the cluster.
analyst/password: analyst_password
analyst/networks/ip:
- 0.0.0.0/0
clusters:
- name: "main"
layout:
shardsCount: 1
replicasCount: 1
settings:
# Pin the ClickHouse image-independent server settings here later.
defaults:
templates:
podTemplate: clickhouse-pod
templates:
podTemplates:
- name: clickhouse-pod
spec:
containers:
- name: clickhouse
image: clickhouse/clickhouse-server:26.3The whole cluster lives in the clusters block: one shard, one replica. The users block creates an analyst user for us. The pod template pins the ClickHouse image to the current Long Term Support release, 26.3. Apply it into its own namespace:
kubectl create namespace ch
kubectl apply -n ch -f first-cluster.yamlStep 3: Watch the operator build everything
kubectl get chi -n ch -wThe chi shorthand lists your ClickHouseInstallations, and its status reaches Completed once the operator finishes. Now look at what it created for you:
kubectl get all -n chYou will see a StatefulSet, a pod named like chi-demo-main-0-0-0, a per-pod Service, and a cluster Service named clickhouse-demo. The operator wrote all of that from your short manifest. It also created the internal users and wired up everything ClickHouse needs to start.
Step 4: Connect and query
The operator made a Service called clickhouse-demo. Forward its HTTP port and query it:
kubectl port-forward -n ch svc/clickhouse-demo 8123:8123curl 'http://localhost:8123/?user=analyst&password=analyst_password' \
--data-binary 'SELECT version()'It returns the ClickHouse version. That is a working, operator-managed cluster, for a fraction of the YAML the manual approach took.
Why this matters
The single node above is not the point; the format is. The same short, declarative description scales. To add replicas you change one number. To add Keeper, storage, users, or settings, you add a few lines, and the operator reconciles the change safely. Everything we do for the rest of the series builds on this CHI resource.
Clean up
kubectl delete namespace chThe operator itself stays installed in kube-system, ready for the next cluster.
What is next
You have installed the operator and run your first managed cluster. In the next article we give ClickHouse proper persistent storage through the operator: StorageClasses, data and log volumes, and how to grow a disk without downtime.
