Installing the Operator

Getting the operator installed

Installing the operator is simple. You can install it with Helm or install it with kubectl, whichever you prefer.

Installing with Helm

Using the package manager for Kubernetes

To install the operator with Helm, you’ll need to add the altinity-docs repo if you haven’t already:

helm repo add altinity-docs https://docs.altinity.com/clickhouse-operator

This adds the repository to your list of repos:

"altinity-docs" has been added to your repositories

(If you’ve already added the altinity-docs repo, you’ll be told that Helm skipped the command.)

Before installing the operator’s Helm chart, it never hurts to make sure you’ve got the latest version (especially if you added the repo earlier):

helm repo update altinity-docs

Helm will send its best wishes:

Hang tight while we grab the latest from your chart repositories...
...Successfully got an update from the "altinity-docs" chart repository
Update Complete. ⎈Happy Helming!⎈

Now you’re ready to install the chart:

helm install clickhouse-operator altinity-docs/altinity-clickhouse-operator \
--namespace kube-system

You’ll see something like this:

NAME: clickhouse-operator
LAST DEPLOYED: Wed Mar 26 14:55:57 2025
NAMESPACE: kube-system
STATUS: deployed
REVISION: 1
TEST SUITE: None

Before we go on, see what version of the chart you’re working with:

helm list --output yaml -n kube-system | grep app_version

If you ran hugo repo update, you’ll have the latest version:

