How to carry on low-level manual upgrades of Percona XtraDB Cluster¶

The default and recommended way to upgrade the database cluster is using the Smart Update strategy. The Operator controls how objects are updated and restarts the Pods in a proper order during the database upgrade or for other events that require the cluster update. To these events belong ConfigMap updates, password rotation or changing resource values.

In some cases running an automatic upgrade of Percona XtraDB Cluster is not an option. For example, if the database upgrade impacts your application, you may want to have a full control over the upgrade process.

Running a manual database upgrade allows you to do just that. You can use one of the following upgrade strategies:

Rolling Update, initiated manually and controlled by Kubernetes . Note that the order of Pods restart may not be optimal from the Percona Server for MongoDB point of view.
On Delete, done by Kubernetes on per-Pod basis when Pods are manually deleted.

Before you start¶

We recommend to update PMM Server before upgrading PMM Client.
If you are using custom configuration for HAProxy, check the HAProxy configuration file provided by the Operator before the upgrade. Find the haproxy-global.cfg for the Operator version 1.17.0 here ).

Make sure that your custom config is still compatible with the new variant, and make necessary additions, if needed.

Rolling Update strategy and semi-automatic updates¶

To run a semi-automatic update of Percona XtraDB Cluster, do the following:

Check the version of the Operator you have in your Kubernetes environment. If you need to update it, refer to the Operator upgrade guide.
Edit the deploy/cr.yaml file and set the updateStrategy key to RollingUpdate.
Check the current version of the Custom Resource and what versions of the database and cluster components are compatible with it. Use the following command:
```
$ curl https://check.percona.com/versions/v1/pxc-operator/1.17.0 |jq -r ‘.versions[].matrix’
```
You can also find this information in the Versions compatibility matrix.

Update the Custom Resource, the database, backup, proxy and PMM Client image names with a newer version tag. 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 pxc command.

With PMM ClientWithout PMM Client

For Percona XtraDB Cluster 8.0For Percona XtraDB Cluster 5.7

$ kubectl patch pxc cluster1 --type=merge --patch '{
   "spec": {
       "crVersion":"1.17.0",
       "pxc":{ "image": "percona/percona-xtradb-cluster:8.0.41-32.1" },
       "proxysql": { "image": "percona/proxysql2:2.7.1-1" },
       "haproxy":  { "image": "percona/haproxy:2.8.14" },
       "backup":   { "image": "percona/percona-xtradb-cluster-operator:1.17.0-pxc8.0-backup-pxb8.0.35" },
       "logcollector": { "image": "percona/percona-xtradb-cluster-operator:1.17.0-logcollector-fluentbit4.0.0" },
       "pmm":      { "image": "percona/pmm-client:2.44.0" }
   }}'

$ kubectl patch pxc cluster1 --type=merge --patch '{
   "spec": {
       "crVersion":"1.17.0",
       "pxc":{ "image": "percona/percona-xtradb-cluster:5.7.44-31.65" },
       "proxysql": { "image": "percona/proxysql2:2.7.1-1" },
       "haproxy":  { "image": "percona/haproxy:2.8.14" },
       "backup":   { "image": "percona/percona-xtradb-cluster-operator:1.17.0-pxc5.7-backup-pxb2.4.29" },
       "logcollector": { "image": "percona/percona-xtradb-cluster-operator:1.17.0-logcollector-fluentbit4.0.0" },
       "pmm":      { "image": "percona/pmm-client:2.44.0" }
   }}'

For Percona XtraDB Cluster 8.0For Percona XtraDB Cluster 5.7

$ kubectl patch pxc cluster1 --type=merge --patch '{
   "spec": {
       "crVersion":"1.17.0",
       "pxc":{ "image": "percona/percona-xtradb-cluster:8.0.41-32.1" },
       "proxysql": { "image": "percona/proxysql2:2.7.1-1" },
       "haproxy":  { "image": "percona/haproxy:2.8.14" },
       "backup":   { "image": "percona/percona-xtradb-cluster-operator:1.17.0-pxc8.0-backup-pxb8.0.35" },
       "logcollector": { "image": "percona/percona-xtradb-cluster-operator:1.17.0-logcollector-fluentbit4.0.0" }
   }}'

$ kubectl patch pxc cluster1 --type=merge --patch '{
   "spec": {
       "crVersion":"1.17.0",
       "pxc":{ "image": "percona/percona-xtradb-cluster:5.7.44-31.65" },
       "proxysql": { "image": "percona/proxysql2:2.7.1-1" },
       "haproxy":  { "image": "percona/haproxy:2.8.14" },
       "backup":   { "image": "percona/percona-xtradb-cluster-operator:1.17.0-pxc5.7-backup-pxb2.4.29" },
       "logcollector": { "image": "percona/percona-xtradb-cluster-operator:1.17.0-logcollector-fluentbit4.0.0" }
   }}'

