Upgrading the Operator

How to move to a different version of the Altinity Kubernetes Operator for ClickHouse®

The Altinity Kubernetes Operator for ClickHouse® can be upgraded at any time by installing a new Helm chart from Altinity’s altinity-docs Helm repo or applying a new YAML manifest from the operator's repository. Our examples here upgrade the operator from version 0.25.1 to 0.25.2. To upgrade to a different version, simply replace 0.25.2 with a different version number.

These instructions assume you installed the operator into the operator namespace. If you installed it somewhere else, obviously use that namespace instead.

The upgrade process varies significantly if you installed the operator via Helm or kubectl:

If you installed the operator with Helm

There are two ways you can upgrade the operator with Helm:

  1. Upgrade the Helm chart, then upgrade the operator’s CRDs.
  2. Uninstall the currently installed Helm chart, install the updated Helm chart, then upgrade the operator’s CRDs.

When you used a Helm chart to install the operator the first time, it included the CRDs as part of the installation. In keeping with Helm's standard practice for dealing with CRDs, the CRDs will not be modified if they already exist. That’s why you have to update the CRDs as a separate step.

Choose your preferred way to upgrade your installation:

Upgrade the existing chart

This method is straightforward. Here are the steps:

Step 1. Upgrade the existing chart

First, check the repo to be sure you get the latest version of the Helm chart:

helm repo update altinity-docs

Helm will let you know you’re up-to-date:

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 new chart:

helm upgrade clickhouse-operator altinity-docs/altinity-clickhouse-operator -n operator

This installs the latest version of the Helm chart. You should 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

You can verify the installed version with this command:

helm list --output yaml -n operator | grep app_version

The new version should be installed:

- app_version: 0.25.2

Step 2. Update the CRDs

To update the CRDs, apply the YAML manifest from the repo:

kubectl apply -f https://raw.githubusercontent.com/Altinity/clickhouse-operator/refs/heads/0.25.2/deploy/operator/parts/crd.yaml

You’ll see something like this:

Warning: resource customresourcedefinitions/clickhouseinstallations.clickhouse.altinity.com is missing the kubectl.kubernetes.io/last-applied-configuration annotation which is required by kubectl apply. kubectl apply should only be used on resources created declaratively by either kubectl create --save-config or kubectl apply. The missing annotation will be patched automatically.
customresourcedefinition.apiextensions.k8s.io/clickhouseinstallations.clickhouse.altinity.com configured
Warning: resource customresourcedefinitions/clickhouseinstallationtemplates.clickhouse.altinity.com is missing the kubectl.kubernetes.io/last-applied-configuration annotation which is required by kubectl apply. kubectl apply should only be used on resources created declaratively by either kubectl create --save-config or kubectl apply. The missing annotation will be patched automatically.
customresourcedefinition.apiextensions.k8s.io/clickhouseinstallationtemplates.clickhouse.altinity.com configured
Warning: resource customresourcedefinitions/clickhouseoperatorconfigurations.clickhouse.altinity.com is missing the kubectl.kubernetes.io/last-applied-configuration annotation which is required by kubectl apply. kubectl apply should only be used on resources created declaratively by either kubectl create --save-config or kubectl apply. The missing annotation will be patched automatically.
customresourcedefinition.apiextensions.k8s.io/clickhouseoperatorconfigurations.clickhouse.altinity.com configured
Warning: resource customresourcedefinitions/clickhousekeeperinstallations.clickhouse-keeper.altinity.com is missing the kubectl.kubernetes.io/last-applied-configuration annotation which is required by kubectl apply. kubectl apply should only be used on resources created declaratively by either kubectl create --save-config or kubectl apply. The missing annotation will be patched automatically.
customresourcedefinition.apiextensions.k8s.io/clickhousekeeperinstallations.clickhouse-keeper.altinity.com configured

You’ll probably get warning messages as shown above; it’s safe to ignore them. The CRDs still exist:

kubectl get crds
NAME                                                           CREATED AT
clickhouseinstallations.clickhouse.altinity.com                2025-07-30T01:54:02Z
clickhouseinstallationtemplates.clickhouse.altinity.com        2025-07-30T01:54:02Z
clickhousekeeperinstallations.clickhouse-keeper.altinity.com   2025-07-30T01:54:02Z
clickhouseoperatorconfigurations.clickhouse.altinity.com       2025-07-30T01:54:02Z

