Skip to content

Commit 302a019

Browse files
androndoclaude
andcommitted
docs+test(backups): update upgrade notes for the plugin flow + cover recovery rendering
Review follow-ups for the CNPG barman-cloud plugin migration (#3300): - docs/operations/backup-classes.md: the 'Upgrade notes from chart-managed backups' section still described the removed native spec.backup.barmanObjectStore behavior. Rewrite it for the plugin flow (chart renders spec.plugins + a barmancloud.cnpg.io/ObjectStore; the driver SSA-applies an ObjectStore and patches spec.plugins), and document the real upgrade hazard: the plugin-barman-cloud operator + cert-manager must be present in cozy-postgres-operator or the Cluster references an unregistered plugin and backups/WAL archiving stall. - apps/postgres backup_storage_test.yaml: add a positive bootstrap-recovery rendering test. Asserts externalClusters[].plugin references barman-cloud.cloudnative-pg.io with barmanObjectName=<release>-recovery and serverName on the plugin parameter, and that the -recovery ObjectStore carries spec.configuration but NOT serverName (the plugin forbids it there). Previously the recovery path had only fail-fast guard tests, no positive coverage. Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]> Signed-off-by: Andrey Kolkov <[email protected]>
1 parent 39bd862 commit 302a019

2 files changed

Lines changed: 67 additions & 4 deletions

File tree

‎docs/operations/backup-classes.md‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -162,12 +162,16 @@ If a deployment runs against an external S3 (no SeaweedFS), set `backupStorage.p
162162

163163
## Upgrade notes from chart-managed backups
164164

165-
> **Postgres `backup.enabled: true` with placeholder credentials no longer renders `barmanObjectStore` on upgrade.**
165+
> **Postgres backups now use the CloudNativePG Barman Cloud plugin, not native `spec.backup.barmanObjectStore`.**
166166
>
167-
> The pre-PR defaults for `backup.s3AccessKey` / `backup.s3SecretKey` in `packages/apps/postgres/values.yaml` were the literal `"<your-access-key>"` / `"<your-secret-key>"` placeholders, so the Postgres chart still rendered `spec.backup.barmanObjectStore` on the `cnpg.io/Cluster` (with junk credentials, `archive_command` failing at runtime). After this PR those defaults are empty strings and the chart NO LONGER renders the backup block at all when the placeholders are unmodified. Tenants on the legacy chart-managed flow who relied on those placeholders see their `barmanObjectStore` disappear from the live `Cluster` on `helm upgrade`. Action — pick one:
167+
> Postgres backups were migrated off the deprecated native `barmanObjectStore` (removed in CNPG 1.29; its `barman-cloud-*` binaries are absent from the pinned image variants) onto the [Barman Cloud plugin](https://github.com/cloudnative-pg/plugin-barman-cloud). The chart now renders `spec.plugins` on the `cnpg.io/Cluster` plus a `barmancloud.cnpg.io/ObjectStore` CR that carries the S3 configuration, and the CNPG backup driver SSA-applies an `ObjectStore` and patches `spec.plugins` (instead of `spec.backup.barmanObjectStore`) for the platform flow; `Backup`/`ScheduledBackup` use `method: plugin`. On `helm upgrade` a legacy chart-managed Cluster's `spec.backup.barmanObjectStore` is replaced by `spec.plugins` + an `ObjectStore`. This only works once the `plugin-barman-cloud` operator is installed and co-located with the CNPG operator in `cozy-postgres-operator` (shipped by the `postgres-operator` chart) and its cert-manager dependency is present — otherwise the Cluster references a plugin that is not registered and backups / WAL archiving stall.
168168
>
169-
> - **Move to the platform flow (recommended).** Set `backup.useSystemBucket: true`; the chart leaves `barmanObjectStore` unset and the CNPG backup driver SSA-patches it onto the live `Cluster` at first BackupJob time. No tenant-side keys required.
170-
> - **Stay on the legacy chart-managed flow.** Supply real `backup.s3AccessKey` / `backup.s3SecretKey` (or a pre-existing `backup.s3CredentialsSecret.name`); the chart renders `barmanObjectStore` exactly as before.
169+
> **Postgres `backup.enabled: true` with placeholder credentials no longer wires backups on upgrade.**
170+
>
171+
> The pre-PR defaults for `backup.s3AccessKey` / `backup.s3SecretKey` in `packages/apps/postgres/values.yaml` were the literal `"<your-access-key>"` / `"<your-secret-key>"` placeholders, so the Postgres chart still rendered a backup block on the `cnpg.io/Cluster` (with junk credentials, WAL archiving failing at runtime). After this PR those defaults are empty strings and the chart NO LONGER renders any backup wiring when the placeholders are unmodified. Tenants on the legacy chart-managed flow who relied on those placeholders see `spec.plugins` and the `ObjectStore` disappear from the live `Cluster` on `helm upgrade`. Action — pick one:
172+
>
173+
> - **Move to the platform flow (recommended).** Set `backup.useSystemBucket: true`; the chart leaves `spec.plugins` unset and the CNPG backup driver SSA-applies the `ObjectStore` and patches `spec.plugins` onto the live `Cluster` at first BackupJob time. No tenant-side keys required.
174+
> - **Stay on the legacy chart-managed flow.** Supply real `backup.s3AccessKey` / `backup.s3SecretKey` (or a pre-existing `backup.s3CredentialsSecret.name`); the chart renders `spec.plugins` + the `ObjectStore` from those coordinates.
171175
>
172176
> The same `useSystemBucket` opt-in applies to ClickHouse — see [ClickHouse: opt-in to the system bucket](#clickhouse-opt-in-to-the-system-bucket). When `useSystemBucket: true` is set on ClickHouse, the legacy `<release>-backup` CronJob, credential Secret, and backup script are no longer rendered (they are mutually exclusive with the platform flow); migrate scheduled backups to a `backups.cozystack.io/Plan` against `cozy-default`.
173177

‎packages/apps/postgres/tests/backup_storage_test.yaml‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -118,6 +118,65 @@ tests:
118118
count: 0
119119
template: templates/backup-secret.yaml
120120

121+
- it: "bootstrap recovery: externalClusters[].plugin + a -recovery ObjectStore (serverName on the plugin param, not the ObjectStore)"
122+
set:
123+
backup:
124+
enabled: true
125+
useSystemBucket: false
126+
s3AccessKey: AKIAEXAMPLE
127+
s3SecretKey: s3cr3t
128+
destinationPath: s3://bucket/pg-test/
129+
endpointURL: https://s3.example:9000
130+
bootstrap:
131+
enabled: true
132+
oldName: old-pg
133+
serverName: old-server
134+
asserts:
135+
# Recovery uses the barman-cloud plugin, not the removed externalClusters[].barmanObjectStore.
136+
- notExists:
137+
path: spec.externalClusters[0].barmanObjectStore
138+
template: templates/db.yaml
139+
documentSelector:
140+
path: kind
141+
value: Cluster
142+
- equal:
143+
path: spec.externalClusters[0].plugin.name
144+
value: barman-cloud.cloudnative-pg.io
145+
template: templates/db.yaml
146+
documentSelector:
147+
path: kind
148+
value: Cluster
149+
- equal:
150+
path: spec.externalClusters[0].plugin.parameters.barmanObjectName
151+
value: pg-test-recovery
152+
template: templates/db.yaml
153+
documentSelector:
154+
path: kind
155+
value: Cluster
156+
# serverName rides on the plugin parameter...
157+
- equal:
158+
path: spec.externalClusters[0].plugin.parameters.serverName
159+
value: old-server
160+
template: templates/db.yaml
161+
documentSelector:
162+
path: kind
163+
value: Cluster
164+
# ...and the -recovery ObjectStore carries the source S3 config but MUST NOT set
165+
# serverName inside spec.configuration (the plugin forbids it there).
166+
- equal:
167+
path: spec.configuration.destinationPath
168+
value: s3://bucket/pg-test/
169+
template: templates/db.yaml
170+
documentSelector:
171+
path: metadata.name
172+
value: pg-test-recovery
173+
- notExists:
174+
path: spec.configuration.serverName
175+
template: templates/db.yaml
176+
documentSelector:
177+
path: metadata.name
178+
value: pg-test-recovery
179+
121180
- it: "bootstrap + useSystemBucket: render fails fast (lock in existing guard)"
122181
template: templates/db.yaml
123182
set:

0 commit comments

Comments
 (0)