Скриншоты предоставить не могу по причине NDA.
Контекст
Я занимаюсь разработкой внутренней платформы на основе Kubernetes для автоматизации процессов разработки и удобного и быстрого вывода новых сервисов в production. Была проблема, что БД под приложения настраивали руками, из-за этого могли забыть что-то сделать или сделать не так, как обычно (в зависимости от исполнителя), неправильно настроить учётки и права в БД, что выяснялось уже после запуска приложений.
Цель
Для подготовки окружений нужно было написать модуль terraform, который должен автоматизировать этот процесс, чтобы уменьшить количество ошибок, связанных с человеческим фактором.
Подготовка к составлению описания
Пошёл по шагам подготовки к составлению описания (модели) из раздела.
Определите предметные роли для всех ситуационных ролей (кто заказчики и адресаты описания, автор – это вы). Определите их интересы.
Заказчик описания я в роли инженер по автоматизации рабочих процессов/DevOps-инжерер/Platform Engineer, цель/интерес - передать сотрудникам метод подготовки новых окружений для приложений, чтобы они могли это делать самостоятельно без привлечения меня. Адресаты описания - сотрудники в роли Service Provisioner (предложил ChatGPT по F.18): дежурные по разворачиванию приложений, SRE и другие роли в роли Service Provisioner.
Определите основные объекты описания. По ним определите уровень абстракции требуемого описания (индивиды, узкие классы, широкие классы).
Речь идёт не о любых возможных приложениях, а о разрабатываемых в компании - то есть будет описание в узких классах.
Определите вид описания: будет ли оно использовано только для чтения или это шаблон (форма) для заполнения.
Вид описания: шаблон, т.к. подразумевается использование модуля для описания окружений разных приложений - фактически пользователи заполняют этот шаблон значениями переменных.
Выберите модальность описания, определите формат (форматы) и язык описания, выберите инструментарий – моделер или несколько моделеров для разных частей описания.
Язык описания выбран русский, IT-матерный, языки предметных областей DevOps и System Administration. Основная модальность текстовая, т.к. код является разновидностью текста. Дополнительно пригодится табличная для документации модуля с помощью инструмента terraform-docs и диаграммная для представления схем объектов и их связей.
Формат - язык Terraform как подмножество HCL (HashiCorp Configuration Language). Соответственно, инструменты для работы с ним:
- текстовый редактор типа VS Code для написания этого кода и чтения людьми
- terraform для чтения и обработки/исполнения этого кода
- mermaid.js/PlantUML для рисования диаграмм из кода (текстового описания)
Узнайте, как называются такие описания в выбранной предметной области.
Создавался модуль terraform - это название описания из предметной области DevOps.
Дайте описанию название,
terraform-модуль для настройки окружения приложения
Определите детальность описания, зафиксируйте число уровней детализации и определите объекты для всех нужных уровней.
Приведу пример уровней детализации и объектов на этих уровнях:
-
Общая конфигурация окружения для разворачивания приложений
- хранилище секретов
- реестр образов контейнеров приложений
- метод аутентификации приложений в хранилище секретов
- общие политики доступа к секретам
- сервера СУБД для приложений
- подсети для размещения СУБД, приложений, средств автоматизации
- GitLab-раннеры для запуска terraform (или это даже на уровне контура, но нам сейчас так высоко наверх не нужно подниматься)
- конфигурация окружения приложения
- БД приложения
- схема миграций приложения
- учётка миграций приложения (часть СУБД, а не БД)
- R/W роль (часть СУБД, а не БД)
- R/O роль (часть СУБД, а не БД)
- учётка приложения (часть СУБД, а не БД)
- привилегии учёток
- проект в Sentry
- секреты приложения в хранилище секретов
- секреты миграций приложения в хранилище секретов
- хранилище образов контейнеров приложения в реестре
- сервисная учётка в хранилище
- БД приложения
- GitOps-конфиги приложения для деплоя в окружение
Выше и ниже есть ещё уровни, которые в данном контексте не важны.
Выберите или разработайте мета-С онтологию в объёме необходимых для описания объектов классификаторов и справочников.
Выделил несколько классификаторов:
| Объект | Классификатор | Классы |
|---|---|---|
| Программный компонент разрабатываемый в компании | Тип компонента | Приложение, Библиотека |
| Приложение | Тип приложения | HTTP-серевер, GRPC-сервер, TCP-сервер, Celery-воркер, Kafka-воркер |
| Приложение | Окружение | dev, test, prod |
| Зависимость/ресурс приложения | Тип зависимости | БД приложения, Очередь в Redis, Пара ключей шифрования для подписи запросов |
Определите, как вы будете именовать объекты.
Имена многих объектов формируются из названия экземпляра приложения в окружении по определённым правилам.
Определите, какие признаки и свойства объектов вам необходимо указать в описании.
Дополнительно для приложения нужно будет указывать как минимум команду-владельца.
Впечатления о проделанной работе
Это описание я составлял до начала прохождения программы “Рабочее развитие”, руководств до этого не читал. Пока не могу сказать, что после прочтения как-то по-другому составлял бы это описание.
Могу отметить, что само описание (описание метода) в виде модуля terraform не особо ценно для адресата, если он не сможет его использовать для выполнения работ - разве что поможет понять связь объектов между собой. Поэтому пришлось дополнительно создать/доработать систему, позволяющую работать с этим модулем. В процессе я составил ещё несколько описаний для согласования деталей реализации этой системы, постановки задач, объяснения, как пользоваться новым модулем/шаблоном, как пользоваться системой.
Временные затраты
Время на подготовку описания в часах уже не посчитаю, но в трекере задач от начала задачи до конца прошло 4-5 недель.