Skip to content
logo
Percona Operator for PostgreSQL
Upgrade Percona Distribution for PostgreSQL and the Operator
Initializing search
    percona/k8spg-docs
    percona/k8spg-docs
    • Welcome
      • System Requirements
      • Design and architecture
      • Comparison with other solutions
      • Install on Minikube
      • Install on Google Kubernetes Engine (GKE)
      • Install with Helm
      • Generic Kubernetes installation
      • Install on OpenShift
      • Application and system users
      • Changing PostgreSQL Options
      • Anti-affinity and tolerations
      • Transport Encryption (TLS/SSL)
      • Telemetry
      • Backup and restore
      • Upgrade Percona Distribution for PostgreSQL and the Operator
        • Upgrading the Operator
        • Upgrading Percona Distribution for PostgreSQL
          • Automatic upgrade
          • Semi-automatic upgrade
      • Horizontal and vertical scaling
      • Monitor with Percona Monitoring and Management (PMM)
      • Restart or pause the cluster
      • Deploy a standby cluster for Disaster Recovery
      • Provide Percona Operator for PostgreSQL single-namespace and multi-namespace deployment
      • Use PostgreSQL tablespaces with Percona Operator for PostgreSQL
      • Custom Resource options
      • Operator installation options
      • Percona certified images
      • Frequently Asked Questions
      • Release notes index
      • Percona Operator for PostgreSQL 1.3.0 (2022-08-04)
      • Percona Operator for PostgreSQL 1.2.0 (2022-04-06)
      • Percona Operator for PostgreSQL 1.1.0 (2021-12-07)
      • Percona Operator for PostgreSQL 1.0.0 (2021-10-07)
      • Percona Operator for PostgreSQL 0.2.0 (2021-08-12)
      • Percona Operator for PostgreSQL 0.1.0 (2021-05-10)

    • Upgrading the Operator
    • Upgrading Percona Distribution for PostgreSQL
      • Automatic upgrade
      • Semi-automatic upgrade

    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).

    1. 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}]'
      
    2. 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.

    3. 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:

    1. 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.

    2. 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 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.

    3. 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).

    1. 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}]'
      
    2. 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.

    3. 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
    Back to top
    Percona LLC and/or its affiliates, © 2009 - 2022
    Made with Material for MkDocs

    Cookie consent

    We use cookies to recognize your repeated visits and preferences, as well as to measure the effectiveness of our documentation and whether users find what they're searching for. With your consent, you're helping us to make our documentation better.