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.

Considerations for Kubernetes Cluster versions and upgrades¶

Before upgrading the Kubernetes cluster, have a disaster recovery plan in place. Ensure that a backup is taken prior to the upgrade.
Plan your Kubernetes cluster or Operator upgrades with version compatibility in mind.

The Operator is supported and tested on specific Kubernetes versions. Always refer to the Operator’s release notes to verify the supported Kubernetes platforms.

Note that while the Operator might run on unsupported or untested Kubernetes versions, this is not recommended. Doing so can cause various issues, and in some cases, the Operator may fail if deprecated API versions have been removed.
During a Kubernetes cluster upgrade, you must also upgrade the kubelet. It is advisable to drain the nodes hosting the database Pods during the upgrade process.
During the kubelet upgrade, nodes transition between Ready and NotReady states. Also in some scenarios, older nodes may be replaced entirely with new nodes. Ensure that nodes hosting database or proxy pods are functioning correctly and remain in a stable state after the upgrade.
Regardless of the upgrade approach, pods will be rescheduled or recycled. Plan your Kubernetes cluster upgrade accordingly to minimize downtime and service disruption.

Considerations for Operator upgrades¶

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.0.1:
- 1 is the major version
- 0 is the minor version
- 1 is the patch version.
You can only upgrade the Operator to the nearest major.minor version (for example, from 1.0.0 to 1.1.0).

If the current Operator version and the version you want to upgrade to differ by more than one minor version, you need to upgrade step by step. For example, if your current version is 1.0.0 and you want to move to 1.2.0, first upgrade to 1.1.0, then to 1.2.0.

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 older minor versions.
The API version in CRDs is changed from v1alpha to v1. To update to version 0.12.0, you must manually delete the CRDs, apply new ones and recreate the cluster. To keep the data, do the following:
- check that the percona.com/delete-mysql-pvc finalizer is not enabled in deploy/cr.yaml
- don’t delete PVCs manually
- Recreate the cluster with the same name. The Operator then automatically reuses the same PVCs.

Manual upgrade¶

Before you start, export your namespace as an environment variable to simplify the configuration:

export NAMESPACE=<my-namespace>

The upgrade includes the following steps.

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-mysql-operator/v1.0.0/deploy/crd.yaml
kubectl apply --server-side -f https://raw.githubusercontent.com/percona/percona-server-mysql-operator/v1.0.0/deploy/rbac.yaml

