302 lines
7.2 KiB
Markdown
302 lines
7.2 KiB
Markdown
# 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/)
|
|
|