Перейти до вмісту
AggregaAggrega
Обрати мову: Українська
Цю сторінку перекладено машинним способом. Читати оригінал англійською.

Таксономія даних і композиція

Уніфікована таксономія даних і правила композиції

Щоб створити передбачувану схему й усунути когнітивне тертя, платформа використовує рівно п’ять загальнозрозумілих ключових слів і структуру YAML, суворо засновану на мапах (словниках), з мапами, а не вкладеними масивами, у корені структури.

1. Стандарт мап із 5 ключовими словами та повна симетрія схем

Прямий структурний словник: фундаментальне правило проєктування схем полягає в тому, що кореневі структури даних мають бути окремими структурними ключовими словами. Хоча розмовні англійські фрази (як-от depends_on чи runs_within) можуть зробити YAML DSL природнішим для читання розробником, вони додають структурної складності під час відображення цих ключів у програмні шаблони Go. Щоб зберегти пряме відображення змінних 1:1 і запобігти фрагментації предметно-орієнтованої мови (DSL), JSON-схеми основних сутностей каталогу (Component, Feature) мають майже повну структурну симетрію, що спирається на той самий базовий набір структурних ключових слів, який використовується в усіх створених слотах екземплярів. Сутності Features облікових даних (з міткою feature.aggrega.ai/kind: secret) мають ту саму парадигму — окремої схеми для секретів немає.

  • parameters (глобальний контракт середовища)
    • Область: визначаються в корені сутності Aggregate; заповнюються сутністю Release (CI/CD) вбудовано в parameters: або через parameters: { $import: <path> }, що вказує на зовнішній файл параметрів.
    • Значення: зовнішні аргументи, що динамічно змінюють когнітивний або логічний стан застосунку між середовищами (наприклад, зміна workers: 2 на workers: 10). Підтримує типізований контракт (повний синтаксис типізованого контракту див. у data-pillars), що перевіряється перед інтерполяцією. Для робочих процесів GitOps, які зберігають значення параметрів в окремому файлі, сутність Release використовує форму $import:; компілятор завантажує вміст файлу й замінює ним вбудовану мапу parameters:. Багатофайлове нашарування виражається ланцюжками extends: сутності Release.
  • values (когнітивний намір - належить розробнику)
    • Область: використовуються однаково в components та їхніх приєднаннях features у сутності Aggregate, включно із сутностями Features облікових даних.
    • Значення: основний когнітивний стан, бізнес-логіка та операційна конфігурація. Непрозорі для компілятора Go, але суворо перевіряються уніфікованим оголошенням schema: каталогу (компактна форма або JSON Schema 2020-12).
  • uses (структурна топологія - декларативний стан)
    • Область: використовуються однаково в components та їхніх приєднаннях features у сутності Aggregate, включно із сутностями Features облікових даних.
    • Значення: декларативне твердження факту, що визначає мережеві ребра й залежності (наприклад, «Цей агент використовує цю базу даних»). Нативно розбирається компілятором Go для побудови графа проміжного представлення (IR). Перевіряється уніфікованим оголошенням usesSchema каталогу для забезпечення безпеки типів між вузлами.
  • infra (фізична реальність - належить Ops)
    • Область: використовується однаково в components межі та їхніх приєднаннях features у сутності Release.
    • Значення: фізичний слід і механічне визначення розмірів, що впроваджуються під час Late Binding (наприклад, cpu_limit: "4", port: 5432). Екземпляри компонентів сутності Aggregate та їхні приєднання features не містять поля infra і разом з additionalProperties: false відхиляють infra під час валідації схеми. Перевіряється уніфікованим оголошенням schema: каталогу.
  • inject (контракт доставки - імперативна команда)
    • Область: використовується на екземплярі компонента, у явних визначеннях цілей у uses та на приєднаних features, включно із сутностями Features облікових даних.
    • Значення: явна імперативна команда, що задає намір доставки (наприклад, «Компіляторе, впровадь це відображене значення як змінну середовища»). Вона встановлює абстрактний контракт (env, file, arg або власні механізми) для фізичного виходу, розв’язаної кінцевої точки чи отриманих облікових даних, тоді як фізична механіка того, як саме виконується це монтування, повністю делегується базовій Recipe від Ops. Кожен механізм — це список записів ([{ in: API_HOST, from: "host" }]), кожен з яких називає свій локальний ідентифікатор через in: і містить рівно одне з from: або value:.
  • .context (універсальний конвеєр метаданих)
    • Область: непомітно впроваджується компілятором у шаблони сутності Recipe від Ops.
    • Значення: несе те, що компілятор зібрав для вузла з решти графа (як-от .context.uses), і передається безпосередньо до рушія шаблонів Ops.

Реальність відображення 1:1

Заміна розмовних прийменників суворими інфраструктурними ключовими словами дає пряме відображення 1:1. Інженерові Ops не потрібно перекладати граматику; він просто посилається на ті самі ключі, які написав розробник.

