Всем добрый вечер! Спешим поделиться новостью о том, что уже в феврале у нас запускается новый поток по курсу «Devops — практики и инструменты» ^[1], а это значит, что пора закончить начатое и опубликовать третью часть статьи: «Почему важна SRE документация» ^[2]. Поехали!

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

Командам SRE для эффективной работы необходима надежная и доступная документация.

Сайт команды

Примечание: Вместо сайта можно использовать отдельный спейс или раздел в Confluence/Wiki.

Сайт команды важен тем, что обеспечивает координацию информации и документации, связанной с командой SRE и ее проектами. Например в Google, многие команды SRE используют g3doc (внутренняя платформа документирования Google, где доки живут в исходном коде вместе со связанным кодом), а некоторые команды используют g3doc и Google Sites: в таком случае страницы g3doc тесно связаны с кодом/деталями реализации.

Устав команды

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

В уставе обычно есть следующие элементы:

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

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

Документация для интеграции новых SRE

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

Многие SRE команды готовят новых сотрудников к сменам с помощью чеклистов. Чеклист для смены обычно охватывает высокоуровневые области (разделенные на подразделы), в которых должны разбираться члены команды. Примерами таких областей могут быть концепции производства, front-end и back-end, автоматизация и инструментарий, мониторинг и логирование. Также в чеклист могут быть включены инструкции по подготовке к смене и задачи, выполняемые во время смены.

Для подготовки новых членов команды SRE также используют ролевые упражнения (в Google их называют Wheel of Misfortune — Колесо Неудачи). Такое упражнение представляет собой сценарий сбоя с определенным набором данных и сигналов, которые гипотетически могут понадобиться SRE для решения проблемы во время смены. Члены команды по очереди играют роль инженера на дежурстве, чтобы отточить мастерство ликвидации последствий сбоя и навык отладки системы. Wheel of Misfortune проверяет, знает ли каждый член команды, где найти нужную для устранения проблемы документацию, и как справиться с произошедшим сбоем.

Управление хранилищем

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

Вот несколько рекомендаций о том, как создавать и поддерживать репозиторий документации:

• Определите ключевых стейкхолдеров и проведите краткие интервью для выявления всех потребностей.
• Найдите как можно больше документации и проанализируйте пробелы в содержании.
• Базово структурируйте сайт, чтобы создавать новую документацию в правильных местах.
• Переместите существующую документацию в новую локацию.
• Заархивируйте и снесите старую документацию.
• Проводите регулярные проверки, чтобы убедиться в качестве/согласованности поддерживаемой документации.
• Убедитесь, что стандартные поисковые запросы выдают необходимые документы в самом верху списка результатов поиска.
• Используйте сигналы, например Google Analytics, для оценки стандартных практик.

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

Доступность репозитория

Команды SRE должны убедиться, что документация остается доступной даже в случае сбоев и недоступности стандартного репозитория. Каждый SRE в Google владеет собственной копией критически важной документации. Эта копия доступна на зашифрованном компактном запоминающем устройстве или каком-то подобном съемном, но безопасном физическом носителе, которое есть у каждого SRE на дежурстве.

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

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

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

Простой email-рассылки недостаточно — необходимо обновить главную страницу документации, playbook’и и codelab’ы. Кроме того, по возможности прокомментируйте заголовочные файлы. Опишите детали объявления в документе (в дополнении к письму), на который можно ссылаться пользователям. Письмо должно быть максимально коротким, но при этом информативным, отражающим все основные моменты. Опишите дополнительные детали: бизнес-мотивацию для выключения сервиса, какие инструменты пользователи могут использовать для миграции на другой сервис, какая поддержка доступна во время миграции. Также стоит создать страницу FAQ, наполняя ее со временем новой информацией по вопросам, которые задают пользователи.

Роль редакторов технической документации

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

Вот несколько практических рекомендаций для технических редакторов по работе с SRE командами.

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

Шаблоны

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

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

Site Reliability Engineering содержит несколько примеров шаблонов документации. В этом разделе мы приведем еще некоторые примеры, чтобы показать, как шаблоны предоставляют структуру и руководство для инженеров для заполнения контентом.

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

Обзор

Что это? Что он делает? Высокоуровнево опишите функциональность, предоставляемую клиентам (конечный пользователь, компоненты, и тд).

Архитектура

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

Клиенты и Зависимости

Перечислите всех клиентов (принадлежащих другим командам), которые зависят от него и все сервисы (принадлежащие другим командам), от которых он зависит. (Это также можно продемонстрировать в форме системной диаграммы.)

Код и Конфигурация

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

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

Опишите следующее: какие конфигурационные файлы были изменены для этого продукта или сервиса? Как осуществляется настройка?

