From f56072a91753368d88d4ecd9f66bc62bd6453a5f Mon Sep 17 00:00:00 2001 From: Gabriele Bartolini Date: Wed, 7 May 2025 10:41:51 +0200 Subject: [PATCH] docs: add migration guide from in-tree to plugin-based Barman Cloud (#316) This commit introduces documentation that guides users through the process of migrating an existing CloudNativePG cluster from the built-in (in-tree) Barman Cloud integration to the external Barman Cloud Plugin. Closes #312. Signed-off-by: Gabriele Bartolini --- web/docs/concepts.md | 4 + web/docs/intro.md | 7 ++ web/docs/migration.md | 171 +++++++++++++++++++++++++++++++++++++++++- 3 files changed, 180 insertions(+), 2 deletions(-) diff --git a/web/docs/concepts.md b/web/docs/concepts.md index 42249ed..3832df3 100644 --- a/web/docs/concepts.md +++ b/web/docs/concepts.md @@ -41,6 +41,10 @@ WAL files are archived in the `wals` directory, while base backups are stored as **tarballs** in the `base` directory, following the [Barman Cloud convention](https://docs.pgbarman.org/cloud/latest/usage/#object-store-layout). +The plugin also offers advanced capabilities, including +[backup tagging](misc.md#backup-object-tagging) and +[extra options for backups and WAL archiving](misc.md#extra-options-for-backup-and-wal-archiving). + :::tip For details, refer to the [API reference for the `ObjectStore` resource](plugin-barman-cloud.v1.md#objectstorespec). diff --git a/web/docs/intro.md b/web/docs/intro.md index 9e2eb5c..f22f383 100644 --- a/web/docs/intro.md +++ b/web/docs/intro.md @@ -12,6 +12,13 @@ enables online continuous physical backups of PostgreSQL clusters to object stor using the `barman-cloud` suite from the [Barman](https://docs.pgbarman.org/release/latest/) project. +:::important +If you plan to migrate your existing CloudNativePG cluster to the new +plugin-based approach using the Barman Cloud Plugin, see +["Migrating from Built-in CloudNativePG Backup"](migration.md) +for detailed instructions. +::: + ## Requirements To use the Barman Cloud Plugin, you need: diff --git a/web/docs/migration.md b/web/docs/migration.md index 481705d..dafbf03 100644 --- a/web/docs/migration.md +++ b/web/docs/migration.md @@ -2,8 +2,175 @@ sidebar_position: 40 --- -# Migrating from CloudNativePG +# Migrating from Built-in CloudNativePG Backup -TODO +The in-tree support for Barman Cloud in CloudNativePG is **deprecated starting +from version 1.26** and will be removed in a future release. + +If you're currently relying on the built-in Barman Cloud integration, you can +migrate seamlessly to the new **plugin-based architecture** using the Barman +Cloud Plugin, with **no downtime**. Follow these steps: + +- [Install the Barman Cloud Plugin](installation.md) +- Create an `ObjectStore` resource by translating the contents of the + `.spec.backup.barmanObjectStore` section from your existing `Cluster` + definition +- 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 + +:::tip +For a working example, refer to [this commit](https://github.com/cloudnative-pg/cnpg-playground/commit/596f30e252896edf8f734991c3538df87630f6f7) +from the [CloudNativePG Playground project](https://github.com/cloudnative-pg/cnpg-playground), +which demonstrates a full migration. +::: + +--- + +## Step 1: Define the `ObjectStore` + +Begin by creating an `ObjectStore` resource in the same namespace as your +PostgreSQL `Cluster`. + +There is a **direct mapping** between the `.spec.backup.barmanObjectStore` +section in CloudNativePG and the `.spec.configuration` field in the +`ObjectStore` CR. The conversion is mostly mechanical, with one key difference: + +:::warning +In the plugin architecture, retention policies are defined as part of the `ObjectStore`. +In contrast, the in-tree implementation defined them at the `Cluster` level. +::: + +If your `Cluster` used `.spec.backup.retentionPolicy`, move that configuration +to `.spec.retentionPolicy` in the `ObjectStore`. + +--- + +### Example + +Here’s an excerpt from a traditional in-tree CloudNativePG backup configuration +taken from the CloudNativePG Playground project: + +```yaml +apiVersion: postgresql.cnpg.io/v1 +kind: Cluster +metadata: + name: pg-eu +spec: + # [...] + backup: + barmanObjectStore: + 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 +``` + +This configuration translates to the following `ObjectStore` resource for the +plugin: + +```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 +``` + +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` + +Once the `ObjectStore` resource is in place, update the `Cluster` resource as +follows in a single atomic change: + +- Remove the `.spec.backup.barmanObjectStore` section +- Remove `.spec.backup.retentionPolicy` if it was defined (as it is now in the + `ObjectStore`) +- Remove the entire `spec.backup` section if it is now empty +- Add `barman-cloud.cloudnative-pg.io` to the `plugins` list, as described in + [Configuring WAL archiving](usage.md#configuring-wal-archiving) + +This will trigger a rolling update of the `Cluster`, switching continuous +backup from the in-tree implementation to the plugin-based approach. + +### Example + +The updated `pg-eu` cluster will have this configuration instead of the +previous `backup` section: + +```yaml + plugins: + - name: barman-cloud.cloudnative-pg.io + isWALArchiver: true + parameters: + barmanObjectName: minio-eu +``` + +--- + +## Step 3: Update the `ScheduledBackup` + +After switching the `Cluster` to use the plugin, update your `ScheduledBackup` +resources to match. + +Set the backup `method` to `plugin` and reference the plugin name via +`pluginConfiguration`, as shown in ["Performing a base backup"](usage.md#performing-a-base-backup). + +### Example + +Original in-tree `ScheduledBackup`: + +```yaml +apiVersion: postgresql.cnpg.io/v1 +kind: ScheduledBackup +metadata: + name: pg-eu-backup +spec: + cluster: + name: pg-eu + schedule: '0 0 0 * * *' + backupOwnerReference: self +``` + +Updated version using the plugin: + +```yaml +apiVersion: postgresql.cnpg.io/v1 +kind: ScheduledBackup +metadata: + name: pg-eu-backup +spec: + cluster: + name: pg-eu + schedule: '0 0 0 * * *' + backupOwnerReference: self + method: plugin + pluginConfiguration: + name: barman-cloud.cloudnative-pg.io +``` + +---