Skip to content

Commit 1def42d

Browse files
gbartolinigbartolini
committed
docs: import content from CNPG
Re-organise the pages too. Closes #290 Signed-off-by: Gabriele Bartolini <[email protected]>
1 parent b974838 commit 1def42d

File tree

7 files changed

+222
-60
lines changed

7 files changed

+222
-60
lines changed

‎web/docs/backup.md‎

Lines changed: 165 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,165 @@
1+
---
2+
sidebar_position: 10
3+
---
4+
5+
# Backup
6+
7+
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
8+
9+
The **Barman Cloud Plugin** adds support for **hot (online) backups** of
10+
PostgreSQL clusters in CloudNativePG, enabling continuous physical backup and
11+
WAL archiving to an **object store**—without requiring downtime. It also enables
12+
**Full Recovery** and **Point-in-Time Recovery (PITR)** of a Postgres cluster.
13+
14+
Instead of relying on a traditional, centralised Barman server, the plugin
15+
orchestrates backup operations directly within the Kubernetes cluster using the
16+
following tools from the [`barman-cloud`](https://pgbarman.org) suite:
17+
18+
- `barman-cloud-wal-archive`
19+
- `barman-cloud-check-wal-archive`
20+
- `barman-cloud-backup`
21+
- `barman-cloud-backup-list`
22+
- `barman-cloud-backup-delete`
23+
24+
Base backups are stored as **tarballs**, and both base backups and WAL files
25+
can be compressed and encrypted.
26+
27+
Backups are taken from a **primary** or **designated primary** instance in a
28+
`Cluster` (see
29+
[replica clusters](https://cloudnative-pg.io/documentation/current/replica_cluster/)
30+
) or, alternatively, from a [standby instance](https://cloudnative-pg.io/documentation/current/backup/#backup-from-a-standby).
31+
32+
## Retention Policies
33+
34+
The Barman Cloud Plugin supports **automated cleanup of obsolete backups** via
35+
retention policies, configured in the `.spec.retentionPolicy` field of the
36+
`ObjectStore` resource.
37+
38+
:::note
39+
This feature uses the `barman-cloud-backup-delete` command with the
40+
`--retention-policy "RECOVERY WINDOW OF {{ value }} {{ unit }}"` syntax.
41+
:::
42+
43+
### Example: 30-Day Retention Policy
44+
45+
```yaml
46+
apiVersion: barmancloud.cnpg.io/v1
47+
kind: ObjectStore
48+
metadata:
49+
name: my-store
50+
spec:
51+
[...]
52+
retentionPolicy: "30d"
53+
````
54+
55+
:::note
56+
A **recovery window retention policy** ensures the cluster can be restored to
57+
any point in time between the calculated *Point of Recoverability* (PoR) and
58+
the latest WAL archive. The PoR is defined as `current time - recovery window`.
59+
The **first valid backup** is the most recent backup completed before the PoR.
60+
Backups older than that are marked as *obsolete* and deleted after the next
61+
backup completes.
62+
:::
63+
64+
## Compression Support
65+
66+
By default, backups and WAL files are archived **uncompressed**. However, the
67+
plugin supports several compression algorithms via `barman-cloud-backup` and
68+
`barman-cloud-wal-archive`:
69+
70+
- `bzip2`
71+
- `gzip`
72+
- `lz4`
73+
- `snappy`
74+
- `xz`
75+
- `zstd`
76+
77+
Compression settings for base backups and WALs are configured independently.
78+
Refer to:
79+
80+
- [DataBackupConfiguration](https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api#DataBackupConfiguration)
81+
- [WALBackupConfiguration](https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api#WalBackupConfiguration)
82+
83+
:::important
84+
Compression affects backup/restore speed and file size. Choose the
85+
algorithm based on your recovery objectives and storage performance.
86+
:::
87+
88+
### Compression Benchmark (on MinIO)
89+
90+
| Compression | Backup Time (ms) | Restore Time (ms) | Uncompressed Size (MB) | Compressed Size (MB) | Ratio |
91+
| ----------- | ---------------- | ----------------- | ---------------------- | -------------------- | ----- |
92+
| None | 10,927 | 7,553 | 395 | 395 | 1.0:1 |
93+
| bzip2 | 25,404 | 13,886 | 395 | 67 | 5.9:1 |
94+
| gzip | 116,281 | 3,077 | 395 | 91 | 4.3:1 |
95+
| snappy | 8,134 | 8,341 | 395 | 166 | 2.4:1 |
96+
97+
:::info
98+
For a deeper comparison, see the [Barman GitHub benchmark discussion](https://github.com/EnterpriseDB/barman/issues/344#issuecomment-992547396).
99+
:::
100+
101+
## Backup Object Tagging
102+
103+
You can tag backup artefacts (base backups, WAL files, history files) using
104+
key-value metadata through the following fields in `.spec.configuration`:
105+
106+
- `tags`: tags for base backups and WALs
107+
- `historyTags`: tags for history files
108+
109+
### Example
110+
111+
```yaml
112+
apiVersion: barmancloud.cnpg.io/v1
113+
kind: ObjectStore
114+
metadata:
115+
name: my-store
116+
spec:
117+
configuration:
118+
[...]
119+
tags:
120+
backupRetentionPolicy: "expire"
121+
historyTags:
122+
backupRetentionPolicy: "keep"
123+
[...]
124+
```
125+
126+
## Extra Options for Backup and WAL Archiving
127+
128+
Use the `additionalCommandArgs` field to pass extra arguments to:
129+
130+
- `barman-cloud-backup` (`.spec.configuration.data.additionalCommandArgs`)
131+
- `barman-cloud-wal-archive` (`.spec.configuration.wal.additionalCommandArgs`)
132+
133+
These are lists of string arguments appended to the command line. If an
134+
argument is already defined elsewhere, it will be ignored.
135+
136+
### Example: Extra Backup Options
137+
138+
```yaml
139+
kind: ObjectStore
140+
metadata:
141+
name: my-store
142+
spec:
143+
configuration:
144+
data:
145+
additionalCommandArgs:
146+
- "--min-chunk-size=5MB"
147+
- "--read-timeout=60"
148+
```
149+
150+
### Example: Extra WAL Archive Options
151+
152+
```yaml
153+
kind: ObjectStore
154+
metadata:
155+
name: my-store
156+
spec:
157+
configuration:
158+
wal:
159+
additionalCommandArgs:
160+
- "--max-concurrency=1"
161+
- "--read-timeout=60"
162+
```
163+
164+
For a full list of supported options, see the official
165+
[`barman-cloud` documentation](https://docs.pgbarman.org/release/latest/).

‎web/docs/features.md‎

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

‎web/docs/installation.md‎

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

55
# Installation

‎web/docs/intro.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
---
2+
sidebar_position: 1
3+
sidebar_label: "Introduction"
4+
---
5+
6+
# Barman Cloud Plugin
7+
8+
The **Barman Cloud Plugin** for [CloudNativePG](https://cloudnative-pg.io/)
9+
enables onlinecontinuous physical backups of PostgreSQL clusters to object storage
10+
using the `barman-cloud` suite from the [Barman](https://docs.pgbarman.org/release/latest/)
11+
project.
12+
13+
## Requirements
14+
15+
To use the Barman Cloud Plugin, you need:
16+
17+
- [CloudNativePG](https://cloudnative-pg.io) version **1.26** <!-- ADD WHEN 1.27 IS OUT "or later" -->
18+
- [cert-manager](https://cert-manager.io/) to enable TLS communication between
19+
the plugin and the operator
20+
21+
## Key Features
22+
23+
This plugin provides the following capabilities:
24+
25+
- Physical online backup of the data directory
26+
- Physical restore of the data directory
27+
- Write-Ahead Log (WAL) archiving
28+
- WAL restore
29+
- Full cluster recovery
30+
- Point-in-Time Recovery (PITR)
31+
- Seamless integration with replica clusters for bootstrap and WAL restore from archive
32+
33+
:::important
34+
The Barman Cloud Plugin is designed to **replace the in-tree object storage support**
35+
previously provided via the `.spec.backup.barmanObjectStore` section in the
36+
`Cluster` resource.
37+
Backups created using the in-tree approach are fully supported and compatible
38+
with this plugin.
39+
:::
40+
41+
## Supported Object Storage Providers
42+
43+
The plugin works with all storage backends supported by `barman-cloud`, including:
44+
45+
- **Amazon S3**
46+
- **Google Cloud Storage**
47+
- **Microsoft Azure Blob Storage**
48+
49+
In addition, the following S3-compatible and simulator solutions have been
50+
tested and verified:
51+
52+
- [MinIO](https://min.io/) – An S3-compatible storage solution
53+
- [Azurite](https://github.com/Azure/Azurite) – A simulator for Azure Blob Storage
54+
- [fake-gcs-server](https://github.com/fsouza/fake-gcs-server) – A simulator for Google Cloud Storage
55+
```

‎web/docs/prerequisites.md‎

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

‎web/docs/usage.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
---
2-
sidebar_position: 5
2+
sidebar_position: 20
33
---
44

55
# Usage

‎web/docs/welcome.md‎

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

0 commit comments

Comments
 (0)