Skip to content

feat: record the backup location in the Backup plugin metadata - #1141

Open
BoxBoxJason wants to merge 1 commit into
cloudnative-pg:mainfrom
BoxBoxJason:dev/1140
Open

BoxBoxJason wants to merge 1 commit into
cloudnative-pg:mainfrom
BoxBoxJason:dev/1140

Conversation

@BoxBoxJason

@BoxBoxJason BoxBoxJason commented Oct 4, 2026 •

Copy link
Copy Markdown

Problem

A Backup taken through the plugin doesn't record where it was written. Backup.status.pluginMetadata only holds the cluster UID, the timeline and the plugin identity, so to create a recovery cluster from a given backup you have to find its ObjectStore and serverName some other way and write them by hand in the externalClusters entry.

This is painful when the serverName changes over time, for example a timestamped serverName per cluster generation: the recovery default for serverName is the name of the new cluster, which never matches. The in-tree integration kept this link in Backup.status.serverName, destinationPath and endpointURL, so users migrating to the plugin lose it.

Closes #1140

Change

newBackupResultMetadata now also records the configuration the backup was taken with:

Key Value
barmanObjectName name of the ObjectStore used for the backup
serverName resolved server name (the serverName parameter, or the cluster name when unset)
destinationPath destinationPath of the ObjectStore at backup time
endpointURL endpointURL of the ObjectStore at backup time
  • Keys are only added, and left out when empty, so the metadata keeps the same shape as for backups taken by older versions.
  • The plugin only writes these keys. Nothing reads them back yet, so existing behaviour doesn't change.
  • Credentials embedded in destinationPath or endpointURL (https://user:password@host) are masked with url.Redacted() before being recorded, because Backup objects are readable by more people than the ObjectStore's secrets.
  • The new "Locating a backup" section in usage.md documents the keys. It also says that barmanObjectName always refers to an ObjectStore in the Cluster's namespace, so restoring into another namespace needs an ObjectStore there that points to the same location.

Follow-up

These keys would also let the catalog maintenance (useSameBackupLocation in retention.go) skip Backup objects taken against another location. Today it deletes them when the cluster switches to another ObjectStore or serverName, which I believe is what #405 reports. That's left out of this PR on purpose; I've detailed it in #405.

Testing

Unit tests cover the recorded keys, empty values, a missing ObjectStore and credential masking. go vet, go test ./internal/cnpgi/instance/... and golangci-lint pass.

I also ran it on a local kind cluster (Kubernetes v1.37.0, CloudNativePG 1.30.1, cert-manager, RustFS as the S3 store), starting from the released plugin v0.15.1 and then switching the plugin and sidecar images to a build of this commit:

  • Backup taken with v0.15.1: pluginMetadata has none of the new keys, as expected.
  • Same cluster after the upgrade, new backup: barmanObjectName, serverName (a timestamped one set through the parameter), destinationPath and endpointURL are recorded and match the ObjectStore and the folder in the bucket. The backup taken before the upgrade is unchanged and both survive the periodic catalog maintenance.
  • Restore from the recorded values only: I built the externalClusters entry and recoveryTarget.backupID from the Backup status and nothing else. The new cluster came up healthy with the data from before and after the upgrade.
  • Backup store different from the recovery store, no serverName set: the backup records the backup store and the default server name (the cluster name), not the recovery source.
  • Credentials in endpointURL (https://user:password@host): the backup completes, and pluginMetadata holds https://user:xxxxx@host. The password appears nowhere in the Backup object.

I used an AI assistant (Claude) to help review and write this change, as the AI policy asks for disclosure. The commit carries an Assisted-by: trailer.

Add the `ObjectStore` name, the server name, the `destinationPath` and
the `endpointURL` a backup was written to in the backup result metadata,
so that they end up in `Backup.status.pluginMetadata`. A recovery cluster
can then be pointed at the right location without listing the bucket or
digging through old manifests, which matters when `serverName` changes
across cluster generations.

The keys are only added, and left out when empty, so the metadata of
backups taken by older versions keeps the same shape. The plugin writes
them but doesn't read them back. Credentials embedded in
`destinationPath` or `endpointURL` are masked before being recorded.

Closes cloudnative-pg#1140

Assisted-by: Claude Opus 5.5
Signed-off-by: BoxBoxJason <contact@boxboxjason.dev>
@BoxBoxJason
BoxBoxJason marked this pull request as ready for review October 5, 2026 17:27
@BoxBoxJason
BoxBoxJason requested a review from a team as a code owner October 5, 2026 17:27

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Record the object store and server name of a backup in Backup.status.pluginMetadata

1 participant