Сетевое взаимодействие через границы — одно намерение, два развёртывания
Стек из двух компонентов — веб-интерфейс базы данных Adminer и база данных PostgreSQL — разделён на две границы, и Adminer должен обращаться к базе данных через шов между границами. Одно и то же намерение разработчика развёртывается двумя способами, и именно контраст между ними и есть урок:
- Локально (Docker Compose): каждая граница — это отдельная сеть compose, и сервис в одной из них не может обратиться к сервису в другой по имени. FeatureRecipe для compose у сущности Feature
core/compose-bridgeиз стандартной библиотеки генерирует шлюзaggrega-gw, чтобы преодолеть этот шов. - Kubernetes (Helm): каждая граница — это отдельное пространство имён, и под в
одном из них обращается к Service в другом через встроенный межпространственный DNS
(
db-default.backend) — без моста. База данных публикует простое имя сервиса; маршрутизирующая функция потребителяcore/k8s-dns-resolverдополняет его целевым пространством имён.
Мост compose — это то, что пространства имён Kubernetes и межпространственный DNS дают вам
изначально. Преодоление шва — это задача Ops/Operator, которая зависит от целевой платформы;
намерение разработчика не меняется. Одна и та же аннотация границы aggrega.ai/namespace
управляет размещением по сетям compose в одном варианте и размещением по пространствам имён
Kubernetes в другом.
Общее намерение разработчика
aggregate.yaml одинаков для обоих вариантов:
components: adminer: type: core/devtool/adminer uses: databases: primary: target: db inject: env: - in: ADMINER_DEFAULT_SERVER # rewritten/resolved per variant from: host # ← the target db's provides.host db: type: core/datastore/postgresЕдинственное ребро uses внедряет host базы данных в ADMINER_DEFAULT_SERVER.
То, во что разрешается этот хост, — задача Ops, решаемая ниже уровня сущности Aggregate, поэтому
одно и то же ребро даёт aggrega-gw:5432 в compose и db-default.backend
в helm, без каких-либо изменений в намерении разработчика.
Создание примера
Этот пример можно собрать командами ниже или поручить сборку вашему ИИ-ассистенту.
Запишите пример в новую папку, названную по его имени:
aggrega scaffold --example cross-boundary-networkingЗатем она выводит команды, которые нужно выполнить дальше. Первая переходит в новую папку:
cd cross-boundary-networkingСборка
Каждый вариант — это одна сущность Release, собираемая с собственной папкой каталога, одна сущность Release за запуск:
aggrega pull --release release-compose.yaml --catalog catalog-composeaggrega build --release release-compose.yaml --catalog catalog-composeaggrega pull --release release-helm.yaml --catalog catalog-helmaggrega build --release release-helm.yaml --catalog catalog-helmС ИИ-ассистентом
ИИ-ассистент, настроенный с инструментами Aggrega, может сделать то же самое: вставьте в него этот промпт.
Используйте только инструменты Aggrega и не создавайте папки самостоятельно. Если в папке рабочей области ещё нет папки `cross-boundary-networking`, вызовите инструмент `scaffold` один раз, задав `example` равным `cross-boundary-networking` и не указывая `dir`: он запишет пример в новую папку `cross-boundary-networking`. Затем вызовите инструмент `build`, задав `workspace_root` равным `cross-boundary-networking`, `release` равным `release-compose.yaml`, `catalog_dirs` равным списку, содержащему `catalog-compose`, `auto_pull` равным true и `write` равным true. Затем так же вызовите инструмент `build`, задав `release` равным `release-helm.yaml` и `catalog_dirs` равным списку, содержащему `catalog-helm`. Сообщите мне, какие файлы записала каждая сборка; они находятся в `cross-boundary-networking/dist/`.Вариант A — локальный (Docker Compose): мост
aggrega pull --release release-compose.yaml --catalog catalog-composeaggrega build --release release-compose.yaml --catalog catalog-composeРодительская граница bridge содержит две дочерние, frontend (adminer) и backend (db), которые используют один каталог и потому сливаются в единый dist/bridge/compose/docker-compose.yaml. Аннотация aggrega.ai/namespace каждой дочерней границы становится сетью compose. core/compose-bridge, подключённый к родительской границе (на уровне границы), выводит шлюз aggrega-gw из межсетевого ребра uses. Его FeatureRecipe из стандартной библиотеки один раз для границы вычисляет таблицу рёбер, которые нужно соединить мостом, — оба конца в этом одном файле compose, в разных сетях, — и всё, что описано ниже, его собственные шаблоны читают из этой таблицы:
- его
valuesMappingзаписывает конфигурацию nginxstreamшлюза, которая передаётся как смонтированный config compose (верхнеуровневыйconfigs:, смонтированный в/etc/nginx/nginx.conf); она содержитresolverи переменнуюproxy_passдля каждого ребра, чтобы upstream разрешался в момент соединения ($экранируется как$$, чтобы интерполяция Compose оставила его нетронутым для nginx); - тот же
valuesMappingназывает оба конца вx-aggrega-networks-ofшлюза, которое разрешает провайдер compose, поэтому шлюз подключается к обеим соединяемым сетям; - его
injectMapping, выполняемый для adminer, перезаписываетADMINER_DEFAULT_SERVERпотребителя наaggrega-gw:5432. Перезапись заменяет то, что передало собственное соединениеdatabasesсервиса adminer; если бы эту переменную передала другая сущность Feature, подключённая к adminer, сборка остановилась бы с указанием обеих, а не заменила бы её.
Таким образом, трафик идёт по пути adminer → aggrega-gw:5432 → proxy_pass db:5432, пересекая
границу сетей через шлюз.
Запуск
cd dist/bridge/composedocker compose upОткройте http://localhost:8080 (сервер заранее заполнен: aggrega-gw:5432) и войдите:
| Поле | Значение |
|---|---|
| Система | PostgreSQL |
| Сервер | aggrega-gw:5432 (заполнено заранее) |
| Имя пользователя | appuser |
| Пароль | apppass |
| База данных | appdb |
Учётные данные предназначены только для демонстрации (заданы прямо в рецепте db, чтобы стек запускался без дополнительной настройки); в реальном развёртывании используется подсистема учётных данных.
Вариант B — Kubernetes (Helm): пространства имён + межпространственный DNS
aggrega pull --release release-helm.yaml --catalog catalog-helmaggrega build --release release-helm.yaml --catalog catalog-helmТот же Aggregate, развёрнутый в Kubernetes. Две соседние границы, каждая со своей аннотацией aggrega.ai/namespace, которая каскадно распространяется на каждый ресурс как
metadata.namespace:
dist/frontend/helm/adminer-deployment.yaml # metadata.namespace: frontenddist/frontend/helm/adminer-default-service.yaml # metadata.namespace: frontenddist/backend/helm/db-statefulset.yaml # metadata.namespace: backenddist/backend/helm/db-default-service.yaml # metadata.namespace: backenddist/backend/helm/db-headless-service.yaml # metadata.namespace: backendЗдесь нет aggrega-gw. Рецепт helm db публикует голое имя сервиса
в provides.host — провайдер helm называет синтезированный Service
<rendered_name>-<service-key> (db-default), без пространства имён. Потребитель
подключает маршрутизирующую функцию core/k8s-dns-resolver (Release направляет её на
ADMINER_DEFAULT_SERVER), и функция дополняет это голое имя хоста пространством имён
цели на стороне самого потребителя — получая межпространственное DNS-имя
db-default.backend до рендеринга Adminer. Хост выводится, а не
прописывается вручную в производителе:
- name: ADMINER_DEFAULT_SERVER value: db-default.backend # == the rendered db Service <name>.<namespace>Это значение побайтово совпадает с metadata.name +
metadata.namespace отрендеренного Service базы данных, и в этом всё доказательство: межпространственный DNS в Kubernetes —
детерминированный контракт, поэтому если отрендеренный хост равен отрендеренной идентичности
Service, он разрешается во время выполнения — без шлюза и без работающего кластера для проверки
связей.
Двойственность
| compose (вариант A) | helm (вариант B) | |
|---|---|---|
| шов границы | отдельные сети compose | отдельные пространства имён |
| механизм пересечения | шлюз core/compose-bridge (aggrega-gw) | встроенный межпространственный DNS |
ADMINER_DEFAULT_SERVER разрешается в | aggrega-gw:5432 (переписано) | db-default.backend (уточнено на стороне вызывающего) |
| дополнительный ресурс | сервис aggrega-gw и его конфигурация | нет |
одна и та же аннотация aggrega.ai/namespace определяет | размещение в сети compose | размещение в пространстве имён k8s |
Одно намерение разработчика; пересечение шва — это специфичный для провайдера механизм Ops/Operator. Мост compose существует потому, что в плоской сети compose нет DNS с областью видимости пространства имён; Kubernetes даёт вам это изначально.
Когда два конца рендерятся разными провайдерами
Оба варианта выше сохраняют одно намерение разработчика и позволяют пересечению опираться на
детерминированную строку-указатель: provides.host базы данных передаётся через
шов границы как стабильный указатель, и каждая цель разрешает этот указатель по-своему —
как адрес шлюза compose или как DNS-имя между пространствами имён. Указатель
пересекает шов всегда, потому что компилятор передаёт строки между производителем и
потребителем, не интерпретируя их.
Провайдер может пойти дальше и связать нативной перекрёстной ссылкой два своих
собственных собранных артефакта по разные стороны шва — ссылкой в собственном словаре
этого провайдера, которую целевая платформа разрешает во время развёртывания. Провайдер
CloudFormation делает это для ребра uses, пересекающего стеки: стек-производитель
публикует Export, а стек-потребитель читает его через
Fn::ImportValue (см. providers/cloudformation.md).
Нативная перекрёстная ссылка — это улучшение в пределах одного провайдера: она работает, потому что оба
конца говорят на одном словаре артефактов, и одна сторона может опубликовать ссылку, которую
другая умеет разрешить.
Когда ребро uses пересекает границу между двумя разными провайдерами — производитель собирается одним провайдером, а потребитель другим, — нативная перекрёстная ссылка невозможна. Ссылка, созданная в словаре одного провайдера, ничего не значит для другого, и компилятор не переводит между ними: он передаёт строки, не выводит смысл и не переписывает ссылку одного провайдера в форму другого. Поэтому детерминированный указатель производителя пересекает шов без изменений; если любой из двух провайдеров сам связывает нативные перекрёстные ссылки, как это делает CloudFormation, компилятор выдаёт предупреждение с указанием обеих конечных точек, имён обоих провайдеров и сокета; и сборка завершается с этим указателем. Компилятор доверяет автору и не останавливается: детерминированный указатель, заданный автором, вполне может разрешаться через шов — стабильное DNS-имя или строка интерполяции инфраструктуры, — и только автор знает целевую топологию.
Так пересечение шва остаётся там, где ему место. Пригоден ли указатель между провайдерами — вопрос развёртывания, за который отвечает автор; перевод нативной ссылки одного провайдера в форму потребителя другого провайдера — это работа с собственным мнением, специфичная для провайдера, и она находится за пределами нейтрального ядра.
Структура
cross-boundary-networking/├── .aggrega-config.yaml # marks this folder as the workspace root; names the hub registry├── aggregate.yaml # SHARED developer intent (both variants)├── release-compose.yaml # Variant A: parent bridge boundary + two networks├── manifest-compose.yaml├── catalog-compose/ # local adminer compose recipe (the component + the rest from standard)├── release-helm.yaml # Variant B: two namespace boundaries, no bridge├── manifest-helm.yaml└── catalog-helm/ # local adminer helm recipe (the components + the rest from standard)Этот пример использует стандартную библиотеку. Каждый вариант собирается с --catalog catalog-<variant>, собственным локальным каталогом, и разрешает то, чего этот каталог не объявляет, из hub.aggrega.ai — реестра по умолчанию, который указывает .aggrega-config.yaml, — поэтому локальные сущности разрешаются раньше общих. core/datastore/postgres, общий UI-компонент core/devtool/adminer, сущности Features core/compose-bridge и core/k8s-dns-resolver с их сущностями FeatureRecipes для compose и helm, а также провайдеры compose/helm берутся из стандартного каталога. Локальным остаётся учебное содержимое, специфичное для примера: рецепты Adminer для каждой цели. Рецепт helm db — это helm/postgres из стандартной библиотеки, чей provides.host — простое, самодостаточное имя сервиса. Потребитель дополняет его целевым пространством имён на своей стороне с помощью маршрутизирующей функции стандартной библиотеки core/k8s-dns-resolver, поэтому рецепт не задаёт жёстко пространство имён границы.
В собранном варианте встречаются две категории файлов: созданные автором входные данные (всё
перечисленное выше) и сгенерированный компилятором вывод в dist/ (объединённый
docker-compose.yaml или манифесты helm для каждого пространства имён); последние вы
не пишете. dist/ заново генерируется командой aggrega build и указан в .gitignore.