Upgrade

There are two independent upgrades, and they are not the same operation:

  • The operator is upgraded by OLM, which replaces the operator's ClusterServiceVersion. This does not restart your database pods.
  • The operand — the ClickHouse® engine running in your clusters — is upgraded by changing the ClickHouseInstallation resource. This does restart database pods, one replica at a time.

Upgrade the operator first. A newer operator is expected to manage an older operand; the reverse is not.

Upgrade the operator

If the Subscription was created with installPlanApproval: Automatic, OLM upgrades the operator as soon as a newer version appears in the stable channel. With Manual, an InstallPlan is created and waits for approval:

kubectl -n operators get installplan
kubectl -n operators patch installplan <installplan-name> --type merge -p '{"spec":{"approved":true}}'

Upgrade from v4.4.x to v4.5.1

v4.5.1 moves the operator to a new upstream base (Altinity clickhouse-operator 0.27.4; v4.4.x was built on 0.20.0), updates the default ClickHouse® server image from 25.8.33.6 (25.8 LTS) to 26.8.39.19 (26.8 LTS), and adds the ClickHouseKeeperInstallation resource. What to expect:

  • Default server image moves to 26.8.39.19. Instances whose pod templates omit a container image roll to the new default 26.8.39.19 image automatically when the operator updates their StatefulSets. Instances that pin an explicit 25.8.x server image in spec.templates.podTemplates keep that image until you update image to the <registry>/eco-oss/clickhouse-group/clickhouse-server:v26.8.39.19-780010d9 tag configured in the v4.5.1 operator Deployment's CK_SERVER_IMAGE environment variable.

  • One rolling restart of every instance. The new operator renders the ClickHouse® host configuration and StatefulSets differently from the old one, so after the upgrade it updates each instance once, one host at a time. Replicated instances stay available; an instance with a single replica is unavailable while its pod restarts. Plan the operator upgrade for a maintenance window if you run single-replica instances. Wait until every instance reports Completed before you change instances or start other maintenance:

    kubectl get chi -A
  • Data volumes are kept. The restart reuses each host's PersistentVolumeClaim; no data is copied or moved.

  • Keeper quorums you built yourself keep working. The operator does not manage a hand-built Keeper StatefulSet and does not touch it during the upgrade, and instances that list its members under zookeeper.nodes keep using it. Moving to an operator-managed quorum is optional; see Migrate from a manual Keeper StatefulSet to ClickHouseKeeperInstallation.

  • The new CRD is installed with the operator. clickhousekeeperinstallations.clickhouse-keeper.altinity.com appears when the v4.5.1 operator is installed; the existing three CRDs are updated in place.

WARNING

Rolling the operator back to v4.4.x after you have created any ClickHouseKeeperInstallation is not supported. The v4.4.x operator does not know that resource: the Keeper quorum would no longer be reconciled, and instances that refer to it under zookeeper.keeper would lose their coordination settings at the next reconcile.


ClickHouse is a registered trademark of ClickHouse, Inc. https://clickhouse.com

Alauda is an independent vendor. This product is not affiliated with, endorsed by, or sponsored by ClickHouse, Inc. All trademarks are the property of their respective owners and are used here for identification purposes only.