Backup y restauración del estado del cluster

Backup del cluster no es lo mismo que backup de tus datos. Son dos universos. Esta guía trata solo del primero.

Qué es el estado del cluster

HeroCtl mantiene un catálogo de lo que existe: jobs declarados, secretos almacenados, reglas de ACL, historial reciente de métricas, ingress configurado, nodos conocidos. Todo eso es el estado del plano de control.

Si pierdes ese estado, el cluster olvida lo que debía correr. Los contenedores pueden seguir de pie, pero nadie sabe ya gestionarlos. Es el tipo de situación que termina en rebuild manual.

Backup de ese estado es barato. No hacerlo es caro.

Lo que NO entra en el snapshot: los datos que viven dentro de tus contenedores. Base Postgres, volúmenes, uploads de usuario. Esos necesitan backup propio (pg_dump, snapshots del storage, etc).

Snapshot manual

El comando es una línea:

heroctl snapshot save /tmp/snap-2026-04-26.tar.gz

La salida:

snapshot saved: 4.2 MB
included: 47 jobs, 23 secrets, 12 acl rules, 4 nodes
duration: 1.3s

Por dentro el archivo es un tarball comprimido con:

• Definiciones de jobs
• Secretos (cifrados)
• Políticas de ACL y tokens
• Configuración de ingress
• Lista de nodos conocidos
• Historial de métricas de los últimos 7 días

No incluye logs antiguos ni imágenes de contenedor.

Restauración

Restaurar es más delicado. El cluster necesita estar parado:

# Para o cluster em todos os nós
sudo systemctl stop heroctl-server

# Em UM nó, restaura o snapshot
heroctl snapshot restore /backups/snap-2026-04-26.tar.gz

# Sobe o nó restaurado
sudo systemctl start heroctl-server

# Os demais nós sincronizam automaticamente ao subir
sudo systemctl start heroctl-server  # nos outros

Atención: la restauración sobreescribe el estado actual. Si el snapshot es de ayer, pierdes todo lo que sucedió desde entonces. Haz un snapshot del estado actual antes, aunque esté roto — puede salvar evidencias.

Backup automático (Plan Business)

Los snapshots manuales funcionan. Los snapshots programados funcionan más.

Configuración:

# /etc/heroctl/server.yaml
backup:
  enabled: true
  schedule: "0 3 * * *"        # 3h da manhã, todo dia
  retention_days: 30
  storage:
    type: s3
    bucket: heroctl-backups
    region: us-east-2
    prefix: cluster-prod/
    access_key_id: AKIA...
    secret_access_key: <em segredo>

El schedule es cron-like. Ejemplos:

Storage compatible

Cualquier storage S3-compatible sirve:

• AWS S3
• Cloudflare R2
• Backblaze B2
• Wasabi
• MinIO (self-hosted)

La elección es tuya. R2 y B2 son generalmente los más baratos para retención larga.

Retención

retention_days: 30

Snapshots más antiguos que 30 días se borran automáticamente. Puedes usar valores diferentes:

• 7 — equipos pequeños, solo operacional
• 30 — estándar recomendado
• 90 — auditoría, ambientes regulados
• 365 — compliance fuerte

Cada snapshot pesa entre 2 MB y algunas decenas de MB. Incluso 365 copias ocupan poco.

Encryption

Todo snapshot se cifra en reposo con AES-256. La clave queda configurada en el servidor:

backup:
  encryption_key_file: /etc/heroctl/backup.key

Genera la clave una vez:

openssl rand -base64 32 > /etc/heroctl/backup.key
chmod 600 /etc/heroctl/backup.key

Atención: sin esa clave el snapshot se vuelve basura. Guarda una copia fuera del cluster. En cofre de contraseñas. En papel en un sobre. Donde tenga sentido — pero guárdala.

Disaster recovery

Tres escenarios, tres respuestas.

Escenario 1: cluster perdió coordinación

Más nodos cayeron de los que sobraron. El cluster se traba en modo solo-lectura.

Solución normal: traer los nodos caídos de vuelta. Re-sincronizan y todo vuelve.

Solución de emergencia (último recurso): bootstrap forzado a partir del snapshot más reciente.

# Em um nó saudável
heroctl snapshot restore /backups/snap-mais-recente.tar.gz --force-bootstrap

Pierdes cambios hechos después del último snapshot.

Escenario 2: storage del cluster corrupto

Disco murió. Datacenter incendiado. Operador borró /var/lib/heroctl.

Mismo procedimiento:

1. Provisiona nodos nuevos.
2. Instala HeroCtl.
3. heroctl snapshot restore en uno de ellos.
4. Haz que los demás entren como pares.

Si tenías snapshot off-site, recuperas en minutos. Si no, recuperas en días (rehaciendo todo desde cero).

Escenario 3: datos de las aplicaciones se perdieron

El snapshot del cluster no te ayuda aquí. Necesitas:

• pg_dump programado para Postgres
• Snapshot del volumen para storage de archivos
• Replicación para Redis (si es persistente)

Cada workload es responsable de su propio backup de datos. HeroCtl orquesta; no sustituye tu estrategia de backup de aplicación.

Pruebas de restauración

Backup que nadie probó no es backup. Es archivo.

HeroCtl Business programa pruebas automáticas:

backup:
  test_restore:
    enabled: true
    schedule: "0 4 1 * *"     # dia 1 de cada mês, 4h
    target: staging-cluster

Mensualmente el cluster de staging tira su estado, restaura el último snapshot de producción y corre un conjunto de verificaciones:

• ¿Volvieron todos los jobs?
• ¿Los secretos descifran correctamente?
• ¿La ACL es consistente?

Si algo falla, alerta en el canal configurado.

Buenas prácticas

La regla 3-2-1 del backup tradicional vale aquí también:

• 3 copias del snapshot
• 2 medios diferentes (disco local + nube)
• 1 off-site (proveedor diferente del cluster)

Aplicado:

• Copia 1: generada en el nodo coordinador.
• Copia 2: replicada a un bucket S3 en la misma región.
• Copia 3: replicada a un bucket en otra región u otro proveedor.

Cuando el datacenter entero caiga, es la copia 3 la que te salva.

Resumen

Próximos pasos:

• Métricas y alertas — sabe cuándo el backup falló.
• ACL — quién puede disparar la restauración.
• Troubleshooting — cuando la restauración no funciona.