How-To

Update CNPG Operator Version¶

Update the CloudNativePG operator and barman plugin to newer versions.

The operator reconciles every CloudNativePG cluster in the fleet, so treat an operator update as a planned maintenance event, not a routine merge.

Important

This deployment is a k3s HelmChart resource: the k3s helm-controller runs helm upgrade at sync time. The chart version in config.yaml (for example 0.29.0) selects the operator app version (for example 1.30.0) — the two are not the same number. Confirm the mapping before you start: helm show chart cloudnative-pg/cloudnative-pg --version <chart> | grep appVersion.

Renovate¶

Renovate proposes CNPG operator updates one minor version at a time (separateMultipleMinor), labeled needs-maintenance-window. Merge them in order (do not jump several minors in one step) and follow this guide for each merge. CloudNativePG explicitly recommends upgrading through each minor version in sequence rather than skipping.

Before you start¶

Work through these checks before merging an operator update.

Warning

An operator upgrade triggers a switchover on every managed cluster. All kup6s CNPG clusters run two instances with primaryUpdateStrategy: unsupervised, so each one fails over to its replica automatically (seconds of blip, no data loss). Do it in a low-traffic window and confirm all clusters report two healthy instances first: kubectl get clusters.postgresql.cnpg.io -A

CRD upgrades. helm upgrade does not upgrade CRDs that ship in the chart’s crds/ directory (a Helm limitation), so a new operator may expect CRD fields that never get applied. Before merging, diff the chart’s CRDs against the cluster and apply them manually with kubectl apply --server-side if they changed.
Barman plugin compatibility. kup6s backs up through the plugin-barman-cloud HelmChart (not native Barman). Confirm the installed plugin version supports the target operator version, and bump barmanPlugin in the same window if required.
Read the release notes for every minor version you cross: https://cloudnative-pg.io/documentation/. Note especially the 1.30 security changes (operator-side SCRAM-SHA-256 password encoding, pooled-connection search_path hardening) — transparent for standard password and certificate auth, but verify authentication after the upgrade.
Native Barman removal. Native barmanObjectStore backups are removed in operator 1.31. kup6s already uses the plugin, so this is not a blocker, but do not reintroduce native Barman.

Prerequisites¶

Access to dp-infra repository
Node.js and npm installed (for CDK8S build)

Step 1: Check Available Versions¶

# Search CloudNativePG chart versions
helm search repo cloudnative-pg/cloudnative-pg --versions

# Search barman plugin versions
helm search repo cloudnative-pg/plugin-barman-cloud --versions

Step 2: Update Configuration¶

Edit dp-infra/cnpg/config.yaml:

versions:
  operator: "0.27.0"  # New chart version
  barmanPlugin: "0.3.0"  # New plugin version

Step 3: Rebuild Manifests¶

cd dp-infra/cnpg
npm run build

This regenerates manifests/cnpg.k8s.yaml with new versions.

Step 4: Review Changes¶

git diff manifests/cnpg.k8s.yaml

Verify:

Chart version updated
No unexpected changes

Step 5: Commit and Push¶

git add config.yaml manifests/cnpg.k8s.yaml
git commit -m "Update CNPG operator to v0.27.0 and barman plugin to v0.3.0"
git push

Step 6: Verify ArgoCD Sync¶

ArgoCD automatically syncs changes:

# Watch ArgoCD Application
kubectl get application cnpg-app-* -n argocd -w

# Check sync status
argocd app get cnpg-app-* -n argocd

Step 7: Verify Operator Update¶

# Check operator pod version
kubectl get deployment cnpg-cloudnative-pg -n cnpg-system \
  -o jsonpath='{.spec.template.spec.containers[0].image}'

# Check operator logs
kubectl logs -n cnpg-system -l app.kubernetes.io/name=cloudnative-pg

# Verify existing clusters still healthy (all should report 2/2 ready instances)
kubectl get clusters.postgresql.cnpg.io -A

After the switchovers settle, verify the parts most likely to be affected:

# Applications reconnect (SCRAM-SHA-256 change) — check a few app pods have no auth errors
kubectl logs -n kup-openproject deploy/openproject-web --tail=20

# Continuous archiving still works (barman plugin)
kubectl get clusters.postgresql.cnpg.io -A \
  -o custom-columns='NS:.metadata.namespace,NAME:.metadata.name,ARCHIVING:.status.conditions[?(@.type=="ContinuousArchiving")].status'

Rollback (if needed)¶

If the update causes issues:

cd dp-infra/cnpg

# Revert config.yaml to previous version
git revert HEAD

# Rebuild and push
npm run build
git add config.yaml manifests/
git commit -m "Rollback CNPG operator version"
git push

ArgoCD will automatically sync the rollback.