Barman Cloud CNPG-I plugin

The Barman Cloud Plugin for CloudNativePG enables online continuous physical backups of PostgreSQL clusters to object storage. It utilizes the barman-cloud suite from the Barman project to manage data directory backups, restores, and Write-Ahead Log (WAL) archiving.

Key Capabilities

• Physical online backup and restore of the data directory.
• Write-Ahead Log (WAL) archiving and restore.
• Full cluster recovery and Point-in-Time Recovery (PITR).
• Integration with replica clusters for bootstrap and WAL restore from archive.

Migration Note

This plugin is designed to replace the in-tree object storage support (previously configured via .spec.backup.barmanObjectStore in the Cluster resource). Backups created using the in-tree approach are fully compatible with this plugin. If you are migrating an existing cluster, refer to the migration guide.

The Barman Cloud Plugin is distributed using two distinct container images that serve different roles in a CloudNativePG environment:

1. Plugin Container Image: Contains the logic required to operate the plugin within your Kubernetes environment.
2. Sidecar Container Image: Runs alongside each PostgreSQL instance in a CloudNativePG Cluster. It includes Barman Cloud and performs WAL archiving and backups.

These images are published on the GitHub Container Registry (ghcr.io).

ghcr.io/cloudnative-pg/plugin-barman-cloud
ghcr.io/cloudnative-pg/plugin-barman-cloud-sidecar

When using the plugin-barman-cloud, be aware of the following architectural limitations:

1. Sidecar resource sharing: The plugin sidecar container shares the same pod resources (CPU/Memory) as the PostgreSQL container.
2. Plugin restart behavior: If the sidecar container needs to be restarted, you must restart the entire PostgreSQL pod.

After migrating from in-tree backups to the plugin-barman-cloud plugin, the syntax for the kubectl cnpg backup command changes. The --method=barmanObjectStore flag is no longer valid and must be replaced with the plugin-based method.

New command format: Use --method=plugin and specify the plugin name --plugin-name=barman-cloud.cloudnative-pg.io.

# Old command (in-tree, no longer works after migration)
kubectl cnpg backup -n <namespace> <cluster-name> \
  --method=barmanObjectStore

# New command (plugin-based)
kubectl cnpg backup -n <namespace> <cluster-name> \
  --method=plugin --plugin-name=barman-cloud.cloudnative-pg.io

The ObjectStore custom resource (CRD) is the interface between your PostgreSQL cluster and the target object storage system. It manages how data is stored, archived, and retained.

Key configuration areas in the .spec:

• .spec.configuration: Defines authentication and bucket location.
• .spec.configuration.wal: Configures WAL archiving (compression, parallelism, encryption).
• .spec.configuration.data: Configures base backup options (compression, concurrency, encryption).
• .spec.retentionPolicy: Manages the lifecycle of archived WALs and backups.

Storage Layout:

• WAL files are stored in the wals/ directory.
• Base backups are stored as tarballs in the base/ directory, following the Barman Cloud convention.

The retentionPolicy field in the ObjectStoreSpec determines the duration for which backups and WALs are retained.

Format: XXu where XX is a positive integer and u is the unit. Supported units:

• d: days
• w: weeks
• m: months

Example values: 60d, 2w, 1m.

The serverRecoveryWindow is part of the ObjectStoreStatus and provides visibility into the data restorability of your PostgreSQL servers. It maps each server to a RecoveryWindow object.

A RecoveryWindow consists of:

• firstRecoverabilityPoint: The earliest point in time to which the database can be restored.
• lastSuccessfulBackupTime: The timestamp of the most recent successful backup.
• lastFailedBackupTime: The timestamp of the most recent failed backup.

A recovery window retention policy ensures that the cluster can be restored to any point in time within a specific window.

Key Concepts:

• Point of Recoverability (PoR): Calculated as current time - recovery window.
• Valid Backups: The system ensures the most recent backup completed before the PoR is preserved. This ensures continuous coverage from the PoR up to the latest WAL archive.
• Cleanup Logic: Backups older than the first valid backup (the one immediately preceding the PoR) are marked as obsolete. These obsolete backups are deleted once the next backup cycle completes.

The Barman Cloud Plugin enables hot (online) physical backups and continuous WAL archiving for CloudNativePG PostgreSQL clusters using barman-cloud. It stores data in an object store without interrupting write operations.

Key capabilities include:

• Continuous WAL archiving: Automatically archives WAL files to the object store.
• Physical base backups: Supports full backups and Point-in-Time Recovery (PITR).
• Sidecar execution: Backup and archiving operations are performed by sidecar containers running in the same pod as the PostgreSQL instance (primary or standby).
• Non-destructive recovery: Recovery is performed by bootstrapping a brand-new cluster from the object store rather than an in-place operation.

The Barman Cloud Plugin allows storing PostgreSQL cluster backups in various object storage services. To use object storage, you must define an ObjectStore object (API version barmancloud.cnpg.io/v1) which establishes the connection between your PostgreSQL cluster and the backend.

Supported providers include:

• Amazon S3
• Microsoft Azure Blob Storage
• Google Cloud Storage
• Any S3-compatible or Azure-compatible implementation.

Note on Authentication: The plugin passes credentials to barman-cloud, which performs the actual authentication. Users should verify their chosen method against the official Barman Cloud documentation.

apiVersion: barmancloud.cnpg.io/v1
kind: ObjectStore
metadata:
  name: my-store
spec:
  configuration:
    destinationPath: "s3://BUCKET_NAME/path"
    # ... provider specific credentials ...

When you deploy a MinIO Tenant resource, the following services are created based on the metadata.name (represented here as <tenant>):

• <tenant>-console: The management UI. Accessible on port 9090 (with autocert) or 9443 (without autocert).
• <tenant>-hl: The S3-compatible API service. Accessible on port 9000. This is the endpoint used for database backups and WAL archiving.

If requestAutoCert is enabled in the Tenant, communication with these services should occur over HTTPS.