Структурні форми: мапи в корені, масиви в корисному навантаженні. Кореневі блоки топології — components, features, aggregates, subsystems, boundaries — це мапи YAML, ключі яких, написані користувачем, слугують стабільними ідентифікаторами екземплярів. Масиви в цих позиціях неприпустимі; ключ мапи — це ідентичність, яку компілятор використовує для перехресних посилань (target: my-db), побудови вузлів графа та розв’язання сутності Manifest. Усередині непрозорих блоків корисного навантаження (values, infra, parameters) масиви повністю дозволені — розробники можуть писати tools_allowed: ["sql", "web"] або hostnames: ["stripe.com", "twilio.com"] у values сутності Component. Схема сутності Aggregate оголошує ці блоки корисного навантаження як additionalProperties: true, тож вони непрозорі для компілятора Go й повністю перевіряються вбудованим оголошенням schema: каталогу. Так мінливість фреймворків (нові форми API штучного інтелекту, нові хмарні формати корисного навантаження) опиняється в домені каталогу, де може розвиватися незалежно, а компілятор Go у структурному корені працює лише з адресовними ключами.

2. Інформаційні потоки: хто, коли й для чого?

Щоб запобігти колізіям просторів імен у шаблонах і ненавмисному просочуванню конфігурацій фізичної інфраструктури в когнітивну логіку застосунку, архітектура явно розділяє дані на шість окремих потоків:

  • Потік 1: ін’єкція середовища (parameters): конвеєр CI/CD впроваджує реалії розгортання. Компілятор перевіряє кожне значення, надане сутністю Release, на відповідність типізованому контракту parameters:, а потім інтерполює розв’язані змінні шаблонів Go до запуску подальшої валідації схеми values:.
    • Рекомендоване використання: parameters призначені для когнітивної логіки застосунку, що відрізняється між середовищами (наприклад, LOG_LEVEL=debug, ENABLE_BETA=true). Операційне визначення розмірів і питання фізичної інфраструктури — репліки, ліміти CPU, ARN AWS, імена хостів ingress — проходять через блок infra сутності Release та накладки меж, завдяки чому сутність Aggregate розробника зосереджена на намірі застосунку.
    • Прагматичний запасний вихід: для менших команд, швидкого прототипування чи застарілих інтеграцій CI/CD, де суворе розділення непрактичне, parameters можуть переносити глобальні конфігурації середовища крізь увесь стек. Компілятор приймає все, що проходить валідацію схеми; рекомендація вище — це суспільний договір, а не правило компілятора.
  • Потік 2: когнітивний намір застосунку (values у сутностях Components): визначає внутрішню логіку застосунку. Оголошення schema: сутності Component (компактна форма або JSON Schema 2020-12) забезпечує сувору перевірку типів і валідацію цього корисного навантаження, даючи розробникам миттєвий зворотний зв’язок у дусі «Shift-Left» і гарантуючи, що запитані конфігурації відповідають API базової інфраструктури.
  • Потік 3: операційний намір сутності Feature (values у сутностях Features): в сутності Aggregate розробник запитує можливості інфраструктури, поведінка яких є наміром застосунку, і запитує суворо типізовані облікові дані, не змінюючи внутрішнього коду. Сутність Feature, усі вхідні дані якої операційні, не несе values розробника: команда експлуатації приєднує її в сутності Release разом з її infra (потік 4).
  • Потік 4: визначення розмірів фізичної інфраструктури (infra): повністю оминаючи розробника, фізичні розміри infra явно проєктуються зі специфічної для середовища сутності Release безпосередньо на сутності Components локальної області та приєднані до них сутності Features, зокрема сутності Features для облікових даних. Щоб уникнути колізій валідації закритих схем через дослівне поширення словників, визначення розмірів infra суворо локалізується в явному компоненті, що на нього націлений. Це утримує обчислювальні ліміти, репліки та механічні вимоги до ресурсів у домені Ops.
  • Потік 5: каскадні анотації (контекстні метадані): широкі контекстні дані (як-от операційні домени, простори імен чи коди білінгу) обробляються через каскадні анотації, що запобігає забрудненню через поширення infra. Їх розподіляють у сегменти за походженням, і передбачене використання кожного сегмента, описане нижче, є суспільним договором: шаблон сутності Recipe може читати всі три, а компілятор не примушує до цього розподілу (див. labels-and-annotations):
    • .context.annotations.release (межі домену 4): використовуються виключно для керування фізичними реаліями. Ops явно спрямовує ці анотації в суворі локальні поля infra через шаблони Go (наприклад, відображаючи регіональний простір імен на обчислювальний компонент).
    • .context.annotations.aggregate (підсистеми домену 1): використовуються виключно для керування когнітивною та операційною логікою. Ці анотації явно спрямовуються в корисне навантаження values компонента (наприклад, каскадно передаючи код білінгу команди аж до конфігурації застосунку).
    • .context.annotations.catalog (каталог домену 2): незмінні внутрішні риси, створені архітектором, що використовуються переважно для програмного обчислення політик Wasm.
  • Потік 6: конвеєр метаданих (.context): застосовує глобальні корпоративні вимоги (теги SOC2) безпосередньо до шаблонів фізичної інфраструктури.

