# 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)

```yaml
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)

```yaml
# ❌ 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:

```yaml
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:

```yaml
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:

```yaml
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:

```bash
kubectl cnpg backup my-cluster --method plugin
```

## Retention Policies

The plugin supports advanced retention policies:

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

## Supported Storage Backends

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

### Ceph S3 (RGW) - Your Setup
```yaml
destinationPath: s3://postgres-backups/
endpointURL: http://rook-ceph-rgw-ceph-objectstore.rook-ceph.svc:80
```

### Azure Blob Storage
```yaml
destinationPath: https://storageaccount.blob.core.windows.net/container/
```

### Google Cloud Storage
```yaml
destinationPath: gs://bucket-name/
```

### MinIO
```yaml
destinationPath: s3://bucket-name/
endpointURL: http://minio:9000
```

## Verification

After deploying, verify the plugin is running:

```bash
# 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":

```bash
# 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

```bash
# 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

```bash
# 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**:
   ```yaml
   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](https://cloudnative-pg.io/plugin-barman-cloud/)
- [CloudNativePG Backup Guide](https://cloudnative-pg.io/documentation/1.27/backup/)
- [CNPG-I Plugin Architecture](https://cloudnative-pg.io/documentation/1.27/cnpg_i/)