Installing the Operator

Getting the operator installed

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.

NOTE: This procedure only installs the operator, it does not create a ClickHouse cluster. The Quick Start Guide shows you how to do that.

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, add the helm.altinity.com repo if you haven’t already:

helm repo add altinity https://helm.altinity.com

This adds the repository to your list of repos under the name altinity:

"altinity" has been added to your repositories

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

DEPRECATION WARNING

The correct Helm repo to use is now https://helm.altinity.com. The previous repo, https://docs.altinity.com/clickhouse-operator, is deprecated and at some point will be deleted. Any changes or updates to the Helm charts will be applied to the old repo until it's removed.

If you’ve previously installed the old repo, you should uninstall it and install the correct repo at helm.altinity.com now. First, use the helm repo list command to see which repos you have installed:

> helm repo list
NAME            	URL
devtron         	https://helm.devtron.ai
harness-delegate	https://app.harness.io/storage/harness-download/delegate-helm-chart/
superset        	https://apache.github.io/superset
eks             	https://aws.github.io/eks-charts
altinity-docs   	https://docs.altinity.com/clickhouse-operator

In this example, the old repo was installed with the name altinity-docs. (The name could be anything.) These commands delete the old repo named altinity-docs and install the correct one under the name altinity:

helm repo remove altinity-docs
helm repo add altinity https://helm.altinity.com


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

This refreshes the local cache of chart repositories on your machine. Helm will send its best wishes:

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

Now you’re ready to install the chart. We’ll do this with the helm upgrade command, telling Helm to create the clickhouse namespace if it doesn’t exist already, then upgrade or install version 0.25.4 of the operator into that namespace. (It’s not installed yet, of course, so this will just do an install. We’ll see the helm upgrade command again later.)

helm upgrade --install clickhouse-operator \
  altinity/altinity-clickhouse-operator \
  --version 0.25.4 \
  --namespace clickhouse \
  --create-namespace

You’ll see something like this:

NAME: clickhouse-operator
LAST DEPLOYED: Tue Jul  15 17:13:55 2025
NAMESPACE: clickhouse
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 clickhouse | grep app_version

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

- app_version: 0.25.4

To verify that the installation worked, run this command:

kubectl get deployment.apps -n clickhouse

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!

Going beyond the basics, there are a number of parameters you can pass to the Helm chart. See the Operator's Artifact Hub page for complete details.

NOTE: The Helm repo has older versions of the operator chart if you need them. The command helm search repo altinity-clickhouse-operator --versions will list all versions of the operator chart.

The Quick Start Guide and other resources

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:

See the operator repo for a complete description of all the resources.

Installing with kubectl

To deploy version 0.25.4 of the ClickHouse operator into the clickhouse namespace, run this command:

curl -s https://raw.githubusercontent.com/Altinity/clickhouse-operator/refs/heads/0.25.4/deploy/operator-web-installer/clickhouse-operator-install.sh | OPERATOR_NAMESPACE=clickhouse bash

The script uses kubectl to create the clickhouse namespace and then install and configure the operator. You’ll see something like this:

Setup ClickHouse Operator into 'clickhouse' namespace.
No 'clickhouse' namespace found. Going to create.
namespace/clickhouse created
Namespace 'clickhouse' exists.
Looks like clickhouse-operator is not installed in 'clickhouse' namespace.
Install operator from template https://raw.githubusercontent.com/Altinity/clickhouse-operator/master/deploy/operator/clickhouse-operator-install-template.yaml into clickhouse 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 and ending the command above with something like OPERATOR_NAMESPACE=clickhouse OPERATOR_VERSION=0.24.2 bash. 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 clickhouse -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.4

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 clickhouse

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

The Quick Start Guide and other resources

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 to 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:

See the operator repo for a complete description of all the resources.

Next you’ll need to Create a ClickHouse Cluster if you haven’t already done so.