Держите сетевые схемы в актуальном состоянии после каждого релиза

Почему сетевые схемы так быстро устаревают

Большинство сетевых схем изначально верны. Потом происходит несколько обычных релизов, и картинка больше не совпадает с системой.

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

Так начинается дрейф. Обычно он не возникает из‑за одного большого редизайна. Он появляется после десяти обычных pull request'ов, каждый из которых меняет одно подключение, один порт, одну зависимость или одно правило окружения.

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

Цена проявляется при отладке. Срабатывает алерт, падает трафик, и команда открывает диаграмму, которая всё ещё показывает старый маршрут. Сначала люди задают неправильные вопросы. Они проверяют балансировщик нагрузки, который больше не обслуживает этот маршрут, или пропускают новый слой кеша, который начал падать после последнего деплоя.

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

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

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

Иногда это одна новая коробка, одна удалённая стрелка или одна заметка о пути трафика. Грубая диаграмма, соответствующая реальности, гораздо полезнее идеальной, которой два месяца.

Что заслуживает обновления диаграммы

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

Крупные изменения очевидны. Разделение монолита, добавление новой базы данных, переход с одного региона на два или установка gateway перед внутренними сервисами — всё это меняет форму системы. И картинка должна поменяться тоже.

Маленькие правки тоже важны. Перемещение сервиса в другую подсеть, добавление исходящего вызова к стороннему API, изменение порта, влияющего на правила файрвола, или размещение кеша между приложением и базой — в pull request это может выглядеть мелким. Во время инцидента эти детали быстро перестают быть мелкими.

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

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

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

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

Что должна содержать лёгкая диаграмма

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

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

На практике это значит показывать точки входа — DNS, CDN, балансировщик или API‑шлюз; сервисы, обрабатывающие запрос; базы данных, очереди, кеши или объектное хранилище, от которых зависят эти сервисы; и любые сторонние системы, которые команда должна проверять при инциденте. Если владение распределено между командами, добавьте короткую метку владельца.

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

Сфокусируйтесь на системах, к которым люди действительно обращаются во время инцидентов. Это часто означает многое исключить. Вам не нужны каждая внутренняя библиотека, каждый background job или каждая переменная окружения. Если никто не проверяет это в 2:00, когда растёт количество ошибок, это, вероятно, не нужно в релизном виде.

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

Здесь простота лучше полировки. Чем легче править диаграмму, тем больше вероятность, что команда будет поддерживать её после каждого релиза.

Привязывайте диаграммы к pull request'ам

Относитесь к диаграмме как к коду. Если релиз меняет, как двигаются запросы, какой сервис с какой базой общается или где появляется новая зависимость, pull request должен нести и это изменение. Это самый простой способ остановить дрейф диаграмм без создания второй работы для команды.

Небольшое изменение шаблона pull request обычно достаточно. Добавьте короткий подсказ, который заставит автора остановиться и проверить систему, а не только код:

• Изменило ли это изменение поток трафика, границы сервисов, порты, очереди или внешние зависимости?
• Если да — обновили ли вы диаграмму в этой ветке?
• Если нет — почему текущая диаграмма всё ещё соответствует продакшену?

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

Держите визуал в той же ветке, что и код. Одна ветка, один обзор, один merge. Если код попадает в продакшен во вторник, а обновление диаграммы «позже», оно обычно так и не попадает. Отдельная задача в бэклоге выглядит аккуратно, но ломает привычку и оставляет рецензентов в догадках.

Рецензенты должны проверять диаграмму так же, как они проверяют тесты. Им не нужно инспектировать каждую коробку и линию. Им нужно ответить на один вопрос: соответствует ли эта картинка реальности после merge? Если ответ неясен, pull request не готов.

Короткая пометка от рецензента тоже помогает. Что‑нибудь вроде «диаграмма соответствует новому пути воркера» — достаточно. Это создаёт цепочку, к которой можно обратиться позже, чтобы понять, когда форма системы изменилась.

Со временем это убирает обычную отговорку, что диаграммы всегда старые. Они перестают быть побочными документами и становятся частью самого релиза.

Как инциденты должны возвращать изменения в диаграмму

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

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

Этот эскиз должен отмечать три вещи: путь, который упал, запасной путь и фикc, который изменил поведение. Держите это просто.

Хороший эскиз инцидента объясняет проблему быстрее, чем длинная запись инцидента. Например, он может показать, что запросы доходят до основного API и затем застревают на узле Redis во время деплоя. Или что приложение должно было читать с реплики, но маршрут в продакшен‑конфиге отсутствовал.

Превратите эскиз в новую базовую диаграмму

После релиза исправления не оставляйте этот эскиз в заброшенной папке с инцидентами. Обновите основную диаграмму так, чтобы она отражала систему, которая существует сейчас. Если вы добавили очередь, изменили health check или убрали прямую зависимость, основная диаграмма должна это показать до следующего релиза.

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

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