`- app_version: 0.24.5

To verify that the installation worked, run this command:

kubectl get deployment.apps -n kube-system

Keep checking this command until you see clickhouse-operator-altinity-clickhouse-operator and Ready 1/1 in the output:

NAME                                               READY   UP-TO-DATE   AVAILABLE   AGE
clickhouse-operator-altinity-clickhouse-operator   1/1     1            1           80s
coredns                                            1/1     1            1           44m

(What you see besides clickhouse-operator-altinity-clickhouse-operator will vary depending on your platform and your Kubernetes cluster’s configuration, of course.)

So it’s just that simple - you’ve installed the operator in your Kubernetes cluster!

If you’d like to go through a tutorial to create a ClickHouse cluster with persistent storage and replication, move on to the Quick Start Guide. If you want to see the details of the Kubernetes resources created when you install the operator, see the Operator details section below.

Other resources you might want co check out include the Operator Resources section and our list of advanced topics. And there’s always the directory of advanced samples in the operator repo.

Installing with kubectl

Using native Kubernetes tooling

Here’s how to deploy version 0.24.5 of the clickhouse-operator-install-bundle.yaml file from the Altinity clickhouse-operator repository into the `kube-system` namespace:

kubectl apply -f https://raw.githubusercontent.com/Altinity/clickhouse-operator/release-0.24.5/deploy/operator/clickhouse-operator-install-bundle.yaml

If everything worked, you’ll see something like this:

customresourcedefinition.apiextensions.k8s.io/clickhouseinstallations.clickhouse.altinity.com created
customresourcedefinition.apiextensions.k8s.io/clickhouseinstallationtemplates.clickhouse.altinity.com created
customresourcedefinition.apiextensions.k8s.io/clickhouseoperatorconfigurations.clickhouse.altinity.com created
customresourcedefinition.apiextensions.k8s.io/clickhousekeeperinstallations.clickhouse-keeper.altinity.com created
serviceaccount/clickhouse-operator created
clusterrole.rbac.authorization.k8s.io/clickhouse-operator-kube-system created
clusterrolebinding.rbac.authorization.k8s.io/clickhouse-operator-kube-system created
configmap/etc-clickhouse-operator-files created
configmap/etc-clickhouse-operator-confd-files created
configmap/etc-clickhouse-operator-configd-files created
configmap/etc-clickhouse-operator-templatesd-files created
configmap/etc-clickhouse-operator-usersd-files created
configmap/etc-keeper-operator-confd-files created
configmap/etc-keeper-operator-configd-files created
configmap/etc-keeper-operator-templatesd-files created
configmap/etc-keeper-operator-usersd-files created
secret/clickhouse-operator created
deployment.apps/clickhouse-operator created
service/clickhouse-operator-metrics created

Customizing the installation

You can install a different version of the operator by selecting a different YAML file from the Operator's repo. In general, changing the version number in the filename will do the trick.
You can install the operator to a different namespace by adding -n my-namespace at the end of the kubectl apply command above.

This set of piped commands shows you the full name of the image behind the operator:

kubectl get pods -l app=clickhouse-operator -n kube-system -o jsonpath="{.items[*].spec.containers[*].image}" | tr ' ' '\n' | grep -v 'metrics-exporter' | sort -u

You’ll see something like this:

altinity/clickhouse-operator:0.24.5

NOTE

We recommend that you always specify a particular version of any container image or YAML file. In our examples here, we’ll use a tag on every image and a version number on every YAML file. That makes our examples slightly longer, but it can prevent all sorts of errors and strange behaviors later.

To verify that the installation worked, run this command:

kubectl get deployment.apps -n kube-system

Keep checking this command until you see clickhouse-operator and Ready 1/1 in the output:

NAME                  READY   UP-TO-DATE   AVAILABLE   AGE
clickhouse-operator   1/1     1            1           80s
coredns               1/1     1            1           102d

(What you see besides clickhouse-operator will vary depending on your platform and your Kubernetes cluster’s configuration, of course.)

Other resources you might want co check out include the Operator Resources section and our list of advanced topics. And there’s always the directory of advanced samples in the operator repo.

Operator details

Installing the Altinity Kubernetes Operator for ClickHouse creates several resources:

We’ll take a quick look at the details of these resources. (If you’d like to take a look, there is a complete description of all of the resources in the operator repo.)

`CustomResourceDefinition`

customresourcedefinition.apiextensions.k8s.io/clickhouseinstallations.clickhouse.altinity.com created
customresourcedefinition.apiextensions.k8s.io/clickhouseinstallationtemplates.clickhouse.altinity.com created
customresourcedefinition.apiextensions.k8s.io/clickhouseoperatorconfigurations.clickhouse.altinity.com created
customresourcedefinition.apiextensions.k8s.io/clickhousekeeperinstallations.clickhouse-keeper.altinity.com created

There are four CustomResourceDefinitions. The ClickHouseInstallation CRD includes the abbreviation chi. It extends the Kubernetes API so you can manage ClickHouseInstallation resources. When you start working with the operator, this is probably the resource you’ll interact with the most.

Here’s how to verify the installation:

kubectl get crds

You should see something like this:

NAME                                                           CREATED AT
clickhouseinstallations.clickhouse.altinity.com                2025-05-11T18:44:30Z
clickhouseinstallationtemplates.clickhouse.altinity.com        2025-05-11T18:44:30Z
clickhousekeeperinstallations.clickhouse-keeper.altinity.com   2025-05-11T18:44:30Z
clickhouseoperatorconfigurations.clickhouse.altinity.com       2025-05-11T18:44:30Z

`ServiceAccount`

serviceaccount/clickhouse-operator created

The new ServiceAccount is named clickhouse-operator. A service account provides an identity used to contact the apiserver by the processes that run in a Pod. Processes in containers inside pods can contact the apiserver, and when they do, they are authenticated as the clickhouse-operator ServiceAccount.

Here’s how to verify the installation:

kubectl get serviceaccounts -n kube-system

You should see something like this:

NAME                                          SECRETS   AGE
. . . 
clickhouse-operator                           0         61s
. . .

`ClusterRoleBinding`

clusterrolebinding.rbac.authorization.k8s.io/clickhouse-operator created

A new CluserRoleBinding named clickhouse-operator is created. A role binding grants the permissions defined in a role to a set of users. It holds a reference to the role being granted to the list of subjects (users, groups, or service accounts). In this case this role:

roleRef:
  apiGroup: rbac.authorization.k8s.io
  kind: ClusterRole
  name: cluster-admin

is granted to the clickhouse-operator ServiceAccount created earlier:

subjects:
  - kind: ServiceAccount
    name: clickhouse-operator
    namespace: kube-system

Permissions are granted cluster-wide with a ClusterRoleBinding.

Here’s how to verify the installation:

kubectl get clusterrolebinding

You should see something like this:

NAME                                                            ROLE                                                                               AGE
. . . 
clickhouse-operator-kube-system                                 ClusterRole/clickhouse-operator-kube-system                                        2m16s
. . .

`Deployment`

deployment.apps/clickhouse-operator configured

A new Deployment named clickhouse-operator is created. The ClickHouse operator app ise run by this deployment in the kube-system namespace.

Here’s how to verify the installation:

kubectl get deploy -n kube-system

You should see something like this:

NAME                  READY   UP-TO-DATE   AVAILABLE   AGE
. . . 
clickhouse-operator   1/1     1            1           3m33s
. . .