Runbooks и документация: как не изобретать велосипед в 3 часа ночи

Представьте пилота пассажирского самолёта. Перед взлётом он не полагается на память, он достаёт чек-лист и проходит по нему шаг за шагом. Выпуск шасси, закрылки, давление в гидравлике. Всё по бумажке. Даже если пилот налетал тысячи часов.

Чеклист FlyByWire A320Neo

Почему? Потому что в стрессовой ситуации память подводит. А чек-лист нет.

В SRE тот же принцип. Когда в 3 часа ночи у вас падает прод, вы не хотите вспоминать, в каком файле лежит конфиг репликации или кого дёргать, если сломался DNS. Вы хотите открыть документ и прочитать: «Шаг 1. Проверь А. Шаг 2. Сделай Б. Если не помогло — эскалируй Вове».

Runbook vs playbook vs постмортем

Важно не путать три вещи:

  • Runbook — это инструкция «что делать прямо сейчас». Конкретные шаги для конкретной ситуации. Упал nginx? Открой runbook по nginx.
  • Playbook — это сценарий для сложного, многоэтапного процесса. Например, playbook по запуску GameDay или по миграции дата-центра. Он отвечает на вопрос «какую пьесу мы сегодня играем и кто какую роль исполняет».
  • Постмортем — это уже после. Разбор того, что пошло не так. Не путайте его с runbook'ом. Подробнее — в главе про blameless postmortem.

Что делает runbook полезным

Хороший runbook отвечает на пять вопросов:

  1. Как понять, что это оно? — симптомы, по которым дежурный опознаёт ситуацию. Не «проверь логи», а «если в логах есть connection refused на порту 5432, переходи к шагу 3».
  2. Что делать? — конкретная последовательность действий. Без вариантов «возможно, нужно перезапустить». Только: «выполни kubectl rollout restart deployment/api».
  3. Что должно получиться? — ожидаемый результат каждого шага. Если после шага 2 метрика не изменилась — это сигнал, что диагноз неверный.
  4. Когда звать подмогу? — чёткий триггер эскалации. «Если через 5 минут после шага 3 доступность не восстановилась — звони L2 по телефону +7...».
  5. Где смотреть? — ссылки на дашборды, логи, алерты.

Анти-паттерны

«Всё в голове у Васи». Вася знает, как чинить этот сервис. Вася — единственный. Когда Вася в отпуске или уволился — вы в жопе. Runbook — это страховка от единой точки отказа.

«Напишем на 50 страниц». Никто не будет читать 50 страниц в 3 часа ночи. Runbook должен быть коротким — максимум 10–15 шагов. Если больше — разбивайте на подпроцедуры.

«Скопируем документацию от вендора». Документация PostgreSQL расскажет, как настроить репликацию. Но только ваш runbook расскажет, что перед переключением на реплику нужно позвонить в поддержку платежей, потому что у них там блокировка на таблице.

«Напишем когда-нибудь». Runbook для топ-3 инцидентов, написанных сегодня, полезнее, чем идеальный план для гипотетической катастрофы, который никто не написал.

Runbook как код

Современный подход — хранить runbook'и прямо в репозитории сервиса, в Markdown, рядом с кодом. Это даёт:

  • Версионирование: изменилась процедура деплоя — обновился runbook.
  • Code review: коллеги проверяют, не наврали ли вы в инструкции.
  • Автоматизация: из runbook'а можно сделать скрипт, а из скрипта — кнопку в панели управления.

Некоторые команды идут дальше и превращают runbook'и в код: CI/CD может запускать процедуру восстановления автоматически. Это уже граничит с AI-агентами, которые читают runbook'и и выполняют шаги без человека.

С чего начать

Не пытайтесь написать runbook'и на все случаи жизни сразу. Сделайте так:

  1. Откройте дашборд инцидентов за последние 3 месяца.
  2. Возьмите топ-3 повторяющихся причины.
  3. Напишите для каждой runbook по шаблону выше.
  4. Потестируйте на ближайшем GameDay: дайте стажёру runbook и попросите выполнить.
  5. Повторите.

Уже через месяц вы заметите, что типовые инциденты решаются быстрее, а дежурные перестают паниковать. Не потому, что система стала надёжнее — а потому что инструкция лежит под рукой.