feat: support S3 SSE-C (customer-provided encryption keys)

[schaurian]

Summary

Adds support for S3 Server-Side Encryption with Customer-provided keys (SSE-C) to the ObjectStore resource, closing #646.

S3-compatible providers such as Hetzner Object Storage do not offer bucket-managed encryption (SSE-S3 / SSE-KMS) and only support SSE-C. Without this, backups and WALs can only be stored unencrypted at rest on those providers.

Users can now reference a secret holding a base64-encoded 256-bit AES key via a new sseCustomerKey field:

apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
spec:
  configuration:
    destinationPath: "s3://BUCKET_NAME/path/to/folder"
    endpointURL: "https://fsn1.your-objectstorage.com"
    s3Credentials:
      accessKeyId: { name: aws-creds, key: ACCESS_KEY_ID }
      secretAccessKey: { name: aws-creds, key: ACCESS_SECRET_KEY }
      sseCustomerKey: { name: aws-sse-c, key: key }

What changed

The field is defined in the shared barman-cloud library and flows through the embedded BarmanObjectStoreConfiguration, so the plugin change is intentionally small:

File	Change
go.mod / go.sum	Point barman-cloud at the version carrying sseCustomerKey (see below)
internal/cnpgi/operator/specs/secrets.go	Include sseCustomerKey in CollectSecretNamesFromCredentials, so the instance Role covers a key kept in its own Secret (by @andrein, with test)
config/crd/bases/…_objectstores.yaml	Regenerated CRD (adds sseCustomerKey)
manifest.yaml	Regenerated consolidated installer
web/docs/object_stores.md	New "Server-Side Encryption with Customer Keys (SSE-C)" section
.wordlist.txt	Spellcheck entries for the new docs section

No controller logic changes are needed: the library injects --sse-customer-key file://… into every barman-cloud-* command (backup, wal-archive, wal-restore, restore, backup-list, backup-delete, check-wal-archive) and materializes the key from its secret, so all read/write paths are covered.

sseCustomerKey cannot be combined with data.encryption / wal.encryption: barman-cloud rejects --sse-customer-key together with --encryption. barman-cloud#284 adds that check to ValidateBackupConfiguration; note that this plugin does not currently call ValidateBackupConfiguration for ObjectStore objects, so today the combination is only caught at run time (documented as such). Happy to wire the validation into the plugin in a follow-up if you'd like it enforced at admission.

Dependency

This PR depends on cloudnative-pg/barman-cloud#284. Until that is merged and released, go.mod carries a temporary replace directive pointing at the PR head:

replace github.com/cloudnative-pg/barman-cloud => github.com/schaurian/barman-cloud v0.5.2-0.20260908142745-14f89b687e74

Once barman-cloud#284 is released, the replace should be dropped and the require bumped to the released version.

Runtime use requires Barman ≥ 3.20.0 (--sse-customer-key option), which the sidecar image pins since v0.15.0 — this branch is rebased on main accordingly.

Testing

