[Перевод] Почему важна SRE документация. Ч. 2

Всем добрый вечер!

Вот и осталось всего ничего (то есть один день) до запуска потока курса «DevOps практики и инструменты», а значит нам надо успеть за это время довыложить оставшиеся части статьи «Почему важна SRE документация».

Продолжаем.

Документы для Онбординга Нового Сервиса

SRE проводят PRR (production readiness review, обзор готовности производства) для проверки соответствия сервиса стандартам операционной готовности, а также чтобы убедиться, что владельцы сервиса понимают, как пользоваться знаниями SRE для управления большими системами.

Сервису необходимо пройти эту проверку до запуска в продакшн. (До запуска его поддерживают не SRE, а сама команда разработки.) Цель PRR на данном этапе — убедиться, что сервис будет удовлетворять минимальным стандартам надежности на момент запуска.

_vwtdnedz_cwmkdqrwb3r2oz0mc.png

Следующий PRR происходит перед передачей сервиса SRE, то есть после запуска может пройти очень много времени. И когда команда SRE решает взять новый сервис, проводится тщательный анализ состояния производства и используемых практик сервиса. Цель — упростить процесс передачи сервиса с точки зрения надежности и операционной устойчивости, а также помочь SRE лучше разобраться с ним.

Проводя PRR перед передачей сервиса, SRE могут задать больше вопросов и установить более высокие стандарты надежности и простоты эксплуатации, чем при проведении PRR перед запуском. PRR перед запуском может быть «облегченным», чтобы не тормозить команду разработки.

В истории Зоуи у команды не было стандартизированного процесса или чеклиста PRR, а значит они могли упустить очень важные вопросы при передаче сервиса. Так возникает риск столкновения с большим количеством проблем, которые можно было с легкостью предвосхитить и решить еще до взятия на себя ответственности за управление сервисом.

PRR/передача сервиса требует создания PRR шаблонов и процессной документации (process doc), описывающей, как команды SRE будут работать с новым сервисом и использовать PRR шаблоны. Шаблоны, используемые в процессе передачи, могут быть более исчерпывающими, чем те, что применялись во время запуска.

Шаблон PRR охватывает несколько областей и необходим для проверки наличия ответов на критические вопросы. В Таблице 1 показаны некоторые области и связанные с ними вопросы, которые охватывает шаблон.

Область Вопросы
Архитектура и зависимости Каков путь запроса от клиента к фронтенду, а затем бэкенду? Существуют ли различные типы запросов с различными требованиями к задержке?
Планирование мощностей Каковы ожидания по поводу объемов трафика и скорости роста во время и после запуска? Обладаете ли вы вычислительными мощностями, необходимыми для поддержки этого трафика?
Типы отказов Есть ли единые точки отказа в вашей архитектуре? Как вы устраняете недоступность зависимостей?
Процессы и автоматизация Есть ли какие-то ручные процессы, необходимые для поддержки сервиса?
Внешние зависимости От каких сторонних данных, кода, сервисов или событий зависят сервис и запуск? Зависят ли какие-то ваши партнеры от сервиса? Если да, необходимо ли их уведомить о запуске?


Таблица 1. Пример областей PRR шаблона

В процессной документации также должны быть указаны документы, которые SRE должны запросить у команды разработки продукта в качестве пререквизитов для передачи. Например, они могут попросить команду разработки создать playbook для стандартных проблем.

Кроме того, SRE организации понадобится создать обзорный документ, в общих словах объясняющий команде разработки роль и зоны ответственности SRE. Это необходимо для формирования реалистичных ожиданий. Первый документ должен объяснять, что такое SRE, охватывать все темы, затронутые в прошлой части и начале этой статьи, включая основные функции, жизненный цикл сервиса, обязанности поддержки/обслуживания. Основная цель этого документа — убедиться, что разработчики не путают SRE с командой OPS и не считают ответы на пейджер единственной должностной обязанностью SRE. Как было показано в ранее описанной истории, если на момент передачи сервиса разработчики не до конца понимают, чем занимаются SRE, то это приведет к проблемам коммуникации и недопониманию.

Кроме того, необходимо создать документ модели взаимодействия (engagement model document) для прояснения ожиданий и объяснения процесса взаимодействия команды SRE с командой разработки продукта во время и после передачи сервиса. Темы, затронутые в документации, могут быть следующими:

  • Критерии передачи сервиса и процесс PRR.
  • Процесс обсуждения отчетов целей уровня обслуживания (service-level objectives, кратко SLO) и расчет погрешности.
  • Новый критерий запуска и политика заморозки запуска (если возможно).
  • Содержание и частота статус-репортов сервиса от команды SRE.
  • Требования к персоналу SRE.
  • Процесс планирования роадмапа нового функционала и приоритет функционала, повышающего надежность (требуемый SRE) над новым функционалом продукта.

Документация по эксплуатации сервиса

