From e89f09ccedc4bedc230ed06175c7c7cd0df72f27 Mon Sep 17 00:00:00 2001
From: Francesco Canovai <francesco.canovai@enterprisedb.com>
Date: Thu, 8 May 2025 14:33:49 +0200
Subject: [PATCH 1/2] docs: document replica cluster migration

Add a documentation section about updating the externalClusters to use
the plugin.

Closes #322

Signed-off-by: Francesco Canovai <francesco.canovai@enterprisedb.com>
---
 web/docs/migration.md | 83 ++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 82 insertions(+), 1 deletion(-)

diff --git a/web/docs/migration.md b/web/docs/migration.md
index dafbf039..a1ac9e3e 100644
--- a/web/docs/migration.md
+++ b/web/docs/migration.md
@@ -102,7 +102,7 @@ As you can see, the contents of `barmanObjectStore` have been copied directly
 under the `configuration` field of the `ObjectStore` resource, using the same
 secret references.
 
-## Step 2: Update the `Cluster`
+## Step 2: Update the `Cluster` for plugin WAL archiving
 
 Once the `ObjectStore` resource is in place, update the `Cluster` resource as
 follows in a single atomic change:
@@ -174,3 +174,84 @@ spec:
 ```
 
 ---
+
+## Step 4: Update `externalClusters` configuration
+
+If the cluster has external clusters that use the built-in Barman
+Cloud integration, you'll need to update those configurations as well.
+
+When a cluster is configured as a replica using an external Barman Cloud backup,
+you need to:
+
+1. Create an `ObjectStore` resource for the external cluster, similar to the one
+   created in [step 1](#step-1-define-the-objectstore)
+2. Update the `externalClusters` section in your replica cluster to reference
+   the plugin
+
+### Example
+
+Original external cluster configuration using in-tree backup:
+
+```yaml
+apiVersion: postgresql.cnpg.io/v1
+kind: Cluster
+metadata:
+  name: pg-us
+spec:
+  # [...]
+  externalClusters:
+  - name: pg-eu
+    barmanObjectStore:
+      destinationPath: s3://backups/
+      endpointURL: http://minio-eu:9000
+      serverName: pg-eu
+      s3Credentials:
+        accessKeyId:
+          name: minio-eu
+          key: ACCESS_KEY_ID
+        secretAccessKey:
+          name: minio-eu
+          key: ACCESS_SECRET_KEY
+      wal:
+        compression: gzip
+```
+
+Create the `ObjectStore` resource for the external cluster:
+
+```yaml
+apiVersion: barmancloud.cnpg.io/v1
+kind: ObjectStore
+metadata:
+  name: minio-eu
+spec:
+  configuration:
+    destinationPath: s3://backups/
+    endpointURL: http://minio-eu:9000
+    s3Credentials:
+    accessKeyId:
+        name: minio-eu
+        key: ACCESS_KEY_ID
+    secretAccessKey:
+        name: minio-eu
+        key: ACCESS_SECRET_KEY
+    wal:
+      compression: gzip
+```
+
+Update the external cluster configuration to use the plugin:
+
+```yaml
+apiVersion: postgresql.cnpg.io/v1
+kind: Cluster
+metadata:
+  name: pg-us
+spec:
+  # [...]
+  externalClusters:
+  - name: pg-eu
+    plugin:
+      name: barman-cloud.cloudnative-pg.io
+      parameters:
+        barmanObjectName: minio-eu
+        serverName: pg-eu
+```

From 788d2a1cbc9999b2c7168aefb7702b2580e80070 Mon Sep 17 00:00:00 2001
From: Gabriele Bartolini <gabriele.bartolini@enterprisedb.com>
Date: Fri, 9 May 2025 08:38:41 +0200
Subject: [PATCH 2/2] docs: review

Signed-off-by: Gabriele Bartolini <gabriele.bartolini@enterprisedb.com>
---
 web/docs/migration.md | 22 ++++++++++++----------
 1 file changed, 12 insertions(+), 10 deletions(-)

diff --git a/web/docs/migration.md b/web/docs/migration.md
index a1ac9e3e..3c4ba98a 100644
--- a/web/docs/migration.md
+++ b/web/docs/migration.md
@@ -20,6 +20,7 @@ Cloud Plugin, with **no downtime**. Follow these steps:
 - Modify the `Cluster` resource in a single atomic change to switch from
   in-tree backup to the plugin
 - Update any `ScheduledBackup` resources to use the plugin
+- Update the `externalClusters` configuration, where applicable
 
 :::tip
 For a working example, refer to [this commit](https://github.com/cloudnative-pg/cnpg-playground/commit/596f30e252896edf8f734991c3538df87630f6f7)
@@ -175,22 +176,23 @@ spec:
 
 ---
 
-## Step 4: Update `externalClusters` configuration
+## Step 4: Update the `externalClusters` configuration
 
-If the cluster has external clusters that use the built-in Barman
-Cloud integration, you'll need to update those configurations as well.
+If your `Cluster` relies on one or more external clusters that use the in-tree
+Barman Cloud integration, you need to update those configurations to use the
+plugin-based architecture.
 
-When a cluster is configured as a replica using an external Barman Cloud backup,
-you need to:
+When a replica cluster fetches WAL files or base backups from an external
+source that used the built-in backup method, follow these steps:
 
-1. Create an `ObjectStore` resource for the external cluster, similar to the one
-   created in [step 1](#step-1-define-the-objectstore)
-2. Update the `externalClusters` section in your replica cluster to reference
-   the plugin
+1. Create a corresponding `ObjectStore` resource for the external cluster, as
+   shown in [Step 1](#step-1-define-the-objectstore)
+2. Update the `externalClusters` section of your replica cluster to use the
+   plugin instead of the in-tree `barmanObjectStore` field
 
 ### Example
 
-Original external cluster configuration using in-tree backup:
+Consider the original configuration using in-tree Barman Cloud:
 
 ```yaml
 apiVersion: postgresql.cnpg.io/v1