Barman-Cloud Sidecar Retention Policy#

The barman-cloud sidecar runs a continuous polling loop — CatalogMaintenanceRunnable — that periodically enforces backup retention policies, reconciles Kubernetes Backup objects against the barman catalog, and updates the cluster's first recoverability point.

How the Loop Works#

CatalogMaintenanceRunnable.Start runs a for loop that:

1. Calls cycle() to enforce retention and get the next wait interval.
2. Waits for that interval (via time.After) or for ctx.Done() — whichever fires first.
3. Returns nil when the context is cancelled (SIGTERM path).

The loop only enforces retention on the current primary pod; replicas skip maintenance silently 1.

Each cycle() does three things 2:

• Calls barmanCommand.DeleteBackupsByPolicy with the RetentionPolicy from ObjectStore.spec.retentionPolicy (skipped if the field is empty).
• Calls barmanCommand.GetBackupList and deletes any Backup Kubernetes objects not present in the barman catalog.
• Updates ObjectStore.status.serverRecoveryWindow via updateRecoveryWindow.

The CatalogMaintenanceRunnable is registered as a controller-runtime Runnable and started alongside the CNPG-i gRPC server in instance.Start.

Interval Configuration#

The polling interval is set via ObjectStore.spec.instanceSidecarConfiguration.retentionPolicyIntervalSeconds 3.

The two defaults serve different purposes:

• 1800 s is the steady-state interval — used when the ObjectStore is fetched successfully and cycle() returns cleanly.
• 300 s is the error-recovery interval — used when cycle() returns 0 (i.e., the cluster or object store couldn't be read, or enforcement failed) 6.

SIGTERM / Shutdown Delay#

The loop's select block exits immediately on ctx.Done() 7, so the inter-cycle sleep is fully interruptible. However, if a retention cycle is actively running when SIGTERM arrives, the sidecar will not respond until the in-flight cycle() call completes. Depending on the size of the backup catalog and the latency of the object store API, this can introduce a meaningful delay before the pod terminates.

To reduce worst-case shutdown time, lower retentionPolicyIntervalSeconds — this has no effect on active cycles but makes the pod more responsive when idle between cycles. There is no separate timeout on the cycle() call itself; the context passed to barmanCommand.DeleteBackupsByPolicy and barmanCommand.GetBackupList is the same manager context that is cancelled on SIGTERM, so Kubernetes' terminationGracePeriodSeconds remains the hard upper bound.

Key Source Files#