3. Абстракція мережі: домовленість «Zero-Port»

  • Найкраща практика: розробникам варто не вказувати порти в сутності Aggregate. Recipe від Ops динамічно обробляє внутрішню маршрутизацію.
  • Запасний вихід: якщо внутрішній код застосунку неможливо змінити, архітектор платформи явно надає поле port в оголошенні schema:. Архітектурна примітка: домовленість «Zero-Port» — найпомітніший приклад ширшого розділення відповідальності платформи. Та сама філософія — абстрагувати фізичну механіку від розробника — застосовується до запитів CPU, лімітів пам’яті, операційних доменів і розмірів дисків. Щоразу, коли обмеження фізичної інфраструктури мусить просочитися в корисне навантаження застосунку розробника (через застарілий код або суворі апаратні вимоги), ним завжди має керувати явний «запасний вихід» в оголошенні schema: архітектора — оголошенні, за яким валідується корисне навантаження розробника.

Назва «Zero-Port» позначає цю домовленість; принцип узагальнюється на будь-яке обмеження фізичної інфраструктури, яке застарілий застосунок жорстко закодовує. Схема нижче використовує tcp_keepalive_seconds як розібраний приклад — таймінг ядра/мережі, якого застосунок очікує на рівні сокетів, — бо він чітко лежить на осі просочування infra.

Схема (домен 2):

values:
image: { type: string, required: true }
# The architect explicitly allows the developer to declare a hardcoded constraint
tcp_keepalive_seconds: { type: integer, min: 10, max: 300 }

YAML розробника (домен 1):

components:
legacy-payment-engine:
type: core/java-tomcat:1.0.0
values:
image: "corp/payments:v4"
tcp_keepalive_seconds: 120 # The infrastructure must adapt to the app, not vice versa

Поведінка компілятора: компілятор Go передає tcp_keepalive_seconds: 120 у граф IR. Потім Recipe від Ops зчитує {{ .values.tcp_keepalive_seconds }}, щоб налаштувати специфікацію пода Kubernetes або тайм-аут простою балансувальника навантаження хмарного провайдера, успішно долаючи розрив із застарілим кодом без порушення схеми.

4. Контракт ін’єкції та попередньо розв’язана мапа

Серед п’яти структурних ключових слів inject має іншу форму, ніж решта. parameters, values, uses та infra — це декларативний стан — розробник записує факти про те, чим є застосунок і від чого він залежить. inject — це імперативна команда — розробник визначає, як значення має бути доставлене до запущеного контейнера, відображаючи абстрактні джерела даних (ключі provides цілі, власні значення компонента, відповідь сховища сутності Feature облікових даних) на конкретні механізми доставки (env, file, arg або власний механізм, який оголошує сутність Component).

Це роз’єднання є структурним. Сутність Aggregate розробника каже «впровадь хост бази даних як змінну середовища DB_HOST», не називаючи фізичної адреси бази даних, шляху в сховищі секретів чи формату імен хостів хмарного провайдера. Recipe від Ops отримує розв’язаний рядок через .context.inject і використовує його, не створюючи ланцюжка пошуку.

Попередньо розв’язана мапа. Під час рендерингу компілятор розв’язує кожне джерело ін’єкції — літерали самоін’єкції та посилання from: на власні provides компонента, міжкомпонентні посилання через uses[].inject, перехоплення injectMapping сутності FeatureRecipe — в єдиний сплощений словник у .context.inject. На момент запуску шаблону valuesMapping базової Recipe кожен ключ ін’єкції вже має своє остаточне рядкове значення. Сутності Recipes ітерують мапу безпосередньо ({{ range $k, $v := .context.inject.env }}), не проходячи ланцюжком розв’язання.

Назви, які розробник дає власним значенням компонента. Там, де сутність Component оголошує spec.inject, власний блок inject: розробника обирає назви, під якими власні значення та provides компонента потрапляють до каналу доставлення. Компілятор повідомляє сутності Recipe в .context.self_inject те одне власне значення, яке читає шаблон кожного запису, — для кожного механізму кожна назва зіставлена з provides.<key>, з values.<key> для шаблону, що читає рівно одне власне значення й нічого іншого, або з порожнім рядком — у формі, якої набувають назви з’єднання в .context.uses.<alias>.inject. Домовленість каталогу стандартної бібліотеки для сутності Recipe, що запускає образ розробника, полягає в тому, щоб вважати назви, які вона інакше обрала б для власних значень компонента, типовими й передавати власне значення під його типовою назвою лише тоді, коли жоден запис ще не зіставлений із ним. Це домовленість каталогу, а не правило компілятора: корпоративний каталог може передавати власні значення своїх компонентів так, як вважає за потрібне. Компілятор читає відображення з тексту, який написав розробник, і не вкладає в назви жодного сенсу.

Повна специфікація контракту ін’єкції — семантика контексту з подвійним станом, правила колізій ключів, модель перехоплення сутності FeatureRecipe та розібрані приклади — міститься в topology-triad.

5. Рушій шаблонів (DX для Ops)

