argocd-apps/docs/cnpg-restore.md

CNPG restore

Recovery is always into a new Cluster that bootstraps from the object store — CNPG never restores in place. The source backups live in s3://cnpg-<app> under serverName: <app> (see cnpg-backups.md). Do all of this in the source cluster's namespace so the cnpg-<app>-backup-s3 Secret and vault-ca-cert are present.

(a) Full restore into a new cluster

Recover the latest available state into a fresh cluster named postgres-restore. The externalClusters entry points at the existing backup path; serverName under barmanObjectStore (the new cluster's own archive target) MUST differ from the source, or the restored cluster will overwrite the archive it just recovered from.

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: postgres-restore
  namespace: <app>
spec:
  instances: 3
  imageName: ghcr.io/cloudnative-pg/postgresql:18.1-system-trixie  # match source
  storage:
    size: 20Gi
    storageClass: cephrbd-fast-delete
  bootstrap:
    recovery:
      source: source-archive          # references externalClusters below

  # New archive target — DIFFERENT serverName from the source (avoids collision).
  backup:
    retentionPolicy: 30d
    barmanObjectStore:
      destinationPath: s3://cnpg-<app>
      endpointURL: https://s3.ceph.unkin.net
      endpointCA: {name: vault-ca-cert, key: ca.crt}
      s3Credentials:
        accessKeyId: {name: cnpg-<app>-backup-s3, key: AWS_ACCESS_KEY_ID}
        secretAccessKey: {name: cnpg-<app>-backup-s3, key: AWS_SECRET_ACCESS_KEY}
      serverName: <app>-restored       # NOT "<app>"
      wal: {compression: zstd}
      data: {compression: bzip2}

  externalClusters:
    - name: source-archive
      barmanObjectStore:
        destinationPath: s3://cnpg-<app>
        endpointURL: https://s3.ceph.unkin.net
        endpointCA: {name: vault-ca-cert, key: ca.crt}
        s3Credentials:
          accessKeyId: {name: cnpg-<app>-backup-s3, key: AWS_ACCESS_KEY_ID}
          secretAccessKey: {name: cnpg-<app>-backup-s3, key: AWS_SECRET_ACCESS_KEY}
        serverName: <app>              # the SOURCE archive to read from

kubectl apply -f postgres-restore.yaml
kubectl -n <app> get cluster postgres-restore -w   # wait for Cluster in healthy state

(b) Point-in-time recovery (PITR)

Same as above, but add recoveryTarget to stop replay at a timestamp. WAL is replayed from the most recent base backup up to targetTime.

  bootstrap:
    recovery:
      source: source-archive
      recoveryTarget:
        # RFC3339 with timezone. Also valid: targetLSN, targetXID, targetName.
        targetTime: "2026-07-26 14:30:00.000000+00"

# List backups to pick a base that precedes your target time
kubectl -n <app> get backups.postgresql.cnpg.io \
  -o custom-columns=NAME:.metadata.name,START:.status.startedAt,STOP:.status.stoppedAt

To recover from one specific base backup instead of the newest, point the source at a Backup object:

  externalClusters:
    - name: source-archive
      # ...barmanObjectStore as above...
  bootstrap:
    recovery:
      backup:
        name: <backup-object-name>
      recoveryTarget:
        targetTime: "2026-07-26 14:30:00+00"

(c) Verify, then cut over

# 1. Sanity-check the recovered data before touching production.
kubectl cnpg psql postgres-restore -n <app> -- -c '\l'
kubectl cnpg psql postgres-restore -n <app> -d <db> -- \
  -c 'select max(id), count(*) from <sanity_table>;'

# 2. Confirm the restored cluster is archiving to its NEW serverName.
kubectl cnpg status postgres-restore -n <app>

Cutover = repoint the app at the new cluster. CNPG service names track the Cluster name (<cluster>-rw / -ro / -r), so update whatever the app connects through — the CNPG Pooler (cnpg_pooler.yaml) cluster.name, or the app's DB host env — to postgres-restore, then retire the old cluster. There is no in-place rename; the new name is the cluster's identity. If you truly need the old name back, restore again with metadata.name set to the original (after deleting the old one).

(d) Gotchas

• serverName collision. The new cluster's spec.backup...serverName must differ from the source's, or it re-uses the same path and corrupts/overwrites the source archive on its first WAL push. Use <app>-restored (or similar) as above.
• Secrets must exist in the target namespace. cnpg-<app>-backup-s3 and vault-ca-cert are referenced by both externalClusters and backup. Restoring into a different namespace means recreating (or reflecting) those first — the ObjectStoreUser/Bucket CRs are namespace-scoped.
• Match the image major. Bootstrap-recovery replays WAL; use the same imageName Postgres major as the source (mismatched majors will refuse to start).
• PITR base must precede the target. targetTime has to fall after a completed base backup's start; otherwise there's nothing to replay onto.
• recoveryTarget is one-shot. It only applies during bootstrap. Once promoted, the cluster is a normal primary — you can't "re-PITR" it; start a new restore.