After you applied the patch, the deployment rollout will be triggered automatically. You can track the rollout process in real time using the kubectl rollout status command with the name of your cluster:
```
$ kubectl rollout status sts cluster1-pxc
```

Manual upgrade (the On Delete strategy)¶

To update Percona XtraDB Cluster manually, do the following:

Check the version of the Operator you have in your Kubernetes environment. If you need to update it, refer to the Operator upgrade guide.
Edit the deploy/cr.yaml file and set the updateStrategy key to OnDelete.
Check the current version of the Custom Resource and what versions of the database and cluster components are compatible with it. Use the following command:
```
$ curl https://check.percona.com/versions/v1/pxc-operator/1.17.0 |jq -r ‘.versions[].matrix’
```
You can also find this information in the Versions compatibility matrix.

Update the Custom Resource, the database, backup, proxy and PMM Client image names with a newer version tag. 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 pxc command.

With PMM ClientWithout PMM Client

For Percona XtraDB Cluster 8.0For Percona XtraDB Cluster 5.7

$ kubectl patch pxc cluster1 --type=merge --patch '{
   "spec": {
       "crVersion":"1.17.0",
       "pxc":{ "image": "percona/percona-xtradb-cluster:8.0.41-32.1" },
       "proxysql": { "image": "percona/proxysql2:2.7.1-1" },
       "haproxy":  { "image": "percona/haproxy:2.8.14" },
       "backup":   { "image": "percona/percona-xtradb-cluster-operator:1.17.0-pxc8.0-backup-pxb8.0.35" },
       "logcollector": { "image": "percona/percona-xtradb-cluster-operator:1.17.0-logcollector-fluentbit4.0.0" },
       "pmm":      { "image": "percona/pmm-client:2.44.0" }
   }}'

$ kubectl patch pxc cluster1 --type=merge --patch '{
   "spec": {
       "crVersion":"1.17.0",
       "pxc":{ "image": "percona/percona-xtradb-cluster:5.7.44-31.65" },
       "proxysql": { "image": "percona/proxysql2:2.7.1-1" },
       "haproxy":  { "image": "percona/haproxy:2.8.14" },
       "backup":   { "image": "percona/percona-xtradb-cluster-operator:1.17.0-pxc5.7-backup-pxb2.4.29" },
       "logcollector": { "image": "percona/percona-xtradb-cluster-operator:1.17.0-logcollector-fluentbit4.0.0" },
       "pmm":      { "image": "percona/pmm-client:2.44.0" }
   }}'

For Percona XtraDB Cluster 8.0For Percona XtraDB Cluster 5.7

$ kubectl patch pxc cluster1 --type=merge --patch '{
   "spec": {
       "crVersion":"1.17.0",
       "pxc":{ "image": "percona/percona-xtradb-cluster:8.0.41-32.1" },
       "proxysql": { "image": "percona/proxysql2:2.7.1-1" },
       "haproxy":  { "image": "percona/haproxy:2.8.14" },
       "backup":   { "image": "percona/percona-xtradb-cluster-operator:1.17.0-pxc8.0-backup-pxb8.0.35" },
       "logcollector": { "image": "percona/percona-xtradb-cluster-operator:1.17.0-logcollector-fluentbit4.0.0" }
   }}'

$ kubectl patch pxc cluster1 --type=merge --patch '{
   "spec": {
       "crVersion":"1.17.0",
       "pxc":{ "image": "percona/percona-xtradb-cluster:5.7.44-31.65" },
       "proxysql": { "image": "percona/proxysql2:2.7.1-1" },
       "haproxy":  { "image": "percona/haproxy:2.8.14" },
       "backup":   { "image": "percona/percona-xtradb-cluster-operator:1.17.0-pxc5.7-backup-pxb2.4.29" },
       "logcollector": { "image": "percona/percona-xtradb-cluster-operator:1.17.0-logcollector-fluentbit4.0.0" }
   }}'

The Pod with the newer Percona XtraDB Cluster image will start after you delete it. Delete targeted Pods manually one by one to make them restart in desired order:
1. Delete the Pod using its name with the command like the following one:
```
$ kubectl delete pod cluster1-pxc-2
```
2. Wait until Pod becomes ready:
```
$ kubectl get pod cluster1-pxc-2
```
  The output should be like this:
```
NAME             READY   STATUS    RESTARTS   AGE
cluster1-pxc-2   1/1     Running   0          3m33s
```

The update process is successfully finished when all Pods have been restarted.

Last update: 2025-08-07