Backup e restore do estado do cluster

Backup do cluster não é a mesma coisa que backup dos seus dados. São dois universos. Este guia trata só do primeiro.

O que é o estado do cluster

O HeroCtl mantém um catálogo do que existe: jobs declarados, secrets armazenados, regras de ACL, histórico recente de métricas, ingress configurado, nós conhecidos. Tudo isso é o estado do plano de controle.

Se você perder esse estado, o cluster esquece o que devia rodar. Os contêineres podem continuar de pé, mas ninguém mais sabe gerenciá-los. É o tipo de situação que termina em rebuild manual.

Backup desse estado é barato. Não fazer é caro.

O que NÃO entra no snapshot: os dados que vivem dentro dos seus contêineres. Banco Postgres, volumes, uploads de usuário. Esses precisam de backup próprio (pg_dump, snapshots do storage, etc).

Snapshot manual

O comando é uma linha:

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

A saída:

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

Por dentro o arquivo é um tarball comprimido com:

• Definições de jobs
• Secrets (criptografados)
• Políticas de ACL e tokens
• Configuração de ingress
• Lista de nós conhecidos
• Histórico de métricas dos últimos 7 dias

Não inclui logs antigos nem imagens de contêiner.

Restore

Restaurar é mais delicado. O cluster precisa 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

Atenção: restore sobrescreve o estado atual. Se o snapshot é de ontem, você perde tudo que aconteceu desde então. Faça um snapshot do estado atual antes, mesmo que esteja quebrado — pode salvar evidências.

Backup automático (Plano Business)

Snapshots manuais funcionam. Snapshots agendados funcionam mais.

Configuração:

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

O schedule é cron-like. Exemplos:

Storage compatível

Qualquer storage S3-compatible serve:

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

A escolha é sua. R2 e B2 são geralmente os mais baratos para retenção longa.

Retenção

retention_days: 30

Snapshots mais antigos que 30 dias são apagados automaticamente. Você pode usar valores diferentes:

• 7 — equipes pequenas, apenas operacional
• 30 — padrão recomendado
• 90 — auditoria, ambientes regulados
• 365 — compliance forte

Cada snapshot pesa entre 2 MB e algumas dezenas de MB. Mesmo 365 cópias ocupam pouco.

Encryption

Todo snapshot é criptografado em repouso com AES-256. A chave fica configurada no servidor:

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

Gere a chave uma vez:

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

Atenção: sem essa chave o snapshot vira lixo. Guarde uma cópia fora do cluster. Em cofre de senhas. Em papel num envelope. Onde fizer sentido — mas guarde.

Disaster recovery

Três cenários, três respostas.

Cenário 1: cluster perdeu coordenação

Mais nós caíram do que sobraram. O cluster trava em modo somente-leitura.

Solução normal: trazer os nós caídos de volta. Eles re-sincronizam e tudo volta.

Solução de emergência (último recurso): bootstrap forçado a partir do snapshot mais recente.

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

Você perde mudanças feitas depois do último snapshot.

Cenário 2: storage do cluster corrompido

Disco morreu. Datacenter incendiou. Operador deletou /var/lib/heroctl.

Mesmo procedimento:

1. Provisione nós novos.
2. Instale o HeroCtl.
3. heroctl snapshot restore num deles.
4. Faça os outros entrarem como pares.

Se você tinha snapshot off-site, recupera em minutos. Se não tinha, recupera em dias (refazendo tudo do zero).

Cenário 3: dados das aplicações se perderam

Snapshot do cluster não te ajuda aqui. Você precisa de:

• pg_dump agendado para Postgres
• Snapshot do volume para storage de arquivos
• Replicação para Redis (se persistente)

Cada workload é responsável pelo próprio backup de dados. O HeroCtl orquestra; ele não substitui sua estratégia de backup de aplicação.

Testes de restore

Backup que ninguém testou não é backup. É arquivo.

O HeroCtl Business agenda testes automáticos:

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

Mensalmente o cluster de staging derruba seu estado, restaura o último snapshot de produção e roda um conjunto de verificações:

• Todos os jobs voltaram?
• Secrets descriptografam corretamente?
• ACL está consistente?

Se algo falha, alerta no canal configurado.

Boas práticas

A regra 3-2-1 do backup tradicional vale aqui também:

• 3 cópias do snapshot
• 2 mídias diferentes (disco local + nuvem)
• 1 off-site (provedor diferente do cluster)

Aplicado:

• Cópia 1: gerada no nó coordenador.
• Cópia 2: replicada para um bucket S3 na mesma região.
• Cópia 3: replicada para um bucket em outra região ou outro provedor.

Quando o datacenter inteiro cair, é a cópia 3 que te salva.

Resumo

Próximos passos:

• Métricas e alertas — saiba quando o backup falhou.
• ACL — quem pode disparar restore.
• Troubleshooting — quando o restore não funciona.