Таксономия данных и композиция
Унифицированная таксономия данных и правила композиции
Чтобы задать предсказуемую схему и устранить когнитивное трение, платформа использует ровно пять общепонятных ключевых слов и структуру 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 непосредственно к исходящему вызову. Например, смоделировав Stripe API как отдельный узел, разработчик может прикрепить к нему функцию 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приложения.