Інженери Platform Ops створюють шаблони перекладу й потребують усієї потужності стандартного шаблонування інфраструктури без пропрієтарної мови шаблонів. Шаблони Aggrega — це Go text/template:

  • Жодних «магічних» рядків: компілятор зберігає точні ключі мап розробника. Ops безпечно звертається до функцій через стандартне індексування мап Go: {{ (index .features "public-route").infra.hostname }}.
  • Бібліотека Sprig: компілятор нативно реєструє стандартну для Helm бібліотеку Sprig, надаючи миттєвий доступ до конвеєрів на кшталт | default, | quote і | toYaml.
  • Фрагменти MappingLibrary: фрагмент відображення, який повторно використовують кілька сутностей Recipes, зберігається в MappingLibrary і підключається до кожної сутності Recipe через $import:. Допоміжні функції шаблонів чартів Helm (include, tpl, required, warn) не зареєстровані; перелік зареєстрованих наведено в sprig-functions.

6. Правила композиції: Aggregates, підсистеми та Components

  • Логічне групування (масив subsystems): за допомогою subsystems розробники можуть одночасно застосовувати логічні метадані (належність команді, мітки відповідності) та наскрізні функції до десятків компонентів. Підсистеми діють як рекурсивні теки на логічній площині/площині намірів, каскадно передаючи annotations донизу в сегмент .context.annotations.aggregate і приєднуючи функції до всіх вкладених компонентів, не диктуючи фізичних меж. Функції рівня підсистеми дотримуються тієї самої схеми, що й функції рівня компонента (з підтримкою type, values, uses, inject), оскільки належать до домену 1 (намір розробника). Під час фіналізації графа компілятор сплощує функції підсистеми в список функцій кожного вкладеного компонента, розміщуючи їх у порядку виконання після власних функцій компонента та перед будь-якими функціями, приєднаними в сутності Release.
aggregate.yaml
subsystems:
finance-module:
annotations:
"billing.corp.com/team": "payments"
features:
audit-logging:
type: core/audit-logger:1.0.0
values: { log_level: "verbose" }
components:
ledger-api:
type: core/python-worker:1.0.0
ledger-db:
type: core/postgres:1.0.0
  • Складені сутності Aggregates ПІДТРИМУЮТЬСЯ (шаблон модуля): сутності Aggregates виконують роль і кореневої сутності Aggregate, яку збирає сутність Release, і багаторазових модулів. Батьківська сутність Aggregate може оголосити дочірню сутність Aggregate точно так само, як компонент, передаючи в неї parameters. Щоб уникнути тісного зв’язування, дочірні сутності Aggregates надають контракт exportedComponents:, що встановлює стабільне ім’я публічного інтерфейсу. Батьківська сутність досягає компонентів модуля лише через цей інтерфейс: ціль uses: називає модуль і один із його експортованих псевдонімів, і компілятор під’єднує ребро до внутрішнього компонента, який називає цей псевдонім, тоді як ціль, що звертається всередину модуля за будь-яким іншим іменем, зупиняє збірку, називаючи модуль і псевдоніми, які він експортує. Модуль може сам повторно експортувати експортований компонент вкладеного модуля під власним ім’ям інтерфейсу — за потреби перейменувавши його, — і компілятор транзитивно розв’язує такий ланцюжок повторного експорту до базового внутрішнього вузла, тож модулі компонуються на будь-яку глибину, і батьківській сутності не потрібно знати, наскільки глибоко вкладена ціль. Ціль, яка не розв’язується в жоден внутрішній вузол, як і раніше гучно зупиняє збірку, а ланцюжок повторного експорту, що замикається сам на себе, відхиляється, а не обходиться нескінченно.
child-database-module.yaml
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: child-database-module
version: 1.0.0
spec:
components:
internal-pg-primary:
type: core/postgres:1.0.0
exportedComponents:
# The Public Contract (Written once by the module author)
primary_db: "internal-pg-primary"
parent-app.yaml
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: parent-app
version: 1.0.0
spec:
aggregates:
finance-db-subsystem:
type: my-catalog/child-database-module:1.0.0
components:
billing-api:
type: core/python-worker:1.0.0
uses:
databases:
- finance-db-subsystem.primary_db
  • Сутності Components не можуть містити підкомпонентів: сутності Components — атомарні будівельні блоки. Композиція відбувається на рівні сутності Aggregate через підсистеми та підагрегати. Якщо застосунку потрібно кілька фізичних контейнерів (наприклад, API + sidecar), це фізичне вкладення живе всередині шаблону Recipe від Ops, а не у визначенні сутності Component.

  • Один цілісний сервіс на сутність Component — межа одного робочого навантаження: сутність Component моделює один цілісний сервіс — один відкритий сервіс або робоче навантаження (чи навантаження) одного сервісу разом з його суто внутрішніми допоміжними навантаженнями. Її мітка component.aggrega.ai/type називає операційну форму цього одного сервісу. Кілька фізичних робочих навантажень в одній сутності Component допустимі, якщо вони утворюють один цілісний продукт без незалежно придатних до використання частин: сервіс, чий chart запускає контролер, вебхук та інжектор, усе одно є однією сутністю Component. Критерій — не кількість навантажень, а незалежна придатність до використання.

    Межа проводиться там, де пакет містить щось, що інший компонент міг би змістовно використовувати (use) окремо, — особливо сторонню інфраструктуру, як-от базу даних, кеш чи брокер повідомлень, яку Aggrega вже моделює як окрему сутність Component. Такий пакет — не одна сутність Component; це модуль-підагрегат — показаний вище шаблон spec.aggregates + exportedComponents, — що компонує по одній сутності Component на сервіс, щоб кожен сервіс був адресовним вузлом із власним типом, власними ребрами та власною поверхнею політик і масштабування.

    Евристика, сформульована як чітке правило: Чи містить chart щось, що інший компонент міг би змістовно використовувати окремо, або щось, для чого в Aggrega вже є сутність Component? Якщо так, моделюйте це як стек — модуль-підагрегат, що компонує сутності Components за сервісами. Якщо воно обслуговує лише цей один сервіс, моделюйте це як одну сутність Component.

    Обгортання цілого багатосервісного продукту в одну непрозору сутність Component — задокументований антипатерн. Компілятор працює без власної позиції і прийме це — він рендерить усе, що проходить валідацію схеми, — але стандартна бібліотека натомість компонує сутності Components за сервісами в модуль, оскільки монолітна обгортка приховує незалежно моделовані сервіси від топології, від селектора та від політик і масштабування окремих сервісів. Ця дисципліна гранулярності є суспільним договором — див. ../language-reference/vocabulary/social-contracts.md (гранулярність сутності Component).

