Что такое runbook и зачем он нужен

Runbook — это пошаговая инструкция для инженеров (обычно on-call), описывающая действия по диагностике, смягчению и восстановлению работы сервиса при конкретной проблеме. Это «чек-лист в бою»: минимальный набор проверенных шагов, команд и ссылок, который позволяет быстро и воспроизводимо вернуть систему в рабочее состояние.

Основные цели

• ускорить восстановление (снизить MTTR) за счёт понятных шагов;

• уменьшить когнитивную нагрузку on-call инженера в стрессовой ситуации;

• стандартизировать реакцию на типовые инциденты;

• передать знания между командами и новым сотрудникам;

• обеспечить воспроизводимость и возможность автоматизации.

Что обычно содержится в runbook

• заголовок, ответственный (owner), last reviewed date, уровень приоритета;

• область действия / scope (какие сервисы, среда: prod/stage);

• признаки инцидента (как обнаружить: метрики/алерты/логи);

• предпосылки и требования (креды, доступы, права);

• пошаговая инструкция (triage → mitigation → recovery) с точными командами и ожидаемыми результатами;

• проверки валидации (как убедиться, что всё ок);

• команды для отката/rollback;

• контакты и эскалация (on-call, владельцы сервиса, SRE, DB админ);

• ссылки: дашборды, query в лог-сторе, трассы, playbook’ы, run scripts;

• post-incident задачи (постмортем, изменения в runbook после инцидента).

Пример минимального шаблона

pythonTitle: API 500 spike (prod) Owner: team-api@example.com Detection: alert "api_5xx_rate > 1% for 5m" Preconditions: доступ k8s, kubectl config=prod

Steps:

1) Ограничить трафик: включить feature flag X (admin console) — ожидаемый результат: drop в 5xx.

2) Посмотреть поды: kubectl get pods -l app=api -o wide

3) Логи проблемного подраздела: kubectl logs <pod> | grep "Timeout"

4) Если причина — DB timeout: переключить на read-replica: /scripts/switch-db.sh --to replica

5) Проверка: curl -I https://api.example.com/health → 200

6) Если не помогло — эскалация: @sre-lead, открыть conference bridge

Validation: SLI p95 < 300ms и 5xx < 0.1% в течение 10m

Лучшие практики написания

• писать короткими императивными шагами: «выполнить», «проверить»;

• указывать точные команды и ожидаемый вывод;

• не полагаться на память — дать всё необходимое (куда смотреть, что менять);

• использовать структурированные шаблоны и version control (Git) + ревью;

• хранить рядом с дашбордами и системой оповещений;

• отмечать дату проверки и тестировать runbook в «учебных» инцидентах (fire drills);

• автоматизировать рутинные шаги (скрипты, playbooks) и документировать ручные только при необходимости;

• избежать секретов в тексте — держать ссылки на защищённые хранилища с доступом.

Как поддерживать полезность

• назначить владельца, регулярные ревью;

• обновлять после каждого инцидента (lessons learned);

• измерять эффективность: снижение MTTR при использовании runbook, процент успешных восстановлений;

• проводить тренировки и проверку шагов (runbook run-throughs).

Runbook vs playbook vs SOP

• Runbook — конкретная инструкция «что делать сейчас при X».

• Playbook — набор сценариев/связанных runbook’ов для класса инцидентов (может быть более стратегическим).

• SOP — процедурный документ для рутинных операций (менее аварийный, больше про процессы).

Runbook — практический инструмент для быстрого реагирования и передачи операционной памяти: правильно написанный и протестированный он заметно сокращает время простоя и количество ошибок в экстренных ситуациях.