Runbooks e procedimentos operacionais

Nível: B2

Objetivo

Escrever, revisar e seguir runbooks e procedimentos operacionais em inglês, estruturando prerequisites, decision points, rollback steps, verification e escalation path; produzir instruções de produção que sejam seguras, verificáveis e auditáveis.

Explicação

Um runbook é um documento passo a passo usado durante uma operação real: deploy, failover, rotação de credenciais, drenagem de tráfego, resposta a incidente. Diferente de um design doc, ele não propõe mudanças — ele executa mudanças. Por isso, a qualidade da linguagem importa menos que a clareza operacional: alguém cansado, de madrugada, em plantão, precisa seguir o runbook sem ambiguidade.

Um runbook maduro segue uma estrutura reconhecível. As seções abaixo aparecem, em alguma ordem, em quase toda organização:

1. Title and purpose — o que este runbook faz e em que cenário é usado.
2. Owner and last reviewed — quem é dono do documento e quando foi revisado pela última vez. Runbooks vencem.
3. Prerequisites — o que precisa ser verdade antes de começar: acesso, aprovação, mudança em janela, versão de ferramenta, estado de saúde do sistema.
4. Decision points — pontos em que o operador escolhe entre caminhos diferentes, geralmente com base em uma métrica ou um sintoma.
5. Steps — sequência numerada, com o comando exato, o que esperar e o que fazer se a saída não for a esperada.
6. Rollback steps — como reverter o runbook, mesmo quando a operação principal está parcialmente concluída.
7. Verification — como confirmar que a mudança foi aplicada com sucesso (métrica, log, dashboard, smoke test).
8. Escalation path — quem acionar, em que ordem, com qual canal, se um pré-requisito falhar, se uma verificação falhar ou se o rollback não for possível.

A ordem existe por um motivo: o operador precisa saber antes se tem permissão e saúde de sistema para começar (prerequisites), precisa saber durante o que observar e o que considerar aceitável (decision points e verification) e precisa saber o tempo todo quem chamar se algo fugir do script (escalation path). Um runbook sem prerequisites leva a falhas de permissão em produção; um runbook sem rollback leva a incidentes prolongados; um runbook sem verification leva a "deploys silenciosos" que parecem ter funcionado mas não funcionaram.

Frases úteis em B2 para abrir cada seção:

• Purpose: *This runbook drains traffic from the legacy API gateway during a planned cutover.*
• Prerequisites: *Before starting, confirm that you have production write access, that the change ticket CR-4821 is approved, and that the maintenance window is open.*
• Decision point: *If the request error rate is above 0.5%, stop and go to the rollback section. Otherwise, proceed to step 4.*
• Step: *Run the following command: `kubectl drain node-3 --ignore-daemonsets`. Verify that the output contains `node-3 cordoned` before continuing.*
• Verification: *After step 6, the dashboard `payments-latency` should show p99 below 250ms for at least five minutes.*
• Escalation: *If verification fails after two attempts, page the platform on-call and the database owner. Do not attempt a third rollback without sign-off.*

Diferenças de registro também importam. O runbook é um texto imperativo (*drain the node*, *verify the output*), enquanto o postmortem é reflexivo (*we drained*, *the output was*). Misturar os dois registros — escrever *we should drain the node* num runbook — é um sinal clássico de que o documento foi escrito por quem não vai executá-lo.

Por fim, a regra de ouro: um runbook só é confiável depois de ter sido executado em condições reais. Bons times rodam o runbook em ambiente de staging, em modo dry-run, ou pelo menos revisam-no periodicamente com quem está de plantão. Se o seu runbook não foi executado nos últimos seis meses, ele está mentindo para você.

Exemplos

Erros comuns

• Escrever o runbook em tom de postmortem: 'we should drain the node' em vez de 'drain the node'. O leitor do runbook está executando, não debatendo.
• Listar comandos sem saída esperada: 'run the migration' sem dizer o que aparece em caso de sucesso vira suposição em produção.
• Pular prerequisites: começar com 'restart the service' sem verificar janela de manutenção, aprovação de mudança ou estado de saúde leva a falhas caras.
• Tratar rollback como apêndice: rollback precisa estar descrito com o mesmo nível de detalhe dos passos principais, inclusive para o estado parcial.
• Esquecer verification: deploys que 'parecem ter funcionado' são o tipo mais perigoso de incidente. O runbook precisa dizer o que medir e por quanto tempo.
• Escalation path vago: 'escalate if needed' não diz a quem, em que canal, em que ordem e com qual informação. O runbook tem que nomear.
• Não versionar e não datar: um runbook sem 'last reviewed' é um runbook que ninguém confia depois de seis meses. Operadores precisam saber se está atualizado.

Prática guiada

Reescreva o trecho informal abaixo como três seções de um runbook.

Texto informal: `A gente precisa reiniciar o serviço de pagamentos. Antes, tem que ver se a janela tá aberta e se o ticket foi aprovado. Se der erro, chama o Bruno. Se funcionar, olha se a latência caiu.`

Em tom de runbook:

• Prerequisites: *Before starting, confirm that the change ticket CR-5118 is approved, that you are inside the maintenance window (Tuesday 22:00–23:00 UTC), and that the `payments-api` health check is green for the last five minutes.*
• Decision point: *If the health check is red, do not proceed. Escalate to the payments on-call and wait for sign-off.*
• Verification: *After the restart, the dashboard `payments-latency` should show p99 below 250ms for at least ten minutes. If the metric does not return to baseline, follow the rollback steps.*

Repare: prerequisites viraram itens verificáveis (ticket, janela, saúde), o decision point tem ação explícita (não prossiga, escale) e a verification tem métrica com janela de tempo. A frase 'chama o Bruno' virou 'escalate to the payments on-call' — sem nome próprio, mas com papel claro e o canal (on-call) explícito.

Resumo

Runbooks são textos imperativos usados para executar mudanças em produção: drenar tráfego, fazer failover, rotacionar credenciais, responder a um incidente. A estrutura canônica tem oito blocos — purpose, owner, prerequisites, decision points, steps, rollback, verification, escalation — e cada um existe para um erro específico que operadores cometem quando o bloco está faltando. Linguagem de B2 para esse contexto é direta e testável: comandos com saída esperada, decisions com condição e ação, verification com métrica e janela de tempo, escalation com nomes, canais e regra de parada. Um runbook sem prerequisites, rollback, verification e escalation não é seguro para produção, por mais bem escrito que pareça.

História: Runbooks e procedimentos operacionais

Nível: B2

História em inglês

Drafting the runbook

Daniel is a senior platform engineer at a fintech, and his team has been asked to write a runbook for draining a payments node during a planned failover. He starts with the purpose: this runbook moves traffic away from `payments-node-3` so the cluster can be patched. Under owner and last reviewed, he adds himself and a six-month review date, because the previous runbook was so outdated that operators stopped trusting it. The prerequisites include an approved change ticket, an open maintenance window, and a green health check for at least five minutes before starting. He is careful to mark the blast radius as a single node, not the whole cluster, so reviewers know what they are approving.

The dry run

Before publishing the runbook, Daniel schedules a dry run in staging with two operators who have never seen the document. During the dry run, one operator misreads step 3 and runs the drain command without the `--ignore-daemonsets` flag, which fails. Daniel rewrites the step so that the command appears in a code block and the expected output is on the line below, with the word 'expected' in bold. The second operator stops at the decision point and asks whether 0.5% is the right threshold, because their service has a stricter SLO. They agree to lower the threshold to 0.3% and to add a comment in the runbook explaining where the number comes from. Daniel also adds a sign-off step: any rollback during the run requires approval from the incident commander.

A complication in production

Two weeks later, the runbook is executed for real during a Tuesday maintenance window. After step 5, the dashboard `payments-latency` stays at 280ms, which is above the 250ms target written in the verification section. The on-call engineer follows the runbook and goes to the rollback section, as the decision point in step 6 instructs. He re-enables traffic on the stable node, then pages the platform on-call and the database owner, as the escalation path requires. Verification now shows p99 at 180ms for ten minutes, so the runbook owner updates the change ticket with the outcome and closes the incident. The postmortem later finds that the original threshold of 0.5% was correct, but the verification target of 250ms was too tight for this cluster.

Tradução linha por linha

Notas de vocabulário

• this runbook moves traffic away from `payments-node-3` = Purpose em uma frase, com verbo de execução no presente simples e referência técnica em code span.
• owner and last reviewed = metadado obrigatório em todo runbook; sem isso, operadores não sabem se o documento está atualizado.
• blast radius = extensão do impacto caso a operação dê errado; deve ser marcado no runbook para que o reviewer saiba o tamanho do risco.
• dry run = execução simulada, sem efeito real, para validar o runbook com operadores que nunca viram o documento.
• the expected output is on the line below = forma de reduzir ambiguidade: comando, depois 'expected' em negrito, depois a saída esperada.
• sign-off step = passo explícito de aprovação; impede rollback ou retry sem autorização, especialmente durante incidentes.
• decision point = ponto com condição, ação e ponteiro para outra seção; sem isso, o operador tem que adivinhar.
• escalation path = lista de papéis, canais e ordem de acionamento; substitui 'tell someone if something goes wrong'.
• verification now shows p99 at 180ms for ten minutes = verification combina métrica (p99), alvo (180ms) e janela de tempo (dez minutos) — formato padrão.

Perguntas de compreensão

1. What does Daniel's runbook do, in one sentence?
2. Which prerequisites must be satisfied before the runbook starts?
3. What is the blast radius of this runbook?
4. Why did Daniel rewrite step 3 after the dry run?
5. What threshold did the team change during the dry run, and to what?
6. Why did the on-call engineer stop the production execution and go to rollback?
7. Who did the on-call engineer page, and why?
8. What did the postmortem find about the original thresholds?
9. What did Daniel add after the dry run, besides the lower threshold?

Prática com a história

1. Reescreva em tom de runbook: Antes de tudo, vê se a janela tá aberta.
2. Classifique a frase: If the dashboard stays red for more than five minutes, escalate to the platform on-call.
3. Escreva um verification de uma frase para o runbook do story, mencionando métrica, alvo e janela de tempo.
4. Faça uma pergunta de revisão sugerindo um dry run antes da execução em produção.