If you want, you can even check the versions of the CRDs. Run this command:

for crd in clickhouseinstallations.clickhouse.altinity.com clickhouseinstallationtemplates.clickhouse.altinity.com clickhousekeeperinstallations.clickhouse-keeper.altinity.com clickhouseoperatorconfigurations.clickhouse.altinity.com; do
  echo "Checking version of CRD $crd..."
  kubectl describe crd $crd | grep Labels
done

You’ll see something like this:

Checking version of CRD clickhouseinstallations.clickhouse.altinity.com...
Labels:       clickhouse.altinity.com/chop=0.25.2
Checking version of CRD clickhouseinstallationtemplates.clickhouse.altinity.com...
Labels:       clickhouse.altinity.com/chop=0.25.2
Checking version of CRD clickhousekeeperinstallations.clickhouse-keeper.altinity.com...
Labels:       clickhouse-keeper.altinity.com/chop=0.25.2
Checking version of CRD clickhouseoperatorconfigurations.clickhouse.altinity.com...
Labels:       clickhouse.altinity.com/chop=0.25.2
                  Labels:

Uninstall the old chart, then install the new one

Step 1. Uninstall the existing Helm chart

The first step is straightforward:

helm uninstall clickhouse-operator -n operator

You’ll get feedback that the chart was uninstalled:

release "clickhouse-operator" uninstalled

As we mentioned above, the Helm chart doesn’t do anything with CRDs. They still exist:

kubectl get crds
NAME                                                           CREATED AT
clickhouseinstallations.clickhouse.altinity.com                2025-07-30T19:11:56Z
clickhouseinstallationtemplates.clickhouse.altinity.com        2025-07-30T19:11:56Z
clickhousekeeperinstallations.clickhouse-keeper.altinity.com   2025-07-30T19:11:56Z
clickhouseoperatorconfigurations.clickhouse.altinity.com       2025-07-30T19:11:56Z

Step 2. Install the new Helm chart

Before you install the new chart, check the repo to be sure you get the latest version:

helm repo update altinity-docs

Helm will let you know you’re up-to-date:

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 install the latest version of the Helm chart:

helm install clickhouse-operator altinity-docs/altinity-clickhouse-operator \
-n operator

You’ll see something like this:

NAME: clickhouse-operator
LAST DEPLOYED: Wed Jul 30 13:42:18 2025
NAMESPACE: operator
STATUS: deployed
REVISION: 1
TEST SUITE: None

Check the installed version of the operator with this command:

helm list --output yaml -n operator | grep app_version

The operator should be at the latest version:

- app_version: 0.25.2

Step 3. Update the CRDs

To update the CRDs, apply the YAML manifest from the repo:

kubectl apply -f https://raw.githubusercontent.com/Altinity/clickhouse-operator/refs/heads/0.25.2/deploy/operator/parts/crd.yaml

You’ll see something like this:

Warning: resource customresourcedefinitions/clickhouseinstallations.clickhouse.altinity.com is missing the kubectl.kubernetes.io/last-applied-configuration annotation which is required by kubectl apply. kubectl apply should only be used on resources created declaratively by either kubectl create --save-config or kubectl apply. The missing annotation will be patched automatically.
customresourcedefinition.apiextensions.k8s.io/clickhouseinstallations.clickhouse.altinity.com configured
Warning: resource customresourcedefinitions/clickhouseinstallationtemplates.clickhouse.altinity.com is missing the kubectl.kubernetes.io/last-applied-configuration annotation which is required by kubectl apply. kubectl apply should only be used on resources created declaratively by either kubectl create --save-config or kubectl apply. The missing annotation will be patched automatically.
customresourcedefinition.apiextensions.k8s.io/clickhouseinstallationtemplates.clickhouse.altinity.com configured
Warning: resource customresourcedefinitions/clickhouseoperatorconfigurations.clickhouse.altinity.com is missing the kubectl.kubernetes.io/last-applied-configuration annotation which is required by kubectl apply. kubectl apply should only be used on resources created declaratively by either kubectl create --save-config or kubectl apply. The missing annotation will be patched automatically.
customresourcedefinition.apiextensions.k8s.io/clickhouseoperatorconfigurations.clickhouse.altinity.com configured
Warning: resource customresourcedefinitions/clickhousekeeperinstallations.clickhouse-keeper.altinity.com is missing the kubectl.kubernetes.io/last-applied-configuration annotation which is required by kubectl apply. kubectl apply should only be used on resources created declaratively by either kubectl create --save-config or kubectl apply. The missing annotation will be patched automatically.
customresourcedefinition.apiextensions.k8s.io/clickhousekeeperinstallations.clickhouse-keeper.altinity.com configured

