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
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
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
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:
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
To update the CRDs, run the following command:
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.
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
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.
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.
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.
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.