commit 4db9f14285f950c928536a68435614a445801156 Author: deimo72 Date: Sat Sep 5 21:15:47 2026 -0400 feat: CloudNativePG backup strategy manifests and documentation diff --git a/README.md b/README.md new file mode 100644 index 0000000..d10a1e0 --- /dev/null +++ b/README.md @@ -0,0 +1,143 @@ +# CNPG-Backup + +Estrategia de backup y recuperación para clusters PostgreSQL usando [CloudNativePG](https://cloudnative-pg.io/) en Kubernetes. + +## Visión general + +Este repositorio contiene los manifiestos necesarios para configurar una estrategia de backup continua y Point-In-Time Recovery (PITR) para clusters PostgreSQL gestionados por CloudNativePG, utilizando object storage (S3 compatible) como destino de los backups y WAL archives. + +## Arquitectura + +``` +┌─────────────────────────────────────────────────────┐ +│ Kubernetes Cluster │ +│ │ +│ ┌─────────────┐ ┌──────────────────────────────┐ │ +│ │ Cluster │ │ ObjectStore (S3/MinIO) │ │ +│ │ PostgreSQL │───│ ┌────────────────────────┐ │ │ +│ │ │ │ │ base backups (full) │ │ │ +│ │ Primary │ │ │ WAL archives (stream) │ │ │ +│ │ Standby │ │ └────────────────────────┘ │ │ +│ └──────┬──────┘ └──────────────────────────────┘ │ +│ │ WAL archiving (barman-cloud plugin) │ +│ │ Scheduled backups (base + WAL) │ +└─────────┴─────────────────────────────────────────────┘ +``` + +## Componentes + +### 1. ObjectStore + +Define el bucket de object storage donde se almacenarán los backups y los WAL archives. Soporta S3, Azure Blob Storage, GCS y cualquier servicio S3-compatible (MinIO, etc.). + +**Requisitos:** +- Un bucket existente en el proveedor de object storage +- Credenciales de acceso (Access Key + Secret Key) con permisos de lectura/escritura +- El cluster de Kubernetes debe tener acceso de red al endpoint del object store + +### 2. Cluster PostgreSQL + +El cluster debe configurarse para usar el plugin `barman-cloud` como archiver de WAL y para ejecutar backups al object store configurado. + +### 3. ScheduledBackup + +Programa backups automáticos (base completos) según una expresión cron. Se recomienda: +- Backups base: diario (medianoche) +- WAL archiving: continuo (cada cambio se archiva) + +### 4. Backup on-demand + +Permite disparar backups manuales cuando sea necesario mediante el recurso `Backup`. + +## Estrategia de Retención + +| Tipo | Retención | Descripción | +|------|-----------|-------------| +| Base backups | 7 días | Backups completos diarios | +| WAL archives | 14 días | Archivos de transacciones para PITR | +| Recuperación | Hasta 14 días atrás | Point-in-Time Recovery | + +La retención se gestiona a través de la configuración de Barman Cloud en el recurso `ObjectStore`. + +## Recuperación (PITR) + +Para restaurar el cluster a un momento específico: + +```bash +# Listar backups disponibles +kubectl get backup -o wide + +# Restaurar a un timestamp específico +kubectl cnpg restore --backup= --restore-to= +``` + +O mediante el recurso `Cluster` con `bootstrap.recovery`: + +```yaml +apiVersion: postgresql.cnpg.io/v1 +kind: Cluster +metadata: + name: pg-restored +spec: + bootstrap: + recovery: + backup: + name: + recoveryTarget: + targetImmediate: true + # o targetTimeStamp: "2024-01-15T10:30:00Z" +``` + +## Pre-requisitos + +1. CloudNativePG instalado en el cluster +2. Plugin Barman Cloud instalado: + ```bash + kubectl apply -f https://github.com/cloudnative-pg/cnpg-i/releases/download/v0.5.0/manifest.yaml + ``` +3. Acceso al object store desde el cluster +4. Bucket configurado y credenciales disponibles + +## Estructura de Archivos + +``` +CNPG-Backup/ +├── README.md # Este archivo +├── manifests/ +│ ├── 00-secret.yaml # Credenciales del object store +│ ├── 01-objectstore.yaml # Configuración del bucket +│ ├── 02-cluster.yaml # Cluster PostgreSQL con backup habilitado +│ ├── 03-scheduledbackup.yaml # Backups programados +│ └── 04-backup-ondemand.yaml # Backup manual (opcional) +└── docs/ + └── recovery-procedure.md # Procedimiento de recuperación +``` + +## Configuración + +Edita los archivos en `manifests/` para adaptarlos a tu entorno: + +- **`00-secret.yaml`**: Reemplazar `ACCESS_KEY_ID` y `ACCESS_SECRET_KEY` +- **`01-objectstore.yaml`**: Configurar endpoint, bucket name y región +- **`02-cluster.yaml`**: Ajustar tamaño de storage, versión de PostgreSQL, etc. + +## Monitoreo + +Los backups pueden ser monitoreados mediante: + +```bash +# Ver estado de un backup +kubectl describe backup + +# Listar todos los backups +kubectl get backups -o wide + +# Ver logs del operador +kubectl logs -l app=cloudnative-pg -n cnpg-system +``` + +## Referencias + +- [Documentación oficial CloudNativePG - Backup](https://cloudnative-pg.io/docs/current/backup/) +- [Barman Cloud Plugin](https://cloudnative-pg.io/plugin-barman-cloud/) +- [CloudNativePG - WAL Archiving](https://cloudnative-pg.io/docs/current/wal_archiving/) \ No newline at end of file diff --git a/manifests/00-secret.yaml b/manifests/00-secret.yaml new file mode 100644 index 0000000..7741bca --- /dev/null +++ b/manifests/00-secret.yaml @@ -0,0 +1,11 @@ +--- +apiVersion: v1 +kind: Secret +metadata: + name: object-store-creds + labels: + app: cloudnative-pg +type: Opaque +stringData: + accessKeyId: "ACCESS_KEY_ID" + accessSecretKey: "ACCESS_SECRET_KEY" \ No newline at end of file diff --git a/manifests/01-objectstore.yaml b/manifests/01-objectstore.yaml new file mode 100644 index 0000000..c4200d1 --- /dev/null +++ b/manifests/01-objectstore.yaml @@ -0,0 +1,25 @@ +--- +apiVersion: barmancloud.cnpg.io/v1 +kind: ObjectStore +metadata: + name: pg-backup-store +spec: + configuration: + s3: + bucket: "cnpg-backups" + endpoint: "https://s3.mitac.duckdns.org" + region: "us-east-1" + accessKeyId: + name: object-store-creds + key: accessKeyId + secretAccessKey: + name: object-store-creds + key: accessSecretKey + wal: + compression: gzip + maxParallel: 8 + retentionPolicy: "14 days" + data: + compression: gzip + retentionPolicy: "7 days" + maxParallel: 8 \ No newline at end of file diff --git a/manifests/02-cluster.yaml b/manifests/02-cluster.yaml new file mode 100644 index 0000000..68b04e2 --- /dev/null +++ b/manifests/02-cluster.yaml @@ -0,0 +1,41 @@ +--- +apiVersion: postgresql.cnpg.io/v1 +kind: Cluster +metadata: + name: pg-backup + labels: + app: postgresql +spec: + instances: 3 + description: "PostgreSQL cluster with continuous backup to object store" + postgresql: + parameters: + wal_level: replica + max_wal_senders: 10 + max_replication_slots: 10 + archive_mode: on + archive_command: "barman-cloud-archive '%p'" + archive_timeout: 60000 + storage: + size: 50Gi + storageClass: "standard" + resources: + requests: + cpu: "500m" + memory: "256Mi" + limits: + cpu: "2" + memory: "1Gi" + monitoring: + enabled: true + backup: + target: "prefer-standby" + barmanObjectStore: + objectStore: + name: pg-backup-store + plugins: + - name: barman-cloud.cloudnative-pg.io + isWALArchiver: true + parameters: + barmanObjectName: pg-backup-store + serverName: pg-backup \ No newline at end of file diff --git a/manifests/03-scheduledbackup.yaml b/manifests/03-scheduledbackup.yaml new file mode 100644 index 0000000..613a97d --- /dev/null +++ b/manifests/03-scheduledbackup.yaml @@ -0,0 +1,14 @@ +--- +apiVersion: postgresql.cnpg.io/v1 +kind: ScheduledBackup +metadata: + name: daily-backup +spec: + schedule: "0 0 0 * * *" + immediate: true + backupOwnerReference: self + cluster: + name: pg-backup + method: plugin + pluginConfiguration: + name: barman-cloud.cloudnative-pg.io \ No newline at end of file diff --git a/manifests/04-backup-ondemand.yaml b/manifests/04-backup-ondemand.yaml new file mode 100644 index 0000000..71b1c94 --- /dev/null +++ b/manifests/04-backup-ondemand.yaml @@ -0,0 +1,11 @@ +--- +apiVersion: postgresql.cnpg.io/v1 +kind: Backup +metadata: + name: backup-ondemand +spec: + cluster: + name: pg-backup + method: plugin + pluginConfiguration: + name: barman-cloud.cloudnative-pg.io \ No newline at end of file