Merge 129542b481 into a95197e648

Corrected path for retention policy in documentation.

Closes #1061

Signed-off-by: dblugeon <dblugeon@users.noreply.github.com>

Taskfile.yml

@@ -23,7 +23,7 @@ tasks:
       # renovate: datasource=git-refs depName=golangci-lint lookupName=https://github.com/sagikazarmark/daggerverse currentValue=main
       DAGGER_GOLANGCI_LINT_SHA: ff27cd50f6b4eed2e3753c520632cd6099e1ce52
       # renovate: datasource=docker depName=golangci/golangci-lint versioning=semver
-      GOLANGCI_LINT_VERSION: v2.13.1
+      GOLANGCI_LINT_VERSION: v2.13.2
     cmds:
       - >
         GITHUB_REF= dagger -sc "github.com/sagikazarmark/daggerverse/golangci-lint@${DAGGER_GOLANGCI_LINT_SHA}

web/docs/concepts.md

@@ -35,7 +35,7 @@ object storage system. It allows you to configure:
 - **Base backup options**—with similar settings for compression, concurrency,
   and encryption—under `.spec.configuration.data`
 - **Retention policies** to manage the life-cycle of archived WALs and backups
-  via `.spec.configuration.retentionPolicy`
+  via `.spec.retentionPolicy`
 
 WAL files are archived in the `wals` directory, while base backups are stored
 as **tarballs** in the `base` directory, following the

web/docs/parameters.md

@@ -10,7 +10,11 @@ The following parameters are available for the Barman Cloud Plugin:
 
 - `barmanObjectName`: references the `ObjectStore` resource to be used by the
   plugin.
-- `serverName`: Specifies the server name in the object store.
+- `serverName`: the archive namespace used under the ObjectStore
+  `destinationPath` for base backups and WAL files. If omitted, it defaults to
+  the Cluster name. Change this value when you need a separate archive path,
+  for example during a
+  [PostgreSQL major upgrade](usage.md#archive-path-separation-for-postgresql-major-upgrades).
 
 :::important
 The `serverName` parameter in the `ObjectStore` resource is retained solely for

web/docs/upgrades.mdx

@@ -9,6 +9,19 @@ sidebar_position: 25
 You can upgrade the plugin simply by installing the new version. Unless
 explicitly stated below or in the release notes, no special steps are required.
 
+## PostgreSQL major version upgrades
+
+Upgrading the PostgreSQL major version of a Cluster that uses this plugin is
+handled by CloudNativePG. The plugin does **not** automatically separate backup
+and WAL archives across majors.
+
+Before you change `imageName` to a new major, update the Cluster plugin
+`serverName` so the upgraded cluster writes to a new archive path. See
+[Archive path separation for PostgreSQL major upgrades](usage.md#archive-path-separation-for-postgresql-major-upgrades)
+and the CloudNativePG
+[PostgreSQL major upgrades](https://cloudnative-pg.io/documentation/current/postgres_upgrades/)
+guide.
+
 ## Upgrading to version 0.8.x from previous versions
 
 Version **0.8.0** introduces breaking changes to resource naming.

web/docs/usage.md

@@ -79,6 +79,85 @@ spec:
 
 This configuration enables both WAL archiving and data directory backups.
 
+By default, the plugin uses the Cluster name as the `serverName` archive
+namespace under the ObjectStore `destinationPath`. You can override it with the
+`serverName` plugin parameter. See
+[Parameters](parameters.md) for details.
+
+## Archive path separation for PostgreSQL major upgrades
+
+The Barman Cloud Plugin does **not** automatically separate archives when you
+perform a PostgreSQL major version upgrade. If you keep the same `serverName`,
+the upgraded cluster continues to write backups and WAL files into the same
+object-store path used before the upgrade.
+
+That is unsafe because `pg_upgrade` creates a new database system with a new
+*System ID* and resets the PostgreSQL timeline to 1. Reusing the same archive
+path can:
+
+- overwrite or collide with previous timeline 1 history files
+- mix backups and WAL files from different PostgreSQL majors in one archive
+- cause timeline/history conflicts for replicas restoring from that archive
+
+:::warning
+Point-in-time recovery (PITR) is not supported across major PostgreSQL version
+boundaries. Pre-upgrade backups cannot recover to a point in time after the
+upgrade. Take a new base backup as soon as possible after upgrading.
+:::
+
+### Recommended practice
+
+Change the Cluster plugin `serverName` when you change `imageName` for the
+major upgrade. Existing backups and WAL files remain available under the old
+`serverName` path. New backups and WAL archives go to the new path.
+
+Before upgrade (PostgreSQL 16):
+
+```yaml
+apiVersion: postgresql.cnpg.io/v1
+kind: Cluster
+metadata:
+  name: cluster-example
+spec:
+  imageName: ghcr.io/cloudnative-pg/postgresql:16
+  plugins:
+    - name: barman-cloud.cloudnative-pg.io
+      isWALArchiver: true
+      parameters:
+        barmanObjectName: prod-store
+        serverName: cluster-pg16
+```
+
+After upgrade (PostgreSQL 18) — update both `imageName` and `serverName`
+together:
+
+```yaml
+apiVersion: postgresql.cnpg.io/v1
+kind: Cluster
+metadata:
+  name: cluster-example
+spec:
+  imageName: ghcr.io/cloudnative-pg/postgresql:18
+  plugins:
+    - name: barman-cloud.cloudnative-pg.io
+      isWALArchiver: true
+      parameters:
+        barmanObjectName: prod-store
+        serverName: cluster-pg18
+```
+
+With this configuration:
+
+- pre-upgrade backups remain under `serverName: cluster-pg16`
+- the upgraded cluster archives to `serverName: cluster-pg18`
+- you can still recover the pre-upgrade cluster by pointing recovery
+  `externalClusters` plugin parameters at the old `serverName`
+
+For the full CloudNativePG major-upgrade procedure, including backup and WAL
+archive considerations, see the
+[PostgreSQL major upgrades](https://cloudnative-pg.io/documentation/current/postgres_upgrades/)
+documentation.
+
 ## Performing a Base Backup
 
 Once WAL archiving is enabled, the cluster is ready for backups. Backups can be