Найти тему
ITSumma

Что обязательно должно быть в инфраструктурной документации?

Оглавление

У всех проектов инфраструктуры уникальны.

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

Инвентори — полный список ресурсов

  • виртуальные и железные серверы
  • облачные ресурсы и сервисы
  • количество CPU
  • размер RAM и ROM
  • способы доступа к тому или иному ресурсу, если они имеют какие-то
  • особенности расположение ресурсов проекта — в каких датацентрах, у каких хостеров или на каких железных серверах они находятся
Инвентори — самая важная часть инфраструктурной документации. Так что если ресурсов на технописательство немного, то это первое и основное, что требуется создать.

Деление на контуры, среды, продукты или подпроекты

Prod — боевой контур, который выполняет основную работу; на него ложится основная нагрузка. Для обеспечения отказоустойчивости используется контур reserve.

Dev-контур — для разработки, test- и stage-контуры — для тестирования, infra-контур — для обеспечения мониторинга и логирования основных ресурсов и т.д.

Такая дифференциация поможет быстрее понять взаимосвязи сервисов.

Шаблоны

Следующий шаг — понять, к какому типу инфраструктуры относится каждый контур. Например: LAMP-стек, Kubernetes, облачные инфраструктуры. В зависимости от этого создаются шаблоны для описания контура.

В шаблонах описываются клиентские сервисы и приложения — и схемы их взаимодействия. Также подробно описываются базы данных: перечень баз и используемых СУБД, настроены ли репликации и куда/откуда, есть ли исключения для баз или таблиц.

Описание системы резервирования и схема того, что и как зарезервировано

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

Если в проекте есть IaC, то нужно рассказать как оно работает: указать, какая часть инфраструктуры описана в коде, а какая нет, добавить флоу и правила работы. Также резон указать схему деплоя, добавить описание CI/CD и существующей автоматизации.

Общая схема инфраструктуры

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

На этом первичное общее описание проекта закончено. Далее в документацию к каждому проекту добавляются свои уникальные инструкции, регламенты и другие дополнения.

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