Upgrading Percona Server for MySQL¶

You can decide how to run the database upgrades:

Automatically - the Operator periodically checks for new versions of the database images and for valid image paths and automatically updates your deployment with the latest, recommended or a specific version of the database and other components included. To do so, the Operator queries a special Version Service server at scheduled times. If the current version should be upgraded, the Operator updates the Custom Resource to reflect the new image paths and sequentially deletes Pods, allowing StatefulSet to redeploy the cluster Pods with the new image.
Manually - you manually update the Custom Resource and specify the desired version of the database. Then, depending on the configured update strategy, either the Operator automatically updates the deployment to this version. Or you manually trigger the upgrade by deleting Pods.

The way to instruct the Operator how it should run the database upgrades is to set the upgradeOptions.apply Custom Resource option to one of the following:

Never - the Operator never makes automatic upgrades. You must upgrade the Custom Resource and images manually.
Disabled - the Operator doesn’t not carry on upgrades automatically. You must upgrade the Custom Resource and images manually.
Recommended - the Operator automatically updates the database and components to the version flagged as Recommended.
Latest - the Operator automatically updates the database and components to the most recent available version
version - specify the specific database version that you want to update to in the format 8.4.6-6.1, 8.0.43-34.1, etc. The Operator updates the database to it automatically. Find available versions in the list of certified images.

For previous versions, refer to the old releases documentation archive .

Minor upgrade to a specific version¶

Assumptions¶

For the procedures in this tutorial, we assume that you have set up the Smart Update strategy to update the objects in your database cluster.

Before you start¶

Before updating the database, complete the following preparation steps:

Check the version of the Operator you have in your Kubernetes environment. If you need to update it, refer to the Operator upgrade guide.
Check the Custom Resource manifest configuration to ensure the following:
- spec.updateStrategy option is set to SmartUpdate
- spec.upgradeOptions.apply option is set to Never or Disabled (this means that the Operator will not carry on upgrades automatically)
```
...
spec:
  updateStrategy: SmartUpdate
  upgradeOptions:
    apply: Disabled
    ...
```
Before selecting the update command, identify your current setup:
- MySQL version: Check your current mysql.image value in your Custom Resource
- Replication type: Check the mysql.clusterType option in your Custom Resource (async or group)
- Proxy type: For async replication, you use HAProxy. For group replication, check if proxy.haproxy.enabled or proxy.router.enabled is set to true in your Custom Resource
We recommend to update PMM Server before upgrading PMM Client.

Update commands¶

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" }
   }}'

Track the upgrade progress¶

After applying the patch, 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 sts ps-cluster1-ps

Automated upgrade¶

Assumptions¶

For the procedures in this tutorial, we assume that you have set up the Smart Update strategy to update the objects in your database cluster.

Before you start¶

We recommend to update PMM Server before upgrading PMM Client.

Procedure¶

Check the version of the Operator you have in your Kubernetes environment. If you need to update it, refer to the Operator upgrade guide
Change spec.crVersion option to match the version of the Custom Resource Definition upgrade while upgrading the Operator:
```
...
spec:
  crVersion: 1.0.0
  ...
```
Note

If you don’t update crVersion, minor version upgrade is the only one to occur. For example, the image percona-server:8.0.30-22 can be upgraded to percona-server:8.0.32-24.
Make sure that spec.updateStrategy option is set to SmartUpdate.
Change the upgradeOptions.apply option from Disabled to one of the following values:
- Recommended - the Operator will choose the most recent version of software flagged as “Recommended”
- Latest - automatic upgrades will choose the most recent version of the software available,
- version number - specify the desired version explicitly (version numbers are specified as 8.0.43-34.1, etc.). Actual versions can be found in the list of certified images (for older releases, please refer to the old releases documentation archive ).
Make sure to set the valid Version Server URL for the upgradeOptions.versionServiceEndpoint key. The Operator checks the new software versions in the Version Server. If the Operator can’t reach the Version Server, the upgrades won’t happen.
Percona’s Version Service (default)Version Service inside your cluster
You can use the URL of the official Percona’s Version Service (default). Set upgradeOptions.versionServiceEndpoint to https://check.percona.com.
Alternatively, you can run Version Service inside your cluster. This can be done with the kubectl command as follows:
kubectl run version-service --image=perconalab/version-service --env="SERVE_HTTP=true" --port 11000 --expose
Specify the schedule to check for the new versions in in CRON format for the upgradeOptions.schedule option.

The following example sets the midnight update checks with the official Percona’s Version Service:
```
spec:
  updateStrategy: SmartUpdate
  upgradeOptions:
    apply: Recommended
    versionServiceEndpoint: https://check.percona.com
    schedule: "0 0 * * *"
...
```
Note

You can force an immediate upgrade by changing the schedule to * * * * * (continuously check and upgrade) and changing it back to another more conservative schedule when the upgrade is complete.
Apply your changes to the Custom Resource in the usual way:
```
kubectl apply -f deploy/cr.yaml
```

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