Перейти до вмісту
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-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, без жодної зміни наміру розробника.

Створення прикладу

Цей приклад можна зібрати командами нижче або доручити збирання вашому ШІ-асистенту.

Запишіть приклад у нову теку, названу за ним:

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

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