Installing the Operator
Installing the operator is simple. You can install it with Helm or install it with a shell script (which in turn uses kubectl
), whichever you prefer.
Choose your adventure - Helm or kubectl
Use these tabs to choose your install path.
Installing with Helm
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 it’s been a while since you added the repo):
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!⎈
Create the operator
namespace next. We’ll install the operator in that namespace and then create our ClickHouse clusters and the resources they need in that namespace as well.
kubectl create namespace operator
Now you’re ready to install the chart:
helm install clickhouse-operator altinity-docs/altinity-clickhouse-operator \
-n operator
You’ll see something like this:
NAME: clickhouse-operator
LAST DEPLOYED: Tue Jul 15 17:13:55 2025
NAMESPACE: operator
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 operator | grep app_version
If you ran hugo repo update
, you’ll have the latest version:
- app_version: 0.25.2
To verify that the installation worked, run this command:
kubectl get deployment.apps -n operator
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 54s
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:
- Four CustomResourceDefinitions (CRDs):
clickhouseinstallation
(abbreviatedchi
)clickhouseinstallationtempate
clickhousekeeperinstallation
(abbreviatedchk
)clickhouseoperatorconfiguration
- A ServiceAccount:
clickhouse-operator
- A ClusterRoleBinding:
clickhouse-operator
- A Deployment:
clickhouse-operator
See the operator repo for a complete description of all of the resources.
Installing with kubectl
To deploy version 0.25.2 of the ClickHouse operator into the operator
namespace, run this command:
curl -s https://raw.githubusercontent.com/Altinity/clickhouse-operator/refs/heads/0.25.2/deploy/operator-web-installer/clickhouse-operator-install.sh | OPERATOR_NAMESPACE=operator bash
The script uses kubectl
to create the operator
namespace and then install and configure the operator. You’ll see something like this:
Setup ClickHouse Operator into 'operator' namespace.
No 'operator' namespace found. Going to create.
namespace/operator created
Namespace 'operator' exists.
Looks like clickhouse-operator is not installed in 'operator' namespace.
Install operator from template https://raw.githubusercontent.com/Altinity/clickhouse-operator/master/deploy/operator/clickhouse-operator-install-template.yaml into operator namespace
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-operator created
clusterrolebinding.rbac.authorization.k8s.io/clickhouse-operator-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 shell script 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 operator -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.2
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 operator
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 8m19s
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:
- Four CustomResourceDefinitions (CRDs):
clickhouseinstallation
(abbreviatedchi
)clickhouseinstallationtempate
clickhousekeeperinstallation
(abbreviatedchk
)clickhouseoperatorconfiguration
- A ServiceAccount:
clickhouse-operator
- A ClusterRoleBinding:
clickhouse-operator
- A Deployment:
clickhouse-operator
See the operator repo for a complete description of all of the resources.