У всех проектов инфраструктуры уникальны.
Поэтому очень сложно создать универсальный шаблон технической документации. Но мы выделили несколько элементов, которые обязательно должны войти в “техническую летопись” проекта.
Инвентори — полный список ресурсов
- виртуальные и железные серверы
- облачные ресурсы и сервисы
- количество CPU
- размер RAM и ROM
- способы доступа к тому или иному ресурсу, если они имеют какие-то
- особенности расположение ресурсов проекта — в каких датацентрах, у каких хостеров или на каких железных серверах они находятся
Инвентори — самая важная часть инфраструктурной документации. Так что если ресурсов на технописательство немного, то это первое и основное, что требуется создать.
Деление на контуры, среды, продукты или подпроекты
Prod — боевой контур, который выполняет основную работу; на него ложится основная нагрузка. Для обеспечения отказоустойчивости используется контур reserve.
Dev-контур — для разработки, test- и stage-контуры — для тестирования, infra-контур — для обеспечения мониторинга и логирования основных ресурсов и т.д.
Такая дифференциация поможет быстрее понять взаимосвязи сервисов.
Шаблоны
Следующий шаг — понять, к какому типу инфраструктуры относится каждый контур. Например: LAMP-стек, Kubernetes, облачные инфраструктуры. В зависимости от этого создаются шаблоны для описания контура.
В шаблонах описываются клиентские сервисы и приложения — и схемы их взаимодействия. Также подробно описываются базы данных: перечень баз и используемых СУБД, настроены ли репликации и куда/откуда, есть ли исключения для баз или таблиц.
Описание системы резервирования и схема того, что и как зарезервировано
Для резервного контура нужно добавить инструкцию по переключению, чтобы оно происходило быстро и четко.
Если в проекте есть IaC, то нужно рассказать как оно работает: указать, какая часть инфраструктуры описана в коде, а какая нет, добавить флоу и правила работы. Также резон указать схему деплоя, добавить описание CI/CD и существующей автоматизации.
Общая схема инфраструктуры
Здесь указываются все серверы и работающие на них сервисы, точки входа трафика, проксирования, репликации и синхронизации, а также любые другие взаимосвязи сервисов или контуров.
На этом первичное общее описание проекта закончено. Далее в документацию к каждому проекту добавляются свои уникальные инструкции, регламенты и другие дополнения.
Подробнее о том, что должно быть и чем полезна техническая документация веб-сервиса читайте тут.