Introduction to the Altinity® Kubernetes Operator for ClickHouse®

This is the fourth article in our series on running the ClickHouse® database on Kubernetes with the Altinity® Kubernetes Operator. In the previous article we deployed a single ClickHouse node by hand and saw how much manual work a real cluster would demand. Now we introduce the tool that removes that work.

What is the Altinity Kubernetes Operator

Recall the operator pattern from the first article: an operator is a program that runs inside your cluster and teaches Kubernetes how to manage a specific application. The Altinity Kubernetes Operator does exactly this 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 that powers Altinity.Cloud, so it is heavily proven in production.

Instead of writing StatefulSets, Services, volume claims, and configuration files yourself, you describe the ClickHouse cluster you want in a single short resource, and the operator continuously builds and maintains everything underneath it. As of mid-2026 the current release is the 0.27 line, with version 0.27.0 published on 8 May 2026 and version 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

When you install the operator, it extends Kubernetes with new kinds of object, called Custom Resource Definitions. You will mostly use two of them in this series.

A ClickHouseInstallation, usually shortened to CHI, describes a ClickHouse cluster: how many shards and replicas, what storage, which users and settings. This is the main resource you will write.

A ClickHouseKeeperInstallation, shortened to CHK, describes a ClickHouse Keeper ensemble, the coordination service that replication needs. We give it its own article shortly.

There are two more advanced resources, a ClickHouseInstallationTemplate for reusable defaults and a ClickHouseOperatorConfiguration for operator-wide settings, but you can ignore them while learning.

How the operator works: the reconcile loop

The operator watches for these resources. When you create or change a CHI, the operator 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 to make reality match. This is the same reconcile loop that Kubernetes itself uses, applied to ClickHouse. You declare intent; the operator does the plumbing and keeps doing it.

Step 1: Install the operator with kubectl

The simplest way to install is to apply 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.yaml

You will see it create a CustomResourceDefinition, a ServiceAccount, a ClusterRoleBinding, and a Deployment. Confirm the operator pod is running:

kubectl get pods -n kube-system -l app=clickhouse-operator

NAME                                   READY   STATUS    RESTARTS   AGE
clickhouse-operator-5c46dfc7bd-7cz5l   1/1     Running   0          40s

That single running pod is now watching 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-operator

Either method 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

Here is the entire description of a single-node ClickHouse cluster managed by the operator. Compare its length to 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.3

The whole cluster is described 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.yaml

Step 3: Watch the operator build everything

kubectl get chi -n ch -w

The chi shorthand lists your ClickHouseInstallations. Its status moves to Completed once the operator finishes. Now look at what it created for you:

kubectl get all -n ch

You 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 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:8123

curl 'http://localhost:8123/?user=analyst&password=analyst_password' \
  --data-binary 'SELECT version()'

It returns the ClickHouse version. You have a working, operator-managed cluster, and you wrote a fraction of the YAML you wrote by hand last time.

Why this matters

The single node above is not the point. The point is that the same short, declarative format 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 ch

The 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.

References

• Altinity Kubernetes Operator (GitHub)
• Altinity Operator release notes
• Altinity Operator Helm chart
• Kubernetes: custom resources