7. Типова область — поступове розкриття групування

subsystems (у сутності Aggregate) і boundaries (у сутності Release) — це конструкції групування, але розробникові не потрібно оголошувати їх наперед. Кожна сутність пропонує дві форми запису, і вони взаємовиключні: компоненти записують згрупованими в іменованих областях або записують безпосередньо на верхньому рівні — ніколи обидва способи одночасно. Документ, що оголошує і components верхнього рівня, і іменовані області, зупиняється під час завантаження з помилкою конверта.

Для пласкої форми (components верхнього рівня) компілятор синтезує справжню область default під час завантаження й згортає в неї компоненти верхнього рівня, тож кожен наступний прохід бачить однорідну структуру з областями. Синтезована область — не прихований контейнер: це справжній вузол в IR, позначений своїм походженням, який можна відрізнити від області, яку розробник явно назвав default. Вона прихована лише там, де автор читає шляхи, — діагностика й адресація показують кореневий шлях .spec.components[…], який розробник насправді написав.

  • Пласка сутність Aggregate (компоненти верхнього рівня): компоненти записують у spec.components без subsystems. Компілятор згортає їх під час завантаження в синтезовану підсистему default. Анотації області підсистеми та функції рівня підсистеми застосовуються лише до оголошених підсистем; пласка форма не несе жодних.
  • Пласка сутність Release (компоненти верхнього рівня): компоненти записують у spec.components без boundaries. Компілятор згортає їх у синтезовану межу default, вивід якої плаский, — артефакти потрапляють безпосередньо в dist/ (для кожного провайдера: dist/compose/, dist/helm/, …), без сегмента з назвою межі. Це найпростіший випадок: aggrega build над пласкою ціллю Compose або ціллю з одним кластером без іменування меж. (Межа, яку розробник оголошує й називає default, є звичайною іменованою межею й, не маючи власного directory:, виводить у dist/boundaries/default/, як і будь-яка інша.)
  • Шлях розширення: коли пласка архітектура зростає до такої, що потребує групування (різні простори імен, окремі логічні групи, розгортання на кілька меж), розробник переносить компоненти верхнього рівня в явні subsystems або Ops запроваджує явні boundaries. Оскільки дві форми взаємовиключні, це перехід від пласкої форми до форми з областями — а не змішування обох, — і ідентичність вузлів зберігається під час переходу.

Обґрунтування — поступове розкриття: вимога обов’язкового групування для тривіальних випадків (демо з однією службою, швидкий локальний прототип) створює зайве тертя. Тест адаптації «від нуля до робочого результату за 10 хвилин» вимагає, щоб розробник міг написати мінімальну сутність Aggregate з одним компонентом, однією сутністю Manifest і однією сутністю Release та отримати робочий вивід, не розбираючись спершу в підсистемах чи межах. Типова область — це в’їзд; оголошені області — це те, куди рухається архітектура, коли зростає.

