Update Percona Operator for PostgreSQL¶

Percona Operator for PostgreSQL allows upgrades to newer versions. This includes upgrades of the Operator itself, and upgrades of the Percona Distribution for PostgreSQL.

Upgrading the Operator¶

Note

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

The following steps will allow you to update the Operator to current version (use the name of your cluster instead of the <cluster-name> placeholder).

Pause the cluster in order to stop all possible activities:

$ kubectl patch perconapgcluster/<cluster-name> --type json -p '[{"op": "replace", "path": "/spec/pause", "value": true},{"op":"replace","path":"/spec/pgBouncer/size","value":0}]'

If you upgrade the Operator from a version earlier than 1.1.0, the following additional step is needed for the 1.0.0 → 1.1.0 upgrade.
```
$ export CLUSTER=<cluster-name>
$ for user in postgres primaryuser $(kubectl get perconapgcluster/${CLUSTER} -o yaml | yq r - 'spec.user'); do args+="--from-literal=$user=$(kubectl get secret/${CLUSTER}-${user}-o yaml | yq r - 'data.password' | base64 --decode) "; done; eval kubectl create secret generic ${CLUSTER}-users "${args}"
```
This command creates users’ secrets with existing passwords. Otherwise, new secrets with autogenerated passwords will be created automatically, so existing passwords will be overwritten.

Note

The pgbouncer user password is stored in encrypted form, and therefore it is not included in the above command. If you know this password and/or would like to update it, please add it as pgbouncer: base64encodednewpassword to the resulted Secret manually. Otherwise, this password needs no actions and will be overwritten by the Operator during upgrade.

Remove the old Operator and start the new Operator version:

$ kubectl delete \
    serviceaccounts/pgo-deployer-sa \
    clusterroles/pgo-deployer-cr \
    configmaps/pgo-deployer-cm \
    configmaps/pgo-config \
    clusterrolebindings/pgo-deployer-crb \
    jobs.batch/pgo-deploy \
    deployment/postgres-operator

$ kubectl create -f https://raw.githubusercontent.com/percona/percona-postgresql-operator/v1.3.0/deploy/operator.yaml
$ kubectl wait --for=condition=Complete job/pgo-deploy --timeout=90s

Upgrading Percona Distribution for PostgreSQL¶

Automatic upgrade¶

Starting from version 1.1.0, the Operator does fully automatic upgrades to the newer versions of Percona PostgreSQL Cluster within the method named Smart Updates.

The Operator will carry on upgrades according to the following algorithm. It will query a special Version Service server at scheduled times to obtain fresh information about version numbers and valid image paths needed for the upgrade. If the current version should be upgraded, the Operator updates the CR to reflect the new image paths and carries on sequential Pods deletion in a safe order, allowing the cluster Pods to be re-deployed with the new image.

Note

Version Service is in technical preview status and is disabled by default for the Operator version 1.1.0. Disabling Version Service makes Smart Updates rely on the image keys in the Operator’s Custom Resource.

The upgrade details are set in the upgradeOptions section of the deploy/cr.yaml configuration file. Make the following edits to configure updates:

Set the apply option to one of the following values:
- recommended - automatic upgrades will choose the most recent version of software flagged as recommended (for clusters created from scratch, the Percona Distribution for PostgreSQL 14 version will be selected instead of the Percona Distribution for PostgreSQL 13 or 12 version regardless of the image path; for already existing clusters, 14 vs. 13 or 12 branch choice will be preserved),
- 14-recommended, 13-recommended, 12-recommended - same as above, but preserves specific major Percona Distribution for PostgreSQL version for newly provisioned clusters (for example, 14 will not be automatically used instead of 13),
- latest - automatic upgrades will choose the most recent version of the software available,
- 14-latest, 13-latest, 12-latest - same as above, but preserves specific major Percona Distribution for PostgreSQL version for newly provisioned clusters (for example, 14 will not be automatically used instead of 13),
- version number - specify the desired version explicitly,
- never or disabled - disable automatic upgrades
Note

When automatic upgrades are disabled by the apply option, Smart Update functionality will continue working for changes triggered by other events, such as updating a ConfigMap, rotating a password, or changing resource values.
Make sure the versionServiceEndpoint key is set to a valid Version Server URL (otherwise Smart Updates will not occur).
Percona’s Version ServiceVersion Service inside your cluster
You can use the URL of the official Percona’s Version Service (default). Set 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
Note

Version Service is never checked if automatic updates are disabled. If automatic updates are enabled, but Version Service URL can not be reached, upgrades will not occur.
Use the schedule option to specify the update checks time in CRON format.

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

Semi-automatic upgrade¶

Semi-automatic update of Percona Distribution for PostgreSQL should be used with the Operator version 1.0.0 or earlier. For all newer versions, use automatic update instead.

The following steps will allow you to update the Operator to current version (use the name of your cluster instead of the <cluster-name> placeholder).

Pause the cluster in order to stop all possible activities:

$ kubectl patch perconapgcluster/<cluster-name> --type json -p '[{"op": "replace", "path": "/spec/pause", "value": true},{"op":"replace","path":"/spec/pgBouncer/size","value":0}]'

Now you can switch the cluster to a new version:

$ kubectl patch perconapgcluster/<cluster-name> --type json -p '[{"op": "replace", "path": "/spec/backup/backrestRepoImage", "value": "percona/percona-postgresql-operator:1.3.0-ppg14-pgbackrest-repo"},{"op":"replace","path":"/spec/backup/image","value":"percona/percona-postgresql-operator:1.3.0-ppg13-pgbackrest"},{"op":"replace","path":"/spec/pgBadger/image","value":"percona/percona-postgresql-operator:1.3.0-ppg14-pgbadger"},{"op":"replace","path":"/spec/pgBouncer/image","value":"percona/percona-postgresql-operator:1.3.0-ppg14-pgbouncer"},{"op":"replace","path":"/spec/pgPrimary/image","value":"percona/percona-postgresql-operator:1.3.0-ppg14-postgres-ha"},{"op":"replace","path":"/spec/userLabels/pgo-version","value":"v1.3.0"},{"op":"replace","path":"/metadata/labels/pgo-version","value":"v1.3.0"},{"op": "replace", "path": "/spec/pause", "value": false}]'

Note

The above example is composed in asumption of using PostgreSQL 14 as a database management system. For PostgreSQL 13 you should change all occurrences of the ppg14 substring to ppg13.

This will carry on the image update, cluster version update and the pause status switch.

Now you can enable the pgbouncer again:

$ kubectl patch perconapgcluster/<cluster-name --type json -p \
    '[
        {"op":"replace","path":"/spec/pgBouncer/size","value":1}
    ]'

Wait until the cluster is ready.

Contact Us

For free technical help, visit the Percona Community Forum.

To report bugs or submit feature requests, open a JIRA ticket.

For paid support and managed or consulting services , contact Percona Sales.

Last update: 2023-02-09