Документация

Архитектура проекта

Как устроена система: от периметра до наблюдения. Простая схема, которую легко описать, проверить и поддерживать.

Иллюстрация: сеть узлов, связанных каналами.
Иллюстрация: сеть узлов, связанных каналами.

Слои системы

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

КлиентПериметрМаршрутизацияБалансировкаСервисы браузер, VPNTLS · фильтрацияBGP · DNSпроверка узловприложения Независимый мониторинг проверки с внешних точек · оповещения
СлойНазначениеЧто документируем
ПериметрПриём подключений, TLS, базовая фильтрацияОткрытые порты, сертификаты, правила доступа
Маршрутизация и DNSДоставка трафика и разрешение имёнЗоны, записи, маршруты, TTL
БалансировкаРаспределение запросов между узламиПроверки здоровья, алгоритм, порядок вывода узла
СервисыПриложения, которыми пользуются клиентыВерсии, зависимости, конфигурация
НаблюдениеМетрики, проверки, оповещенияЧто измеряется, пороги, кто получает уведомления
Схема: путь запроса при разрешении имени.
Схема: путь запроса при разрешении имени.
Иллюстрация: ряды серверных стоек в машинном зале.
Иллюстрация: ряды серверных стоек в машинном зале.

Принципы проектирования

  • Минимум связей. Чем меньше зависимостей между компонентами, тем проще изолировать сбой.
  • Сегментация. Административные интерфейсы и рабочие сервисы разделены сетями и правилами доступа.
  • Конфигурация как код. Настройки хранятся в репозитории, изменения проходят просмотр и оставляют след в истории.
  • Независимое наблюдение. Проверки выполняются снаружи, чтобы сбой сети не скрыл сам себя.

Что должно быть описано

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

Компонент:    DNS-резолвер
Назначение:   разрешение внутренних и внешних имён
Владелец:     [ответственный]
Зависимости:  сеть управления, NTP
Порты:        53/udp, 53/tcp (только из внутренней сети)
Проверка:     dig @127.0.0.1 example.org +short
Восстановление: см. «Эксплуатация и обновления»
Совет. Если карточку невозможно заполнить без догадок, это сигнал: компонент недостаточно изучен или его роль не определена.