Upgrade PGO operator and Postgres cluster versions

PGO upgrades fall into two separate concerns: upgrading the operator itself (new PGO release), and upgrading the Postgres major version running inside your clusters. These are independent operations with different procedures. You can upgrade the operator without touching Postgres, and you upgrade Postgres using the PGUpgrade custom resource regardless of how you installed the operator.

Before any upgrade, read the release notes for the target PGO version. Breaking changes and required manual steps are called out explicitly in the changelog.

Upgrade the operator

The operator upgrade process re-applies updated manifests. Because PGO uses a Recreate deployment strategy (not RollingUpdate), the old pod is terminated before the new one starts. This means there is a brief window during which the operator is not running. Existing Postgres clusters are not affected — they continue serving traffic while the operator is offline.

Kustomize
Helm

Pull the latest changes in your examples fork

cd postgres-operator-examples
git fetch origin
git merge origin/main

Review the diff before applying

Preview what will change before touching the cluster:

kubectl diff --server-side -k kustomize/install/default

Pay attention to any CRD schema changes — these apply immediately and affect all clusters.

Apply the updated manifests

Use the same --server-side flag you used during the initial install:

kubectl apply --server-side -k kustomize/install/default

Kubernetes performs a server-side apply merge, so only changed fields are updated.

Watch the operator pod roll

kubectl rollout status deployment/pgo -n postgres-operator

deployment "pgo" successfully rolled out

Confirm the new version

kubectl get deployment pgo -n postgres-operator \
  -o jsonpath='{.spec.template.spec.containers[0].image}'

The image tag should reflect the new PGO version.

Update the chart repository

helm repo update

Check the available chart versions

helm search repo crunchy-data/pgo --versions

Apply CRD updates manually

Helm does not upgrade CRDs automatically during helm upgrade. Apply them before upgrading the chart:

kubectl apply --server-side -f \
  https://raw.githubusercontent.com/CrunchyData/postgres-operator-examples/main/kustomize/install/default/crds.yaml

Skipping this step when CRDs have changed can cause the operator to malfunction or fail to start after the upgrade.

Upgrade the Helm release

helm upgrade pgo crunchy-data/pgo \
  --namespace postgres-operator \
  --values pgo-values.yaml

To upgrade to a specific chart version:

helm upgrade pgo crunchy-data/pgo \
  --namespace postgres-operator \
  --version 5.x.x \
  --values pgo-values.yaml

Watch the operator pod roll

kubectl rollout status deployment/pgo -n postgres-operator

Backward compatibility

PGO follows semantic versioning for its operator releases:

Patch releases (e.g., 5.6.0 → 5.6.1): backward-compatible bug fixes. Safe to apply without reviewing cluster behavior.
Minor releases (e.g., 5.5.x → 5.6.x): backward-compatible new features. CRD schemas may be extended with new optional fields. Existing clusters are unaffected.
Major releases (e.g., 5.x → 6.x): may include breaking changes to the CRD API, RBAC, or default behavior. Always read the migration guide in the release notes before upgrading.

Downgrading the operator is not supported. If an upgrade introduces a problem, restore from a backup of your cluster data rather than rolling the operator back.

Upgrade Postgres major versions

Upgrading the Postgres major version (for example, from Postgres 15 to Postgres 16) requires an in-place pg_upgrade. PGO handles this through the PGUpgrade custom resource, which orchestrates a controlled shutdown, data upgrade, and restart of your cluster.

The PGUpgrade resource upgrades the Postgres data directory in place. This is separate from upgrading the PGO operator itself and can be done independently.

How PGUpgrade works

When you create a PGUpgrade resource that references an existing PostgresCluster:

PGO shuts down the cluster gracefully.
The upgrade job runs pg_upgrade to convert the data directory from the old Postgres major version format to the new one.
PGO restarts the cluster with the new Postgres version image.
The cluster resumes serving traffic.

Example PGUpgrade resource

apiVersion: postgres-operator.crunchydata.com/v1beta1
kind: PGUpgrade
metadata:
  name: hippo-upgrade
  namespace: postgres-operator
spec:
  # Reference the cluster you want to upgrade
  postgresClusterName: hippo

  # The Postgres major version you are upgrading FROM
  fromPostgresVersion: 15

  # The Postgres major version you are upgrading TO
  toPostgresVersion: 16

Apply the resource:

kubectl apply -f hippo-upgrade.yaml

Watch the upgrade progress

kubectl get pgupgrade hippo-upgrade -n postgres-operator -w

NAME             STATUS      AGE
hippo-upgrade    Pending     5s
hippo-upgrade    Running     12s
hippo-upgrade    Succeeded   2m14s

Once the PGUpgrade reaches Succeeded, the cluster is running on the new Postgres version. Verify by checking the cluster status:

kubectl get postgrescluster hippo -n postgres-operator \
  -o jsonpath='{.status.postgresVersion}'

Update the PostgresCluster spec

After a successful upgrade, update your PostgresCluster manifest to reflect the new Postgres version so that future reconciliations use the correct image:

spec:
  postgresVersion: 16

Apply the change:

kubectl apply -f hippo-cluster.yaml

The PGUpgrade resource performs an in-place upgrade. Ensure you have a current pgBackRest backup of your cluster before starting. See Backups for how to trigger a manual backup.

PGUpgrade prerequisites

The target Postgres version image must be listed as a RELATED_IMAGE_POSTGRES_* environment variable in the operator Deployment. These are set automatically when you install or upgrade PGO via the provided overlays.
The cluster must be in a healthy state before the upgrade starts (primary running, all replicas caught up).
Remove any extensions that are not available in the target Postgres version before upgrading.

For the full PGUpgrade API reference, see PGUpgrade reference.

Next steps

Update Postgres minor versions

Roll out Postgres patch releases to your clusters with minimal downtime.

Backups

Take a manual backup before any upgrade operation.

PGUpgrade reference

Full API reference and field descriptions for the PGUpgrade resource.

Supported platforms

Check which Kubernetes versions and distributions PGO supports.

Get Started

Installation

Core Operations

Day-Two Operations

Security

Upgrade PGO operator and Postgres cluster versions

Upgrade the operator

Backward compatibility

Upgrade Postgres major versions

How PGUpgrade works

Example PGUpgrade resource

Watch the upgrade progress

Update the PostgresCluster spec

PGUpgrade prerequisites

Next steps

Update Postgres minor versions

Backups

PGUpgrade reference

Supported platforms

​Upgrade the operator

​Backward compatibility

​Upgrade Postgres major versions

​How PGUpgrade works

​Example PGUpgrade resource

​Watch the upgrade progress

​Update the PostgresCluster spec

​PGUpgrade prerequisites

​Next steps

Update Postgres minor versions

Backups

PGUpgrade reference

Supported platforms

Upgrade the operator

Backward compatibility

Upgrade Postgres major versions

How PGUpgrade works

Example PGUpgrade resource

Watch the upgrade progress

Update the PostgresCluster spec

PGUpgrade prerequisites

Next steps