Scheduled Backup Retention#

The ScheduledBackup controller in CloudNativePG creates Kubernetes Backup resources on a cron schedule. Over time these objects accumulate. Retention — pruning both the actual backup data in object storage and the corresponding Backup CRs — is handled at two independent levels:

1. Object-store data retention — configured on the Cluster or ObjectStore, enforced by the instance manager.
2. Kubernetes Backup CR cleanup — a catalog-reconciliation step that deletes CRs whose backup IDs are no longer present in the object-store catalog.

There is no numeric history-limit field on ScheduledBackup itself. The full ScheduledBackupSpec exposes only scheduling, cluster reference, owner-reference, method, target, and volume-snapshot options.

The retentionPolicy field (in-tree Barman path)#

Cluster.spec.backup.retentionPolicy accepts a recovery-window string (60d, 8w, 2m). It applies only to the barmanObjectStore method 1 and governs which base backups the Barman catalog considers obsolete.

When a backup completes, backupMaintenance runs two steps in sequence:

1. Calls barmanCommand.DeleteBackupsByPolicy with the configured policy string to prune expired data from object storage 2.
2. Fetches the updated catalog and calls deleteBackupsNotInCatalog to delete completed Backup CRs whose BackupID no longer appears in the catalog.

The CR cleanup is catalog-driven, not count-driven: it deletes a CR only if its BackupID is absent from the catalog after the retention policy was applied 3. Only completed CRs that share the same Barman endpoint/path/credentials as the cluster are considered 4 5.

Plugin path (plugin-barman-cloud)#

The Barman Cloud plugin uses an equivalent mechanism via CatalogMaintenanceRunnable. A background goroutine in the instance sidecar runs the cycle method periodically 6. On each cycle it:

1. Applies objectStore.Spec.RetentionPolicy using barmanCommand.DeleteBackupsByPolicy 7.
2. Calls deleteBackupsNotInCatalog with the same catalog-reconciliation logic as the in-tree path.

The check interval defaults to 5 minutes 8 and is otherwise controlled by objectStore.Spec.InstanceSidecarConfiguration.RetentionPolicyIntervalSeconds 9. Only the current primary runs maintenance 10.

Volume-snapshot backups#

retentionPolicy has never been enforced for volumeSnapshot-method backups. The operator has no built-in retention controller for volume-snapshot Backup CRs or their underlying VolumeSnapshot/VolumeSnapshotContent objects. Community workarounds use a CronJob that deletes old Backup resources by age or label, relying on snapshotOwnerReference: backup so Kubernetes garbage-collection cascades to the VolumeSnapshot 11.

The backupOwnerReference field and Kubernetes GC#

ScheduledBackupSpec.backupOwnerReference (none | self | cluster, default none) determines whether the generated Backup resources carry an owner reference 12. When set to self or cluster, deleting the owning object cascades deletion of all child Backup resources via standard Kubernetes garbage collection. This is not a rolling history limit; it doesn't prune old backups while the owner still exists.

Known issue: terminal error: Backup not found after retention#

When a Backup CR is deleted by the retention process while the backup controller still has it in its work queue, backup_controller.go returns reconcile.TerminalError(err) on the NotFound case — a regression introduced in PR #9353. PR #11484 fixes this by converting the NotFound return to a no-op, matching the behaviour of the scheduledbackup_controller.go 13 14. The practical impact is a permanently incrementing controller_runtime_reconcile_total{result="error"} metric for the backup controller 14.

Key entry points#