cloudnative-pg · mnencia · Dec 30, 2025 · Dec 30, 2025
@@ -0,0 +1,43 @@
+---
+sidebar_position: 80
+---
+
+# Compression
+
+<!-- SPDX-License-Identifier: CC-BY-4.0 -->
+
+By default, backups and WAL files are archived **uncompressed**. However, the
+Barman Cloud Plugin supports multiple compression algorithms via
+`barman-cloud-backup` and `barman-cloud-wal-archive`, allowing you to optimize
+for space, speed, or a balance of both.
+
+### Supported Compression Algorithms
+
+- `bzip2`
+- `gzip`
+- `lz4` (WAL only)
+- `snappy`
+- `xz` (WAL only)
+- `zstd` (WAL only)
+
+Compression settings for base backups and WAL archives are configured
+independently. For implementation details, refer to the corresponding API
+definitions:
+
+- [`DataBackupConfiguration`](https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api#DataBackupConfiguration)
+- [`WALBackupConfiguration`](https://pkg.go.dev/github.com/cloudnative-pg/barman-cloud/pkg/api#WalBackupConfiguration)
+
+:::important
+Compression impacts both performance and storage efficiency. Choose the right
+algorithm based on your recovery time objectives (RTO), storage capacity, and
+network throughput.
+:::
+
+## Compression Benchmark (on MinIO)
+
+| Compression | Backup Time (ms) | Restore Time (ms) | Uncompressed Size (MB) | Compressed Size (MB) | Ratio |
+| ----------- | ---------------- | ----------------- | ---------------------- | -------------------- | ----- |
+| None        | 10,927           | 7,553             | 395                    | 395                  | 1.0:1 |
+| bzip2       | 25,404           | 13,886            | 395                    | 67                   | 5.9:1 |
+| gzip        | 116,281          | 3,077             | 395                    | 91                   | 4.3:1 |
+| snappy      | 8,134            | 8,341             | 395                    | 166                  | 2.4:1 |
@@ -0,0 +1,177 @@
+---
+sidebar_position: 10
+---
+
+# Main Concepts
+
+<!-- SPDX-License-Identifier: CC-BY-4.0 -->
+
+:::important
+Before proceeding, make sure to review the following sections of the
+CloudNativePG documentation:
+
+- [**Backup**](https://cloudnative-pg.io/documentation/current/backup/)
+- [**WAL Archiving**](https://cloudnative-pg.io/documentation/current/wal_archiving/)
+- [**Recovery**](https://cloudnative-pg.io/documentation/current/recovery/)
+:::
+
+The **Barman Cloud Plugin** enables **hot (online) backups** of PostgreSQL
+clusters in CloudNativePG through [`barman-cloud`](https://pgbarman.org),
+supporting continuous physical backups and WAL archiving to an **object
+store**—without interrupting write operations.
+
+It also supports both **full recovery** and **Point-in-Time Recovery (PITR)**
+of a PostgreSQL cluster.
+
+## The Object Store
+
+At the core is the [`ObjectStore` custom resource (CRD)](plugin-barman-cloud.v1.md#objectstorespec),
+which acts as the interface between the PostgreSQL cluster and the target
+object storage system. It allows you to configure:
+
+- **Authentication and bucket location** via the `.spec.configuration` section
+- **WAL archiving** settings—such as compression type, parallelism, and
+  server-side encryption—under `.spec.configuration.wal`
+- **Base backup options**—with similar settings for compression, concurrency,
+  and encryption—under `.spec.configuration.data`
+- **Retention policies** to manage the life-cycle of archived WALs and backups
+  via `.spec.configuration.retentionPolicy`
+
+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).
+:::
+
+## Integration with a CloudNativePG Cluster
+
+CloudNativePG can delegate continuous backup and recovery responsibilities to
+the **Barman Cloud Plugin** by configuring the `.spec.plugins` section of a
+`Cluster` resource. This setup requires a corresponding `ObjectStore` resource
+to be defined.
+
+:::important
+While it is technically possible to reuse the same `ObjectStore` for multiple
+`Cluster` resources within the same namespace, it is strongly recommended to
+dedicate one object store per PostgreSQL cluster to ensure data isolation and
+operational clarity.
+:::
+
+The following example demonstrates how to configure a CloudNativePG cluster
+named `cluster-example` to use a previously defined `ObjectStore` (also named
+`cluster-example`) in the same namespace. Setting `isWALArchiver: true` enables
+WAL archiving through the plugin:
+
+```yaml
+apiVersion: postgresql.cnpg.io/v1
+kind: Cluster
+metadata:
+  name: cluster-example
+spec:
+  # Other cluster settings...
+  plugins:
+    - name: barman-cloud.cloudnative-pg.io
+      isWALArchiver: true
+      parameters:
+        barmanObjectName: cluster-example
+```
+
+## Backup of a Postgres Cluster
+
+Once the object store is defined and the `Cluster` is configured to use the
+Barman Cloud Plugin, **WAL archiving is activated immediately** on the
+PostgreSQL primary.
+
+Physical base backups are seamlessly managed by CloudNativePG using the
+`Backup` and `ScheduledBackup` resources, respectively for
+[on-demand](https://cloudnative-pg.io/documentation/current/backup/#on-demand-backups)
+and
+[scheduled](https://cloudnative-pg.io/documentation/current/backup/#scheduled-backups)
+backups.
+
+To use the Barman Cloud Plugin, you must set the `method` to `plugin` and
+configure the `pluginConfiguration` section as shown:
+
+```yaml
+[...]
+spec:
+  method: plugin
+  pluginConfiguration:
+    name: barman-cloud.cloudnative-pg.io
+  [...]
+```
+
+With this configuration, CloudNativePG supports:
+
+- Backups from both **primary** and **standby** instances
+- Backups from **designated primaries** in a distributed topology using
+  [replica clusters](https://cloudnative-pg.io/documentation/current/replica_cluster/)
+
+:::tip
+For details on how to back up from a standby, refer to the official documentation:
+[Backup from a standby](https://cloudnative-pg.io/documentation/current/backup/#backup-from-a-standby).
+:::
+
+:::important
+Both backup and WAL archiving operations are executed by sidecar containers
+running in the same pod as the PostgreSQL `Cluster` primary instance—except
+when backups are taken from a standby, in which case the sidecar runs alongside
+the standby pod.
+The sidecar containers use a [dedicated container image](images.md) that
+includes only the supported version of Barman Cloud.
+:::
+
+## Recovery of a Postgres Cluster
+
+In PostgreSQL, *recovery* refers to the process of starting a database instance
+from an existing backup.  The Barman Cloud Plugin integrates with CloudNativePG
+to support both **full recovery** and **Point-in-Time Recovery (PITR)** from an
+object store.
+
+Recovery in this context is *not in-place*: it bootstraps a brand-new
+PostgreSQL cluster from a backup and replays the necessary WAL files to reach
+the desired recovery target.
+
+To perform a recovery, define an *external cluster* that references the
+appropriate `ObjectStore`, and use it as the source in the `bootstrap` section
+of the target cluster:
+
+```yaml
+[...]
+spec:
+  [...]
+  bootstrap:
+    recovery:
+      source: source
+  externalClusters:
+  - name: source
+    plugin:
+      name: barman-cloud.cloudnative-pg.io
+      parameters:
+        barmanObjectName: cluster-example
+        serverName: cluster-example
+  [...]
+```
+
+The critical element here is the `externalClusters` section of the `Cluster`
+resource, where the `plugin` stanza instructs CloudNativePG to use the Barman
+Cloud Plugin to access the object store for recovery.
+
+This same mechanism can be used for a variety of scenarios enabled by the
+CloudNativePG API, including:
+
+* **Full cluster recovery** from the latest backup
+* **Point-in-Time Recovery (PITR)**
+* Bootstrapping **replica clusters** in a distributed topology
+
+:::tip
+For complete instructions and advanced use cases, refer to the official
+[Recovery documentation](https://cloudnative-pg.io/documentation/current/recovery/).
+:::
@@ -0,0 +1,37 @@
+---
+sidebar_position: 99
+---
+
+# Container Images
+
+<!-- SPDX-License-Identifier: CC-BY-4.0 -->
+
+The Barman Cloud Plugin is distributed using two container images:
+
+- One for deploying the plugin components
+- One for the sidecar that runs alongside each PostgreSQL instance in a
+  CloudNativePG `Cluster` using the plugin
+
+## Plugin Container Image
+
+The plugin image contains the logic required to operate the Barman Cloud Plugin
+within your Kubernetes environment with CloudNativePG. It is published on the
+GitHub Container Registry at `ghcr.io/cloudnative-pg/plugin-barman-cloud`.
+
+This image is built from the
+[`Dockerfile.plugin`](https://github.com/cloudnative-pg/plugin-barman-cloud/blob/main/containers/Dockerfile.plugin)
+in the plugin repository.
+
+## Sidecar Container Image
+
+The sidecar image is used within each PostgreSQL pod in the cluster. It
+includes the latest supported version of Barman Cloud and is responsible for
+performing WAL archiving and backups on behalf of CloudNativePG.
+
+It is available at `ghcr.io/cloudnative-pg/plugin-barman-cloud-sidecar` and is
+built from the
+[`Dockerfile.sidecar`](https://github.com/cloudnative-pg/plugin-barman-cloud/blob/main/containers/Dockerfile.sidecar).
+
+These sidecar images are designed to work seamlessly with the
+[`minimal` PostgreSQL container images](https://github.com/cloudnative-pg/postgres-containers?tab=readme-ov-file#minimal-images)
+maintained by the CloudNativePG Community.
@@ -0,0 +1,109 @@
+---
+sidebar_position: 20
+---
+
+# Installation
+
+:::important
+1. The plugin **must** be installed in the same namespace as the CloudNativePG
+   operator (typically `cnpg-system`).
+
+2. Keep in mind that the operator's **listening namespaces** may differ from its
+   installation namespace. Double-check this to avoid configuration issues.
+:::
+
+## Verifying the Requirements
+
+Before installing the plugin, make sure the [requirements](intro.md#requirements) are met.
+
+### CloudNativePG Version
+
+Ensure you're running a version of CloudNativePG that is compatible with the
+plugin. If installed in the default `cnpg-system` namespace, you can verify the
+version with:
+
+```sh
+kubectl get deployment -n cnpg-system cnpg-controller-manager \
+  -o jsonpath="{.spec.template.spec.containers[*].image}"
+```
+
+Example output:
+
+```output
+ghcr.io/cloudnative-pg/cloudnative-pg:1.26.0
+```
+
+The version **must be 1.26 or newer**.
+
+### cert-manager
+
+Use the [cmctl](https://cert-manager.io/docs/reference/cmctl/#installation)
+tool to confirm that `cert-manager` is installed and available:
+
+```sh
+cmctl check api
+```
+
+Example output:
+
+```output
+The cert-manager API is ready
+```
+
+Both checks are required before proceeding with the installation.
+
+## Installing the Barman Cloud Plugin
+
+import { InstallationSnippet } from '@site/src/components/Installation';
+
+Install the plugin using `kubectl` by applying the manifest for the latest
+release:
+
+<InstallationSnippet />
+
+Example output:
+
+```output
+customresourcedefinition.apiextensions.k8s.io/objectstores.barmancloud.cnpg.io created
+serviceaccount/plugin-barman-cloud created
+role.rbac.authorization.k8s.io/leader-election-role created
+clusterrole.rbac.authorization.k8s.io/metrics-auth-role created
+clusterrole.rbac.authorization.k8s.io/metrics-reader created
+clusterrole.rbac.authorization.k8s.io/objectstore-editor-role created
+clusterrole.rbac.authorization.k8s.io/objectstore-viewer-role created
+clusterrole.rbac.authorization.k8s.io/plugin-barman-cloud created
+rolebinding.rbac.authorization.k8s.io/leader-election-rolebinding created
+clusterrolebinding.rbac.authorization.k8s.io/metrics-auth-rolebinding created
+clusterrolebinding.rbac.authorization.k8s.io/plugin-barman-cloud-binding created
+secret/plugin-barman-cloud-8tfddg42gf created
+service/barman-cloud created
+deployment.apps/barman-cloud configured
+certificate.cert-manager.io/barman-cloud-client created
+certificate.cert-manager.io/barman-cloud-server created
+issuer.cert-manager.io/selfsigned-issuer created
+```
+
+Finally, check that the deployment is up and running:
+
+```sh
+kubectl rollout status deployment \
+  -n cnpg-system barman-cloud
+```
+
+Example output:
+
+```output
+deployment "barman-cloud" successfully rolled out
+```
+
+This confirms that the plugin is deployed and ready to use.
+
+## Testing the latest development snapshot
+
+You can also test the latest development snapshot of the plugin with the
+following command:
+
+```sh
+kubectl apply -f \
+  https://raw.githubusercontent.com/cloudnative-pg/plugin-barman-cloud/refs/heads/main/manifest.yaml
+```