Upgrading the Operator
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.3. To upgrade to a different version, simply replace 0.25.3 with a different version number.
WARNING
As you upgrade the operator, do not, under any circumstances, delete the Custom Resource Definitions (CRDs). If you do, Kubernetes will attempt to delete any chi and chk resources you’ve created.
To sum up: Do not, under any circumstances, delete the CRDs.
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:
- Upgrade the Helm chart, then upgrade the operator’s CRDs.
- 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.
NOTE: Our examples here upgrade the operator from version 0.25.1 to 0.25.3. If you’re upgrading to a different version (you’re moving from 0.24.2 to 0.24.5, for example), use the --version option on the helm command:
helm upgrade --version 0.24.5 clickhouse-operator altinity-docs/altinity-clickhouse-operator -n operator
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.3
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.3/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.3
Checking version of CRD clickhouseinstallationtemplates.clickhouse.altinity.com...
Labels: clickhouse.altinity.com/chop=0.25.3
Checking version of CRD clickhousekeeperinstallations.clickhouse-keeper.altinity.com...
Labels: clickhouse-keeper.altinity.com/chop=0.25.3
Checking version of CRD clickhouseoperatorconfigurations.clickhouse.altinity.com...
Labels: clickhouse.altinity.com/chop=0.25.3
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.3
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.3/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.3
Checking version of CRD clickhouseinstallationtemplates.clickhouse.altinity.com...
Labels: clickhouse.altinity.com/chop=0.25.3
Checking version of CRD clickhousekeeperinstallations.clickhouse-keeper.altinity.com...
Labels: clickhouse-keeper.altinity.com/chop=0.25.3
Checking version of CRD clickhouseoperatorconfigurations.clickhouse.altinity.com...
Labels: clickhouse.altinity.com/chop=0.25.3
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.3:
curl -s https://raw.githubusercontent.com/Altinity/clickhouse-operator/refs/heads/0.25.3/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 might see the old version of the operator alongside the new one:
altinity/clickhouse-operator:0.25.1
altinity/clickhouse-operator:0.25.3
This is because the previous version of the operator is terminating. After a short while, running this command will show only version 0.25.3.
If you want, you can also 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.3
Checking version of CRD clickhouseinstallationtemplates.clickhouse.altinity.com...
Labels: clickhouse.altinity.com/chop=0.25.3
Checking version of CRD clickhousekeeperinstallations.clickhouse-keeper.altinity.com...
Labels: clickhouse-keeper.altinity.com/chop=0.25.3
Checking version of CRD clickhouseoperatorconfigurations.clickhouse.altinity.com...
Labels: clickhouse.altinity.com/chop=0.25.3
Labels:
Congratulations! You’ve upgraded the operator to version 0.25.3.