Для поддержки сервиса команды SRE в первую очередь опираются на основную эксплуатационную документацию: общее описание (овервью) сервиса, playbook«и и процедуры, постмортемы, директивы и SLA. (Примечание: этот раздел присутствовал в главе «Do Docs Better» в Seeking SRE.)

Овервью сервиса

Общее описание сервиса критически важно для понимания SRE, что за сервис они поддерживают. SRE необходимо знать архитектуру системы, ее компоненты и зависимости, контакты сервиса и его владельцев. Общее описание сервиса — результат совместной работы команды разработки и команды SRE, оно создается для руководства и приоритизации задач SRE и выявления областей для дальнейшего изучения. Такие овервью обычно получаются в результате проведения PRR и должны обновляться по мере изменения сервиса (например, если появились новые зависимости).

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

Playbook

Иногда еще называемый runbook, он представляет собой основополагающий документ, который позволяет инженерам во время смены реагировать на уведомления системы мониторинга сервиса. Например, если бы у команды Зоуи был playbook, объясняющий значение алерта «Джоб Ragnarok откинулся», и что нужно делать в ситуации его получения, инцидент бы разрешился за считанные минуты. Playbook«и сокращают время на устранение последствий инцидентов, а также предоставляют полезные ссылки на консоли и процедуры.

В playbook«ах содержатся инструкции по проверке, устранению и эскалации любого сгенерированного уведомления процессов сетевого мониторинга. Названия уведомлений в playbook«ах обычно совпадают с тем, что генерирует система. Они содержат команды и шаги, которые нужно протестировать на точность. Их нужно регулярно обновлять при обнаружении новых способов решения проблем, а также при выявлении новых типов отказа и добавлении зависимостей.

Playbook«и не создаются эксклюзивно для уведомлений. Также в них могут содержаться производственные процедуры для выпуска релизов, мониторинга и устранения неполадок. Другие примеры производственных процедур включают в себя включение/выключение сервиса, техническое обслуживание сервиса и аварии/эскалацию.

Постмортем

SRE работают с крупномасштабными, сложными, распределенными системами, а также улучшают сервисы с помощью нового функционала и добавления новых систем. Поэтому, учитывая масштаб и скорость изменений, инциденты и сбои неизбежны. Постмортем является важным инструментом SRE, формализацией процесса обучения на своих ошибках. В гипотетической истории Зоуи, у команды не было формальной процедуры постмортема, поэтому не было и формального процесса для фиксирования выводов инцидента, которые бы предотвратили его повторение. А значит команда обречена повторять те же ошибки снова и снова.

Командам SRE необходимо создать стандартизированный шаблон постмортема с разделами, в которых фиксируется важная информация о сбое. В идеале, шаблон должен быть структурирован так, чтобы его можно было легко парсить инструментом для анализа данных. Он отправляет репорты о динамике сбоя, используя постмортемы в качестве источника данных. Каждый постмортем, созданный по такому шаблону, описывает производственный сбой, включая следующую информацию (минимум):

  • Хронология событий (timeline).
  • Описание влияния на пользователя.
  • Первопричина.
  • Вопросы, требующие решений (action items) / извлеченные уроки.

Постмортем пишется членом команды, столкнувшимся со сбоем, в идеале тем, кто участвовал в его устранении и может взять на себя ответственность за доработки. Постмортем должен быть написан в безобвинительной манере. В нем должна быть информация, необходимая для понимания произошедшего, а также список решений, которые необходимо принять для снижения вероятности повторения, уменьшения последствий и/или упрощения восстановления.

Директивы

В директивной документации (policy document) указываются особые технические и нетехнические правила и директивы производства. Технические правила могут распространяться, например, на логирование изменений в производстве, сохранение логов, наименование внутренних сервисов (правила наименования, которым должны следовать инженеры при внедрении сервисов), а также использование и доступность экстренных идентификационных данных.

Директивы также могут быть направлены на процессы. Правила эскалации помогают инженерам классифицировать сбои как аварийные и не-аварийные и понимать, какие действия совершать в той или иной ситуации; директивы сменных ожиданий описывают структуру команды и зону ответственности каждого ее участника.

Соглашение об Уровне Обслуживания

Соглашение об уровне обслуживания (Service-Level Agreement, кратко — SLA) — официальное соглашение с клиентом о предоставляемой работе сервиса и действиях, предпринимаемых в случае невыполнения обязательств. Команды SRE документируют доступность и задержку сервиса, а также мониторят производительность сервиса, связанную с SLA.

Документация и публикация SLA, а также тщательный анализ пользовательского опыта и его сравнение с SLA, позволяет командам SRE быстрее внедрять инновации, не теряя качества UX. SRE, поддерживающие сервисы с четким SLA, быстрее замечают сбои, и поэтому быстрее их устраняют. SLA также снижает количество «трений» между командами SRE и SWE (разработчиками ПО), позволяя командам объективно обсуждать цели и результаты, избегая субъективных суждений о риске.

