veda/apps/cloudnative-pg-plugin

CloudNativePG Barman-Cloud Plugin

Overview

The Barman Cloud Plugin provides object storage backup capabilities for CloudNativePG using the Barman toolset.

Important: As of CloudNativePG v1.26+, the native barmanObjectStore backup method is deprecated. You should use this plugin instead.

Why This Plugin is Required

From the CloudNativePG 1.27 documentation:

Starting with version 1.26, native backup and recovery capabilities are being progressively phased out of the core operator and moved to official CNPG-I plugins.

The built-in barman integration (method: barmanObjectStore) is deprecated and will be removed in future versions. This plugin provides the official replacement.

What This Plugin Provides

• ✅ WAL archiving to S3-compatible object stores
• ✅ Base backups with compression and encryption
• ✅ Point-in-time recovery (PITR)
• ✅ Retention policies for automated cleanup
• ✅ Backup from standby servers
• ✅ Support for multiple storage backends: S3, Azure Blob, GCS, MinIO, Ceph S3 (RGW)

Installation

This application deploys the plugin to the cnpg-system namespace where the CloudNativePG operator runs.

The plugin will be available for all PostgreSQL clusters managed by CloudNativePG.

Configuration in PostgreSQL Clusters

Using the Plugin (New Method)

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: my-cluster
spec:
  backup:
    target: prefer-standby
    
    # Use the plugin method (required for v1.26+)
    method: plugin
    
    # Plugin configuration
    pluginConfiguration:
      name: barman-cloud.cloudnative-pg.io
      
      # S3 configuration
      barmanObjectStore:
        destinationPath: s3://postgres-backups/
        endpointURL: http://rook-ceph-rgw-ceph-objectstore.rook-ceph.svc:80
        
        # Credentials
        s3Credentials:
          accessKeyId:
            name: backup-credentials
            key: ACCESS_KEY_ID
          secretAccessKey:
            name: backup-credentials
            key: ACCESS_SECRET_KEY
        
        # Compression and parallelism
        data:
          compression: bzip2
          jobs: 2
          immediateCheckpoint: true
        
        wal:
          compression: bzip2
          maxParallel: 2
        
        # Retention policy
        retentionPolicy: "30d"
        
        # Tags for organization
        tags:
          environment: "production"
          cluster: "my-cluster"

Old Method (Deprecated)

# ❌ DON'T USE - This is deprecated
spec:
  backup:
    method: barmanObjectStore  # Deprecated!
    barmanObjectStore:
      # ... config

WAL Archiving

The plugin also handles WAL archiving. Configure it at the cluster level:

apiVersion: postgresql.cnpg.io/v1
kind: Cluster
metadata:
  name: my-cluster
spec:
  backup:
    # Backup configuration (as above)
    ...
    
  # WAL archiving uses the same plugin configuration
  # Automatically enabled when backup is configured

Scheduled Backups

Create scheduled backups using the plugin:

apiVersion: postgresql.cnpg.io/v1
kind: ScheduledBackup
metadata:
  name: daily-backup
spec:
  schedule: "0 0 2 * * *"  # 2 AM daily
  backupOwnerReference: self
  cluster:
    name: my-cluster
  
  # Use plugin method
  method: plugin
  
  # Plugin configuration (or inherits from cluster)
  pluginConfiguration:
    name: barman-cloud.cloudnative-pg.io

On-Demand Backups

Trigger manual backups:

apiVersion: postgresql.cnpg.io/v1
kind: Backup
metadata:
  name: manual-backup
spec:
  cluster:
    name: my-cluster
  
  method: plugin
  
  pluginConfiguration:
    name: barman-cloud.cloudnative-pg.io

Or use kubectl:

kubectl cnpg backup my-cluster --method plugin

Retention Policies

The plugin supports advanced retention policies:

pluginConfiguration:
  barmanObjectStore:
    retentionPolicy: "30d"  # Keep backups for 30 days
    # or
    # retentionPolicy: "7 days"
    # retentionPolicy: "4 weeks"
    # retentionPolicy: "3 months"

Supported Storage Backends

AWS S3

destinationPath: s3://bucket-name/
# endpointURL not needed for AWS S3

Ceph S3 (RGW) - Your Setup

destinationPath: s3://postgres-backups/
endpointURL: http://rook-ceph-rgw-ceph-objectstore.rook-ceph.svc:80

Azure Blob Storage

destinationPath: https://storageaccount.blob.core.windows.net/container/

Google Cloud Storage

destinationPath: gs://bucket-name/

MinIO

destinationPath: s3://bucket-name/
endpointURL: http://minio:9000

Verification

After deploying, verify the plugin is running:

# Check plugin deployment
kubectl get deployment -n cnpg-system | grep plugin

# Check plugin pods
kubectl get pods -n cnpg-system -l app=barman-cloud-plugin

# Verify plugin is registered
kubectl get configmap -n cnpg-system cnpg-plugin-registry -o yaml

Troubleshooting

Plugin Not Found

If you see errors like "plugin not found":

# Check if plugin is deployed
kubectl get pods -n cnpg-system -l app=barman-cloud-plugin

# Check operator logs
kubectl logs -n cnpg-system -l app.kubernetes.io/name=cloudnative-pg

Backup Failures

# Check backup status
kubectl get backup -n <namespace>

# Check backup logs
kubectl describe backup <backup-name> -n <namespace>

# Check PostgreSQL pod logs
kubectl logs -n <namespace> <postgres-pod> | grep -i backup

WAL Archiving Issues

# Check WAL archive status
kubectl exec -it -n <namespace> <postgres-pod> -- \
  psql -c "SELECT * FROM pg_stat_archiver;"

# Check plugin logs
kubectl logs -n cnpg-system -l app=barman-cloud-plugin

Migration from Built-in to Plugin

If you're migrating from the deprecated barmanObjectStore method:

1. Deploy this plugin application
2. Update your Cluster resource:

   spec:
     backup:
       method: plugin  # Change from barmanObjectStore
       pluginConfiguration:
         name: barman-cloud.cloudnative-pg.io
         barmanObjectStore:
           # Keep same configuration
   

3. Existing backups remain accessible - the plugin can read backups created by the built-in method

Best Practices

1. ✅ Always use the plugin for CloudNativePG v1.26+
2. ✅ Configure retention policies to manage storage costs
3. ✅ Enable backup from standby to reduce primary load
4. ✅ Use compression (bzip2) to reduce storage usage
5. ✅ Set up scheduled backups for automated protection
6. ✅ Test recovery procedures regularly
7. ✅ Monitor backup status with Prometheus metrics
8. ✅ Tag backups for easy identification and filtering

Next Steps

1. Deploy this application: git add . && git commit && git push
2. Wait for ArgoCD to sync
3. Update your PostgreSQL Cluster to use method: plugin
4. Create an S3 bucket for backups (ObjectBucketClaim)
5. Configure backup credentials
6. Test with an on-demand backup

Additional Resources

• Barman Cloud Plugin Documentation
• CloudNativePG Backup Guide
• CNPG-I Plugin Architecture