Next, update the Percona Server for MySQL 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. Use the following command to update the Operator to the 1.0.0 version:
For single-namespace deploymentFor cluster-wide deployment
Use the following command if you deploy both the Operator and the database cluster in the same namespace:
kubectl apply --server-side -f https://raw.githubusercontent.com/percona/percona-server-mysql-operator/v1.0.0/deploy/operator.yaml
If you deployed the Operator to manage several clusters in different namespaces (the so-called cluster-wide mode), use the following command
kubectl apply --server-side -f https://raw.githubusercontent.com/percona/percona-server-mysql-operator/v1.0.0/deploy/cw-operator.yaml
For previous releases, please refer to the old releases documentation archive
The deployment rollout will be automatically triggered. 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-mysql-operator
```
Note

Labels set on the Operator Pod will not be updated during upgrade.
Update the Custom Resource, the database and components. This step ensures all new features and improvements of the latest release work well within your environment.

Update the Custom Resource, the database and components

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-mysql-operator/v1.0.0/deploy/crd.yaml
kubectl apply --server-side -f https://raw.githubusercontent.com/percona/percona-server-mysql-operator/v1.0.0/deploy/rbac.yaml

Next, update the Operator deployment.
With default parametersWith customized parameters
If you installed the Operator with default parameters, the upgrade can be done as follows:
helm upgrade my-op percona/ps-operator --version 1.0.0
If you installed the Operator with some customized parameters , you should list these options in the upgrade command.

You can get the list of the used options in YAML format with the helm get values my-op -a > my-values.yaml command. Then pass this file directly to the upgrade command as follows:
helm upgrade my-op percona/ps-operator --version 1.0.0 -f my-values.yaml
Update the Custom Resource, the database and components. This step ensures all new features and improvements of the latest release work well within your environment.

Update the Custom Resource, the database and components

Update the Custom Resource, the database and components¶

Update the Custom Resource, the database, backup, proxy 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 updated your PMM Server 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 ps command.

Select the command that matches your setup from the sections below.

MySQL 8.4MySQL 8.0

Asynchronous replication (tech preview)Group replication with HAProxyGroup replication with MySQL Router

Asynchronous replication uses HAProxy and Orchestrator. It does not use MySQL Router.

With PMM Client

kubectl patch ps ps-cluster1 --type=merge --patch '{
   "spec": {
       "crVersion":"1.0.0",
       "mysql":{ "image": "percona/percona-server:8.4.6-6.1" },
       "proxy":{
          "haproxy":{ "image": "percona/haproxy:2.8.15" }
       },
       "orchestrator":{ "image": "percona/percona-orchestrator:3.2.6-18" },
       "backup":{ "image": "percona/percona-xtrabackup:8.4.0-4.1" },
       "toolkit":{ "image": "percona/percona-toolkit:3.7.0-2" },
       "pmm": { "image": "percona/pmm-client:3.4.1" }
   }}'

Without PMM Client

kubectl patch ps ps-cluster1 --type=merge --patch '{
   "spec": {
       "crVersion":"1.0.0",
       "mysql":{ "image": "percona/percona-server:8.4.6-6.1" },
       "proxy":{
          "haproxy":{ "image": "percona/haproxy:2.8.15" }
       },
       "orchestrator":{ "image": "percona/percona-orchestrator:3.2.6-18" },
       "backup":{ "image": "percona/percona-xtrabackup:8.4.0-4.1" },
       "toolkit":{ "image": "percona/percona-toolkit:3.7.0-2" }
   }}'

Group replication with HAProxy uses HAProxy only. It does not use MySQL Router or Orchestrator.

With PMM Client

kubectl patch ps ps-cluster1 --type=merge --patch '{
   "spec": {
       "crVersion":"1.0.0",
       "mysql":{ "image": "percona/percona-server:8.4.6-6.1" },
       "proxy":{
          "haproxy":{ "image": "percona/haproxy:2.8.15" }
       },
       "backup":{ "image": "percona/percona-xtrabackup:8.4.0-4.1" },
       "toolkit":{ "image": "percona/percona-toolkit:3.7.0-2" },
       "pmm": { "image": "percona/pmm-client:3.4.1" }
   }}'

Without PMM Client

kubectl patch ps ps-cluster1 --type=merge --patch '{
   "spec": {
       "crVersion":"1.0.0",
       "mysql":{ "image": "percona/percona-server:8.4.6-6.1" },
       "proxy":{
          "haproxy":{ "image": "percona/haproxy:2.8.15" }
       },
       "backup":{ "image": "percona/percona-xtrabackup:8.4.0-4.1" },
       "toolkit":{ "image": "percona/percona-toolkit:3.7.0-2" }
   }}'

Group replication with MySQL Router uses MySQL Router only. It does not use HAProxy or Orchestrator.

With PMM Client

kubectl patch ps ps-cluster1 --type=merge --patch '{
   "spec": {
       "crVersion":"1.0.0",
       "mysql":{ "image": "percona/percona-server:8.4.6-6.1" },
       "proxy":{
          "router":{ "image": "percona/percona-mysql-router:8.4.6" }
       },
       "backup":{ "image": "percona/percona-xtrabackup:8.4.0-4.1" },
       "toolkit":{ "image": "percona/percona-toolkit:3.7.0-2" },
       "pmm": { "image": "percona/pmm-client:3.4.1" }
   }}'

Without PMM Client

kubectl patch ps ps-cluster1 --type=merge --patch '{
   "spec": {
       "crVersion":"1.0.0",
       "mysql":{ "image": "percona/percona-server:8.4.6-6.1" },
       "proxy":{
          "router":{ "image": "percona/percona-mysql-router:8.4.6" }
       },
       "backup":{ "image": "percona/percona-xtrabackup:8.4.0-4.1" },
       "toolkit":{ "image": "percona/percona-toolkit:3.7.0-2" }
   }}'

Asynchronous replication (tech preview)Group replication with HAProxyGroup replication with MySQL Router

Asynchronous replication uses HAProxy and Orchestrator. It does not use MySQL Router.

With PMM Client

kubectl patch ps ps-cluster1 --type=merge --patch '{
   "spec": {
       "crVersion":"1.0.0",
       "mysql":{ "image": "percona/percona-server:8.0.43-34.1" },
       "proxy":{
          "haproxy":{ "image": "percona/haproxy:2.8.15" }
       },
       "orchestrator":{ "image": "percona/percona-orchestrator:3.2.6-18" },
       "backup":{ "image": "percona/percona-xtrabackup:8.0.35-34.1" },
       "toolkit":{ "image": "percona/percona-toolkit:3.7.0-2" },
       "pmm": { "image": "percona/pmm-client:3.4.1" }
   }}'

Without PMM Client

kubectl patch ps ps-cluster1 --type=merge --patch '{
   "spec": {
       "crVersion":"1.0.0",
       "mysql":{ "image": "percona/percona-server:8.0.43-34.1" },
       "proxy":{
          "haproxy":{ "image": "percona/haproxy:2.8.15" }
       },
       "orchestrator":{ "image": "percona/percona-orchestrator:3.2.6-18" },
       "backup":{ "image": "percona/percona-xtrabackup:8.0.35-34.1" },
       "toolkit":{ "image": "percona/percona-toolkit:3.7.0-2" }
   }}'

Group replication with HAProxy uses HAProxy only. It does not use MySQL Router or Orchestrator.

With PMM Client

kubectl patch ps ps-cluster1 --type=merge --patch '{
   "spec": {
       "crVersion":"1.0.0",
       "mysql":{ "image": "percona/percona-server:8.0.43-34.1" },
       "proxy":{
          "haproxy":{ "image": "percona/haproxy:2.8.15" }
       },
       "backup":{ "image": "percona/percona-xtrabackup:8.0.35-34.1" },
       "toolkit":{ "image": "percona/percona-toolkit:3.7.0-2" },
       "pmm": { "image": "percona/pmm-client:3.4.1" }
   }}'

Without PMM Client

kubectl patch ps ps-cluster1 --type=merge --patch '{
   "spec": {
       "crVersion":"1.0.0",
       "mysql":{ "image": "percona/percona-server:8.0.43-34.1" },
       "proxy":{
          "haproxy":{ "image": "percona/haproxy:2.8.15" }
       },
       "backup":{ "image": "percona/percona-xtrabackup:8.0.35-34.1" },
       "toolkit":{ "image": "percona/percona-toolkit:3.7.0-2" }
   }}'

Group replication with MySQL Router uses MySQL Router only. It does not use HAProxy or Orchestrator.

With PMM Client

kubectl patch ps ps-cluster1 --type=merge --patch '{
   "spec": {
       "crVersion":"1.0.0",
       "mysql":{ "image": "percona/percona-server:8.0.43-34.1" },
       "proxy":{
          "router":{ "image": "percona/percona-mysql-router:8.0.43" }
       },
       "backup":{ "image": "percona/percona-xtrabackup:8.0.35-34.1" },
       "toolkit":{ "image": "percona/percona-toolkit:3.7.0-2" },
       "pmm": { "image": "percona/pmm-client:3.4.1" }
   }}'

Without PMM Client

kubectl patch ps ps-cluster1 --type=merge --patch '{
   "spec": {
       "crVersion":"1.0.0",
       "mysql":{ "image": "percona/percona-server:8.0.43-34.1" },
       "proxy":{
          "router":{ "image": "percona/percona-mysql-router:8.0.43" }
       },
       "backup":{ "image": "percona/percona-xtrabackup:8.0.35-34.1" },
       "toolkit":{ "image": "percona/percona-toolkit:3.7.0-2" }
   }}'

Last update: December 2, 2025
Created: December 2, 2025