Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

Таксономия данных и композиция

Унифицированная таксономия данных и правила композиции

Чтобы задать предсказуемую схему и устранить когнитивное трение, платформа использует ровно пять общепонятных ключевых слов и структуру 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.
aggregate.yaml
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: называет модуль и один из его экспортированных псевдонимов, и компилятор подключает ребро к внутреннему компоненту, который называет этот псевдоним, тогда как цель, обращающаяся внутрь модуля по любому другому имени, останавливает сборку, называя модуль и псевдонимы, которые он экспортирует. Модуль может сам реэкспортировать экспортированный компонент вложенного модуля под собственным именем интерфейса — при необходимости переименовав его, — и компилятор транзитивно разрешает такую цепочку реэкспорта до нижележащего внутреннего узла, так что модули компонуются на любую глубину, и родителю не нужно знать, насколько глубоко вложена цель. Цель, которая не разрешается ни в один внутренний узел, по-прежнему громко останавливает сборку, а цепочка реэкспорта, замыкающаяся сама на себя, отклоняется, а не обходится бесконечно.
child-database-module.yaml
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: child-database-module
version: 1.0.0
spec:
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"
parent-app.yaml
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: parent-app
version: 1.0.0
spec:
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 и получить рабочий вывод, не разбираясь сначала в подсистемах или границах. Область по умолчанию — это въезд; объявленные области — это то, куда движется архитектура по мере роста.

Ниже приведены один рекомендуемый шаблон и пять ограничений. Схемы обеспечивают ограничения 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); структурная маршрутизация относится к столпам, проверяемым схемой.
  • Ограничение 4: сущность Release не может переопределять значения разработчика

    • Неподдерживаемый шаблон: Ops пытается из сущности Release переопределить когнитивную логику разработчика (например, изменить workers: 4 на workers: 10).
    • Почему: сущность Aggregate — единый источник истины для намерения разработчика. Если значение жёстко задано в сущности Aggregate, оно неизменно во всех средах. Если значение должно меняться в зависимости от среды, разработчик использует подъём параметров. Схема сущности Release обеспечивает это, запрещая блоки values и ограничивая Ops выполнением контракта parameters и определением физической infra.
  • Ограничение 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 по одному Kubernetes NetworkPolicy на каждую рабочую нагрузку, которую рендерит этот компонент, разрешая исходящий трафик только к его собственным подам, к подам целей его рёбер 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 key

2. Домен 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/v1beta1
kind: Recipe
metadata:
name: oracle-dsn-formatter
version: 1.0.0
spec:
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: 1521

4. Выполнение компилятором при рендеринге (передача)

  1. Компилятор вычисляет сущность Recipe для legacy-oracle. Для сущности Release, предоставляющей legacy_oracle_ip: "10.0.4.55", её primary_endpoint равен oracle://10.0.4.55:1521/PROD_DB.
  2. На helm ссылочная сущность Workload рендерит один ExternalName Service legacy-oracle с externalName: 10.0.4.55 и портом 1521; на compose она ничего не рендерит.
  3. Затем компилятор рендерит сущность 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 в конечном счёте являются лишь физическими облачными ресурсами, они моделируются точно так же, как компоненты приложения.

  1. Платформенная сущность Aggregate: команда инфраструктуры пишет стандартный Aggregate.yaml, компонентами которого являются core/aws-vpc, core/eks-cluster и core/istio-base.
  2. Платформенная сущность Release: команда развёртывает этот агрегат. Рендерер, привязанный к этим платформенным компонентам, выводит артефакты, необходимые для развёртывания базовой инфраструктуры.
  3. Сущность Release приложения: когда разработчик приложения готов развернуть своего ИИ-агента, команда Ops просто указывает только что созданный кластер как цель границы в собственном файле Release приложения.