Runbooks for critical operations

Nível: C1

Objetivo

Escrever runbooks em C1 para operações críticas com decision tree, prerequisites, commands, expected output, rollback e escalation. O foco é o on-call às 3h conseguir seguir o runbook sem precisar pensar.

Explicação

Runbooks em C1 são o que separa sênior de pleno: runbook bom funciona às 3h, sem o autor, com sono. Cinco blocos:

1. Decision tree

Árvore de decisão explícita. C1 cita: 'is the error rate above 1%? yes -> go to step 2. no -> go to step 5'. Decision tree em C1 é o que o on-call segue, não texto corrido.

2. Prerequisites

O que precisa estar pronto antes de seguir o runbook. C1 cita: 'prerequisites: access to the production dashboard, ssh key on the bastion, pager credentials'. Prerequisites em C1 evitam 'ah, não tenho acesso' às 3h.

3. Commands

Comandos exatos a executar. C1 cita: 'run: kubectl rollout undo deployment/checkout; expected: deployment rolled back in 30s'. Commands em C1 são copy-paste, não 'rode kubectl'.

4. Expected output

O que o on-call deve ver. C1 cita: 'expected: error rate returns to 0.5% within 2 minutes'. Expected output em C1 é o que confirma que o passo funcionou.

5. Rollback e escalation

O que fazer se o passo falhar. C1 cita: 'if error rate does not return, escalate to the platform lead within 15 minutes'. Rollback e escalation em C1 são o que evita o on-call ficar preso.

Exemplos

Erros comuns

• Texto corrido: runbook sem decision tree é 'leia tudo e decida'; on-call às 3h não decide, segue.
• Sem prerequisites: 'ah, não tenho acesso' é 30 min perdidos; prerequisites em C1 são explícitas.
• Comandos vagos: 'rode kubectl' é vago; 'kubectl rollout undo deployment/checkout' é copy-paste.
• Sem expected output: 'deu certo' é opinião; 'error rate returns to 0.5% within 2 min' é mensurável.
• Sem escalation: on-call preso às 3h com runbook que não funciona; escalation em C1 é o backup.

Prática guiada

Reescreva cada bloco abaixo no padrão C1 de runbook.

1. Decision tree: árvore explícita, não texto.
2. Prerequisites: lista do que precisa estar pronto.
3. Commands: copy-paste exato.
4. Expected output: o que confirma que funcionou.
5. Rollback e escalation: o que fazer se o passo falhar.

Resumo

Runbook C1 tem cinco blocos: decision tree (árvore), prerequisites (acesso), commands (copy-paste), expected output (métrica de sucesso), rollback e escalation (backup). Runbook sem esses blocos é texto corrido; com eles, é execução confiável às 3h.

História: Runbooks for critical operations

Nível: C1

História em inglês

Writing the runbook for the checkout rollback

On Wednesday, I wrote the runbook for the checkout rollback. I opened with the decision tree: is the error rate above 1%? yes -> go to step 2. no -> go to step 5. I listed the prerequisites: dashboard access, ssh key on the bastion, pager credentials. I added the commands: run kubectl rollout undo deployment/checkout; expected: deployment rolled back in 30s. I added expected output: error rate returns to 0.5% within 2 minutes. I closed with escalation: if error rate does not return, escalate to the platform lead within 15 minutes.

Tradução linha por linha

Notas de vocabulário

• is error rate above 1%? yes -> go to step 2. no -> go to step 5 = Decision tree: árvore explícita.
• dashboard access, ssh key, pager credentials = Prerequisites: o que precisa estar pronto.
• kubectl rollout undo deployment/checkout; expected: deployment rolled back in 30s = Commands: copy-paste exato.
• error rate returns to 0.5% within 2 minutes = Expected output: métrica de sucesso.
• escalate to the platform lead within 15 minutes = Escalation: backup para o on-call.

Perguntas de compreensão

1. O que diferencia decision tree C1 de texto corrido?
2. Por que prerequisites em C1?
3. O que torna commands C1 útil?
4. Por que escalation em C1?

Prática com a história

1. Escreva um runbook C1 para um spike de error rate em checkout.
2. Escreva o expected output C1 para um runbook de rollback.
3. Escreva as prerequisites C1 para um runbook de produção.