Нижче наведено один рекомендований шаблон і п’ять обмежень. Схеми забезпечують обмеження 4 і 5 — сутність Release не має блоку values, а екземпляр компонента в сутності Aggregate не має ключа labels; решта — це домовленості, які компілятор не перевіряє.

  • Рекомендований шаблон: підняття параметрів через рядки шаблонів

    • Приклад: розробник пише workers: {{ .parameters.env_workers }} у своєму блоці values без лапок, щоб значення надійшло як ціле число, яким його оголошено.
    • Чому: якщо сутність Aggregate оголошує env_workers як типізований параметр (type: integer), компілятор спершу перевіряє значення, надане сутністю Release, на відповідність контракту. Перевірка контракту параметрів відбувається до інтерполяції; інтерполяція відбувається до перевірки навколишньої схеми values:. Це зберігає повторну використовуваність сутності Aggregate: Ops надає ціле число через parameters: сутності Release, компілятор перевіряє його щодо типізованого оголошення parameters:, підставляє розв’язане значення в документ, і оголошення schema: сутності Component успішно перевіряє отримане ціле число.
  • Обмеження 1: облікові дані — це вкладення, а не значення

    • Небажаний шаблон: розробник пише values: { password: "123" } у компоненті.
    • Чому: домовленість стандартної бібліотеки полягає в тому, що облікові дані запитують як вкладення в features:, указуючи type сутності Feature для облікових даних (з міткою feature.aggrega.ai/kind: secret) і використовуючи власні values цього вкладення для опису запиту до сховища секретів. Це домовленість, а не перевірка компілятора — компілятор не інтерпретує, що означає листок values, і переносить вбудований літерал дослівно. Саме поверхня вкладень робить добре написану форму доступною й типізованою.
  • Обмеження 2: Components, агностичні щодо можливостей

    • Непідтримуваний шаблон: архітектор пише aws_instance_type: string в оголошенні schema: сутності Component.
    • Чому: за домовленістю Components агностичні щодо можливостей. Фізичні апаратні цілі належать до Recipes команди Ops або до загальних анотацій .context, а не до базової когнітивної логіки застосунку.
  • Обмеження 3: умовна логіка на метаданих

    • Непідтримуваний шаблон: Ops пише {{ if eq .context.labels.gpu "true" }} у сутності Recipe, щоб докорінно змінити стратегію розгортання.
    • Чому: канал .context обходить перевірку schema: кожного стовпа. Покладання на неперевірені мітки в базовій логіці інфраструктури робить платформу крихкою. Об’єкт .context несе теги метаданих (напр., білінг, SOC2); структурна маршрутизація належить до стовпів, перевірених схемою.
  • Обмеження 4: сутність Release не може перевизначати значення розробника

    • Непідтримуваний шаблон: Ops намагається з сутності Release перевизначити когнітивну логіку розробника (напр., змінити workers: 4 на workers: 10).
    • Чому: сутність Aggregate — єдине джерело істини для наміру розробника. Якщо значення жорстко закодоване в сутності Aggregate, воно незмінне в усіх середовищах. Якщо значення має змінюватися залежно від середовища, розробник використовує підняття параметрів. Схема сутності Release забезпечує це, забороняючи блоки values і обмежуючи Ops виконанням контракту parameters та визначенням фізичної infra.
  • Обмеження 5: мітки рівня екземпляра в сутності Aggregate

    • Непідтримуваний шаблон: розробник пише labels: {} в екземплярі компонента всередині сутності Aggregate.
    • Чому: мітки — це незмінні риси рівня каталогу, які створює архітектор платформи, — семантична ідентичність, яку читають рушії політик і селектори. Сутність Release спрямовує компоненти до меж через явне націлювання за ID на основі мап (components: { "my-agent": {} }), що зберігає можливість вкладати infra і перевизначення функцій для кожного компонента, не змішуючи авторство міток із сутністю Aggregate розробника.

9. Периметр безпеки & явні запобіжники вихідного трафіку (призначення поза периметром)

Жоден застосунок не існує у вакуумі. Скомпільована архітектура Aggrega являє собою строго відображений граф. Проте сучасні системи ШІ постійно взаємодіють із сутностями поза цим скомпільованим периметром — як-от публічні SaaS LLM (Anthropic, OpenAI), загальні публічні API (Stripe, Twilio) чи застарілі brownfield-бази даних (локальний Oracle).

Щоб безпечно інтегрувати ці зовнішні системи, Aggrega строго відокремлює межу безпеки від механіки виконання. Межа безпеки регулюється універсальним правилом сутності Component і явним запобіжником вихідного трафіку.

1. Універсальне правило сутності Component

Якщо застосунок взаємодіє із сутністю — чи то локальною базою даних, керованим хмарним ресурсом, SaaS LLM, чи загальною публічною кінцевою точкою API, — цю сутність ОБОВ’ЯЗКОВО слід оголосити як окрему сутність Component у сутності Aggregate. Це правило є домовленістю: компілятор не бачить викликів, які робить застосунок, тож ніщо його не перевіряє.

Розглядаючи зовнішні SaaS API та застарілі бази даних як повноправні вузли в графі проміжного представлення (IR), розробники отримують змогу приєднувати конфігурації проксі Zero-Trust безпосередньо до вихідного виклику. Наприклад, змоделювавши API Stripe як окремий вузол, розробник може приєднати до нього функцію header-injector, гарантуючи, що згенерована конфігурація не дасть агенту, який здійснює виклик, зберігати сирий токен API у власній пам’яті.

2. Явний запобіжник вихідного трафіку (відповідність інфраструктури)