Процессы

Опишите следующее: Какие демоны и прочие процессы должны быть запущены для работы сервиса? Какие были созданы контрольные скрипты для управления сервисом?

Выходные данные

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

Дашборды и Инструменты

Вставьте ссылки на соответствующие дашборды и инструменты.

Мощность

Укажите мощность единичного инстанса; ЦОДа глобально: QPS, пропускную способность и значения задержки.

SLA

Предоставьте целевые показатели доступности.

Стандартные Процедуры

Добавьте ссылки на процедуры, включая нагрузочное тестирование, обновления/пуши/состояния флагов, и тд. Добавьте ссылки на документацию оповещений в playbook’е оповещений.

Референсы

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

Playbook

Название

В названии укажите имя оповещения (например, ОбычноеОповещение_ОповещениеОченьОбычное).

Обзор

Опишите следующее: Что значит это оповещение? Оно приходит на пейджер или только на почту? Какие факторы вызывают оповещение? Какие части сервиса затронуты? Какие оповещения взаимосвязаны с ним? Кого нужно оповестить?

Уровень Опасности Оповещения

Обоснуйте степень опасности оповещения и влияние затронутых частей на общее состояние сервиса.

Подтверждение

Предоставьте четкие инструкции по проверке и подтверждению актуальности состояния.

Устранение Проблемы

Перечислите и опишите методы отладки и связанные источники информации. Не забудьте про ссылки на соответствующие дашборды. Включите предупреждения. Опишите следующее: Что появится в логах при срабатывании оповещения? Какие есть обработчики отладки? Есть ли полезные скрипты и команды? Какие выходные данные они генерируют? Есть ли дополнительные задачи, которые нужно решить, после устранения оповещения?

Решение

Опишите и перечислите все возможные решения проблемы, вызывающей оповещение. Опишите следующее: Как решить проблему и устранить оповещение? Какие команды запустить, чтобы перезагрузиться? Кого оповестить, если оповещение сработало из-за действий пользователя? У кого есть опыт отладки подобной проблемы?

Эскалация

Перечислите и опишите пути эскалации. Укажите человека или команду, которых нужно оповестить, и когда необходимо это сделать. Если в эскалации нет необходимости — напишите об этом.

Ссылки по Теме

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

Планирование Мощностей

Включая:

• Фактический спрос на сервис, начиная с прошлых 6-8 кварталов, выраженный в наиболее релевантных для сервиса метриках (например, QPS или DAU).
• Прогноз спроса на следующие 8 кварталов.
• План мощностей, удовлетворяющий прогнозируемый спрос на требуемом уровне избыточности — уточните дефицит и/или риски планирования мощностей.

Также рекомендуем добавить прогнозы для 2-4 прошлых кварталов, чтобы читатель мог оценить стабильность и точность прогнозов.

Выполнение SLA / Доступность

Все сервисы, поддерживаемые SRE, должны иметь письменное SLA, по которому каждый квартал оценивается эффективность работы.

Раздел SLA должен содержать параметры основных компонентов сервиса для измерения ежеквартальной выполнимости условий SLA, а также ссылку на письменное SLA команды.

Сопутствующие Инциденты (Опционально)

Перечислите 3-5 главных инцидента или сбоя за квартал.

Достижения (Опционально)

Перечислите главные достижения за квартал.

Изменения SLA (Желательно)

Последние изменения в SLA.

Детали сервиса (Желательно)

Раздел может включать в себя рост, статистику задержек, и тд.

Информация о Команде (Опционально)

Может включать информацию о составе команды, статусах, проектах, статистике смен.

Источники Данных (Обязательно)

Опишите источники, используемые для получения значений доступности, методы вычисления, укажите ссылки на соответствующие дашборды.

Устав Команды

Кто Мы

В одно предложение (~1 строка) опишите технологическую среду, клиентов и предложения команды, а также степень SRE вовлеченности и особую экспертизу.

Поддерживаемые Сервисы

Для дополнительного уточнения объема работ опишите сервисы (или их группу), которые поддерживает команда.

Как Мы Распределяем Время

Определение объема работ помогает в создании дорожной карты и достижении и поддержке целей в долгосрочной перспективе.

Ценности Команды

Четко опишите ценности. Это влияет на манеру взаимодействия членов команды друг с другом, и то, как ваша команда воспринимается другими.

Заключение

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

Таким образом мы опубликовали заключительную часть данной статьи, первую ^[2] и вторую ^[3] части можно прочитать кликнув по гиперссылкам, а получить еще больше полезной информации вы сможете на нашем открытом уроке ^[4], который пройдет уже 19 февраля. Ждём всех!

Автор: MaxRokatansky

Источник ^[5]