Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

A newer version of this documentation is available.

View Latest

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:

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

      • Immediate upgrades upgrade all pods at the same time

      This 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

      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 affect on client performance as all pods in the cluster are undergoing upgrade at the same time.

      You can balance time against risk by tailoring rolling upgrades 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.

      Ideally, the Operator should replace an old pod for a new one, retaining any existing persistent storage, then performing a delta-node recovery to perform a fast upgrade. Couchbase Server requires an offline upgrade task to migrate old data structures to new ones before starting the service. The Operator is unable — at present — to perform this upgrade action, therefore it must create new storage for new pods and copy data to the new storage. Any time required for an upgrade must be considered when planning an upgrade.

      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.