mirror of
https://github.com/cloudnative-pg/plugin-barman-cloud.git
synced 2026-01-11 21:23:12 +01:00
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 <gabriele.bartolini@enterprisedb.com>
This commit is contained in:
Gabriele Bartolini
GitHub
parent
45055d049d
commit
f56072a917
@ -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).
|
||||
|
||||
@ -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:
|
||||
|
||||
@ -2,8 +2,175 @@
|
||||
sidebar_position: 40
|
||||
---
|
||||
|
||||
# Migrating from CloudNativePG
|
||||
# Migrating from Built-in CloudNativePG Backup
|
||||
|
||||
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
Loading…
Reference in New Issue
Block a user