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

Таксономія сутностей

Архітектура 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:

#СутністьДоменРоль
1AggregateДомен 1 — Намір розробникаКреслення топології застосунку
2ComponentДомен 2 — Platform CatalogАбстрактний інтерфейс обчислювального вузла
3FeatureДомен 2 — Platform CatalogОпераційна ознака (зокрема сутності Features для облікових даних)
4RecipeДомен 3 — Інфраструктурна основаРеалізація сутності Component для кожного постачальника
5FeatureRecipeДомен 3 — Інфраструктурна основаРеалізація сутності Feature для кожного постачальника
6PluginДомен 3 — Інфраструктурна основаПлагін WebAssembly з адресацією за вмістом (рендеринг постачальників, кроки конвеєра, лінтинг)
7ManifestДомен 4 — Маршрутизація та політикиLock-файл залежностей, що зіставляє інтерфейси із сутностями Recipes
8ReleaseДомен 4 — Маршрутизація та політикиМаршрутизатор розгортання, що прив’язує сутність Aggregate до сутності Manifest
9SchemaLibraryРівень 3 — БібліотекиБагаторазово використовувані визначення JSON Schema 2020-12
10MappingLibraryРівень 3 — БібліотекиБагаторазово використовувані фрагменти шаблонів Go
11WorkloadLibraryРівень 3 — БібліотекиБагаторазово використовувані фрагменти шаблонів сутності Workload
12ArtifactLibraryРівень 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.

Онтологія як мітка. Операційну хмарну онтологію оголошено в 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 сховища, монтування томів секретів). Щоб охопити весь цей спектр, підтримує три окремі блоки виконання:
    1. pipeline: послідовний масив плагінів WebAssembly (Wasm) для мутації сутності Workload після рендерингу (наприклад, впровадження sidecar Envoy через JSONPatch або монтування тому секретів).
    2. source і valuesMapping, workload, artifacts: ті самі три види вхідних даних, що їх несе сутність Recipe; використовуються для генерування ресурсів, дозволяючи Ops нативно рендерити статичні шаблони (наприклад, генерувати новий CRD HTTPRoute або CRD ExternalSecret) поруч із базовим компонентом.
    3. 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 цього приєднання під тим самим ім’ям.

Навіщо відокремлювати сутність 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 використовують які записи бібліотеки).