Installing the Operator
Installing the operator is simple. You can install it with Helm or install it with kubectl
, whichever you prefer.
Choose your adventure - Helm or kubectl
Use these tabs to choose your install tool.
Helm bills itself as “the package manager for Kubernetes.” It makes it easy to install resources in your Kubernetes cluster. See the Installing Helm page to install Helm on your system.
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: Mon May 26 11:34:51 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.25.0
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 15s
coredns 1/1 1 1 90s
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 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 deeper dive, 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 CustomResourceDefinition
s. 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.
If you go through the Quick Start Guide to create a ClickHouse cluster, you may also use the ClickHouseKeeperInstallation
(abbreviated chk
) resource. That makes it easy to create the ClickHouse Keeper resources you need to enable replication.
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 | grep clickhouse
You should see something like this:
NAME SECRETS AGE
clickhouse-operator-altinity-clickhouse-operator 0 4m41s
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 | grep clickhouse
You should see something like this:
NAME ROLE AGE
clickhouse-operator-altinity-clickhouse-operator ClusterRole/clickhouse-operator-altinity-clickhouse-operator 6m4s
Deployment
deployment.apps/clickhouse-operator configured
A new Deployment
is created. The ClickHouse operator app is 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-altinity-clickhouse-operator 1/1 1 1 13m
coredns 1/1 1 1 63m
Here’s how to deploy version 0.25.0 of the clickhouse-operator-install-bundle.yaml file from the Altinity clickhouse-operator repository:
kubectl apply -f https://raw.githubusercontent.com/Altinity/clickhouse-operator/release-0.25.0/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
role.rbac.authorization.k8s.io/clickhouse-operator created
rolebinding.rbac.authorization.k8s.io/clickhouse-operator 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
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. For complete details of all installation options, see the ClickHouse Operator installation page in the repo.
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.25.0
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.)
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 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.)
NOTE: The names of some of the resources may vary depending on whether you installed the operator with Helm or kubectl
. Helm installs the operator as clickhouse-operator-altinity-clickhouse-operator
, while kubectl
installs it with the much shorter name clickhouse-operator
. Whatever its name may be, the operator works exactly the same way.
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 CustomResourceDefinition
s. 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.
If you go through the Quick Start Guide, you may also use the ClickHouseKeeperInstallation
(abbreviated chk
) resource as well. That makes it easy to create the ClickHouse Keeper resources you need to enable replication.
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 | grep clickhouse
You should see something like this:
NAME SECRETS AGE
clickhouse-operator 0 52m
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 | grep clickhouse
You should see something like this:
NAME ROLE AGE
clickhouse-operator-kube-system ClusterRole/clickhouse-operator-kube-system 53m
Deployment
deployment.apps/clickhouse-operator configured
A new Deployment
is created. The ClickHouse operator app is 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 54m
coredns 1/1 1 1 55m