Skip to content

Upgrading

This page covers how to upgrade the CloudNativePG operator and your PostgreSQL clusters.

Upgrade Process Overview

Upgrading CloudNativePG involves two steps:

  1. Operator upgrade: Update the controller deployment to the new version.
  2. Instance manager upgrade: The operator automatically updates the instance manager in each PostgreSQL pod.

Before You Upgrade

Warning

"Review Release Notes" Always review the CloudNativePG release notes before upgrading. Some versions may have specific requirements or breaking changes.

Before upgrading, complete the following pre-upgrade checklist:

  • Review the release notes for the target version.
  • Verify your Kubernetes version is supported (see Version Support).
  • Ensure all PostgreSQL clusters are healthy.
  • Plan for brief application reconnection during primary switchover.

Upgrading the Operator

Using Helm

Update the Helm repository and upgrade:

helm repo update pgedge
helm upgrade cnpg pgedge/cloudnative-pg --namespace cnpg-system

To upgrade to a specific version:

helm upgrade cnpg pgedge/cloudnative-pg \
  --namespace cnpg-system \
  --version 0.27.1

Using Manifests

Apply the new manifest version:

kubectl apply --server-side -f \
  https://raw.githubusercontent.com/pgEdge/pgedge-cnpg-dist/main/manifests/cloudnative-pg/v1.28.1/cnpg-1.28.1.yaml

PostgreSQL Cluster Updates

After upgrading the operator, PostgreSQL clusters update their instance manager automatically. The update strategy is controlled by the primaryUpdateStrategy setting in your cluster spec.

Update Strategies

Strategy Behavior
unsupervised (default) Automatic rolling update with switchover
supervised Requires manual promotion after replicas update

With unsupervised mode, expect a brief service interruption during the primary switchover. Applications should handle reconnection automatically.

Controlling Update Spread

For large deployments, spread updates across clusters to reduce resource impact:

Environment Variable Description Default
CLUSTERS_ROLLOUT_DELAY Delay between cluster rollouts 0 seconds
INSTANCES_ROLLOUT_DELAY Delay between instance updates 0 seconds

Configure these in the operator deployment:

helm upgrade cnpg pgedge/cloudnative-pg \
  --namespace cnpg-system \
  --set env.CLUSTERS_ROLLOUT_DELAY=30 \
  --set env.INSTANCES_ROLLOUT_DELAY=10

Version Compatibility

CloudNativePG follows semantic versioning. Compatibility is guaranteed within the same minor series (patch releases only). Minor-level upgrades (e.g., 1.26 → 1.27) can introduce behavior or breaking changes. pgEdge recommends upgrading sequentially through each minor version rather than skipping releases. Always review the release notes and intermediate minor upgrade instructions before upgrading.

Verifying the Upgrade

Check the operator version:

kubectl get deployment -n cnpg-system cnpg-controller-manager -o jsonpath='{.spec.template.spec.containers[0].image}'

Check cluster status:

kubectl cnpg status my-cluster

Rollback

If issues occur after upgrading, roll back to the previous version:

Helm Rollback

helm rollback cnpg --namespace cnpg-system

Manifest Rollback

Apply the previous manifest version:

kubectl apply --server-side -f \
  https://raw.githubusercontent.com/pgEdge/pgedge-cnpg-dist/main/manifests/cloudnative-pg/v1.27.1/cnpg-1.27.1.yaml

Resources