Замість того щоб покладатися на жорстко закодовану логіку компілятора для керування вихідним мережевим трафіком, Aggrega повністю делегує безпеку периметра агностичним рушіям політик підприємства та плагінам рендерингу Wasm. Це гарантує, що згенеровані конфігурації строго відповідають явним дозволам на вихідний трафік.

  • Гачок каталогу (домен 2): коли архітектор визначає публічний SaaS-компонент (напр., core/external-service), він приєднує до нього незмінну корпоративну мітку (напр., security.enterprise.com/zone: "untrusted-external").
  • Запобіжник політики (під час компіляції): перш ніж буде згенеровано будь-яку конфігурацію, рушій політик OPA або Kyverno оцінює граф. Підприємство пише просте правило: «Якщо внутрішній вузол з’єднується з вузлом із міткою untrusted-external, ID цього цільового вузла має бути явно вказаний у масиві parameters.approved_egress середовища». Якщо розробник намагається спрямувати дані до несхваленого зовнішнього призначення, рушій політик зупиняє збірку.
  • Генерування конфігурації (час рендерингу): якщо політику пройдено, правило вихідного трафіку рендериться з того, що приєднав оператор. Сутність Feature core/egress-allowlist, приєднана до компонента, що здійснює виклик, у сутності Release, рендерить на helm по одному Kubernetes NetworkPolicy на кожне робоче навантаження, яке рендерить цей компонент, дозволяючи вихідний трафік лише до його власних подів, до подів цілей його ребер uses на портах, які оголошують ці поди, до DNS кластера та до діапазонів адрес, які вкладення перелічує для цілі, що не працює в кластері, як-от публічного SaaS API. Збірка зупиняється, якщо сутність Release не підтверджує за допомогою infra.control_plane_present: true, що мережевий плагін кластера застосовує мережеву політику, а також зупиняється, називаючи будь-яке таке зовнішнє з’єднання без зазначеного діапазону адрес; на compose, де немає мережевої політики, вкладення зупиняє збірку. Розробник ніколи не пише правило брандмауера.

Це гарантує — через роль вердикту врядування, що оцінює оголошену топологію, — що явно оголошена інфраструктура відповідає політиці вихідного трафіку, без потреби для базового компілятора Go розуміти, що означає «зовнішній». (Примітка: справжній вихідний трафік zero-trust залежить від того, чи цільовий кластер під час виконання запускає CNI з Default Deny; згенеровані конфігурації лише відображають авторизовані винятки).

Одна сутність Component на кожну зовнішню службу

Кожна зовнішня служба оголошується як окремий компонент, а не згортається в масив із кількома цілями. Якщо застосунок викликає п’ять різних сторонніх API, розробник оголошує п’ять окремих компонентів core/external-service. Саме таке оголошення для кожної служби дає змогу рушіям політик і плагінам Wasm націлюватися на кожне вихідне призначення окремо — приєднуючи до кожної зовнішньої залежності різні політики вихідного трафіку, різні функції проксі чи різні гачки спостережуваності.

Відокремлення безпеки від виконання (сценарій «brownfield»)

Важливо зауважити, що семантична мітка (напр., untrusted-external) визначає політику мережевої безпеки, а не виконання. Вона не залежить від того, чи рендерить Aggrega артефакти, які надають ресурс.

  • Сценарій A (публічний SaaS API): позначений untrusted-external у каталозі (запускає запобіжники вихідного трафіку політики). Реалізується посилальним робочим навантаженням (обчислювальні ресурси не надаються; див. §10).
  • Сценарій B (внутрішня застаріла база даних): позначена internal-trusted (обходить запобіжники вихідного трафіку, залишається всередині VPC). Реалізується посилальним робочим навантаженням (обчислювальні ресурси не надаються; див. §10).
  • Сценарій C (самостійно розміщена база даних): позначена internal-trusted. Виконується через плагін рендерингу Helm (фізично надається як StatefulSet Kubernetes).

10. Сервіси, які збірка не надає: посилальні Workloads

Коли застосунок взаємодіє із застарілою локальною базою даних або публічним SaaS API (як-от Stripe), універсальне правило сутності Component вимагає оголошувати ці зовнішні сутності як окремі компоненти в сутності Aggregate. Проте Aggrega не повинна намагатися генерувати для них фізичний артефакт Pod Kubernetes чи екземпляра AWS RDS.

Сутність Recipe, що реалізує такий компонент, оголошує сутність Workload з form: reference: endpoint — хост або URL, — за потреби port і жодних контейнерів. Компілятор передає обидва значення як детерміновані рядки-вказівники й ніколи їх не розв’язує. Що провайдер рендерить для посилальної сутності Workload, вирішує сам провайдер: helm видає ExternalName Service з хостом кінцевої точки, щоб робочі навантаження в кластері могли звертатися до сервісу, кінцева точка якого — DNS-ім’я, за стабільним іменем усередині кластера; compose нічого для неї не рендерить. Kubernetes розглядає externalName як DNS-ім’я, тож до кінцевої точки, записаної як IP-адреса, звертаються за адресою, яку отримує споживач, а не через Service.

В обох провайдерів provides: сутності Recipe доходять до кожного споживача через .context.uses і контракт inject точно так само, як у наданого компонента. Тому під’єднання споживача не змінюється, коли його ціль переходить від наданої до посилальної: змінюється лише сутність Recipe, з якою сутність Manifest зіставляє ціль.

Конвеєр виконання крок за кроком