You’ll probably get warning messages as shown above; it’s safe to ignore them. The CRDs still exist:

kubectl get crds
NAME                                                           CREATED AT
clickhouseinstallations.clickhouse.altinity.com                2025-07-30T19:11:56Z
clickhouseinstallationtemplates.clickhouse.altinity.com        2025-07-30T19:11:56Z
clickhousekeeperinstallations.clickhouse-keeper.altinity.com   2025-07-30T19:11:56Z
clickhouseoperatorconfigurations.clickhouse.altinity.com       2025-07-30T19:11:56Z

If you want, you can even check the versions of the CRDs. Run this command:

for crd in clickhouseinstallations.clickhouse.altinity.com clickhouseinstallationtemplates.clickhouse.altinity.com clickhousekeeperinstallations.clickhouse-keeper.altinity.com clickhouseoperatorconfigurations.clickhouse.altinity.com; do
  echo "Checking version of CRD $crd..."
  kubectl describe crd $crd | grep Labels
done

You’ll see something like this:

Checking version of CRD clickhouseinstallations.clickhouse.altinity.com...
Labels:       clickhouse.altinity.com/chop=0.25.2
Checking version of CRD clickhouseinstallationtemplates.clickhouse.altinity.com...
Labels:       clickhouse.altinity.com/chop=0.25.2
Checking version of CRD clickhousekeeperinstallations.clickhouse-keeper.altinity.com...
Labels:       clickhouse-keeper.altinity.com/chop=0.25.2
Checking version of CRD clickhouseoperatorconfigurations.clickhouse.altinity.com...
Labels:       clickhouse.altinity.com/chop=0.25.2
                  Labels:

Congratulations! The operator is now upgraded.

If you installed the operator with kubectl

Deploy the Altinity Kubernetes Operator for ClickHouse from the operator’s repo. This command upgrades the installed version to 0.25.2:

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

(If you want to move to a different version, change the version number in the URL and end the command above with something like OPERATOR_NAMESPACE=operator OPERATOR_VERSION=0.24.3 bash.)

You’ll see something like this (there may be slight variations depending on the version you’re installing):

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

As you can see from the first messages in the output, this command updates all of the CRDs.

Verify the installation with this command:

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 the new version of the operator alongside the old one:

altinity/clickhouse-operator:0.25.1
altinity/clickhouse-operator:0.25.2

If you want, you can check the versions of the CRDs. Run this command:

for crd in clickhouseinstallations.clickhouse.altinity.com clickhouseinstallationtemplates.clickhouse.altinity.com clickhousekeeperinstallations.clickhouse-keeper.altinity.com clickhouseoperatorconfigurations.clickhouse.altinity.com; do
  echo "Checking version of CRD $crd..."
  kubectl describe crd $crd | grep Labels
done

You’ll see something like this:

Checking version of CRD clickhouseinstallations.clickhouse.altinity.com...
Labels:       clickhouse.altinity.com/chop=0.25.2
Checking version of CRD clickhouseinstallationtemplates.clickhouse.altinity.com...
Labels:       clickhouse.altinity.com/chop=0.25.2
Checking version of CRD clickhousekeeperinstallations.clickhouse-keeper.altinity.com...
Labels:       clickhouse-keeper.altinity.com/chop=0.25.2
Checking version of CRD clickhouseoperatorconfigurations.clickhouse.altinity.com...
Labels:       clickhouse.altinity.com/chop=0.25.2
                  Labels:

Congratulations! You’ve upgraded the operator to version 0.25.2.