docs: restructure backup and recovery section for CNPG-I plugins (cloudnative-pg#7581)

With the introduction of the CNPG-I interface and official support for
the Barman Cloud Plugin, the backup and recovery documentation has been
reorganised to reflect the new plugin-based architecture.

This is the first step toward a more modular and extensible approach.
Further work is planned outside the core CloudNativePG repository,
including maintaining an inventory of available plugins and migrating
volume snapshot support into a dedicated plugin.

Closes cloudnative-pg#6876

Signed-off-by: Gabriele Bartolini <gabriele.bartolini@enterprisedb.com>
Signed-off-by: Francesco Canovai <francesco.canovai@enterprisedb.com>
Co-authored-by: Francesco Canovai <francesco.canovai@enterprisedb.com>

Author: gbartolini

.wordlist-en-custom.txt

@@ -507,6 +507,7 @@ Uncomment
 Unrealizable
 UpdateStrategy
 VLDB
+VLDBs
 VM
 VMs
 VOLNAME

docs/mkdocs.yml

@@ -14,6 +14,7 @@ markdown_extensions:
   - def_list
   - attr_list
   - footnotes
+  - pymdownx.caret
 
 nav:
   - index.md
@@ -34,9 +35,7 @@ nav:
   - replication.md
   - logical_replication.md
   - backup.md
-  - backup_barmanobjectstore.md
   - wal_archiving.md
-  - backup_volumesnapshot.md
   - recovery.md
   - service_management.md
   - postgresql_conf.md
@@ -77,4 +76,6 @@ nav:
   - CNCF Projects Integrations:
     - cncf-projects/external-secrets.md
   - Appendixes:
+    - appendixes/backup_volumesnapshot.md
+    - appendixes/backup_barmanobjectstore.md
     - appendixes/object_stores.md

docs/src/backup_barmanobjectstore.md …c/appendixes/backup_barmanobjectstore.mddocs/src/backup_barmanobjectstore.md renamed to docs/src/appendixes/backup_barmanobjectstore.md docs/src/backup_barmanobjectstore.md renamed to docs/src/appendixes/backup_barmanobjectstore.md

@@ -1,11 +1,14 @@
-# Backup on object stores
+# Appendix B - Backup on object stores
+
 <!-- SPDX-License-Identifier: CC-BY-4.0 -->
 
 !!! Warning
-    With the deprecation of native Barman Cloud support in CloudNativePG in
-    favor of the Barman Cloud Plugin, this page—and the backup and recovery
-    documentation—may undergo changes before the official release of version
-    1.26.0.
+    As of CloudNativePG 1.26, **native Barman Cloud support is deprecated** in
+    favor of the **Barman Cloud Plugin**. This page has been moved to the appendix
+    for reference purposes. While the native integration remains functional for
+    now, we strongly recommend beginning a gradual migration to the plugin-based
+    interface after appropriate testing.  For guidance, see
+    [Migrating from Built-in CloudNativePG Backup](https://cloudnative-pg.io/plugin-barman-cloud/docs/migration/).
 
 CloudNativePG natively supports **online/hot backup** of PostgreSQL
 clusters through continuous physical backup and WAL archiving on an object
@@ -34,23 +37,90 @@ as it is composed of a community PostgreSQL image and the latest
 
 A backup is performed from a primary or a designated primary instance in a
 `Cluster` (please refer to
-[replica clusters](replica_cluster.md)
+[replica clusters](../replica_cluster.md)
 for more information about designated primary instances), or alternatively
-on a [standby](backup.md#backup-from-a-standby).
+on a [standby](../backup.md#backup-from-a-standby).
 
 ## Common object stores
 
 If you are looking for a specific object store such as
-[AWS S3](appendixes/object_stores.md#aws-s3),
-[Microsoft Azure Blob Storage](appendixes/object_stores.md#azure-blob-storage),
-[Google Cloud Storage](appendixes/object_stores.md#google-cloud-storage), or
-[MinIO Gateway](appendixes/object_stores.md#minio-gateway), or a compatible
-provider, please refer to [Appendix A - Common object stores](appendixes/object_stores.md).
+[AWS S3](object_stores.md#aws-s3),
+[Microsoft Azure Blob Storage](object_stores.md#azure-blob-storage),
+[Google Cloud Storage](object_stores.md#google-cloud-storage), or a compatible
+provider, please refer to [Appendix C - Common object stores for backups](object_stores.md).
 
-## Retention policies
+## WAL archiving
+
+WAL archiving is the process that feeds a [WAL archive](../backup.md#wal-archive)
+in CloudNativePG.
+
+The WAL archive is defined in the `.spec.backup.barmanObjectStore` stanza of
+a `Cluster` resource.
+
+!!! Info
+    Please refer to [`BarmanObjectStoreConfiguration`](https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api#BarmanObjectStoreConfiguration)
+    in the barman-cloud API for a full list of options.
+
+If required, you can choose to compress WAL files as soon as they
+are uploaded and/or encrypt them:
+
+```yaml
+apiVersion: postgresql.cnpg.io/v1
+kind: Cluster
+[...]
+spec:
+  backup:
+    barmanObjectStore:
+      [...]
+      wal:
+        compression: gzip
+        encryption: AES256
+```
+
+You can configure the encryption directly in your bucket, and the operator
+will use it unless you override it in the cluster configuration.
+
+PostgreSQL implements a sequential archiving scheme, where the
+`archive_command` will be executed sequentially for every WAL
+segment to be archived.
 
 !!! Important
-    Retention policies are not currently available on volume snapshots.
+    By default, CloudNativePG sets `archive_timeout` to `5min`, ensuring
+    that WAL files, even in case of low workloads, are closed and archived
+    at least every 5 minutes, providing a deterministic time-based value for
+    your Recovery Point Objective ([RPO](../before_you_start.md#rpo)). Even though you change the value
+    of the [`archive_timeout` setting in the PostgreSQL configuration](https://www.postgresql.org/docs/current/runtime-config-wal.html#GUC-ARCHIVE-TIMEOUT),
+    our experience suggests that the default value set by the operator is
+    suitable for most use cases.
+
+When the bandwidth between the PostgreSQL instance and the object
+store allows archiving more than one WAL file in parallel, you
+can use the parallel WAL archiving feature of the instance manager
+like in the following example:
+
+```yaml
+apiVersion: postgresql.cnpg.io/v1
+kind: Cluster
+[...]
+spec:
+  backup:
+    barmanObjectStore:
+      [...]
+      wal:
+        compression: gzip
+        maxParallel: 8
+        encryption: AES256
+```
+
+In the previous example, the instance manager optimizes the WAL
+archiving process by archiving in parallel at most eight ready
+WALs, including the one requested by PostgreSQL.
+
+When PostgreSQL will request the archiving of a WAL that has
+already been archived by the instance manager as an optimization,
+that archival request will be just dismissed with a positive status.
+
+## Retention policies
 
 CloudNativePG can manage the automated deletion of backup files from
 the backup object store, using **retention policies** based on the recovery
@@ -163,7 +233,7 @@ spec:
 You can append additional options to the `barman-cloud-backup` and `barman-cloud-wal-archive` commands by using
 the `additionalCommandArgs` property in the
 `.spec.backup.barmanObjectStore.data` and `.spec.backup.barmanObjectStore.wal` sections respectively.
-This properties are lists of strings that will be appended to the
+These properties are lists of strings that will be appended to the
 `barman-cloud-backup` and `barman-cloud-wal-archive` commands.
 
 For example, you can use the `--read-timeout=60` to customize the connection
@@ -209,3 +279,61 @@ spec:
         - "--max-concurrency=1"
         - "--read-timeout=60"
 ```
+
+## Recovery from an object store
+
+You can recover from a backup created by Barman Cloud and stored on a supported
+object store. After you define the external cluster, including all the required
+configuration in the `barmanObjectStore` section, you need to reference it in
+the `.spec.recovery.source` option.
+
+This example defines a recovery object store in a blob container in Azure:
+
+```yaml
+apiVersion: postgresql.cnpg.io/v1
+kind: Cluster
+metadata:
+  name: cluster-restore
+spec:
+  [...]
+
+  superuserSecret:
+    name: superuser-secret
+
+  bootstrap:
+    recovery:
+      source: clusterBackup
+
+  externalClusters:
+    - name: clusterBackup
+      barmanObjectStore:
+        destinationPath: https://STORAGEACCOUNTNAME.blob.core.windows.net/CONTAINERNAME/
+        azureCredentials:
+          storageAccount:
+            name: recovery-object-store-secret
+            key: storage_account_name
+          storageKey:
+            name: recovery-object-store-secret
+            key: storage_account_key
+        wal:
+          maxParallel: 8
+```
+
+The previous example assumes that the application database and its owning user
+are named `app` by default. If the PostgreSQL cluster being restored uses
+different names, you must specify these names before exiting the recovery phase,
+as documented in ["Configure the application database"](../recovery.md#configure-the-application-database).
+
+!!! Important
+    By default, the `recovery` method strictly uses the `name` of the
+    cluster in the `externalClusters` section as the name of the main folder
+    of the backup data within the object store. This name is normally reserved
+    for the name of the server. You can specify a different folder name
+    using the `barmanObjectStore.serverName` property.
+
+!!! Note
+    This example takes advantage of the parallel WAL restore feature,
+    dedicating up to 8 jobs to concurrently fetch the required WAL files from the
+    archive. This feature can appreciably reduce the recovery time. Make sure that
+    you plan ahead for this scenario and correctly tune the value of this parameter
+    for your environment. It will make a difference when you need it, and you will.

docs/src/backup_volumesnapshot.md …/src/appendixes/backup_volumesnapshot.mddocs/src/backup_volumesnapshot.md renamed to docs/src/appendixes/backup_volumesnapshot.md docs/src/backup_volumesnapshot.md renamed to docs/src/appendixes/backup_volumesnapshot.md

@@ -1,12 +1,10 @@
-# Backup on volume snapshots
+# Appendix A - Backup on volume snapshots
 <!-- SPDX-License-Identifier: CC-BY-4.0 -->
 
-!!! Warning
-    As noted in the [backup document](backup.md), a cold snapshot explicitly
-    set to target the primary will result in the primary being fenced for
-    the duration of the backup, rendering the cluster read-only during that
-    For safety, in a cluster already containing fenced instances, a cold
-    snapshot is rejected.
+!!! Important
+    Please refer to the official Kubernetes documentation for a list of all
+    the supported [Container Storage Interface (CSI) drivers](https://kubernetes-csi.github.io/docs/drivers.html)
+    that provide snapshotting capabilities.
 
 CloudNativePG is one of the first known cases of database operators that
 directly leverages the Kubernetes native Volume Snapshot API for both
@@ -53,18 +51,16 @@ volumes of a given storage class, and managed as `VolumeSnapshot` and
 !!! Important
     It is your responsibility to verify with the third party vendor
     that volume snapshots are supported. CloudNativePG only interacts
-    with the Kubernetes API on this matter and we cannot support issues
+    with the Kubernetes API on this matter, and we cannot support issues
     at the storage level for each specific CSI driver.
 
 ## How to configure Volume Snapshot backups
 
-<!-- TODO: Change before 1.26.0 -->
-
 CloudNativePG allows you to configure a given Postgres cluster for Volume
 Snapshot backups through the `backup.volumeSnapshot` stanza.
 
 !!! Info
-    Please refer to [`VolumeSnapshotConfiguration`](cloudnative-pg.v1.md#postgresql-cnpg-io-v1-VolumeSnapshotConfiguration)
+    Please refer to [`VolumeSnapshotConfiguration`](../cloudnative-pg.v1.md#postgresql-cnpg-io-v1-VolumeSnapshotConfiguration)
     in the API reference for a full list of options.
 
 A generic example with volume snapshots (assuming that PGDATA and WALs share
@@ -89,18 +85,21 @@ spec:
     # Volume snapshot backups
     volumeSnapshot:
        className: @VOLUME_SNAPSHOT_CLASS_NAME@
-    # WAL archive
-    barmanObjectStore:
-       # ...
+       
+  plugins:
+  - name: barman-cloud.cloudnative-pg.io
+    isWALArchiver: true
+    parameters:
+      barmanObjectName: @OBJECTSTORE_NAME@
 ```
 
 As you can see, the `backup` section contains both the `volumeSnapshot` stanza
 (controlling physical base backups on volume snapshots) and the
-`barmanObjectStore` one (controlling the [WAL archive](wal_archiving.md)).
+`plugins` one (controlling the [WAL archive](../wal_archiving.md)).
 
 !!! Info
-    Once you have defined the `barmanObjectStore`, you can decide to use
-    both volume snapshot and object store backup strategies simultaneously
+    Once you have defined the `plugin`, you can decide to use
+    both volume snapshot and plugin backup strategies simultaneously
     to take physical backups.
 
 The `volumeSnapshot.className` option allows you to reference the default
@@ -118,6 +117,13 @@ a `ScheduledBackup` resource that requests such backups on a periodic basis.
 
 ## Hot and cold backups
 
+!!! Warning
+    As noted in the [backup document](../backup.md), a cold snapshot explicitly
+    set to target the primary will result in the primary being fenced for
+    the duration of the backup, making the cluster read-only during this
+    period. For safety, in a cluster already containing fenced instances, a cold
+    snapshot is rejected.
+
 By default, CloudNativePG requests an online/hot backup on volume snapshots, using the
 [PostgreSQL defaults of the low-level API for base backups](https://www.postgresql.org/docs/current/continuous-archiving.html#BACKUP-LOWLEVEL-BASE-BACKUP):
 
@@ -335,8 +341,6 @@ spec:
 
 ## Example of Volume Snapshot Backup
 
-<!-- TODO: Change before 1.26.0 -->
-
 The following example shows how to configure volume snapshot base backups on an
 EKS cluster on AWS using the `ebs-sc` storage class and the `csi-aws-vsc`
 volume snapshot class.
@@ -349,7 +353,7 @@ volume snapshot class.
 
 The following manifest creates a `Cluster` that is ready to be used for volume
 snapshots and that stores the WAL archive in a S3 bucket via IAM role for the
-Service Account (IRSA, see [AWS S3](appendixes/object_stores.md#aws-s3)):
+Service Account (IRSA, see [AWS S3](object_stores.md#aws-s3)):
 
 ``` yaml
 apiVersion: postgresql.cnpg.io/v1
@@ -369,13 +373,12 @@ spec:
   backup:
     volumeSnapshot:
        className: csi-aws-vsc
-    barmanObjectStore:
-      destinationPath: s3://@BUCKET_NAME@/
-      s3Credentials:
-        inheritFromIAMRole: true
-      wal:
-        compression: gzip
-        maxParallel: 2
+
+  plugins:
+  - name: barman-cloud.cloudnative-pg.io
+    isWALArchiver: true
+    parameters:
+      barmanObjectName: @OBJECTSTORE_NAME@
 
   serviceAccountTemplate:
     metadata: