Skip to content

Commit 04234a9

Browse files
gbartolinigbartolini
committed
docs: add backup, WAL archive and recovery information
Re-organised the content, with a different structure, added license information and instructions for spellchecking. Closes #290 Signed-off-by: Gabriele Bartolini <gabriele.bartolini@enterprisedb.com>
1 parent 28bc705 commit 04234a9

File tree

13 files changed

+422
-62
lines changed

13 files changed

+422
-62
lines changed

‎.wordlist.txt‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,8 @@ BarmanObjectStore
44
BarmanObjectStoreConfiguration
55
BarmanObjectStores
66
CloudNativePG
7+
CRD
8+
DataBackupConfiguration
79
DigitalOcean
810
Docusaurus
911
EKS
@@ -24,16 +26,23 @@ ObjectStore
2426
ObjectStoreSpec
2527
ObjectStoreStatus
2628
PITR
29+
PoR
30+
Postgres
31+
PostgreSQL
2732
README
2833
RecoveryWindow
2934
RetentionPolicy
35+
RPO
36+
RTO
3037
SAS
3138
SFO
3239
SPDX
3340
ServerRecoveryWindow
41+
SPDX
3442
TLS
3543
TODO
3644
Uncomment
45+
WALBackupConfiguration
3746
WAL
3847
WALs
3948
api
@@ -46,6 +55,7 @@ backend
4655
backends
4756
barmanObjectName
4857
barmancloud
58+
bzip
4959
cd
5060
cloudnative
5161
clusterrole
@@ -63,6 +73,7 @@ env
6373
externalClusters
6474
gcs
6575
gf
76+
gzip
6677
github
6778
hostpath
6879
http
@@ -89,6 +100,7 @@ rc
89100
recoverability
90101
repos
91102
retentionCheckInterval
103+
retentionPolicy
92104
rolebinding
93105
sc
94106
secretKeyRef

