Criação de Runbooks

Crie runbooks operacionais eficazes, procedimentos operacionais padrão e guias de solução de problemas que qualquer engenheiro de plantão possa seguir sob pressão.

Modelo de Runbook — Estrutura Completa

# Runbook: [Service / Process Name]

**Owner:** [Team or individual]
**Last Reviewed:** YYYY-MM-DD
**Version:** X.Y
**Severity if unavailable:** SEV[1-4]

---

## Overview

Brief description of the service, why this runbook exists, and when to
use it.

## Prerequisites

- [ ] Required access / IAM role: [details]
- [ ] Tools installed: [kubectl, aws-cli, psql, etc.]
- [ ] VPN connected to [environment]
- [ ] Communication channel open: [Slack #channel]

## Procedure

### Step 1 — [Action Name]

[Explanation of what this step does and why.]

```bash
# comando aqui
```

**Expected output:** [describe what success looks like]

### Step 2 — [Action Name]

```bash
# comando aqui
```

**Expected output:** [description]

*(Continue with numbered steps...)*

## Verification

How to confirm the procedure succeeded:

- [ ] [Check 1 — e.g., health endpoint returns 200]
- [ ] [Check 2 — e.g., no errors in logs for 5 minutes]
- [ ] [Check 3 — e.g., metrics return to baseline]

## Rollback

If the procedure fails or causes unexpected issues:

### Rollback Step 1
```bash
# comando de rollback
```

### Rollback Step 2
```bash
# comando de rollback
```

## Troubleshooting

| Symptom | Likely Cause | Resolution |
|---------|-------------|------------|
| [symptom 1] | [cause] | [fix] |
| [symptom 2] | [cause] | [fix] |

## Escalation

If unresolved after [X] minutes:
- **Primary:** @[team-lead] — [phone/Slack]
- **Secondary:** @[manager] — [phone/Slack]

## Related Runbooks

- [Link to related runbook 1]
- [Link to related runbook 2]

## Change Log

| Date | Author | Change |
|------|--------|--------|
| YYYY-MM-DD | [Name] | Initial version |

Visão Geral

Faça o failover da instância primária do PostgreSQL para a réplica síncrona quando a primária estiver inacessível ou degradada. Este runbook cobre failover planejado (manutenção) e não planejado (emergência).

Pré-requisitos

• Acesso em nível de DBA ou SRE aos hosts primário e de réplica
• psql cliente instalado (v14+)
• VPN conectada à rede de produção
• Canal do Slack #db-ops aberto
• Confirmar que a réplica está em sincronia: lag de replicação < 1 MB

Procedimento

Etapa 1 — Verificar Saúde da Réplica

psql -h replica.db.internal -U dba -d postgres -c \
  "SELECT pg_is_in_recovery(), pg_last_wal_replay_lsn();"

Saída esperada: pg_is_in_recovery = t, LSN avançando.

Etapa 2 — Parar Gravações da Aplicação

kubectl scale deployment api-server --replicas=0 -n production
kubectl scale deployment worker --replicas=0 -n production

Saída esperada: Deployments escalados para 0 pods.

Etapa 3 — Confirmar Quiescência de Gravação

psql -h primary.db.internal -U dba -d postgres -c \
  "SELECT count(*) FROM pg_stat_activity WHERE state = 'active' AND query !~ 'pg_stat';"

Saída esperada: Contagem = 0 (sem consultas ativas).

Etapa 4 — Promover Réplica

psql -h replica.db.internal -U dba -d postgres -c "SELECT pg_promote();"

Aguarde até 30 segundos e confirme:

psql -h replica.db.internal -U dba -d postgres -c "SELECT pg_is_in_recovery();"

Saída esperada: pg_is_in_recovery = f (não é mais uma réplica).

Etapa 5 — Atualizar DNS

aws route53 change-resource-record-sets \
  --hosted-zone-id Z1234567890 \
  --change-batch '{
    "Changes": [{
      "Action": "UPSERT",
      "ResourceRecordSet": {
        "Name": "db.internal.example.com",
        "Type": "CNAME",
        "TTL": 60,
        "ResourceRecords": [{"Value": "replica.db.internal"}]
      }
    }]
  }'

Etapa 6 — Reiniciar Aplicação

kubectl scale deployment api-server --replicas=6 -n production
kubectl scale deployment worker --replicas=4 -n production

Verificação

• psql -h db.internal.example.com -c "SELECT 1;" retorna com sucesso
• Logs da aplicação mostram conexões de DB bem-sucedidas (sem erros por 5 min)
• Throughput de transações retorna ao baseline no dashboard do Grafana
• Nenhum alerta de lag de replicação disparando

Rollback

Se a réplica promovida tiver problemas, restaure do backup mais recente:

# Restore latest automated snapshot (RDS example)
aws rds restore-db-instance-from-db-snapshot \
  --db-instance-identifier prod-db-restored \
  --db-snapshot-identifier prod-db-latest-snapshot

Escalonamento

…