Upgrade Database and Operator¶

Upgrade from the Operator version 1.x to version 2.x¶

The Operator version 2.x has a lot of differences compared to the version 1.x. This makes upgrading from version 1.x to version 2.x quite different from a normal upgrade. In fact, you have to migrate the cluster from version 1.x to version 2.x.

There are several ways to do such version 1.x to version 2.x upgrade. Choose the method based on your downtime preference and roll back strategy:

	Pros	Cons
Data Volumes migration - re-use the volumes that were created by the Operator version 1.x	The simplest method	- Requires downtime - Impossible to roll back
Backup and restore - take the backup with the Operator version 1.x and restore it to the cluster deployed by the Operator version 2.x	Allows you to quickly test version 2.x	Provides significant downtime in case of migration
Replication - replicate the data from the Operator version 1.x cluster to the standby cluster deployed by the Operator version 2.x	- Quick test of v2 cluster - Minimal downtime during upgrade	Requires significant computing resources to run two clusters in parallel

Update Database and Operator version 2.x¶

Starting from the version 2.2.0 Percona Operator for PostgreSQL allows upgrades to newer 2.x versions. The upgradable components of the cluster are the following ones:

the Operator;
Custom Resource Definition (CRD),
Database Management System (Percona Distribution for PostgreSQL).

The list of recommended upgrade scenarios includes two variants:

Upgrade to the new versions of the Operator and Percona Distribution for PostgreSQL,
Minor Percona Distribution for PostgreSQL version upgrade without the Operator upgrade.

Upgrading the Operator and CRD¶

Note

The Operator supports last 3 versions of the CRD, so it is technically possible to skip upgrading the CRD and just upgrade the Operator. If the CRD is older than the new Operator version by no more than three releases, you will be able to continue using the old CRD and even carry on Percona Distribution for PostgreSQL minor version upgrades with it. But the recommended way is to update the Operator and CRD.

Only the incremental update to a nearest version of the Operator is supported (for example, update from 2.2.0 to 2.3.0). To update to a newer version, which differs from the current version by more than one, make several incremental updates sequentially.

Considering the Operator uses postgres-operator namespace, upgrade to the version 2.4.0 includes the following steps.

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-postgresql-operator/v2.4.0/deploy/crd.yaml
$ kubectl apply -f https://raw.githubusercontent.com/percona/percona-postgresql-operator/v2.4.0/deploy/rbac.yaml -n postgres-operator

Note

In case of cluster-wide installation, use deploy/cw-rbac.yaml instead of deploy/rbac.yaml.

Now you should apply a patch to your deployment, supplying necessary image name with a newer version tag. You can find the proper image name for the current Operator release in the list of certified images. updating to the 2.4.0 version should look as follows:
```
$ kubectl -n postgres-operator patch deployment percona-postgresql-operator \
   -p'{"spec":{"template":{"spec":{"containers":[{"name":"operator","image":"percona/percona-postgresql-operator:2.4.0"}]}}}}'
```
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-postgresql-operator
```

Upgrading Percona Distribution for PostgreSQL¶

Starting from the Operator version 2.4, Percona Distribution for PostgreSQL can be automatically upgrade from one PostgreSQL major version to another (for example, upgrade from PostgreSQL 15 to PostgreSQL 16). Versions earlier than 2.4 support only minor versions upgrade.

Major version upgrade¶

Note

Major version upgrades feature is currently a tech preview, and it is not recommended for production environments.

Upgrade is triggered by applying the YAML file with the information about the existing and desired major versions, with an example present in deploy/upgrade.yaml:

apiVersion: pgv2.percona.com/v2
kind: PerconaPGUpgrade
metadata:
  name: cluster1-15-to-16
spec:
  postgresClusterName: cluster1
  image: percona/percona-postgresql-operator:2.4.0-upgrade
  fromPostgresVersion: 15
  toPostgresVersion: 16

After applying it as usual, by running kubectl apply -f deploy/upgrade.yaml command, the actual upgrade takes place as follows:

The cluster is paused for a while,
The cluster is specially annotated with pgv2.percona.com/allow-upgrade: <PerconaPGUpgrade.Name> annotation,
Jobs are created to migrate the data,
The cluster starts up after the upgrade finishes.

During the upgrade data are duplicated in the same PVC for each major upgrade, and old version data are not deleted automatically. Make sure your PVC has enough free space to store data.

Note

If the upgrade process meets problems and cannot proceed, the cluster will remain paused. In this case you should delete PerconaPGUpgrade object with kubectl delete command and resume the cluster manually to check what went wrong with upgrade.

If there are custom PostgreSQL extensions installed in the cluster, they need to be taken into account: you need to build and package each custom extension for the new PostgreSQL major version. During the upgrade the Operator will install extensions into the upgrade container.

Minor version upgrade¶

Upgrading Percona Distribution for PostgreSQL minor version can be done as follows:

Apply a patch to your Custom Resource, setting necessary Custom Resource version and image names with a newer version tag.

Note

Check the version of the Operator you have in your Kubernetes environment. Please refer to the Operator upgrade guide to upgrade the Operator and CRD, if needed.

Patching Custom Resource is done with the kubectl patch pg command. Actual image names can be found in the list of certified images. For example, updating cluster1 cluster to the 2.4.0 version should look as follows:

$ kubectl -n postgres-operator patch pg cluster1 --type=merge --patch '{
   "spec": {
      "crVersion":"2.4.0",
      "image": "percona/percona-postgresql-operator:2.4.0-ppg15-postgres",
      "proxy": { "pgBouncer": { "image": "percona/percona-postgresql-operator:2.4.0-ppg15-pgbouncer" } },
      "backups": { "pgbackrest":  { "image": "percona/percona-postgresql-operator:2.4.0-ppg15-pgbackrest" } },
      "pmm": { "image": "percona/pmm-client:2.42.0" }
   }}'

Warning

The above command upgrades various components of the cluster including PMM Client. It is highly recommended to upgrade PMM Server before upgrading PMM Client. If it wasn’t done and you would like to avoid PMM Client upgrade, remove it from the list of images, reducing the last of two patch commands as follows:

$ kubectl -n postgres-operator patch pg cluster1 --type=merge --patch '{
   "spec": {
      "crVersion":"2.4.0",
      "image": "percona/percona-postgresql-operator:2.4.0-ppg15-postgres",
      "proxy": { "pgBouncer": { "image": "percona/percona-postgresql-operator:2.4.0-ppg15-pgbouncer" } },
      "backups": { "pgbackrest":  { "image": "percona/percona-postgresql-operator:2.4.0-ppg15-pgbackrest" } }
   }}'

The deployment rollout will be automatically triggered by the applied patch. The update process is successfully finished when all Pods have been restarted.

Get expert help¶

If you need assistance, visit the community forum for comprehensive and free database knowledge, or contact our Percona Database Experts for professional support and services. Join K8S Squad to benefit from early access to features and “ask me anything” sessions with the Experts.

Community Forum Get a Percona Expert Join K8S Squad

Last update: 2024-07-04