Template Runbook

Runbook: o playbook operacional que todo on-call precisa

Um runbook é um documento operacional passo a passo que diz a um engenheiro exatamente o que fazer quando um cenário conhecido acontece — um deploy, um restart, uma rotação de segredo, um disaster recovery, um alerta que acabou de disparar às 03h. A disciplina de escrever runbooks foi popularizada pelo livro Site Reliability Engineering do Google (O'Reilly, 2016), que defendeu que qualquer serviço em produção precisa ter runbook antes de entrar na escala de on-call. O argumento econômico é simples: um runbook bem escrito reduz o MTTR (Mean Time To Recovery) em 50% ou mais, porque quem responde não precisa descobrir o procedimento durante o incidente.

Um runbook sólido tem seções previsíveis: Quando usar (o gatilho — um ID de alerta, um ticket de cliente, uma janela agendada), Pré-requisitos (acessos, ferramentas, VPN, contexto kubectl), Passos (numerados, comandos copia-e-cola), Verificação (como sei que funcionou?), Rollback (como desfaço se não funcionou?), Escalonamento (quem aciono depois de N minutos?) e Runbooks relacionados. O formato importa: a maioria dos times mantém runbooks como Markdown em repositório git (versionado, revisável em PRs) e espelha ou renderiza em Confluence ou Notion para ser buscável.

Categorias de runbook

A maioria dos times converge em três famílias: resposta a incidente (acionado por alerta; PagerDuty ou Opsgenie linka o alerta diretamente ao URL do runbook), agendados (estilo cron — rotação de certificado, vacuum mensal de banco, verificação de backup) e janelas de manutenção (deploys, upgrades maiores, migrações agendadas). Cada família tem tolerância diferente a ambiguidade — runbooks de resposta a incidente precisam ser executáveis em pânico; os agendados podem ser mais longos e didáticos.

Ferramentas, automação e "runbook as code"

Stacks modernas amarram runbooks a alertas e a código executável. PagerDuty e Opsgenie permitem anexar um URL de runbook a cada alerta. Jira Service Management, ServiceNow e Backstage (o portal de desenvolvedor open-source do Spotify) hospedam runbooks ao lado de catálogos de serviço. A evolução natural é "runbook as code": scripts idempotentes que humanos conseguem ler mas que máquinas também conseguem executar — playbooks Ansible, módulos Terraform, AWS Systems Manager Run Command, Rundeck. O runbook em Markdown vira a documentação ao redor de um procedimento automatizado, não mais uma sequência de passos manuais.

Anti-padrões a evitar

Os quatro fracassos clássicos da higiene de runbook: (1) conteúdo desatualizado — "última revisão 2019" é bandeira vermelha; times deveriam revisar runbooks pelo menos trimestralmente, idealmente via um exercício de Chaos Engineering que efetivamente os execute; (2) preâmbulo verboso — no passo 4 o on-call já parou de ler; coloque os comandos no topo; (3) rollback ausente — todo passo destrutivo precisa de um desfazer explícito; (4) sem passo de verificação — "deploy bem-sucedido" não é a mesma coisa que "o serviço está saudável". O livro de SRE do Google e os runbooks públicos de Cybersecurity Operations da NSA são boas referências de formato e tom.

Perguntas frequentes

Runbook substitui documentação? Não — complementa. A documentação explica o que o sistema é e por que funciona assim. O runbook diz o que fazer numa situação operacional específica.

Runbook é obrigatório? Para qualquer coisa que entra na escala de on-call, sim. Times maduros de SRE recusam assumir o pager de um serviço que não tem runbooks para seus principais alertas.

Onde os runbooks devem ficar? A resposta pragmática é "em dois lugares": como Markdown no repositório git do serviço (versionado, revisado em PR) e renderizado ou copiado para Confluence/Notion (buscável a partir do canal de incidente).

Como sei que um runbook ainda funciona? Executando. Game days e exercícios de Chaos Engineering (linhagem do Chaos Monkey, da Netflix) existem justamente para validar que os runbooks continuam corretos frente ao sistema em produção atual.