Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

Сетевое взаимодействие через границы — одно намерение, два развёртывания

Стек из двух компонентов — веб-интерфейс базы данных 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, без каких-либо изменений в намерении разработчика.

Создание примера

Этот пример можно собрать командами ниже или поручить сборку вашему ИИ-ассистенту.

Запишите пример в новую папку, названную по его имени:

Terminal window
aggrega scaffold --example cross-boundary-networking

Затем она выводит команды, которые нужно выполнить дальше. Первая переходит в новую папку:

Terminal window
cd cross-boundary-networking

Сборка

Каждый вариант — это одна сущность Release, собираемая с собственной папкой каталога, одна сущность Release за запуск:

Terminal window
aggrega pull --release release-compose.yaml --catalog catalog-compose
aggrega build --release release-compose.yaml --catalog catalog-compose
aggrega pull --release release-helm.yaml --catalog catalog-helm
aggrega 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): мост

Terminal window
aggrega pull --release release-compose.yaml --catalog catalog-compose
aggrega 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 записывает конфигурацию nginx stream шлюза, которая передаётся как смонтированный 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, пересекая границу сетей через шлюз.

Запуск

Terminal window
cd dist/bridge/compose
docker compose up

Откройте http://localhost:8080 (сервер заранее заполнен: aggrega-gw:5432) и войдите:

ПолеЗначение
СистемаPostgreSQL
Серверaggrega-gw:5432 (заполнено заранее)
Имя пользователяappuser
Парольapppass
База данныхappdb

Учётные данные предназначены только для демонстрации (заданы прямо в рецепте db, чтобы стек запускался без дополнительной настройки); в реальном развёртывании используется подсистема учётных данных.

Вариант B — Kubernetes (Helm): пространства имён + межпространственный DNS

Terminal window
aggrega pull --release release-helm.yaml --catalog catalog-helm
aggrega build --release release-helm.yaml --catalog catalog-helm

Тот же Aggregate, развёрнутый в Kubernetes. Две соседние границы, каждая со своей аннотацией aggrega.ai/namespace, которая каскадно распространяется на каждый ресурс как metadata.namespace:

dist/frontend/helm/adminer-deployment.yaml # metadata.namespace: frontend
dist/frontend/helm/adminer-default-service.yaml # metadata.namespace: frontend
dist/backend/helm/db-statefulset.yaml # metadata.namespace: backend
dist/backend/helm/db-default-service.yaml # metadata.namespace: backend
dist/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. Хост выводится, а не прописывается вручную в производителе:

dist/frontend/helm/adminer-deployment.yaml
- 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.