‎web/README.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,13 @@
33
This website is built using [Docusaurus](https://docusaurus.io/), a modern
44
static website generator.
55

6+
### Requirements
7+
8+
- Docker
9+
- [Yarn](https://yarnpkg.com/)
10+
- [Dagger](https://dagger.io/)
11+
- [Task](https://taskfile.dev/)
12+
613
### Installation
714

815
```shell
@@ -35,6 +42,14 @@ $ yarn serve
3542

3643
By default, this will load your site at http://localhost:3000/.
3744

45+
### Spellchecking
46+
47+
From the top directory:
48+
49+
```shell
50+
task spellcheck
51+
```
52+
3853
### Versioning
3954

4055
Docusaurus allows versioning of the documentation to maintain separate sets of

‎web/docs/compression.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
---
2+
sidebar_position: 80
3+
---
4+
5+
# Compression
6+
7+
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
8+
9+
By default, backups and WAL files are archived **uncompressed**. However, the
10+
Barman Cloud Plugin supports multiple compression algorithms via
11+
`barman-cloud-backup` and `barman-cloud-wal-archive`, allowing you to optimize
12+
for space, speed, or a balance of both.
13+
14+
### Supported Compression Algorithms
15+
16+
- `bzip2`
17+
- `gzip`
18+
- `lz4`
19+
- `snappy`
20+
- `xz`
21+
- `zstd`
22+
23+
Compression settings for base backups and WAL archives are configured
24+
independently. For implementation details, refer to the corresponding API
25+
definitions:
26+
27+
- [`DataBackupConfiguration`](https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api#DataBackupConfiguration)
28+
- [`WALBackupConfiguration`](https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api#WalBackupConfiguration)
29+
30+
:::important
31+
Compression impacts both performance and storage efficiency. Choose the right
32+
algorithm based on your recovery time objectives (RTO), storage capacity, and
33+
network throughput.
34+
:::
35+
36+
## Compression Benchmark (on MinIO)
37+
38+
| Compression | Backup Time (ms) | Restore Time (ms) | Uncompressed Size (MB) | Compressed Size (MB) | Ratio |
39+
| ----------- | ---------------- | ----------------- | ---------------------- | -------------------- | ----- |
40+
| None | 10,927 | 7,553 | 395 | 395 | 1.0:1 |
41+
| bzip2 | 25,404 | 13,886 | 395 | 67 | 5.9:1 |
42+
| gzip | 116,281 | 3,077 | 395 | 91 | 4.3:1 |
43+
| snappy | 8,134 | 8,341 | 395 | 166 | 2.4:1 |

‎web/docs/concepts.md‎

Lines changed: 170 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,170 @@
1+
---
2+
sidebar_position: 10
3+
---
4+
5+
# Main Concepts
6+
7+
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
8+
9+
:::important
10+
Before proceeding, make sure to review the following sections of the
11+
CloudNativePG documentation:
12+
13+
- [**Backup**](https://cloudnative-pg.io/documentation/current/backup/)
14+
- [**WAL Archiving**](https://cloudnative-pg.io/documentation/current/wal_archiving/)
15+
- [**Recovery**](https://cloudnative-pg.io/documentation/current/recovery/)
16+
:::
17+
18+
The **Barman Cloud Plugin** enables **hot (online) backups** of PostgreSQL
19+
clusters in CloudNativePG through [`barman-cloud`](https://pgbarman.org),
20+
supporting continuous physical backups and WAL archiving to an **object
21+
store**—without interrupting write operations.
22+
23+
It also supports both **full recovery** and **Point-in-Time Recovery (PITR)**
24+
of a PostgreSQL cluster.
25+
26+
The plugin integrates seamlessly with CloudNativePG and its `Backup` and
27+
`ScheduledBackup` resources, supporting backups from both primary and
28+
[standby instances](https://cloudnative-pg.io/documentation/current/backup/#backup-from-a-standby)
29+
—including designated primaries in a distributed topology with
30+
[replica clusters](https://cloudnative-pg.io/documentation/current/replica_cluster/).
31+
32+
## The Object Store
33+
34+
At the core is the [`ObjectStore` custom resource (CRD)](plugin-barman-cloud.v1.md#objectstorespec),
35+
which acts as the interface between the PostgreSQL cluster and the target
36+
object storage system. It allows you to configure:
37+
38+
- **Authentication and bucket location** via the `.spec.configuration` section
39+
- **WAL archiving** settings—such as compression type, parallelism, and
40+
server-side encryption—under `.spec.configuration.wal`
41+
- **Base backup options**—with similar settings for compression, concurrency,
42+
and encryption—under `.spec.configuration.data`
43+
- **Retention policies** to manage the life-cycle of archived WALs and backups
44+
via `.spec.configuration.retentionPolicy`
45+
46+
WAL files are archived in the `wals` directory, while base backups are stored
47+
as **tarballs** in the `base` directory, following the
48+
[Barman Cloud convention](https://docs.pgbarman.org/cloud/latest/usage/#object-store-layout).
49+
50+
:::tip
51+
For details, refer to the
52+
[API reference for the `ObjectStore` resource](plugin-barman-cloud.v1.md#objectstorespec).
53+
:::
54+
55+
## Integration with a CloudNativePG Cluster
56+
57+
CloudNativePG can delegate continuous backup and recovery responsibilities to
58+
the **Barman Cloud Plugin** by configuring the `.spec.plugins` section of a
59+
`Cluster` resource. This setup requires a corresponding `ObjectStore` resource
60+
to be defined.
61+
62+
:::important
63+
While it is technically possible to reuse the same `ObjectStore` for multiple
64+
`Cluster` resources within the same namespace, it is strongly recommended to
65+
dedicate one object store per PostgreSQL cluster to ensure data isolation and
66+
operational clarity.
67+
:::
68+
69+
The following example demonstrates how to configure a CloudNativePG cluster
70+
named `cluster-example` to use a previously defined `ObjectStore` (also named
71+
`cluster-example`) in the same namespace. Setting `isWALArchiver: true` enables
72+
WAL archiving through the plugin:
73+
74+
```yaml
75+
apiVersion: postgresql.cnpg.io/v1
76+
kind: Cluster
77+
metadata:
78+
name: cluster-example
79+
spec:
80+
# Other cluster settings...
81+
plugins:
82+
- name: barman-cloud.cloudnative-pg.io
83+
isWALArchiver: true
84+
parameters:
85+
barmanObjectName: cluster-example
86+
```
87+
88+
## Backup of a Postgres Cluster
89+
90+
Once the object store is defined and the `Cluster` is configured to use the
91+
Barman Cloud Plugin, **WAL archiving is activated immediately** on the
92+
PostgreSQL primary.
93+
94+
Physical base backups are seamlessly managed by CloudNativePG using the
95+
`Backup` and `ScheduledBackup` resources, respectively for
96+
[on-demand](https://cloudnative-pg.io/documentation/current/backup/#on-demand-backups)
97+
and
98+
[scheduled](https://cloudnative-pg.io/documentation/current/backup/#scheduled-backups)
99+
backups.
100+
101+
To use the Barman Cloud Plugin, you must set the `method` to `plugin` and
102+
configure the `pluginConfiguration` section as shown:
103+
104+
```yaml
105+
[...]
106+
spec:
107+
method: plugin
108+
pluginConfiguration:
109+
name: barman-cloud.cloudnative-pg.io
110+
[...]
111+
```
112+
113+
With this configuration, CloudNativePG supports:
114+
115+
- Backups from both **primary** and **standby** instances
116+
- Backups from **designated primaries** in a distributed topology using
117+
[replica clusters](https://cloudnative-pg.io/documentation/current/replica_cluster/)
118+
119+
:::tip
120+
For details on how to back up from a standby, refer to the official documentation:
121+
[Backup from a standby](https://cloudnative-pg.io/documentation/current/backup/#backup-from-a-standby).
122+
:::
123+
124+
## Recovery of a Postgres Cluster
125+
126+
In PostgreSQL, *recovery* refers to the process of starting a database instance
127+
from an existing backup. The Barman Cloud Plugin integrates with CloudNativePG
128+
to support both **full recovery** and **Point-in-Time Recovery (PITR)** from an
129+
object store.
130+
131+
Recovery in this context is *not in-place*: it bootstraps a brand-new
132+
PostgreSQL cluster from a backup and replays the necessary WAL files to reach
133+
the desired recovery target.
134+
135+
To perform a recovery, define an *external cluster* that references the
136+
appropriate `ObjectStore`, and use it as the source in the `bootstrap` section
137+
of the target cluster:
138+
139+
```yaml
140+
[...]
141+
spec:
142+
[...]
143+
bootstrap:
144+
recovery:
145+
source: source
146+
externalClusters:
147+
- name: source
148+
plugin:
149+
name: barman-cloud.cloudnative-pg.io
150+
parameters:
151+
barmanObjectName: cluster-example
152+
serverName: cluster-example
153+
[...]
154+
```
155+
156+
The critical element here is the `externalClusters` section of the `Cluster`
157+
resource, where the `plugin` stanza instructs CloudNativePG to use the Barman
158+
Cloud Plugin to access the object store for recovery.
159+
160+
This same mechanism can be used for a variety of scenarios enabled by the
161+
CloudNativePG API, including:
162+
163+
* **Full cluster recovery** from the latest backup
164+
* **Point-in-Time Recovery (PITR)**
165+
* Bootstrapping **replica clusters** in a distributed topology
166+
167+
:::tip
168+
For complete instructions and advanced use cases, refer to the official
169+
[Recovery documentation](https://cloudnative-pg.io/documentation/current/recovery/).
170+
:::

‎web/docs/features.md‎

Lines changed: 0 additions & 35 deletions
This file was deleted.

‎web/docs/installation.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,11 @@
11
---
2-
sidebar_position: 4
2+
sidebar_position: 30
33
---
44

55
# Installation
66

7+
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
8+
79
**IMPORTANT NOTES:**
810

911
1. The plugin **must** be installed in the same namespace where the operator is

0 commit comments

Comments
 (0)