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

Такие схемы полезны всем. Инженеры используют их для быстрой диагностики, стажеры — при онбординге, менеджеры — для согласования изменений, а клиенты — чтобы лучше понять архитектуру.

Какие бывают схемы

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

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

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



Другой тип — схема сети, но в нашем случае это не совсем классическая сетевая схема. Обычно такие схемы отражают взаимодействия на втором и третьем уровнях модели OSI: VLAN’ы, маршрутизация, ARP, таблицы коммутаторов. Мы адаптировали подход: в нашей схеме сети мы показываем, как именно общаются между собой сервисы и серверы — через какие IP-адреса, порты и протоколы. Такая схема может затрагивать сразу несколько уровней OSI — от сетевого до прикладного и позволяет понять, какой сервис что слушает, куда ходит и где может возникнуть проблема при сбоях или при настройке доступа.



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



Конечно, этим список схем не ограничивается. В нашей практике используются и другие типы: схемы проксирования, CI/CD, Kubernetes, потоков данных, а также схемы расположения VM. Почти каждая из них заслуживают отдельного разбора — и мы обязательно расскажем о них подробнее в следующих статьях.

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

Чем больше схем мы составляли, тем яснее становилось: это не просто иллюстрации, а полноценный рабочий инструмент, к которому предъявляются определенные требования. Схема должна быть одновременно информативной и понятной, передавать всё, что важно, но при этом не перегружать деталями. Быстро читаться, быть единообразной и помогать ориентироваться в проекте. Особенно это критично в нашем случае, когда инженеры регулярно переключаются между проектами и должны быстро «въехать» в новую инфраструктуру.

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

Трудности при создании схем

Типичное начало работы над новой схемой

Ниже мы собрали основные трудности, с которыми сталкивается наша команда при работе со схемами — от сбора информации до выбора уровня детализации.

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

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

Другая частая трудность — визуальная перегруженность, которая возникает когда на схеме нужно отразить множество взаимодействий: между серверами, сервисами, базами данных, внешними системами. Это может быть заметно в проектах, где система разбита на несколько контуров.



Под контурами мы понимаем обособленный набор компонентов — веб-сервисы, балансеры, СУБД, системы очередей и другие элементы, которые вместе обеспечивают работу конкретного сайта или приложения. В контур может входить как один, так и несколько серверов. Иногда контуры разделяют по функционалу (например, личный кабинет и мобильный сайт), а иногда по средам: prod, stage, test, dev.

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

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

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

Эти сложности становятся особенно заметны, когда к нам в команду приходит новый человек. Объяснить ему «как правильно» — непросто, потому что в одном случае «правильно» значит строго по правилам из стайлгайда, в другом — опираясь на правила, но «по-своему». Поэтому обычно мы учим не только следовать формату, но и понимать, зачем схема устроена именно так, то есть передаем логику решений, а не только формальности.

Отдельная группа трудностей при создании схем связана не с информацией или структурой схем, а с инструментами, которыми мы пользуемся. Для своей работы мы используем один и тот же редактор схем — он давно стал для нас стандартом. Мы настроили под себя библиотеки, адаптировали процесс создания схем. Это удобно, экономит время и снижает порог входа для новых сотрудников.

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

Поэтому мы стараемся заранее выяснять, с какими инструментами работает клиент, и если нужно, то сразу строим схему в удобном ему редакторе. Это не всегда удобно для нас, но важно для клиента — и мы это учитываем.

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

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

Из-за этого нам важно соблюдать баланс между детализацией и краткостью.


Избыточная детализация — не всегда хорошо

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

Одним из наглядных примеров сложности актуализации являются схемы с Kubernetes. Это одна из тех частей инфраструктуры, которая может меняться достаточно быстро. Поэтому бывает довольно сложно определить, насколько подробно описывать кластер Kubernetes на схеме. Для каждого проекта мы стараемся выбрать уровень детализации, который наиболее точно отражает его специфику. Иногда достаточно просто обозначить на схеме наличие кластера и входящих в него нод. В других случаях важно дополнительно указать ингресы и неймспейсы, которые присутствуют в кластере. В некоторых проектах требуется продемонстрировать сервисы, а в ряде проектов — даже отдельные поды.

Мы пробовали использовать инструменты, которые автоматически строят схему на основе манифестов Kubernetes. Но в нашем случае результат получался слишком перегруженным: такие схемы были избыточно детализированы и трудны для восприятия.

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

Заключение

Работа со схемами кажется простой ровно до того момента, пока не начинаешь делать их системно и для десятков разных проектов. Мы столкнулись с множеством нюансов — и в этой статье постарались честно рассказать, как с ними работаем.

Мы уже унифицировали ключевые типы схем (репликация, сеть, резервирование, проксирование и др.), определили их структуру, уровень детализации и визуальные обозначения, а также оформили эти принципы в стайлгайде. Сейчас продолжаем развивать правила для более сложных случаев — например, схем с Kubernetes и схем, описывающих гибридную инфраструктуру с сочетанием managed-сервисов, on-prem решений и арендуемых у сторонних провайдеров серверов. Мы собираем такие нестандартные случаи, обсуждаем их в команде и при необходимости дополняем или адаптируем внутренние правила.

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

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