Upgrade the Operator and CRD¶

To update the Operator, you need to update the Custom Resource Definition (CRD) and the Operator deployment. Also we recommend to update the Kubernetes database cluster configuration by updating the Custom Resource and the database components to the latest version. This step ensures that all new features that come with the Operator release work in your environment.

The upgrade process is similar for all installation methods, including Helm and OLM.

Considerations¶

The Operator version has three digits separated by a dot (.) in the format major.minor.patch. Here’s how you can understand the version 1.18.0:
- 1 - major version
- 18 - minor version
- 0 - patch version
You can only upgrade the Operator to the nearest major.minor version. For example, from 1.18.0 to 1.19.0. To upgrade to a newer version, which differs from the current minor.major version by more than one, you need to make several incremental upgrades sequentially. For example, to upgrade the Operator from 1.17.0 to 1.19.1, you need to first upgrade it to 1.18.0, and then to 1.19.1.

Patch versions don’t influence the upgrade, so you can safely move from 1.18.0 to 1.19.1.

Check the Release notes index for the list of the Operator versions.
CRD supports the last 3 minor versions of the Operator. This means it is compatible with the newest Operator version and the two previous minor versions. If the Operator is older than the CRD by no more than two versions, you should be able to continue using the old Operator version. But updating the CRD and Operator is the recommended path.
Starting from version 1.14.0, the Operator configures replica set members using local fully-qualified domain names (FQDN). Before this version, if you exposed a replica set, it used the exposed IP addresses in the replica set configuration. Therefore, if you upgrade to version 1.14.0 and your replica set is exposed, the replica set configuration will change to use FQDN. To prevent such reconfiguration, set the clusterServiceDNSMode Custom Resource option to External before the upgrade.
Starting with version 1.12.0, the Operator no longer has a separate API version for each release in CRD. Instead, the CRD has the API version v1. Therefore, if you installed the CRD when the Operator version was older than 1.12.0, you must update the API version in the CRD manually to run the upgrade. To check your CRD version, use the following command:
```
$ kubectl get crd perconaservermongodbs.psmdb.percona.com -o yaml | yq .status.storedVersions
```
Sample output
```
- v1-11-0
- v1
```
If the CRD version is other than v1 or has several entries, run the manual update.
Starting from the Operator version 1.15.0, the spec.mongod section (deprecated since 1.12.0) is finally removed from the Custom Resource configuration. If you have encryption disabled using the deprecated mongod.security.enableEncryption option, you need to set encryption as disabled via the custom configuration before the upgrade:
```
spec:
  ...
  replsets:
    - name: rs0
      ...
      configuration: |
        security:
          enableEncryption: false
        ...
```
Starting from the Operator version 1.16.0, MongoDB 4.4 support in the Operator has reached its end-of-life. Make sure that you have a supported MongoDB version before upgrading the Operator to 1.16.0 (you can use major version upgrade functionality to fix it.
The Operator versions 1.19.0 and 1.19.1 have a recommended MongoDB version set to 7.0 because point-in-time recovery may fail on MongoDB 8.0 if sharding is enabled and the Operator version is 1.19.x. Therefore, upgrading to Operator 1.19.0/1.19.1 is not recommended for sharded MongoDB 8.0 clusters.

Upgrade manually¶

The upgrade includes the following steps.

For Operators older than v1.12.0: Update the API version in the Custom Resource Definition :

ManuallyVia kubectl patch

$ kubectl proxy &  \
$ curl \
       --header "Content-Type: application/json-patch+json" \
       --request PATCH \
       --data '[{"op": "replace", "path": "/status/storedVersions", "value":["v1"]}]' --url "http://localhost:8001/apis/apiextensions.k8s.io/v1/customresourcedefinitions/perconaservermongodbs.psmdb.percona.com/status"

Expected output

{
 {...},
  "status": {
    "storedVersions": [
      "v1"
    ]
  }
}

$ kubectl patch customresourcedefinitions perconaservermongodbs.psmdb.percona.com --subresource='status' --type='merge' -p '{"status":{"storedVersions":["v1"]}}'

Expected output

customresourcedefinition.apiextensions.k8s.io/perconaservermongodbs.psmdb.percona.com patched

Update the Custom Resource Definition for the Operator and the Role-based access control. Take the latest versions from the official repository on GitHub with the following commands:

$ kubectl apply --server-side -f https://raw.githubusercontent.com/percona/percona-server-mongodb-operator/v1.19.1/deploy/crd.yaml
$ kubectl apply -f https://raw.githubusercontent.com/percona/percona-server-mongodb-operator/v1.19.1/deploy/rbac.yaml

Next, update the Percona Server for MongoDB Operator Deployment in Kubernetes by changing the container image of the Operator Pod to the latest version. Find the image name for the current Operator release in the list of certified images. Then apply a patch to the Operator Deployment and specify the image name and version. Use the following command to update the Operator Deployment to the 1.19.1 version:
```
$ kubectl patch deployment percona-server-mongodb-operator \
   -p'{"spec":{"template":{"spec":{"containers":[{"name":"percona-server-mongodb-operator","image":"percona/percona-server-mongodb-operator:1.19.1"}]}}}}'
```
The deployment rollout will be automatically triggered by the applied patch. You can track the rollout process in real time with the kubectl rollout status command with the name of your cluster:
```
$ kubectl rollout status deployments percona-server-mongodb-operator
```
Note

Labels set on the Operator Pod will not be updated during upgrade.
Update the Custom Resource version, the database, the backup and PMM Client image names with a newer version tag. This step ensures all new features and improvements of the latest release work well within your environment.

Find the image names in the list of certified images.

We recommend to update the PMM Server before the upgrade of PMM Client. If you haven’t done it yet, exclude PMM Client from the list of images to update.

Since this is a working cluster, the way to update the Custom Resource is to apply a patch with the kubectl patch psmdb command.

For example, to update the cluster with the name my-cluster-name to the 1.19.1 version, the command is as follows:
With PMM ClientWithout PMM Client
$ kubectl patch psmdb my-cluster-name --type=merge --patch '{ "spec": { "crVersion":"1.19.1", "image": "percona/percona-server-mongodb:7.0.14-8", "backup": { "image": "percona/percona-backup-mongodb:2.8.0" }, "pmm": { "image": "percona/pmm-client:2.44.0" } }}'
$ kubectl patch psmdb my-cluster-name --type=merge --patch '{ "spec": { "crVersion":"1.19.1", "image": "percona/percona-server-mongodb:7.0.14-8", "backup": { "image": "percona/percona-backup-mongodb:2.8.0" } }}'

Upgrade via helm¶

If you have installed the Operator using Helm, you can upgrade the Operator with the helm upgrade command.

Update the Custom Resource Definition for the Operator, taking it from the official repository on Github, and do the same for the Role-based access control:

$ kubectl apply --server-side -f https://raw.githubusercontent.com/percona/percona-server-mongodb-operator/v1.19.1/deploy/crd.yaml
$ kubectl apply -f https://raw.githubusercontent.com/percona/percona-server-mongodb-operator/v1.19.1/deploy/rbac.yaml

If you installed the Operator with no customized parameters , the upgrade can be done as follows:
```
$ helm upgrade my-op percona/psmdb-operator --version 1.19.1
```
The my-op parameter in the above example is the name of a release object which which you have chosen for the Operator when installing its Helm chart.

If the Operator was installed with some customized parameters , you should list these options in the upgrade command.

You can get list of used options in YAML format with the helm get values my-op -a > my-values.yaml command, and this file can be directly passed to the upgrade command as follows:
```
$ helm upgrade my-op percona/psmdb-operator --version 1.19.1 -f my-values.yaml
```

Upgrade via Operator Lifecycle Manager (OLM)¶

If you have installed the Operator on the OpenShift platform using OLM, you can upgrade the Operator within it.

List installed Operators for your Namespace to see if there are upgradable items.
Click the “Upgrade available” link to see upgrade details, then click “Preview InstallPlan” button, and finally “Approve” to upgrade the Operator.

Last update: 2025-04-25