CNPG-I Backup Plugin Architecture#

CNPG-I (CloudNativePG Interface) is a gRPC-based plugin protocol that lets external processes extend the CloudNativePG operator. Backup-related behavior is split across three services that a plugin may expose: Backup, WAL, and RestoreJobHooks. A plugin advertises which services it supports via the Identity service GetPluginCapabilities RPC, which returns capability tokens such as TYPE_BACKUP_SERVICE, TYPE_WAL_SERVICE, and TYPE_RESTORE_JOB.

The reference implementation is plugin-barman-cloud, which handles physical backups and WAL archiving/restore via Barman Cloud.

Backup Service#

The Backup service exposes two RPCs:

The operator passes JSON-serialized Cluster and Backup objects to the plugin. The plugin responds with a BackupResult containing required fields (backup_id, started_at, stopped_at, online) and optional provenance fields (begin_wal, end_wal, begin_lsn, end_lsn, backup_label_file). A freeform metadata map lets plugins store plugin-specific data alongside the Backup CR.

Before dispatching the RPC, the operator checks both that the plugin reports TYPE_BACKUP_SERVICE in its identity capabilities and TYPE_BACKUP in its backup-service capabilities. If either check fails, the backup is rejected before the network call.

WAL Service#

The WAL service exposes five RPCs:

WALRestoreRequest includes a Mode enum (MODE_RECOVERY vs MODE_REWIND) so plugins can handle pg_rewind fetches differently—avoiding WAL prefetching and ignoring cached misses, because pg_rewind treats any restore failure as fatal.

Plugin Status Surfacing in the Cluster CR#

Each plugin can set an arbitrary JSON blob in the Cluster.status.plugins[<name>].status field via the SetStatusInCluster Operator RPC 1. The operator calls this at the end of every reconciliation loop. The PluginStatus struct on the Cluster CR also stores which service capabilities and backup capabilities the plugin declared.

Recoverability Metadata via ObjectStore CR#

For the barman-cloud plugin, backup recovery metadata is not written to the Cluster CR. Instead, the plugin maintains it in its own ObjectStore custom resource under status.serverRecoveryWindow[<serverName>] 2:

ObjectStoreStatus
└── ServerRecoveryWindow: map[string]RecoveryWindow
    └── RecoveryWindow
        ├── FirstRecoverabilityPoint *metav1.Time
        ├── LastSuccessfulBackupTime *metav1.Time
        └── LastFailedBackupTime *metav1.Time

The plugin updates this status in two places:

• After each successful backup — updateRecoveryWindow() reads the backup catalog (catalog.GetFirstRecoverabilityPoint(), catalog.GetLastSuccessfulBackupTime()) and writes to ObjectStore.Status.
• After each failed backup — setLastFailedBackupTime() sets LastFailedBackupTime using retry-on-conflict to avoid race conditions against the controller loop.
• During retention enforcement — updateRecoveryWindow is also called after the retention policy run so the window reflects any expired backups.

The Cluster CR fields FirstRecoverabilityPoint, LastSuccessfulBackup, and LastFailedBackup are deprecated for plugin-based backups and are not populated when a backup plugin is in use 3. The ObjectStore CR is the authoritative source.

Status Command Integration#

The kubectl-cnpg status command bridges the two worlds:

1. PR #8690 4 added detection of the barman-cloud plugin (barman-cloud.cloudnative-pg.io) in Cluster.spec.plugins so the command no longer reports "Not configured" when the native .spec.backup is absent.
2. PR #8780 5 added a getBarmanObject() function that queries barmancloud.cnpg.io/v1/objectstores and displays the ObjectStore's ServerRecoveryWindow — first recoverability point, last successful backup, and last failed backup — directly in the status output.

Key Source References#