1. Домен 1 (сутність Aggregate): намір розробника Розробник запитує застарілу базу даних Oracle. Йому байдуже, де вона розміщена; він лише вказує, що його агент, який здійснює виклик, очікує отримати рядок з’єднання як змінну середовища. Оскільки IP статичний і відомий заздалегідь, він передає його через параметри.

components:
legacy-oracle:
type: core/legacy-database:1.0.0
values:
host: "{{ .parameters.legacy_oracle_ip }}"
sid: "PROD_DB"
my-agent:
type: core/python-worker:1.0.0
values: {}
uses:
databases:
legacy_db:
target: legacy-oracle
inject:
env:
- in: ORACLE_DSN # Local env var
from: "primary_endpoint" # Target provides key

2. Домен 4 (сутність Manifest): маршрутизація Ops зіставляє тип застарілої бази даних із сутністю Recipe, яка форматує її рядок з’єднання. Сутність Manifest називає сутність Recipe і нічого більше; названа сутність Recipe оголошує сутність Workload з form: reference, і саме ця форма не дає вузлу надавати обчислювальні ресурси. Маршрутизація залишається цілком пласкою й передбачуваною, бо мапа має рівно одну форму, хоч би якою була ціль.

spec:
mappings:
components:
type:
"core/legacy-database": "oracle-dsn-formatter:1.0.0"

3. Домен 3 (посилальна сутність Recipe): структурування передачі Інженер Ops пише сутність Recipe. Вона будує рядок з’єднання primary_endpoint з values розробника у своєму блоці locals, публікує його в provides і оголошує посилальну сутність Workload, що вказує на хост бази даних.

apiVersion: aggrega.ai/v1beta1
kind: Recipe
metadata:
name: oracle-dsn-formatter
version: 1.0.0
spec:
capability: helm
implements: core/legacy-database:1.0.0
# The connection string, built from the Developer's values
locals:
primary_endpoint: "oracle://{{ .values.host }}:1521/{{ .values.sid }}"
# The public contract a consumer's inject reads
provides:
primary_endpoint: "{{ .locals.primary_endpoint }}"
# No compute: an endpoint the build does not provision
workload: |
apiVersion: aggrega.ai/v1beta1
kind: Workload
form: reference
endpoint: "{{ .values.host }}"
port: 1521

4. Виконання компілятором під час рендерингу (передача)

  1. Компілятор обчислює сутність Recipe для legacy-oracle. Для сутності Release, що надає legacy_oracle_ip: "10.0.4.55", її primary_endpoint дорівнює oracle://10.0.4.55:1521/PROD_DB.
  2. На helm посилальна сутність Workload рендерить один ExternalName Service legacy-oracle з externalName: 10.0.4.55 і портом 1521; на compose вона нічого не рендерить.
  3. Потім компілятор рендерить сутність Recipe для my-agent. Її канал .context.uses несе provides вузла Oracle, а контракт inject уже розв’язав за ними ORACLE_DSN.

5. Домен 3 (сутність Recipe, що викликає): виконання контракту Стандартний рецепт Helm для воркера Python читає отриману мапу inject точно так само, як для бази даних, яку надає збірка.

# Inside python-worker-helm (The calling agent's recipe)
env:
# The compiler pre-resolved the target's provides into the inject map
{{- range $key, $value := .context.inject.env }}
- name: {{ $key }} # Renders: ORACLE_DSN
value: "{{ $value }}" # Renders: oracle://10.0.4.55:1521/PROD_DB
{{- end }}

11. Передавання між стовпами через schema-bridge: міст від наміру до інфраструктури

Див. inheritance-and-interface щодо шаблону schema-bridge, який безпечно відкриває спеціалізовані параметри інфраструктури через дочірні компоненти, — орієнтоване на розробника поле values:, оголошене в schema: сутності Component, яке шаблон valuesMapping: сутності Recipe передає у відрендерений вивід у формі infra:.

12. Надання ресурсів greenfield («платформні Aggregates»)

Поширена пастка в платформній інженерії — змушувати маршрутизатор (файл Release) виконувати важке надання кластерів дня 0 (напр., піднімати новий кластер AWS EKS перед розгортанням у нього застосунку). Це створює довгі й важкі для читання файли маршрутизації.

Aggrega розв’язує це за принципом «черепахи аж до самого низу». Схема сутності Release не має блоку для встановлення інфраструктури; надання кластерів моделюється за допомогою платформних Aggregates.

Оскільки кластер AWS EKS, площина керування Istio та AWS VPC зрештою є лише фізичними хмарними ресурсами, їх моделюють точно так само, як компоненти застосунку.

  1. Платформна сутність Aggregate: команда інфраструктури пише стандартний Aggregate.yaml, компонентами якого є core/aws-vpc, core/eks-cluster і core/istio-base.
  2. Платформна сутність Release: команда розгортає цей агрегат. Рендерер, прив’язаний до цих платформних компонентів, виводить артефакти, потрібні для розгортання базової інфраструктури.
  3. Сутність Release застосунку: коли розробник застосунку готовий розгорнути свого агента ШІ, команда Ops просто вказує щойно створений кластер як ціль межі у власному файлі Release застосунку.