Стоит заметить, что наличие внешнего, юридически действительного соглашения может быть неприменимо к большей части SRE команд. В таких случаях, SRE команды могут ограничиться целями уровня обслуживания (service-level objectives, кратко — SLO). SLO — определение желаемого уровня обслуживания по конкретной метрике, например, доступности или задержке.

Документация продуктов производства

Команды SRE стремятся тратить 50 процентов своего времени на работу над проектом, разработку ПО для автоматизации ручной работы или улучшения надежности сервиса. В этом разделе описаны документы, связанные с продуктом и инструментами, которые разрабатывают SRE.

Эти документы важны, так как позволяют пользователям понять, подходит ли им данный продукт, как начать с ним работать, и как получить поддержку. Также они обеспечивают корректный пользовательский опыт и облегчают принятие продукта.

Страница «О» продукте

Страница с описанием помогает SRE и инженерам разработки продукта понять, что собой представляет продукт или инструмент, что он делает, и как им пользоваться.

Концепт-руководство

В концепт-руководстве или глоссарии определяются все понятия, уникальные для продукта. Определение понятий позволяет сохранять согласованность в документации и элементах пользовательских интерфейсов, API и CLI (интерфейсе командной строки).

Руководство по началу работы

Цель руководства по началу работы — быстро ввести инженеров в курс дела с минимумом задержек. Это полезно для новых пользователей, которые хотят попробовать продукт.

Codelab

Инженеры могут использовать эти туториалы, сочетающие в себе теоретическое объяснение, примеры кода и упражнения, для быстрого знакомства с продуктом. Codelab«ы также предоставляют подробные сценарии, которые шаг за шагом ведут инженеров по серии задач. Такие туториалы обычно длиннее руководств по началу работы. Они могут охватывать более одного продукта или инструмента, если те с чем-то взаимосвязаны.

Практическое руководство

Такое руководство необходимо пользователям, которые хотят решить конкретную задачу. Эти гайды обычно представляют собой пошаговую инструкцию, которой необходимо следовать.
FAQ

На странице FAQ пользователь может получить ответы на самые популярные вопросы, узнать о трудностях и ограничениях, с которыми можно столкнуться, найти ссылки на документы и другие страницы для более подробной информации.

Поддержка

На странице поддержки инженеры могут узнать, как решить проблему, с которой они столкнулись. Также на ней можно найти план эскалации, информацию об устранении неполадок, групповые ссылки, дашборд и SLO, а также информацию о сменах.

Описание API

В этом руководстве описаны функции, классы и методы обычно с минимумом сопроводительного текста. Такая документация чаще всего создается на основе комментариев в коде и иногда пишется техническими писателями.

Руководство разработчика

Из этого руководства разработчики могут узнать, как программировать с API продукта. Такие гайды обычно необходимы, если SRE создают продукты, предоставляющие API разработчикам, что позволяет создавать смешанные инструменты, вызывающие API друг друга для выполнения более сложных задач.

Документы для отчетности состояния сервиса

В этом разделе описаны документы, которые SRE команда создает для описания состояния поддерживаемых сервисов.

Ежеквартальный обзор сервиса

Информация о состоянии сервиса представляется в двух форматах: ежеквартальном отчете, согласованном SRE-лидом, который распространяется по всей SRE организации, и презентации для лида разработки продукта и команды.

Лиды SRE заинтересованы в ежеквартальных отчетах, так как они дают информацию о следующих вещах:

  • Проблемы поддержки (смены, тикеты, постмортемы). Лиды SRE знают, что если проблемы поддержки начинают отнимать более 50 процентов ресурсов команды SRE, необходимо реагировать и менять приоритеты. Цель — уже на ранних этапах идентифицировать проблему.
  • Исполнение SLA. Лиды SRE хотят знать, все ли в порядке с SLA, есть ли в экосистеме нездоровые компоненты, представляющие угрозу.
  • Риски. Лиды SLA хотят знать о рисках, известных SRE, которые способны помешать целям продукта и бизнеса.


Ежеквартальные отчеты дают SRE команде возможность:

  • Подчеркнуть пользу SRE для команды разработки продукта, а также саму работу команды SRE.
  • Запросить приоритетность решения проблем, которые мешают команде SRE (устойчивость).
  • Запросить фидбек по приоритетам команды SRE.
  • Подчеркнуть более широкий вклад команды.

Обзор успешных методик

Этот обзор помогает принять успешные методики и прийти к стабильному состоянию, в котором на операции требуется минимум времени. Для подготовки таких отчетов команды SRE предоставляют сайт и устав команды, детали состояния смен, проекты vs. прерывания, планирование мощностей, и тд.

Обзор успешных методик помогает команде SRE сравнить себя с остальной организацией SRE и улучшить показатели в ключевых областях: состоянии смен, проектах vs прерываниях, SLO и планировании мощностей.

Конец второй части.

Ждём как обычно ваши вопросы и комментарии.

© Habrahabr.ru