Skip to content

Commit f56072a

Browse files
gbartolinigbartolini
authored
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 <[email protected]>
1 parent 45055d0 commit f56072a

File tree

3 files changed

+180
-2
lines changed

3 files changed

+180
-2
lines changed

‎web/docs/concepts.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -41,6 +41,10 @@ WAL files are archived in the `wals` directory, while base backups are stored
4141
as **tarballs** in the `base` directory, following the
4242
[Barman Cloud convention](https://docs.pgbarman.org/cloud/latest/usage/#object-store-layout).
4343

44+
The plugin also offers advanced capabilities, including
45+
[backup tagging](misc.md#backup-object-tagging) and
46+
[extra options for backups and WAL archiving](misc.md#extra-options-for-backup-and-wal-archiving).
47+
4448
:::tip
4549
For details, refer to the
4650
[API reference for the `ObjectStore` resource](plugin-barman-cloud.v1.md#objectstorespec).

‎web/docs/intro.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,13 @@ enables online continuous physical backups of PostgreSQL clusters to object stor
1212
using the `barman-cloud` suite from the [Barman](https://docs.pgbarman.org/release/latest/)
1313
project.
1414

15+
:::important
16+
If you plan to migrate your existing CloudNativePG cluster to the new
17+
plugin-based approach using the Barman Cloud Plugin, see
18+
["Migrating from Built-in CloudNativePG Backup"](migration.md)
19+
for detailed instructions.
20+
:::
21+
1522
## Requirements
1623

1724
To use the Barman Cloud Plugin, you need:

‎web/docs/migration.md‎

Lines changed: 169 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,175 @@
22
sidebar_position: 40
33
---
44

5-
# Migrating from CloudNativePG
5+
# Migrating from Built-in CloudNativePG Backup
66

77
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
88

9-
TODO
9+
The in-tree support for Barman Cloud in CloudNativePG is **deprecated starting
10+
from version 1.26** and will be removed in a future release.
11+
12+
If you're currently relying on the built-in Barman Cloud integration, you can
13+
migrate seamlessly to the new **plugin-based architecture** using the Barman
14+
Cloud Plugin, with **no downtime**. Follow these steps:
15+
16+
- [Install the Barman Cloud Plugin](installation.md)
17+
- Create an `ObjectStore` resource by translating the contents of the
18+
`.spec.backup.barmanObjectStore` section from your existing `Cluster`
19+
definition
20+
- Modify the `Cluster` resource in a single atomic change to switch from
21+
in-tree backup to the plugin
22+
- Update any `ScheduledBackup` resources to use the plugin
23+
24+
:::tip
25+
For a working example, refer to [this commit](https://github.com/cloudnative-pg/cnpg-playground/commit/596f30e252896edf8f734991c3538df87630f6f7)
26+
from the [CloudNativePG Playground project](https://github.com/cloudnative-pg/cnpg-playground),
27+
which demonstrates a full migration.
28+
:::
29+
30+
---
31+
32+
## Step 1: Define the `ObjectStore`
33+
34+
Begin by creating an `ObjectStore` resource in the same namespace as your
35+
PostgreSQL `Cluster`.
36+
37+
There is a **direct mapping** between the `.spec.backup.barmanObjectStore`
38+
section in CloudNativePG and the `.spec.configuration` field in the
39+
`ObjectStore` CR. The conversion is mostly mechanical, with one key difference:
40+
41+
:::warning
42+
In the plugin architecture, retention policies are defined as part of the `ObjectStore`.
43+
In contrast, the in-tree implementation defined them at the `Cluster` level.
44+
:::
45+
46+
If your `Cluster` used `.spec.backup.retentionPolicy`, move that configuration
47+
to `.spec.retentionPolicy` in the `ObjectStore`.
48+
49+
---
50+
51+
### Example
52+
53+
Here’s an excerpt from a traditional in-tree CloudNativePG backup configuration
54+
taken from the CloudNativePG Playground project:
55+
56+
```yaml
57+
apiVersion: postgresql.cnpg.io/v1
58+
kind: Cluster
59+
metadata:
60+
name: pg-eu
61+
spec:
62+
# [...]
63+
backup:
64+
barmanObjectStore:
65+
destinationPath: s3://backups/
66+
endpointURL: http://minio-eu:9000
67+
s3Credentials:
68+
accessKeyId:
69+
name: minio-eu
70+
key: ACCESS_KEY_ID
71+
secretAccessKey:
72+
name: minio-eu
73+
key: ACCESS_SECRET_KEY
74+
wal:
75+
compression: gzip
76+
```
77+
78+
This configuration translates to the following `ObjectStore` resource for the
79+
plugin:
80+
81+
```yaml
82+
apiVersion: barmancloud.cnpg.io/v1
83+
kind: ObjectStore
84+
metadata:
85+
name: minio-eu
86+
spec:
87+
configuration:
88+
destinationPath: s3://backups/
89+
endpointURL: http://minio-eu:9000
90+
s3Credentials:
91+
accessKeyId:
92+
name: minio-eu
93+
key: ACCESS_KEY_ID
94+
secretAccessKey:
95+
name: minio-eu
96+
key: ACCESS_SECRET_KEY
97+
wal:
98+
compression: gzip
99+
```
100+
101+
As you can see, the contents of `barmanObjectStore` have been copied directly
102+
under the `configuration` field of the `ObjectStore` resource, using the same
103+
secret references.
104+
105+
## Step 2: Update the `Cluster`
106+
107+
Once the `ObjectStore` resource is in place, update the `Cluster` resource as
108+
follows in a single atomic change:
109+
110+
- Remove the `.spec.backup.barmanObjectStore` section
111+
- Remove `.spec.backup.retentionPolicy` if it was defined (as it is now in the
112+
`ObjectStore`)
113+
- Remove the entire `spec.backup` section if it is now empty
114+
- Add `barman-cloud.cloudnative-pg.io` to the `plugins` list, as described in
115+
[Configuring WAL archiving](usage.md#configuring-wal-archiving)
116+
117+
This will trigger a rolling update of the `Cluster`, switching continuous
118+
backup from the in-tree implementation to the plugin-based approach.
119+
120+
### Example
121+
122+
The updated `pg-eu` cluster will have this configuration instead of the
123+
previous `backup` section:
124+
125+
```yaml
126+
plugins:
127+
- name: barman-cloud.cloudnative-pg.io
128+
isWALArchiver: true
129+
parameters:
130+
barmanObjectName: minio-eu
131+
```
132+
133+
---
134+
135+
## Step 3: Update the `ScheduledBackup`
136+
137+
After switching the `Cluster` to use the plugin, update your `ScheduledBackup`
138+
resources to match.
139+
140+
Set the backup `method` to `plugin` and reference the plugin name via
141+
`pluginConfiguration`, as shown in ["Performing a base backup"](usage.md#performing-a-base-backup).
142+
143+
### Example
144+
145+
Original in-tree `ScheduledBackup`:
146+
147+
```yaml
148+
apiVersion: postgresql.cnpg.io/v1
149+
kind: ScheduledBackup
150+
metadata:
151+
name: pg-eu-backup
152+
spec:
153+
cluster:
154+
name: pg-eu
155+
schedule: '0 0 0 * * *'
156+
backupOwnerReference: self
157+
```
158+
159+
Updated version using the plugin:
160+
161+
```yaml
162+
apiVersion: postgresql.cnpg.io/v1
163+
kind: ScheduledBackup
164+
metadata:
165+
name: pg-eu-backup
166+
spec:
167+
cluster:
168+
name: pg-eu
169+
schedule: '0 0 0 * * *'
170+
backupOwnerReference: self
171+
method: plugin
172+
pluginConfiguration:
173+
name: barman-cloud.cloudnative-pg.io
174+
```
175+
176+
---

0 commit comments

Comments
 (0)