Таксономія даних і композиція
Уніфікована таксономія даних і правила композиції
Щоб створити передбачувану схему й усунути когнітивне тертя, платформа використовує рівно п’ять загальнозрозумілих ключових слів і структуру 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.
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:називає модуль і один із його експортованих псевдонімів, і компілятор під’єднує ребро до внутрішнього компонента, який називає цей псевдонім, тоді як ціль, що звертається всередину модуля за будь-яким іншим іменем, зупиняє збірку, називаючи модуль і псевдоніми, які він експортує. Модуль може сам повторно експортувати експортований компонент вкладеного модуля під власним ім’ям інтерфейсу — за потреби перейменувавши його, — і компілятор транзитивно розв’язує такий ланцюжок повторного експорту до базового внутрішнього вузла, тож модулі компонуються на будь-яку глибину, і батьківській сутності не потрібно знати, наскільки глибоко вкладена ціль. Ціль, яка не розв’язується в жоден внутрішній вузол, як і раніше гучно зупиняє збірку, а ланцюжок повторного експорту, що замикається сам на себе, відхиляється, а не обходиться нескінченно.
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: child-database-module version: 1.0.0spec: 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"apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: parent-app version: 1.0.0spec: 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 та отримати робочий вивід, не розбираючись спершу в підсистемах чи межах. Типова область — це в’їзд; оголошені області — це те, куди рухається архітектура, коли зростає.
8. Архітектурні обмеження та рекомендовані шаблони
Нижче наведено один рекомендований шаблон і п’ять обмежень. Схеми забезпечують обмеження 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); структурна маршрутизація належить до стовпів, перевірених схемою.
- Непідтримуваний шаблон: Ops пише
-
Обмеження 4: сутність Release не може перевизначати значення розробника
- Непідтримуваний шаблон: Ops намагається з сутності
Releaseперевизначити когнітивну логіку розробника (напр., змінитиworkers: 4наworkers: 10). - Чому: сутність
Aggregate— єдине джерело істини для наміру розробника. Якщо значення жорстко закодоване в сутностіAggregate, воно незмінне в усіх середовищах. Якщо значення має змінюватися залежно від середовища, розробник використовує підняття параметрів. Схема сутностіReleaseзабезпечує це, забороняючи блокиvaluesі обмежуючи Ops виконанням контрактуparametersта визначенням фізичноїinfra.
- Непідтримуваний шаблон: Ops намагається з сутності
-
Обмеження 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по одному KubernetesNetworkPolicyна кожне робоче навантаження, яке рендерить цей компонент, дозволяючи вихідний трафік лише до його власних подів, до подів цілей його ребер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 key2. Домен 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/v1beta1kind: Recipemetadata: name: oracle-dsn-formatter version: 1.0.0spec: 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: 15214. Виконання компілятором під час рендерингу (передача)
- Компілятор обчислює сутність Recipe для
legacy-oracle. Для сутності Release, що надаєlegacy_oracle_ip: "10.0.4.55", їїprimary_endpointдорівнюєoracle://10.0.4.55:1521/PROD_DB. - На
helmпосилальна сутність Workload рендерить один ExternalName Servicelegacy-oracleзexternalName: 10.0.4.55і портом1521; наcomposeвона нічого не рендерить. - Потім компілятор рендерить сутність 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 зрештою є лише фізичними хмарними ресурсами, їх моделюють точно так само, як компоненти застосунку.
- Платформна сутність Aggregate: команда інфраструктури пише стандартний
Aggregate.yaml, компонентами якого єcore/aws-vpc,core/eks-clusterіcore/istio-base. - Платформна сутність Release: команда розгортає цей агрегат. Рендерер, прив’язаний до цих платформних компонентів, виводить артефакти, потрібні для розгортання базової інфраструктури.
- Сутність Release застосунку: коли розробник застосунку готовий розгорнути свого агента ШІ, команда Ops просто вказує щойно створений кластер як ціль межі у власному файлі
Releaseзастосунку.