Команды, которые так делают, создают диаграммы, которым доверяют. При следующем аутейдже инженеры не тратят двадцать минут на споры о том, идёт ли трафик через сервис A или B. Ответ уже на странице.

Простой пример из обычного релиза

Команда держит веб‑приложение, которое хранит загрузки пользователей в PostgreSQL и обрабатывает запросы через один API. В одном релизе они добавляют фонового воркера, который создаёт миниатюры после каждой загрузки. Изменение кода кажется мелким. Системное изменение — нет.

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

Pull request не требует гигантской диаграммы. Достаточно одного небольшого системного вида. До изменения вид был browser -> API -> database. После — команда обновляет тот же вид, добавив два новых пути: API -> queue и worker -> database.

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

Это маленькое изменение быстро окупается. Во время недели релизов команда видит рост подключений к базе и тревогу по глубине очереди. Без диаграммы люди могли бы начать искать проблему в API, потому что это часть, которую они знают лучше всего. С обновлённой картинкой воркер уже на странице, и его проверяют сразу.

Через пару недель ошибка в конфигурации режет лимит подключений воркера к базе. Задачи накапливаются. Пользователи всё ещё могут загружать изображения, но генерация миниатюр замедляется и служба поддержки получает жалобы. При разборе инцидента команда открывает ту же диаграмму из pull request'а и прослеживает путь за пару минут.

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

Вот как выглядит поддержка диаграмм в реальной жизни. Команды не перерисовывают всю систему после каждого релиза. Они делают одну небольшую правку, когда изменение свежее, а затем повторно используют тот же визуал при возникновении проблем.

Ошибки, которые делают команды

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

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

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

Команды также рисуют слишком много. Они пытаются замапить каждый сервер, каждый порт и каждый кабель, а затем перестают обновлять диаграмму, потому что задача слишком большая. Хорошая релизная диаграмма остаётся маленькой. Она показывает, что изменилось, что от этого зависит и где может распространиться отказ.

Это часто встречается в небольших командах, которые быстро движутся. Кто‑то добавляет фонового воркера, меняет одну очередь на другую или ставит Cloudflare перед сервисом. Код проходит тщательное ревью, но картинка всё ещё показывает прошлую схему.

Самая дорогая ошибка — культурная. Рецензенты одобряют pull request'ы, даже когда визуал отстаёт. Это говорит всем, что диаграмма необязательна, и она отстаёт ещё больше с каждым релизом.

Проблему можно заметить рано. Люди говорят, что последняя диаграмма "где‑то", вместо того чтобы назвать файл. Команда планирует перерисовать всё позже. Правка диаграммы занимает больше времени, чем ревью pull request'а. Инженеры доверяют чьей‑то памяти больше, чем общей визуальной схеме.

Если pull request меняет поток трафика, зависимости, точки входа или пути отказа, диаграмма должна измениться в этом обзоре. Если нет — merge должен подождать.

Это правило кажется строгим неделю или две. После первого неудачного релиза или инцидента оно кажется нормой.

Быстрая проверка перед merge

Прямо перед merge откройте диаграмму, относящуюся к изменению, и посмотрите на неё так, будто видите ветку впервые. Если картинка объясняет систему примерно за две минуты — вы близки. Если нужен долгий устный рассказ — она не готова.

Короткая проверка ловит большинство проблем:

• Новый инженер должен увидеть путь запроса, сервис, который теперь отвечает за работу, и любое хранилище, очередь или внешний API посередине.
• Диаграмма должна показывать и то, что вы добавили, и то, что удалили. Команды часто рисуют новую зависимость, но оставляют старую стрелку.
• Ответственный на дежурстве должен уметь проследить пути отказа, увидеть, где происходят ретраи, и знать, какая новая зависимость может сломать поток.
• Файл должен жить рядом с кодом, заметками к pull request или релизными заметками. Если его нужно искать, обновления прекратятся.

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

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

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

Что сделать дальше

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

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

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

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

Потом добавьте одну привычку в разбор инцидентов. Когда команда находит пропавшую зависимость, скрытую очередь или правило прокси, которое замедлило отклик, внесите это изменение в диаграмму прежде, чем закрыть инцидент. Так эскизы инцидентов перестанут быть декоративными и станут полезными.

Если вы руководите небольшой командой, сделайте 30‑дневный эксперимент. Используйте один сервис, один файл диаграммы и одно правило в pull request. В конце месяца проверьте, стали ли обзоры проще и тратит ли on‑call инженеры меньше времени на догадки. Это лучшее испытание, чем обсуждать процесс на совещании.

Если вам нужна помощь настроить это без тяжёлого процесса, Oleg Sotnikov на oleg.is работает со стартапами и небольшими компаниями как fractional CTO и советник. Он помогает командам наладить рабочие процессы релизов и технические операции так, чтобы люди действительно ими пользовались.