feat: CloudNativePG backup strategy manifests and documentation

2026-09-05 21:15:47 -04:00 · 2026-09-05 21:15:47 -04:00 · 4db9f14285
commit 4db9f14285
6 changed files with 245 additions and 0 deletions
--- a/README.md
+++ 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 <cluster-name> --backup=<backup-id> --restore-to=<timestamp>
+```
+
+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: <backup-id>
+      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 <backup-name>
+
+# 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/)
--- a/manifests/00-secret.yaml
+++ 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"
--- a/manifests/01-objectstore.yaml
+++ 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
--- a/manifests/02-cluster.yaml
+++ 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
--- a/manifests/03-scheduledbackup.yaml
+++ 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
--- a/manifests/04-backup-ondemand.yaml
+++ 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