Как написать runbook для реагирования на инциденты (с шаблонами)

Большинство runbook'ов инцидентов попадают в две категории отказов. Они слишком длинные (тридцатистраничная вики, которую ни один дежурный инженер не будет читать в 3 ночи), или слишком расплывчатые (одна строка, которая говорит «смотрите логи»). Runbook'ы, которые на самом деле используются во время инцидентов, следуют чёткой структуре с конкретными командами и ясными точками принятия решений. Это руководство охватывает структуру, которая работает, с тремя шаблонами, которые вы можете скопировать для ваших наиболее распространённых типов инцидентов.

Что такое runbook и чем он не является

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

Если ваш runbook объясняет, как работает система, он слишком длинный. Если он не указывает конкретные команды и конкретные точки принятия решений, он слишком расплывчатый. Правильный размер для одного runbook'а — примерно на один экран. Если вам нужно больше, разделите его.

Пятичастная структура, которая работает

Пять разделов охватывают то, что нужно дежурному инженеру. Используйте эту структуру для каждого runbook'а в вашей коллекции.

• Симптом: как выглядит оповещение. Приведите текст реального оповещения. Инженер должен узнать это за несколько секунд.
• Влияние: кто затронут и как. Для клиентов? Для внутреннего использования? Просто шум мониторинга? Определяет срочность.
• Диагностика: три команды или ссылки, которые подтверждают диагноз. Не «смотрите логи», а «kubectl logs -n prod web-deployment -c app».
• Исправление: конкретные команды или действия для его исправления. Нумерованные, идемпотентные, безопасные для повтора.
• Эскалация: кого разбудить, если исправление не сработает. Имя и номер телефона.

Шаблон: runbook насыщения пула подключений базы данных

Самый распространённый тип производственного инцидента. Пул подключений к базе данных переполнен, новые запросы истекают, мониторинг срабатывает с оповещениями о высокой задержке.

Симптом: «время отклика p95 выше 5 секунд на /api/health». Влияние: конечные точки API для клиентов истекают. Диагностика: выполните kubectl exec в поде приложения и запустите pg_stat_activity. Ищите долго выполняющиеся запросы. Исправление: отмените самые долго выполняющиеся запросы с помощью pg_cancel_backend, увеличьте размер пула на 20% с помощью helm upgrade, перезагрузите затронутые поды. Эскалация: вызовите лида базы данных, если пул всё ещё насыщен через 10 минут.

Шаблон: runbook истечения сертификата SSL

Предсказуемо, предотвратимо, но в итоге происходит почти с каждой командой. Runbook короток, потому что и ответ короток.

• Признак: SSL монитор срабатывает с «истекает через 7 дней» или «истек».
• Воздействие: каждый браузер показывает красную страницу предупреждения после истечения сертификата. Конверсия падает до нуля.
• Диагностика: выполните команду `echo
• openssl s_client -servername DOMAIN -connect DOMAIN:443 2>/dev/null
• openssl x509 -noout -dates` чтобы увидеть дату истечения сертификата (notAfter).
• Исправление: вручную запустите скрипт обновления (`certbot renew --force-renewal` или эквивалент), затем перезагрузите nginx/балансировщик нагрузки. Проверьте это с помощью той же команды openssl.
• Эскалация: оповестите DevOps если certbot не удаётся. Сертификат должен быть обновлён вручную до истечения.

Шаблон: runbook простоя провайдера-зависимости

Когда сбой вызван сторонней зависимостью (Stripe, Postmark, S3, провайдер аутентификации), ваша задача — признать это, сообщить об этом и не тратить время на отладку собственного кода.

Признак: соответствующая функция не работает, но ваши собственные мониторы показывают зелёный статус. Диагностика: откройте страницу статуса провайдера в новой вкладке. Поищите в недавних коммитах любые изменения интеграции. Исправление: разместите обновление на вашей странице статуса, подтверждающее сбой провайдера, со ссылкой на страницу статуса провайдера. Отключите функцию с помощью feature flag если деградация серьёзная. Эскалация: только если деградация длится более часа без подтверждения от провайдера.

Где их хранить и как их актуализировать

Храните runbooks в том же git репозитории, что и код приложения. Включайте ссылки на них в сообщения об алёртах. Проверяйте их после каждого инцидента: если runbook был неправильным, обновите его сейчас, пока инцидент свежий. Runbook, который не обновлялся год, вероятно уже не актуален. Запланируйте ежеквартальное рассмотрение коллекции runbooks. Удаляйте те, что больше не применяются. Добавляйте новые. Относитесь к ним как к коду.