Таксономия сущностей
Архитектура 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 используют какие записи библиотеки).