Skip to content

Commit 4593290

Browse files
mnenciamnencia
authored
docs(release): documentation for release 0.8.0 (#626)
Signed-off-by: Marco Nenciarini <[email protected]>
1 parent ffb4ffb commit 4593290

18 files changed

+2552
-0
lines changed

‎web/versioned_docs/version-0.8.0/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` (WAL only)
19+
- `snappy`
20+
- `xz` (WAL only)
21+
- `zstd` (WAL only)
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/versioned_docs/version-0.8.0/concepts.md‎

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

‎web/versioned_docs/version-0.8.0/images.md‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
---
2+
sidebar_position: 99
3+
---
4+
5+
# Container Images
6+
7+
<!-- SPDX-License-Identifier: CC-BY-4.0 -->
8+
9+
The Barman Cloud Plugin is distributed using two container images:
10+
11+
- One for deploying the plugin components
12+
- One for the sidecar that runs alongside each PostgreSQL instance in a
13+
CloudNativePG `Cluster` using the plugin
14+
15+
## Plugin Container Image
16+
17+
The plugin image contains the logic required to operate the Barman Cloud Plugin
18+
within your Kubernetes environment with CloudNativePG. It is published on the
19+
GitHub Container Registry at `ghcr.io/cloudnative-pg/plugin-barman-cloud`.
20+
21+
This image is built from the
22+
[`Dockerfile.plugin`](https://github.com/cloudnative-pg/plugin-barman-cloud/blob/main/containers/Dockerfile.plugin)
23+
in the plugin repository.
24+
25+
## Sidecar Container Image
26+
27+
The sidecar image is used within each PostgreSQL pod in the cluster. It
28+
includes the latest supported version of Barman Cloud and is responsible for
29+
performing WAL archiving and backups on behalf of CloudNativePG.
30+
31+
It is available at `ghcr.io/cloudnative-pg/plugin-barman-cloud-sidecar` and is
32+
built from the
33+
[`Dockerfile.sidecar`](https://github.com/cloudnative-pg/plugin-barman-cloud/blob/main/containers/Dockerfile.sidecar).
34+
35+
These sidecar images are designed to work seamlessly with the
36+
[`minimal` PostgreSQL container images](https://github.com/cloudnative-pg/postgres-containers?tab=readme-ov-file#minimal-images)
37+
maintained by the CloudNativePG Community.

‎web/versioned_docs/version-0.8.0/installation.mdx‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
---
2+
sidebar_position: 20
3+
---
4+
5+
# Installation
6+
7+
:::important
8+
1. The plugin **must** be installed in the same namespace as the CloudNativePG
9+
operator (typically `cnpg-system`).
10+
11+
2. Keep in mind that the operator's **listening namespaces** may differ from its
12+
installation namespace. Double-check this to avoid configuration issues.
13+
:::
14+
15+
## Verifying the Requirements
16+
17+
Before installing the plugin, make sure the [requirements](intro.md#requirements) are met.
18+
19+
### CloudNativePG Version
20+
21+
Ensure you're running a version of CloudNativePG that is compatible with the
22+
plugin. If installed in the default `cnpg-system` namespace, you can verify the
23+
version with:
24+
25+
```sh
26+
kubectl get deployment -n cnpg-system cnpg-controller-manager \
27+
-o jsonpath="{.spec.template.spec.containers[*].image}"
28+
```
29+
30+
Example output:
31+
32+
```output
33+
ghcr.io/cloudnative-pg/cloudnative-pg:1.26.0
34+
```
35+
36+
The version **must be 1.26 or newer**.
37+
38+
### cert-manager
39+
40+
Use the [cmctl](https://cert-manager.io/docs/reference/cmctl/#installation)
41+
tool to confirm that `cert-manager` is installed and available:
42+
43+
```sh
44+
cmctl check api
45+
```
46+
47+
Example output:
48+
49+
```output
50+
The cert-manager API is ready
51+
```
52+
53+
Both checks are required before proceeding with the installation.
54+
55+
## Installing the Barman Cloud Plugin
56+
57+
import { InstallationSnippet } from '@site/src/components/Installation';
58+
59+
Install the plugin using `kubectl` by applying the manifest for the latest
60+
release:
61+
62+
<InstallationSnippet />
63+
64+
Example output:
65+
66+
```output
67+
customresourcedefinition.apiextensions.k8s.io/objectstores.barmancloud.cnpg.io created
68+
serviceaccount/plugin-barman-cloud created
69+
role.rbac.authorization.k8s.io/leader-election-role created
70+
clusterrole.rbac.authorization.k8s.io/metrics-auth-role created
71+
clusterrole.rbac.authorization.k8s.io/metrics-reader created
72+
clusterrole.rbac.authorization.k8s.io/objectstore-editor-role created
73+
clusterrole.rbac.authorization.k8s.io/objectstore-viewer-role created
74+
clusterrole.rbac.authorization.k8s.io/plugin-barman-cloud created
75+
rolebinding.rbac.authorization.k8s.io/leader-election-rolebinding created
76+
clusterrolebinding.rbac.authorization.k8s.io/metrics-auth-rolebinding created
77+
clusterrolebinding.rbac.authorization.k8s.io/plugin-barman-cloud-binding created
78+
secret/plugin-barman-cloud-8tfddg42gf created
79+
service/barman-cloud created
80+
deployment.apps/barman-cloud configured
81+
certificate.cert-manager.io/barman-cloud-client created
82+
certificate.cert-manager.io/barman-cloud-server created
83+
issuer.cert-manager.io/selfsigned-issuer created
84+
```
85+
86+
Finally, check that the deployment is up and running:
87+
88+
```sh
89+
kubectl rollout status deployment \
90+
-n cnpg-system barman-cloud
91+
```
92+
93+
Example output:
94+
95+
```output
96+
deployment "barman-cloud" successfully rolled out
97+
```
98+
99+
This confirms that the plugin is deployed and ready to use.
100+
101+
## Testing the latest development snapshot
102+
103+
You can also test the latest development snapshot of the plugin with the
104+
following command:
105+
106+
```sh
107+
kubectl apply -f \
108+
https://raw.githubusercontent.com/cloudnative-pg/plugin-barman-cloud/refs/heads/main/manifest.yaml
109+
```

0 commit comments

Comments
 (0)