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

Upgrade the Operator

      +

      Users upgrading from Operator version 1.x.x must fully read and understand the resource update step before continuing.

      Upgrading the Couchbase Autonomous Operator is a four-step process:

      Step 1: Download the New Operator Package

      Download the Operator package for the version that you want to upgrade to, and unpack it on the same computer where you normally run kubectl or oc.

      The Operator package contains the YAML configuration files and command-line tools that you will use to upgrade and manage the Operator.

      After you unpack the download, the resulting directory will be titled something like couchbase-autonomous-operator-kubernetes_x.x.x-linux_x86_64. Make sure to cd into this directory before you run the commands in this guide.

      Step 2: Uninstall the Old Operator

      What needs to be uninstalled is dependent on the release you are upgrading from. For example, in releases prior to 1.2.0, the Operator used ClusterRole resources for simplicity of configuration. From 1.2.0 onward, the operator uses Role resources to increase security.

      In general, you’ll need to undo the installation steps in reverse order for the specific version of the Operator you are upgrading from.

      Never delete existing CRDs. If an existing CRD is deleted, any CouchbaseCluster resources will also be deleted.

      To uninstall the current Operator version, instructions are provided for Kubernetes and OpenShift.

      Step 3: Update the CRDs

      In the Operator package you downloaded, you’ll find the updated version of the CRDs: crd.yaml. Between releases of the Operator, the CRDs may undergo small changes that don’t affect backward compatibility, and may add new fields or make changes to validation, therefore must be reinstalled. New CRDs may also be introduced that need installing.

      CRDs are distributed as a single file. During the upgrade procedure, errors are expected during the create operation if a CRD already exists for a resource type.

      To update the CRDs, run the following command:

      • Kubernetes

      • OpenShift

      $ kubectl replace -f crd.yaml
$ kubectl create -f crd.yaml
      $ oc replace -f crd.yaml
$ oc create -f crd.yaml

      Step 4: (Optional) Update the Resources

      If you are not upgrading from Operator 1.x, skip to the next step.

      Couchbase custom resources — such as CouchbaseCluster — changed in a way that is not backwards compatible between Operator versions 1 and 2. There is no Kubernetes-native upgrade path, so we provide a tool to perform this step for you.

      • The following process cannot be undone; ensure your data is fully backed up before continuing.

      • The supported Kubernetes versions are unable run different custom resource versions at the same time. Ensure all instances of the Operator in different namespaces are shut down before continuing.

      • All CouchbaseCluster resources in a namespace must be upgraded before restarting the Operator in that namespace.

      • Upon Operator restart, the cluster will undergo a mandatory rolling upgrade to generate required metadata. Ensure your Kubernetes cluster has the required capacity to support this operation.

      The cbopconv tool takes a version 1 CouchbaseCluster and converts it to version 2. Beginning with Operator version 2, data buckets are defined as separate resources, so cbopconv will automatically create these for you. Clusters and buckets will be automatically populated with explicit label selection. The Operator now persists cluster related data in a ConfigMap and cbopconv will create this for you.

      The resources that cbopconv creates will be a like for like replacement. No new features will be enabled (e.g. managed XDCR or RBAC), with the exception of auto-compaction settings. Be aware that auto-compaction settings will be set to Couchbase server defaults and you may wish to edit them before restarting the Operator in step 5.

      The cbopcfg command is interactive and will check that resources are valid before continuing, display the intended upgraded and new resources, and finally prompt for permission to continue. The user may take this opportunity to review the proposed changes before committing them, or abort the process.

      The cbopconv command is distributed in the Operator package downloaded in step 1. To run the upgrade, in each required namespace, run the following.

      $ ./cbopconv --namespace default

      The requirements for TLS certificates have changed from Operator version 2.0.0 onward. TLS certificates should be upgraded before starting the resource upgrade procedure. Please consult the TLS tutorial for certificate requirements, in particular the mandatory X.509 subject alternative names. The cbopconv tool will refuse to upgrade clusters until this step has been performed. The Operator will handle certificate rotation upon restart in the next step, however it can be performed before the entire upgrade procedure is started.

      You can safely install the Dynamic Admission Controller — on its own — before running this update step. This will provide additional safety by validating updated and new resources for correctness. Separate installation instructions are documented for Kubernetes and OpenShift.

      Step 5: Install the New Operator

      After all the previous steps, you can move on to upgrading the Operator itself. Upgrading the Operator is exactly the same as the initial installation, except that you don’t re-install the CRD. To re-install the Operator in all namespaces where previous instances operated on, see the relevant documentation for Kubernetes or OpenShift.