Couchbase Upgrades

      The Operator allows a managed Couchbase cluster to be upgraded. This includes upgrading the Couchbase Server version and also related Kubernetes resources.

      Upgrading Couchbase Server

      The Couchbase Server version can be upgraded by the Operator.

      Upgrades may be performed using one of a number of different strategies as specified by couchbaseclusters.spec.upgradeStrategy in the CouchbaseCluster resource:

      • DeltaRecovery performs an in-place upgrade on one, or more, pods at a time

      • Rolling upgrades upgrade one, or more, pods at a time

      • Immediate upgrades upgrade all pods at the same time

      For rolling and immediate upgrades, the process is as follows:

      • One or more candidate pods are selected

      • New pods are created for each of the candidates with the same Couchbase configuration as the existing ones

      • Data is rebalanced from the old pods to the new ones

      • The candidate pods are deleted

      For delta recovery, the process is as follows:

      • One or more candidate pods are selected

      • Each candidate is failed over and updated with the new version

      • Each PVC associated with the candidate is updated with the new version

      • Operator performs a delta recovery on the candidate

      When using rolling upgrades, performing the operation one pod at a time, risk is limited in the event of an issue, and can be rolled back. A rolling upgrade requires the least network and compute overhead, so will affect client operation less.

      When using immediate upgrades, there is a greater risk, and requires greater resource during the upgrade, however the operation itself is significantly faster. Immediate upgrades may have an undesired effect on client performance as all pods in the cluster are undergoing upgrade at the same time.

      When using delta recovery, the pods and PVCs are updated to use the new version. This is quicker than a rolling upgrade and will retain the same PVCs (data retained). Delta recovery cannot be used in conjunction with immediate upgrades. The validator will fail the request if immediate upgrade strategy and delta recovery upgrade process are both specified. The same pod names and networking settings will be retained when the pod is restarted by the operator.

      You can balance time against risk by tailoring rolling updates with the couchbaseclusters.spec.rollingUpgrade configuration parameter. This allows rolling upgrades to upgrade 2 pods at a time, or 20% of the cluster at a time, for example.

      Couchbase Server Upgrade Constraints

      Not all upgrade paths are supported by Couchbase Server. The Operator enforces the following constraints on Couchbase Server version upgrades.

      • Upgrades must be an upgrade, downgrades are not supported due to potential protocol incompatibility, for example:

        • 5.5.0 to 5.5.3 is allowed

        • 5.5.3 to 5.5.0 is not allowed

      • Upgrades must not cross multiple major version boundaries, for example:

        • 5.x.x to 6.x.x is allowed

        • 5.x.x to 7.x.x is not allowed

      • Couchbase Server versions cannot be changed during an upgrade

      Refer to the Couchbase Server upgrade documentation for more information about direct upgrade paths.

      Modifying the Couchbase Server version during an upgrade is permitted only if the end result is a roll-back to the previous version.

      Upgrading Pods

      In Kubernetes pods are immutable — they cannot be modified once they are created. If a CouchbaseCluster configuration value is modified that would also modify the underlying pod, then the Operator must create a new pod to replace the old one that does not match the required specification. Pod upgrades work in exactly the same way as an upgrade to the Couchbase Server version; in fact upgrading the Couchbase Server image is just a subset of modifying any other pod specification parameter.

      The Operator compares the required pod specification with the one used to create the original pod, a candidate is selected if the specifications differ. The Operator therefore can perform the following tasks:

      This mechanism allows a cluster to be used from evaluation right up to production, with features enabled as they are required, without service disruption.

      Upgrading Persistent Volumes

      Online persistent volume resizing support is not yet available in all supported versions of Kubernetes. As a result the Operator supports persistent volume resizing using a similar mechanism to Upgrading Pods. The Operator will detect a modification to the specification of a persistent volume template and schedule a pod upgrade in order to satisfy the request.

      During delta recovery, the PVC will be updated to include the updated image and couchbase server versions. The size of the PVC and data within it will not be edited.