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 aspgbouncer: 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
ordisabled
- 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).You can use the URL of the official Percona’s Version Service (default). Set
versionServiceEndpoint
tohttps://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 toppg13
.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.