• Full task ci run locally: commitlint, spellcheck, go test (envtest), uncommitted-drift check (CRD / manifest / API docs regenerated via the repo's dagger tasks), docusaurus build, and the ephemeral-k3s e2e suite — 10 passed, 0 failed, 4 skipped (the GCS specs disabled pending barman-cloud-backup 3.20.0 should respect STORAGE_EMULATOR_HOST during multiplepart backup EnterpriseDB/barman#1218). golangci-lint reports only gomoddirectives on the temporary replace line above, which goes away once the replace is dropped.
• CRD and manifest.yaml diff to exactly the new field.
• Field-tested by @andrein against a Ceph RGW store that supports only SSE-C, with CloudNativePG 1.30.0 (continuous WAL archiving with Encryption: SSE-C objects, base backup, backup-list, retention via backup-delete, serverRecoveryWindow, and recovery into a new Cluster via externalClusters[].plugin) — see the comment below.

Closes #646

🤖 Generated with Claude Code

[andrein]

Tested at adb7045 with main merged in for Barman 3.20.0, against a Ceph RGW
object store that supports only SSE-C, with CloudNativePG 1.30.0 and
cloudnative-pg/barman-cloud#284 at a300841.

Two changes were required:

1. sseCustomerKey is not collected by CollectSecretNamesFromCredentials, so
   the instance Role does not cover a key stored in its own Secret, as in the
   aws-sse-c docs example, and credential resolution fails with a forbidden
   error. fix: grant the instance role access to the SSE-C key secret schaurian/plugin-barman-cloud#1 against this branch adds it with a test.
2. The branch is based on v0.14.0, whose sidecar pins Barman 3.19.1;
   --sse-customer-key exists from 3.20.0, pinned on main since v0.15.0.

With those:

• key materialised in the sidecar and passed to every barman-cloud command,
  including backup-list and backup-delete
• WAL archiving continuous; objects report Encryption: SSE-C, 400 without the key
• base backup completed with Backup.status populated
• ObjectStore.status.serverRecoveryWindow populated
• retention applied on the primary
• recovery into a new Cluster through externalClusters[].plugin reproduced
  the source database

[schaurian]

Thanks for the end-to-end run and the RBAC fix, @andrein — merged schaurian#1 into this branch.

Updated the branch (eed228a):

• Rebased onto main, so the sidecar carries Barman 3.20.0 and the branch no longer conflicts.
• go.mod replace now points at the current head of feat: add support for S3 SSE-C (customer-provided encryption keys) barman-cloud#284 (14f89b6), which includes your ValidateBackupConfiguration change.
• CRD, manifest.yaml and API docs regenerated with the repo's dagger tasks; the diff against main is exactly the new field.
• Docs: the SSE-C section no longer claims the field is independent of encryption — it now states that sseCustomerKey cannot be combined with data.encryption / wal.encryption — and the version note points at Barman ≥ 3.20.0 (sidecar since v0.15.0) instead of the barman issue.
• Added the new docs words to .wordlist.txt; spellcheck was the other reason the first CI run failed.

Local task ci on this head: commitlint, spellcheck, go test, uncommitted-drift check, docusaurus build and the ephemeral e2e suite (10 passed, 0 failed, 4 skipped — the GCS specs) all pass. golangci-lint reports only gomoddirectives for the temporary replace, which disappears once barman-cloud#284 is released and the replace is dropped.

One observation: the plugin does not call ValidateBackupConfiguration anywhere, so the new barman-cloud check does not currently guard ObjectStore objects — an object store with both sseCustomerKey and data.encryption is still accepted and fails at the first backup. The docs describe that behaviour. If you'd like it rejected at admission, I'm happy to wire the validation into the plugin in a follow-up.

[armru]

I pushed a few commits on top:

• main merged in, so the e2e runs on RustFS;
• the replace bumped to the new head of feat: add support for S3 SSE-C (customer-provided encryption keys) barman-cloud#284;
• CEL rules on ObjectStore that reject sseCustomerKey together with data.encryption / wal.encryption at admission, with the docs updated;
• a replica cluster e2e where the source and the replica object stores use different SSE-C keys, each kept in its own secret. It checks that every object in each bucket is readable with its own key only.

That e2e is what found the check-wal-archive problem fixed in cloudnative-pg/barman-cloud#284: --sse-customer-key no longer reaches that command, and the combination with encryption is now rejected at admission instead of failing at run time. The PR description could be updated on both points.

[gustabowill]

Following the same suggestion I left in: https://github.com/cloudnative-pg/barman-cloud/pull/284/changes#r4197823691

Suggested change

	When set, every object barman-cloud uploads to and downloads from
	S3 is encrypted with this key using the AWS SSE-C protocol
	(the `--sse-customer-key` barman-cloud option).
	// When set, it is the key barman-cloud uses to encrypt objects uploaded
	// to S3 and to decrypt them when they are read back, following the AWS
	// SSE-C protocol (the `--sse-customer-key` barman-cloud option).

[gustabowill]

Following the same suggestion I left in: https://github.com/cloudnative-pg/barman-cloud/pull/284/changes#r4197823691

Suggested change

	When set, every object barman-cloud uploads to and downloads from
	S3 is encrypted with this key using the AWS SSE-C protocol
	(the `--sse-customer-key` barman-cloud option).
	// When set, it is the key barman-cloud uses to encrypt objects uploaded
	// to S3 and to decrypt them when they are read back, following the AWS
	// SSE-C protocol (the `--sse-customer-key` barman-cloud option).```