Мережева взаємодія через межі — один намір, два розгортання
Стек із двох компонентів — інтерфейс бази даних 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-bridge — це те, що простори імен 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 |
Облікові дані — лише для демонстрації (задані безпосередньо в recipe 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, спільний компонент інтерфейсу 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.