Таксономія сутностей
Архітектура Aggrega організована в чотири домени, кожен з яких належить іншій персоні та містить певні види сутностей, а також шар бібліотек рівня 3 — третій рівень моделі рівнів сутностей довідника мови, — що зберігає багаторазово використовуваний вміст схем, зіставлень, робочих навантажень і артефактів. Наведений нижче огляд показує, як чотири домени та бібліотеки рівня 3 пов’язані між собою; кожен наступний розділ починається з діаграми власних сутностей, на якій сутність з іншого домену зображено пунктирним контуром. Детальні авторські поверхні (поля, схеми, приклади) кожної сутності наведено в каталозі сутностей довідника мови.
graph TD
Intent["<b>Domain 1: Developer Intent</b><br/><i>Developer</i>"]
Catalog["<b>Domain 2: Platform Catalog</b><br/><i>Platform Architect</i>"]
Routing["<b>Domain 4: Routing & Policy</b><br/><i>Platform Operator / DevOps</i>"]
Infra["<b>Domain 3: Infrastructure Base</b><br/><i>Infrastructure Engineer / Ops</i>"]
Libs["<b>Tier 3: Libraries</b>"]
Intent -->|"requests, attaches"| Catalog
Intent -->|"binds via"| Routing
Routing -->|"attaches"| Catalog
Catalog -->|"resolved to"| Infra
Routing -->|"resolves, renders via"| Infra
Catalog -.->|"$ref"| Libs
Infra -.->|"$import"| Libs
Корпус охоплює чотири домени та шар бібліотек рівня 3:
| # | Сутність | Домен | Роль |
|---|---|---|---|
| 1 | Aggregate | Домен 1 — Намір розробника | Креслення топології застосунку |
| 2 | Component | Домен 2 — Platform Catalog | Абстрактний інтерфейс обчислювального вузла |
| 3 | Feature | Домен 2 — Platform Catalog | Операційна ознака (зокрема сутності Features для облікових даних) |
| 4 | Recipe | Домен 3 — Інфраструктурна основа | Реалізація сутності Component для кожного постачальника |
| 5 | FeatureRecipe | Домен 3 — Інфраструктурна основа | Реалізація сутності Feature для кожного постачальника |
| 6 | Plugin | Домен 3 — Інфраструктурна основа | Плагін WebAssembly з адресацією за вмістом (рендеринг постачальників, кроки конвеєра, лінтинг) |
| 7 | Manifest | Домен 4 — Маршрутизація та політики | Lock-файл залежностей, що зіставляє інтерфейси із сутностями Recipes |
| 8 | Release | Домен 4 — Маршрутизація та політики | Маршрутизатор розгортання, що прив’язує сутність Aggregate до сутності Manifest |
| 9 | SchemaLibrary | Рівень 3 — Бібліотеки | Багаторазово використовувані визначення JSON Schema 2020-12 |
| 10 | MappingLibrary | Рівень 3 — Бібліотеки | Багаторазово використовувані фрагменти шаблонів Go |
| 11 | WorkloadLibrary | Рівень 3 — Бібліотеки | Багаторазово використовувані фрагменти шаблонів сутності Workload |
| 12 | ArtifactLibrary | Рівень 3 — Бібліотеки | Багаторазово використовувані іменовані пакети артефактів |
Ця таблиця — повний набір видів авторських сутностей, тобто видів, які автор оголошує в полі kind:. Вид Workload — це вміст, що належить платформі й вбудовується в синтезовані вхідні дані сутності Recipe, а не окрема сутність каталогу (див. розділ 16), тому його свідомо немає в таблиці вище.
Plugin — це повноцінна сутність авторингу — з власним kind, власною JSON Schema та власною текою в каталозі, — якою володіє Platform Ops у домені 3. Сутність Plugin — це адресоване за вмістом посилання на артефакт WebAssembly, що оголошує один тип сокета, який вона реалізує. Таксономія має сім членів: provider (рендерить вузли IR у нативні для провайдера артефакти), linter (видає діагностику щодо створеного вмісту), pipeline-step (крок feature-recipe-pipeline), governance (виконує роль управління — перетворює мітки чи анотації або повертає вердикт прийняття чи відхилення щодо графа IR або відрендерених артефактів), cli (додає підкоманду aggrega, яку оператор викликає з командного рядка), parser (перетворює сторонній вихідний текст на канонічне структуроване дерево) та importer (перетворює стороннє джерело інфраструктури чи визначень агентів на чернетки файлів авторингу Aggrega). Сутність Plugin для рендерингу провайдера (pluginType: provider) — це одиниця, що обслуговує рендеринг провайдера: вона оголошує в spec.provider.capabilities ім’я чи імена провайдерів, які рендерить, і переносить решту метаданих свого сокета провайдера в тому самому блоці spec.provider. Компілятор фіксує й маршрутизує посилання; середовище виконання WebAssembly виконує байти; компілятор не інтерпретує, що робить плагін — плагін є транспортом для специфічного для домену інтелекту, що живе у WebAssembly. Його поверхню авторингу та метаданих задокументовано в language-reference/entities/plugin.md.
Домен 1: намір розробника («що»)
graph LR
classDef ext stroke-dasharray:5 4;
A["Aggregate<br/>The 'What'"]
CC["Component"]:::ext
CapC["Feature"]:::ext
EB["Release"]:::ext
A -.->|"Requests"| CC
A -.->|"Attaches"| CapC
A -->|"Binds via"| EB
- Роль: розробник. Зосереджується суто на архітектурі AI, когнітивних циклах і вимогах до виживання застосунку. Йому не потрібно знати про CEL, OPA чи фізичні порти.
- 1. Aggregate: декларативне креслення топології застосунку на основі мап. Слугуючи чи то кореневою сутністю Aggregate, яку збирає сутність Release, чи то параметризованим модулем для повторного використання, визначає логічні
componentsі приєднує вfeaturesсутності Features, поведінка яких є наміром застосунку, разом з їхнімиvalues; сутність Feature, усі входи якої операційні, натомість приєднує оператор у сутності Release (див. домен 4). Облікові дані запитують на тій самій поверхні приєднанняfeaturesчерез сутність Feature для облікових даних — окремого блоку для цього немає. Визначає абстрактні вимоги до потужності черезparameters(типізовані контракти, записані словником компактної форми) і стан корисного навантаження черезvalues. Екземпляри сутності Component підтримують необов’язкове полеdescriptionдля документації та відображення в Studio. Просуває домовленість «Zero-Port» (абстрагування мережевих портів, якщо наявний код явно їх не вимагає) без жорстко закодованої цільової платформи чи простору імен.
Домен 2: Platform Catalog («інтерфейси та інтелект»)
graph TD
classDef ext stroke-dasharray:5 4;
A["Aggregate"]:::ext
EB["Release"]:::ext
CC["Component<br/>The Compute Interface"]
CapC["Feature<br/>The Operational Trait"]
CD["Recipe"]:::ext
CapD["FeatureRecipe"]:::ext
A -.->|"Requests"| CC
A -.->|"Attaches"| CapC
EB -.->|"Attaches"| CapC
CC -.->|"Resolved to"| CD
CapC -.->|"Resolved to"| CapD
- Роль: Platform Architect. «Програміст» платформи. Розміщує кожен компонент в операційній онтології, пише програмовані політики (мутатори та валідатори Wasm) і встановлює семантичні мітки качиної типізації.
- 2. Component: абстрактний інтерфейс обчислювального вузла. Оголошує свою базову форму через операційну хмарну онтологію (наприклад,
component.aggrega.ai/type: server) і нашаровує свою когнітивну ідентичність через мітки качиної типізації (наприклад,model.aggrega.ai/capability: generative). Оголошує слоти облікових даних черезfeaturesSchema(обов’язкові/необов’язкові, blackbox/прозорі) і використовуєschema:(JSON Schema 2020-12, зазвичай записану скороченим записом компактної форми), щоб суворо валідувати непрозорий блокvaluesрозробника. - 3. Feature: модульна операційна ознака (наприклад, маскування даних, DNS-маршрутизація, керування секретами). Використовує селектори міток
appliesTo, щоб динамічно прив’язуватися до конкретних семантичних міток. Як і сутності Components, оголошує слоти облікових даних черезfeaturesSchema, щоб примусово забезпечити надання ключів API. Важливо, що вона використовуєmetadata.annotations, щоб явно позначати елементи в пласкому графі IR, що підказує низхідним валідаторам політик Wasm і плагінам рендерингу, як обробляти конфігураційне корисне навантаження сутності Feature.- Сутності Features для облікових даних: платформа уніфікує керування обліковими даними в сутності Feature: сутність Feature з міткою
feature.aggrega.ai/kind: secretє функцією облікових даних — вона визначає інтерфейс запитів до сховища секретів (наприклад, AWS Secrets Manager, HashiCorp Vault). Її приєднують уfeatures:, як і будь-яку іншу сутність Feature, на тій самій поверхні й у тій самій формі; мітка — це метадані, які каталог несе, щоб описати, що створює приєднання, і жодна гілка компілятора її не читає. Окремого виду для сховища секретів чи рецепта секрету немає: сутність FeatureRecipe для облікових даних має ту саму форму, що й будь-яка інша FeatureRecipe, конвеєр «отримати, потім доставити» однаковий для обох, а контракт доставленняinject(env,file,arg) спільний. Одна сутність, одне ключове слово приєднання, один шлях виконання модифікаторів через рендеринг — а облікові дані зіставляються вfeatures.typeу сутності Manifest.
- Сутності Features для облікових даних: платформа уніфікує керування обліковими даними в сутності Feature: сутність Feature з міткою
Онтологія як мітка. Операційну хмарну онтологію оголошено в metadata.labels["component.aggrega.ai/type"], а не як поле верхнього рівня spec.type. Цей вибір дає змогу рушію селекторів міток компілятора безпосередньо націлюватися на значення онтології — сутність Feature оголошує appliesTo: "component.aggrega.ai/type in (server, worker)", щоб динамічно приєднуватися до кожного компонента server чи worker без жодної нової логіки Go в основному компіляторі. Той самий механізм селекторів застосовується до кожної мітки Aggrega, тож сутність Feature, селектор сокета чи зіставлення меж у сутності Release читає власний ключ мітки каталогу точно так само, як цей.
component.aggrega.ai/type — це ключ Aggrega, і його набір значень закритий: опублікована схема сутності Component перелічує примітиви, а документ з будь-яким іншим значенням відхиляється під час завантаження, причому E0215 називає мітку й перелічує, що вона приймає. Каталог, якому потрібна класифікація, якої Aggrega не визначає, додає поруч власний ключ мітки — схема сутності Component приймає будь-який додатковий ключ мітки з рядковим значенням, — тож нова вісь коштує власного ключа й жодного нового випуску компілятора, а зарезервований ключ скрізь зберігає одне значення. Саме завдяки цьому сутність Feature, написана для component.aggrega.ai/type in (stateful-server), працює із сутностями Components авторів, які ніколи не зустрічалися.
Домен 3: інфраструктурна основа («реалізації»)
graph LR
classDef ext stroke-dasharray:5 4;
CC["Component"]:::ext
CapC["Feature"]:::ext
ENV["Manifest"]:::ext
EB["Release"]:::ext
CD["Recipe<br/>The Implementation"]
CapD["FeatureRecipe<br/>The Binding"]
T["Plugin<br/>The Wasm Plugin"]
CC -.->|"Resolved to"| CD
CapC -.->|"Resolved to"| CapD
ENV -->|"Resolves Interfaces to"| CD
ENV -->|"Resolves Interfaces to"| CapD
EB -->|"Renders via"| T
- Роль: інженер інфраструктури / Ops. Відповідає за фізичну реальність, призначення мережевих портів і логіку шаблонів.
- 4. Recipe: шаблон перекладу для багатьох постачальників (наприклад, Helm або Docker Compose). Встановлює суворий API-контракт 1:1 з компонентом каталогу через ключове слово
implements. Сутність Recipe зіставляє.valuesрозробника з фізичним форматом. Жорстко закодовує фізичні мережеві порти (наприклад,5432) і читаєprovidesцілі через конвеєр.context.uses, виконуючи контракт впровадження без жорсткого закодовування назв баз даних. - 5. FeatureRecipe: явно зіставляє
Featureз конкретною інфраструктурною реалізацією через ключове словоimplements. Вимагає вказати вcapabilityцільову можливість провайдера (наприклад,helm,compose). Оскільки платформа уніфікує керування обліковими даними в сутності Feature, сутності FeatureRecipes обробляють як операційні функції (маскування даних, DNS-маршрутизація, впровадження sidecar), так і функції облікових даних (генерування CRD сховища, монтування томів секретів). Щоб охопити весь цей спектр, підтримує три окремі блоки виконання:pipeline: послідовний масив плагінів WebAssembly (Wasm) для мутації сутності Workload після рендерингу (наприклад, впровадження sidecar Envoy через JSONPatch або монтування тому секретів).sourceіvaluesMapping,workload,artifacts: ті самі три види вхідних даних, що їх несе сутність Recipe; використовуються для генерування ресурсів, дозволяючи Ops нативно рендерити статичні шаблони (наприклад, генерувати новий CRDHTTPRouteабо CRDExternalSecret) поруч із базовим компонентом.injectMapping(перехоплення перед рендерингом): нативний блок шаблону Go, що виконується до рендерингу базової сутності Recipe. Він виводить словник JSON, який компілятор нативно глибоко зливає поверх конвеєра пам’яті.context.injectвикликача, що дає змогу без Wasm змінювати змінні середовища й рядки підключення на боці викликача.
- Патерн сутності FeatureRecipe для облікових даних: коли сутність FeatureRecipe реалізує сутність Feature для облікових даних (з міткою
feature.aggrega.ai/kind: secret), застосовується стандартний принцип двочастинної сутності Plugin:pipelineпоєднує плагін Fetcher (що генерує CRD, специфічний для сховища), за яким іде плагін Injector (що монтує секрет у цільовий контейнер). Поділ на Fetcher та Injector максимізує повторне використання — перехід з AWS Secrets Manager на HashiCorp Vault вимагає лише заміни плагіна Fetcher; Injector залишається ідентичним.
- 6. Plugin: плагін WebAssembly з адресацією за вмістом. Сутність Plugin для рендерингу постачальника (
pluginType: provider) — це одиниця, що перетворює вхідні види сутності Recipe на остаточний формат файлу у вигляді рядка: вона оголошує вspec.provider.capabilitiesназву чи назви постачальників, яких обслуговує (наприклад,helm), надає експортrender_node, до якого компілятор спрямовує виклики, а решту метаданих свого сокета постачальника (workloadSchema,wellKnownAnnotations) несе в тому самому блоціspec.provider. Інші типи сокетів, які може оголосити сутність Plugin, — цеpipeline-step,linter,governance,cli,parserіimporter. Компілятор маршрутизує закріплене посилання; середовище виконання WebAssembly виконує байти.
Домен 4: маршрутизація та політики («клей»)
graph TD
classDef ext stroke-dasharray:5 4;
A["Aggregate"]:::ext
EB["Release<br/>The Deployment Router"]
ENV["Manifest<br/>The Dependency Lockfile"]
CapC["Feature"]:::ext
T["Plugin"]:::ext
CD["Recipe"]:::ext
CapD["FeatureRecipe"]:::ext
A -->|"Binds via"| EB
EB -.->|"Attaches"| CapC
EB -->|"Uses"| ENV
EB -->|"Renders via"| T
ENV -->|"Resolves Interfaces to"| CD
ENV -->|"Resolves Interfaces to"| CapD
- Роль: Platform Operator / DevOps.
- 7. Manifest: lock-файл залежностей. Використовує пласке зіставлення URI: словник
components.typeзіставляє типи компонентів каталогу з URI сутностей Recipe, а словникfeatures.typeзіставляє типи сутностей Feature з URI сутностей FeatureRecipe. Розв’язання — це прямий пошук URI в lock-файлі та каталозі; визначення можливостей випливає з поляspec.capabilityкожної розв’язаної сутності Recipe під час збирання. Після розв’язання кожна сутність мусить мати зіставлення, інакше компілятор зупиняється. Щоб зберегти екосистему DRY, сутності Manifests підтримують патерн композиції в стилі Kustomize через ключове словоextends, що дає змогу маніфестам для конкретних середовищ (як-от локального чи staging) чисто успадковувати від глобального базового маніфесту й оголошувати лише власні перевизначення. - 8. Release: маршрутизатор. Прив’язує
aggregateдоmanifestі зіставляє компоненти з фізичними межами (наприклад,aws-eks-production). Щоб зберегти робочий процес DRY, сутності Releases підтримують успадкування через ключове словоextends, що дає змогу випускам для конкретних середовищ чисто успадковувати від глобального базового випуску. Виконує абстрактний контракт aggregate, впроваджуючи фізичні реалії суворо в блокparameters, а фізичне визначення розмірів (як-от CPU чи порти) впроваджує через паралельний простір іменinfra. Щоб захистити сутність Aggregate як єдине джерело істини, схема сутності Release механічно забороняє блокvalues:— Ops не можуть із сутності Release оголоситиvaluesдля жодної сутності Component чи Feature. Варіювання значень для розробника залежно від середовища проходить через Parameter Hoisting: розробник відкриває типізоване полеparameters.*у сутності Aggregate, шаблонvaluesсутності Component посилається на нього, а сутність Release заповнює параметр для свого середовища. Відрендерені значення відрізняються між середовищами, тоді як сутність Aggregate — авторська поверхня, що визначає, які значення існують і як вони передаються, — залишається єдиним джерелом істини. Явно сформульовану заборону на рівні схеми див. в обмеженні 4 «Release не може перевизначати значення розробника» в розділі Архітектурні обмеження та рекомендовані патерни. Важливо, що для запобігання невідстежуваним сутностям Releases, які «змінюють aggregate», коли сутність Release використовуєextends, оголошенняaggregateвідхиляється схемою сутності Release (обмеження схеми не дозволяє оголошуватиaggregate, коли використовуєтьсяextends). Дочірній випуск мусить відповідати точно тому самому наміру розробника, що й батьківський. Натомістьmanifestстає необов’язковим, що відкриває «пізнє зв’язування» — Ops можуть успадкувати всю фізичну топологію, але точково замінити lock-файл залежностей.- Приєднання сутностей Feature: сутність Release також приєднує сутності Features — у
featuresна межі або на окремому компоненті. Сутність Feature, усі входи якої операційні, вона приєднує безпосередньо, з їїtypeтаinfra; сутність Feature, приєднану сутністю Aggregate, вона розмірює, записуючиinfraцього приєднання під тим самим ім’ям.
- Приєднання сутностей Feature: сутність Release також приєднує сутності Features — у
Навіщо відокремлювати сутність Manifest від сутності Release. Відокремлення lock-файлу програмного забезпечення (Manifest) від маршрутизатора розгортання (Release) уможливлює форму, якої жодна з цих сутностей не створила б сама: DevOps розгортає один застосунок на кількох регіональних маршрутизаторах розгортання — різних сутностях Releases, що націлені на різні хмарні регіони й усі посилаються на ту саму сутність Manifest, — без дублювання прив’язок сутностей Recipe між середовищами. Кожна регіональна сутність Release несе своє розташування меж і параметри для свого середовища, використовуючи той самий lock-файл програмного забезпечення, який надає сутність Manifest. Масштабування на кілька регіонів випливає з розділення доменів, а не з дублювання сутності Manifest.
Рівень 3: бібліотеки (повторне використання каталогу)
graph LR
classDef ext stroke-dasharray:5 4;
CC["Component"]:::ext
CapC["Feature"]:::ext
CD["Recipe"]:::ext
CapD["FeatureRecipe"]:::ext
SL["SchemaLibrary<br/>JSON Schema definitions"]
ML["MappingLibrary<br/>Go template fragments"]
WL["WorkloadLibrary<br/>Workload template fragments"]
AL["ArtifactLibrary<br/>Named artifact bundles"]
CC -.->|"$ref"| SL
CapC -.->|"$ref"| SL
CD -.->|"valuesMapping $import"| ML
CapD -.->|"$import"| ML
CD -.->|"workload $import"| WL
CD -.->|"artifacts $import"| AL
CapD -.->|"$import"| AL
- Роль: Platform Architect (та сама персона, що й у домені 2), але ця роль вступає в дію лише тоді, коли вміст каталогу виростає настільки, що виграє від повторного використання схем між сутностями Component або повторного використання між сутностями Recipe шаблонів, форм робочих навантажень чи пакетів артефактів. Автори-одинаки та невеликі каталоги обходяться без жодних сутностей рівня 3.
- 9. SchemaLibrary: багаторазово використовувані визначення JSON Schema 2020-12. Бібліотека оголошує іменовані схеми в
spec.schemas:і необов’язкові параметризовані помічники вspec.templates:(з оголошеннями$params:і посиланнями$instantiate:для параметричного повторного використання). Сутності каталогу використовують записи бібліотеки через стандартне ключове слово JSON Schema$ref:, що вказує на запис бібліотеки за ідентичністю, — у формі без хоста<library>#/schemas/<name>(версія береться з lock-файлу, а не з посилання). Іменування в PascalCase, розповсюдження через OCI, закріплення в lock-файлі. Необов’язкова, для каталогів, яким потрібне повторне використання схем між сутностями Component: спільні форми, як-отPodResources,PersistenceSpec,NodePool,MetricsServiceMonitor, повторюються в кожній сутності Component сховища даних і кожній сутності Component робочого навантаження, а записи сутності SchemaLibrary виносять це повторення з авторського опису кожної сутності Component. - 10. MappingLibrary: багаторазово використовувані фрагменти шаблонів Go. Бібліотека оголошує іменовані шаблони в
spec.mappings:. Сутності Recipes і FeatureRecipes використовують записи бібліотеки за ідентичністю черезvaluesMapping: { $import: <library>#/mappings/<name> }. Єдиний авторський режим (лише шаблони Go); паралельного авторського шляху на Jsonnet немає. Необов’язкова, для каталогів, яким потрібне повторне використання зіставлень між сутностями Recipe: спільні патерни, як-от логіка помічників чартів Bitnami чи спільні патерни шаблонів подів, повторюються в кожній сутності Recipe сховища даних, націленій на того самого постачальника, а записи сутності MappingLibrary виносять це повторення з авторського опису кожної сутності Recipe. - 11. WorkloadLibrary: багаторазово використовувані фрагменти шаблонів сутності Workload. Бібліотека оголошує іменовані записи робочих навантажень у
spec.workloads:. Сутність Recipe використовує запис за ідентичністю черезworkload: { $import: <library>#/workloads/<entry> }, а імпортований вміст валідується щодо схеми сутності Workload, що належить платформі, точно так само, як вбудований блокworkload:, — тож робоче навантаження, імпортоване з бібліотеки, рендериться ідентично до рівноцінного вбудованого. Єдиний авторський режим (лише шаблони Go). Необов’язкова, для каталогів, яким потрібне повторне використання робочих навантажень між сутностями Recipe, коли кілька сутностей Recipes мають спільну форму розгортання й відрізняються лише значеннями. - 12. ArtifactLibrary: багаторазово використовувані іменовані пакети артефактів. Бібліотека оголошує іменовані пакети в
spec.artifacts:; кожен пакет групує вихідні файли, що належать разом, — наприклад, CRD, його RBAC і ConfigMap — і імпортується як одна одиниця. Сутності Recipes і FeatureRecipes використовують пакет за ідентичністю черезartifacts.<name>: { $import: <library>#/artifacts/<name> }. Єдиний авторський режим (лише шаблони Go). Необов’язкова, для каталогів, яким потрібне повторне використання артефактів між сутностями Recipe, коли той самий набір допоміжних ресурсів супроводжує багато сутностей Recipes.
Кожна бібліотека публікується через OCI, закріплюється в lock-файлі (розділи schema_libraries:, mapping_libraries:, workload_libraries: і artifact_libraries:) і з’являється в інтерфейсі Hub з обізнаністю про споживачів (які сутності Components посилаються на які записи бібліотеки; які сутності Recipes використовують які записи бібліотеки).