Aggregate
Концептуальная роль сущности Aggregate (Домен 1 — декларативный чертёж топологии от разработчика) описана в architecture/04-entity-taxonomy.md. Паттерны композиции (подсистемы, вложенные агрегаты, Zero-Port Convention, Parameter Hoisting) описаны в architecture/06-data-taxonomy-and-composition.md. На этой странице рассматривается поверхность разработки каталога для сущности Aggregate, а именно создание повторно используемых модулей Aggregate для распространения через каталог.
Область видимости Component: подсистема по умолчанию
Сущность Aggregate организует компоненты в подсистемы — именованные группы для сквозных аспектов (уровень данных, пограничный уровень), у каждой из которых свой каскад аннотаций. У большинства сущностей Aggregates одна группа, поэтому она не требует лишних церемоний.
Единая область (по умолчанию). Объявляйте компоненты непосредственно в spec.components: и опустите блок subsystems::
spec: components: api: type: core/server:1.0.0 worker: type: core/worker:1.0.0Компилятор объединяет их в синтезированную подсистему default. Идентичность узлов не меняется — api остаётся api, а не default.api, — поэтому сущность Aggregate, написанная таким образом, взаимозаменяема с явной формой с одной подсистемой, а обращение к ней (в целях uses:, в диагностике) использует простой путь spec.components.<name>. Синтезированная область честно фиксируется в экспортируемом IR (с маркером синтезированной подсистемы), но никогда не появляется в путях, которые автор пишет или читает.
Несколько областей. Когда компоненты делятся на отдельные сквозные группы, объявите именованные подсистемы в subsystems:. Каждая подсистема содержит собственные компоненты и каскад аннотаций и может включать вложенные подсистемы.
Взаимоисключаемость. spec.components: и spec.subsystems: взаимоисключающие в корне сущности Aggregate — используйте одно или другое, но не оба. Документ, объявляющий оба, останавливается при загрузке с ошибкой конверта. (Подсистема, которую разработчик явно называет default, — обычная объявленная подсистема, к которой обращаются по её полному пути spec.subsystems.default.components.<name>: опускание синтезированной области определяется происхождением, а не именем.)
Переиспользуемые модули Aggregate
Сущности Aggregates выступают и корневой сущностью Aggregate, которую собирает Release, и повторно используемыми модулями. Родительская сущность Aggregate может объявить дочернюю сущность Aggregate точно так же, как компонент, передавая в неё parameters. Чтобы избежать тесной связанности, дочерние сущности Aggregates предоставляют контракт exportedComponents:, устанавливающий стабильное имя публичного интерфейса. Родитель обращается к компонентам модуля только через этот интерфейс: цель uses: — это имя модуля, точка и один из его экспортированных псевдонимов, а компилятор подключает ребро к внутреннему компоненту, который называет псевдоним. Цель, обращающаяся внутрь модуля по любому другому имени — имени компонента внутри модуля или пути в модуль, вложенный в него, — останавливает сборку с указанием модуля и экспортируемых им псевдонимов; см. A uses target names a module’s component the module does not export (Цель называет компонент модуля, который модуль не экспортирует).
Зачем явный список exportedComponents:. Авторы модуля решают, какие из его компонентов образуют публичный интерфейс, а какие остаются деталью реализации. Поскольку родитель может назвать только то, что публикует список, внутренности модуля можно рефакторить — переименовать компонент, разделить один компонент на два, заменить worker управляемым сервисом, — не ломая ни одного родителя, пока каждое опубликованное имя по-прежнему указывает на компонент. Список стоит одну запись на каждый опубликованный компонент, и компонент можно опубликовать под его собственным именем (store: store), если именно это имя должны использовать импортирующие. То же правило действует внутри композиции: модуль обращается к импортируемому модулю через экспортированные псевдонимы этого модуля. Release может связать два компонента одного модуля друг с другом, поскольку такое соединение не пересекает интерфейс ни одного модуля.
Повторный экспорт интерфейса вложенного модуля. Запись exportedComponents: может указывать не на непосредственно объявленный компонент, а на экспортированный псевдоним вложенного подагрегата — так модуль повторно публикует часть импортируемого модуля под своим именем интерфейса, при необходимости с новым именем. Ребро uses:, нацеленное на такой повторно экспортированный псевдоним, транзитивно разрешается по цепочке до конкретного внутреннего узла, поэтому модуль включает более глубокие модули в свой публичный интерфейс, не раскрывая их внутренней структуры, а потребителю никогда не нужно знать, насколько глубоко вложена цель. Дисциплина стабильного интерфейса соблюдается на каждом шаге: каждый модуль повторно экспортирует только то, что решает опубликовать. Повторно экспортированная цель, не разрешающаяся ни в один внутренний узел, явно останавливает сборку так же, как прямая висячая цель, а цепочка повторного экспорта, замыкающаяся на себя, отклоняется, а не обходится бесконечно.
Объявления модуля проверяются так же, как объявления Aggregate. Документ модуля читается только тогда, когда собирается импортирующая его композиция, и его объявления проверяются с этого момента на любой глубине вложенности. Собственный блок inject: компонента модуля подчиняется списку разрешённых spec.inject его типа, а также правилам, запрещающим дважды заявлять один ключ доставки и читать ключ, который тип не публикует. Прикрепление, записанное в одной из собственных подсистем модуля, может называть только сокет, объявленный его сущностью Feature, как и прикрепление, которое сущность Release записывает для компонента, предоставленного модулем.
Прикрепления подсистем модуля распространяются на его компоненты. Feature, которую модуль прикрепляет в одной из собственных подсистем, каскадно распространяется на каждый компонент, объявленный модулем под этой подсистемой, включая вложенные подсистемы, точно так же, как прикрепление подсистемы в Aggregate, — и только на эти компоненты, никогда на компонент импортирующего Aggregate под подсистемой с тем же именем. Оно вычисляется сразу после собственных прикреплений компонента, внешние подсистемы раньше внутренних. Для поля, которое записывают оба, побеждает собственное одноимённое прикрепление компонента, а поля, которые оно опускает, сохраняют значения подсистемы. Каждый компонент, которого оно достигает, проверяет его по appliesTo сущности Feature. Замечание о собственных объявлениях модуля называет модуль и ключ в его документе — например, .spec.subsystems.<subsystem>.features.<attachment>, — поэтому правку вносят в модуле, где находится объявление, а не в импортирующем его Aggregate.
Расположение в каталоге
Переиспользуемый модуль Aggregate располагается в каталоге вида aggregate/ по пути, который сегмент за сегментом задаёт его metadata.name, с каталогом версии на последнем уровне:
aggrega-catalog/└── aggregate/ └── {module-name}/ # the module's metadata.name, segment for segment └── {version}/ # the module's metadata.version └── aggregate.yaml # The module definitionИмя модуля может начинаться с сегмента {publisher}, называющего поставщика или автора — core для стандартной библиотеки, acme для предприятия, — и опубликованные модули стандартной библиотеки названы именно так: core/agenta находится в aggregate/core/agenta/1.0.0/aggregate.yaml. Имя из одного токена располагается на уровень выше, в aggregate/{module-name}/{version}/aggregate.yaml. Обе формы корректны; имя — это то, что пишет автор, а каталог его отражает. Такое отражение — соглашение каталога, а не то, что проверяет компилятор: модуль находится по объявленному им имени, а не по расположению его файла.
OCI URI: hub.aggrega.ai/aggregate/{module-name}:{version} в нижнем регистре — так, модуль с именем core/agenta публикуется в hub.aggrega.ai/aggregate/core/agenta:1.0.0, а модуль с именем db-module — в hub.aggrega.ai/aggregate/db-module:1.0.0.
Шаблон модуля
Дочерний модуль (aggregate/child-database-module/1.0.0/aggregate.yaml, опубликован как hub.aggrega.ai/aggregate/child-database-module:1.0.0):
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"Родительская сущность Aggregate:
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: parent-app version: 1.0.0spec: aggregates: finance-db-subsystem: type: child-database-module:1.0.0
components: billing-api: type: core/python-worker:1.0.0 uses: databases: - finance-db-subsystem.primary_dbМетки модулей
Когда сущность Aggregate публикуется в каталоге как повторно используемый модуль, она может нести metadata.labels в своей YAML-оболочке — например, aggregate.aggrega.ai/tier: infrastructure или aggregate.aggrega.ai/compliance: pci-dss. Эти метки описывают идентичность модуля и хранятся в опубликованном документе модуля; пока ни одна команда их не читает. Поиск по каталогу не индексирует сущности Aggregates, а граф сборки не несёт ни меток модуля, ни его имени в каталоге, поэтому политика управления не может выбирать компоненты модуля по модулю, из которого они пришли.
Ключевое различие. Метки сущности Aggregate описывают идентичность переиспользуемого модуля в каталоге. Они не распространяются вниз на дочерние узлы компонентов. Метки компонентов берутся исключительно из сущности каталога Component в домене 2. Если разработчик импортирует модуль с меткой aggregate.aggrega.ai/tier: infrastructure, отдельные компоненты внутри этого модуля сохраняют только собственные метки, заданные в каталоге (например, component.aggrega.ai/type: stateful-server). Метка сущности Aggregate никогда не внедряется в словарь labels узла IR.
Полное обсуждение составных сущностей Aggregates и шаблона модулей (включая правило об отсутствии подкомпонентов у сущностей Components), а также механизма сквозной группировки subsystems см. в architecture/06-data-taxonomy-and-composition.md §6. Поверхность описания типизированного контракта parameters см. в vocabulary/data-pillars.
Типизированные контракты параметров
Блок spec.parameters: сущности Aggregate объявляет типизированный контракт для параметров, которые заполняет сущность Release. Каждый слот параметра содержит объявленный type, необязательное description, необязательное значение default, необязательные ограничения области значений и (для слотов объектного типа) вложенную структуру. Во время разрешения компилятор проверяет каждое значение, переданное сущностью Release, на соответствие контракту — до того, как выполняется интерполяция параметров.
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: web-app version: 1.0.0spec: parameters: region: type: string description: Cloud region the deployment targets enum: [us-east-1, us-west-2, eu-west-1, ap-northeast-1] default_locale: type: string description: Default UI locale presented to end users enum: [en-US, en-GB, fr-FR, ja-JP] default: en-US enable_debug: type: boolean description: Toggle verbose request logging default: false feature_flags: type: object description: Per-feature enablement map valuesType: { type: boolean } default: {} allowed_hosts: type: array description: Hostnames the ingress accepts items: { type: string, format: hostname } min: 1 default: ["web-app.example.com"]
components: web: type: core/web-server:1.0.0 values: default_locale: "{{ .parameters.default_locale }}" region: "{{ .parameters.region }}" debug: {{ .parameters.enable_debug }}Кавычки в каждой ссылке расставлены намеренно: именно они определяют тип, с которым поступает поднятое значение. См. templates/parameters-context.md.
Словарь слотов параметров
Типизированный блок parameters: принимает словарь компактной формы: type, description, default, enum, min, max, pattern, minLength, maxLength, format, validate и validateMessage (пользовательская проверка и сообщение, которое она выдаёт), items (для массивов), properties (для объектов), valuesType (для карт типизированных значений) и required: true (маркер на уровне слота). Три из этих ключевых слов принимают в качестве значения контракт, а не простую настройку, — items, valuesType и каждая запись в properties, — и в слоте параметра такой вложенный контракт записывается в той же типизированной форме, что и окружающий его слот: valuesType: { type: boolean }, а не valuesType: boolean. Перед интерполяцией компилятор напрямую проверяет объединённую карту параметров на соответствие этим объявлениям: параметр, который не объявлен ни одним слотом, отклоняется; слот с пометкой required: true, который не заполняет сущность Release и для которого нет default, останавливает сборку; каждое переданное значение проверяется на соответствие объявленному type слота, принадлежность к enum, границам minLength и maxLength, регулярному выражению pattern и format для строкового слота, а также границам min и max — значению числового слота, длине строкового слота и числу элементов слота-массива. Слоты объектов и массивов проверяются рекурсивно: каждая запись в properties и каждый элемент относительно items проверяются так же, контракт valuesType управляет ключами, которые не названы в properties, а вложенный ключ, не названный ни одним объявлением, отклоняется. Полный словарь ключевых слов, в том числе случаи, когда столп schema: записывает эти ключевые слова иначе, см. в vocabulary/compact-form-authoring.md.
Перечисленные ниже ключевые слова проверяются также в самом объявлении, до чтения любого значения из сущности Release, поэтому слот, который не может ничего ограничить, останавливает сборку, даже если ни одна сущность Release его не заполняет:
- Границы длины — ноль или больше. Отрицательное значение
minLengthилиmaxLengthв собственном объявлении параметра отклоняется схемой сущности Aggregate при её загрузке с указанием параметра и ключа. Внутри вложенного контракта — вitems,propertiesилиvaluesType— граница длины читается так, как записана, и при загрузке сущности Aggregate не проверяется на этот нижний предел, поэтому и там указывайте ноль или больше: отрицательноеminLengthничего не ограничивает, а отрицательноеmaxLengthотклоняет любое значение. minиmaxдолжны что-то ограничивать. В логическом или объектном слоте эта пара ничего не ограничивает, поэтомуminилиmax, записанные там, отклоняются при загрузке сущности Aggregate с указанием параметра и ключа.- Шаблон должен компилироваться. Каждый
patternкомпилируется как регулярное выражение при чтении контракта параметров — в самом слоте и внутри любого вложенного контракта, на любой глубине, — и шаблон, который не компилируется, отклоняется с указанием параметра, шаблона и причины. Контракт читается при каждой сборке, загрузке и проверке сущности Release, которые затрагивают сущность Aggregate, — будь то собственная сущность Aggregate этой сущности Release или модуль, который эта сущность Aggregate импортирует. Затем при проверке значений каждое переданное значение сопоставляется с тем же скомпилированным выражением. - Формат должен быть одним из проверяемых компилятором.
formatназывает один из форматовemail,uri,hostname,ipv4,ipv6,uuid,date-timeиdateв написании JSON Schema. Любое другое имя — опечатка вродеemialили имя, не определённое в JSON Schema, напримерpassword, — отклоняется при загрузке сущности Aggregate с указанием параметра и списком поддерживаемых имён: в самом слоте — схемой сущности Aggregate, а внутри вложенного контракта, на любой глубине, — при чтении контракта параметров. Затем переданная строка, не соответствующая названному формату, отклоняется с указанием параметра, значения и формата. Что проверяет каждое имя, описано вvocabulary/compact-form-authoring.md.
Параметры объектного типа и типа массива
Слоты параметров принимают любой тип, поддерживаемый компактной формой, включая вложенные объекты и массивы типизированных элементов:
spec: parameters: database_config: type: object description: Database connection configuration properties: host: { type: string, required: true } port: { type: integer, min: 1, max: 65535, default: 5432 } ssl_mode: { type: string, enum: [disable, require, verify-full], default: require } pool_size: { type: integer, min: 1, max: 100, default: 10 }
metric_labels: type: array description: Custom Prometheus labels to attach to scraped metrics items: type: object properties: name: { type: string, required: true } value: { type: string, required: true }Сущность Release заполняет параметры объектного типа структурированным YAML; компилятор проверяет структуру на соответствие объявленной схеме до интерполяции. Шаблоны, ссылающиеся на поля объекта, используют стандартный синтаксис шаблонов Go: {{ .parameters.database_config.host }}, {{ .parameters.database_config.port }} и т. д.
Проверка контракта параметров
Сначала при чтении проверяется сам контракт — проверки границ длины и шаблонов, описанные выше в разделе «Словарь слотов параметров». Затем при обработке параметров компилятор выполняет три подэтапа:
- Заполнение значений по умолчанию — слоты, для которых определён
default:и для которых сущность Release не передала значение, получают своё значение по умолчанию. Для параметров с вложенными объектами действует семантика из трёх случаев для опущенного, явно пустого и частично заданного родительского слота: если родитель опущен, заполняются значения по умолчанию дочерних элементов; если родитель задан как{}, явная пустота сохраняется (значения по умолчанию дочерних элементов подавляются); если родитель задан как непустая карта, заполняются только те дочерние элементы, которые сущность Release не передала. Примеры YAML и руководство по выбору «когда использовать каждую форму» см. вtemplates/parameters-context.md. - Проверка контракта — каждое значение в объединённой карте, переданное сущностью Release или заполненное из
default:, проверяется на соответствие объявленным ограничениямtype/enum/min/max/pattern/ вложенной структуры. При неудачной проверке сборка останавливается с понятной ошибкой, в которой указаны проблемный слот, переданное значение и нарушенное ограничение. Отсутствующие обязательные параметры безdefault:вызывают аналогичную остановку с именем слота. - Интерполяция — компилятор вычисляет весь текст сущности Aggregate как шаблон, прежде чем читать его как YAML, и заменяет каждую ссылку
{{ .parameters.<slot> }}— обычно внутри строкvalues:компонентов, фич или вложенных агрегатов — разрешённым значением; любые другие{{в тексте тоже читаются как синтаксис шаблона, поэтому значение, содержащее собственные двойные фигурные скобки (например, экспортированное определение платформы потоков), записывает каждую{{как{{"{{"}}, как описано в разделе Текст с собственными двойными фигурными скобками. После этого прохода поверхности шаблонов значений получают уже интерполированные литералы и не получают.parametersв своём контексте шаблона.
Объединённая карта параметров остаётся доступной на протяжении рендеринга, чтобы поддерживать вычисление шаблонов путей. Заданные оператором шаблоны directory: и subDirectory: на границах сущности Release читают .parameters.<slot> напрямую во время рендеринга по закрытому списку разрешённых значений; формированию путей нужен словарь регионов и окружений для раскладки артефактов по окружениям, а асимметричное предоставление доступа удерживает эту задачу оператора внутри поверхности оператора, без передачи туда и обратно через values сущности Aggregate. Карта остаётся доступной для чтения, пока не завершатся все фазы рендеринга, и достижима только из той компиляции, для которой она была разрешена; рецепты, использующие заданные разработчиком values:, видят строки после интерполяции, а шаблоны путей видят актуальные данные .parameters на протяжении рендеринга. Матрицу доступности шаблонов путей см. в строке 3 templates/expansion-matrix.md, а список разрешённых переменных шаблонов путей — в path-template-variables.md.
Более широкий контрольный список подъёма параметров (объявление в сущности Aggregate → ссылка в values → заполнение в сущности Release → использование в сущности Recipe) и механику между столпами см. в vocabulary/data-pillars.md, §«Parameters» и §«The parameter-hoisting checklist». Поля контекста шаблона, доступные при интерполяции, и исключение для шаблонов путей см. в templates/parameters-context.md.
Ребро uses — это вызов, который объявляет Aggregate
Ребро uses — это утверждение сущности Aggregate о том, что один компонент вызывает другой. Компилятор передаёт вызывающему значения, которые публикует цель, и ничего не ограничивает: само по себе ребро не разрешает доступ вызывающему и не запрещает его никому другому, а рабочая нагрузка, которая обращается к адресу цели без ребра, всё равно до неё доходит.
Ограничение того, кто может вызывать компонент и что может вызывать он сам, — решение оператора, принимаемое для каждого окружения в сущности Release. Если Release прикрепляет к компоненту Feature core/caller-allowlist из каталога стандартной библиотеки, сборка записывает сетевую политику, которая допускает ровно те компоненты, чьи рёбра uses указывают на него, собственные поды этого компонента и источники, названные в прикреплении. Её исходящий аналог, core/egress-allowlist, позволяет компоненту, к которому он прикреплён, обращаться только к компонентам, на которые указывают его собственные рёбра uses, к своим подам, к DNS кластера и к диапазонам адресов, перечисленным в Release. Вызов, который Aggregate не объявляет как ребро, тогда может быть отклонён кластером на любом конце — везде, где его сетевой плагин применяет сетевые политики. Поэтому записывайте ребро для каждого вызова, который делают ваши компоненты, включая вызов, не внедряющий никаких значений: отсутствующее ребро — это вызов, который огороженный компонент может отклонить. model-server-caller-allowlist показывает сервер модели, доступный только через шлюз перед ним.
Собственные вложения соединения: features в записи uses
Соединение, которое компонент задаёт в развёрнутой форме uses:, является отдельной записью, и помимо target, inject и values оно может нести вложения в features:. Каждое из них имеет ключом слот, объявленный сокетом: потребляющая сущность Component перечисляет в featuresSchema сокета слоты, которые может заполнить каждое соединение, проведённое через этот сокет (см. Сокеты топологии). Так один компонент хранит отдельные учётные данные для каждого компонента, к которому обращается, — шлюз, вызывающий две модели с двумя ключами, или агент, предъявляющий модели собственный ключ.
spec: parameters: openai_key_secret: { type: string } components: router: type: core/gateway/litellm # its `models` socket declares a `credential` slot values: { model: gpt } # the alias it publishes as its model uses: models: gpt: target: gpt features: credential: type: core/referenced-secret values: origin: "{{ .parameters.openai_key_secret }}" key: api-key plain: target: plain # this connection carries no attachment gpt: type: core/ai-model/openai values: { model: gpt-4o-mini } plain: type: core/ai-model/ollama values: { model: llama3.1 }Вложение соединения несёт type (обязательно), необязательное description и values для сущности Feature. Оно не несёт ни uses, ни inject: вложение соединения не бывает вложенным, и то, как его материал достигает потребителя, решает Recipe потребляющего компонента, а не блок inject. Документ, в котором написано любое из них, отклоняется при загрузке с указанием ключа.
Только слоты, объявленные сокетом. Вложение под именем, которого нет в featuresSchema сокета, останавливает сборку при загрузке с указанием соединения, сокета, компонента и слотов, которые сокет объявляет, — а если имя отличается от одного из них на одну правку, то и этого слота как вероятного задуманного написания. Затем заполненный слот на каждом соединении проверяется по собственному объявлению слота: selector, которому не удовлетворяют метки сущности Feature, вызывает остановку на этой записи, а слот required, оставленный пустым на любом соединении, вызывает остановку с указанием этого соединения. Сокет, не объявляющий слотов, не допускает вложений на своих соединениях; не допускает их и ad-hoc-сокет — тот, который Aggregate проводит без объявления в сущности Component, — поскольку он вообще не объявляет слотов. Компонент, добавленный подмодулем, подчиняется тому же правилу, а сообщение указывает на собственный документ подмодуля. См. A connection carries an attachment under a name its socket declares no slot for (Соединение несёт вложение под именем, для которого его сокет не объявляет слот).
Соединение, заданное сущностью Feature, вложений не несёт. Собственный блок uses: подключённой сущности Feature — на компоненте или на подсистеме — пишется в той же форме, но отклоняет features: при загрузке документа. Учётные данные, нужные такому соединению, заполняют слот, который Feature объявляет в собственной featuresSchema, и подключаются рядом с Feature; см. Собственные учётные данные сущности Feature.
Имя вложения. Каждое вложение соединения становится вложением потребляющего компонента с именем <alias>.<slot> — псевдоним, под которым записано соединение, точка и слот: выше это gpt.credential. Точка — разделитель, зарезервированный для имён, составляемых компилятором; её не может содержать ни один псевдоним, слот или имя вложения в Aggregate, поэтому составное имя никогда не совпадает с именем, записанным в собственном блоке features: компонента; сущность Release, указывающая его на компоненте или границе, отклоняется (см. Настройка соединений по рёбрам). Под этим именем вложение индексируется на уровне экземпляров сущности Manifest (см. Плоское сопоставление URI), под ним о нём сообщают диагностика и граф IR, и это значение FeatureRecipe вложения читает как .attachment_name (см. Имена, производные от вложения соединения).
Дальше оно разрешается как любое вложение: Manifest связывает его тип Feature с FeatureRecipe, его values проверяются по схеме сущности Feature — об ошибке сообщается на записи соединения, где они записаны, — и его FeatureRecipe отрисовывается по собственным values и infra вложения. От собственных вложений компонента его отличают две вещи:
- Его нет в
.featuresпотребляющей сущности Recipe. Этот раздел несёт только вложения, записанные в собственном блоке компонента, поэтому Recipe, ищущий в.featuresсвои вложения по типу, никогда не получит учётные данные соединения. Recipe читает вложение соединения из самого соединения, по пути.context.uses.<alias>.features.<slot>, в той же форме, что несёт.features, — включая разрешённыеprovides(см. Вложения соединения). - Оно достаётся только потребителю. Отрисованный результат цели одинаков, что бы ни несли достигающие её соединения.
Копия записанного блока в графе. Граф IR хранит блок uses: каждого компонента в записанном виде, и там вложение соединения сохраняет свои type и description, но не values. Значения появляются один раз — на вложении, которое несёт потребитель, где значение, объявленное сущностью Feature как чувствительное, скрывается.
Сущность Release может задать размер объявленного здесь вложения через infra или подключить собственное вложение на достигаемом ею соединении — см. Настройка соединений по рёбрам.
Отключение компонента или модуля: active:
Экземпляр компонента и модуль вложенного агрегата принимают переключатель active:, который определяет, входит ли эта сущность в скомпилированную топологию вообще. Если его опустить, сущность присутствует; это поведение по умолчанию и обычный случай.
spec: parameters: enable_cache: type: boolean default: false components: api: type: core/server:1.0.0 redis: type: core/redis:1.0.0 active: "{{ .parameters.enable_cache }}" aggregates: reporting: type: my-catalog/reporting-module:1.0.0 active: falseМожно записать булево значение напрямую или шаблон над .parameters, который разрешается в булево значение. Именно ради шаблонной формы переключатель и существует: она позволяет сущности Release решать, присутствует ли сущность, через заполнение параметра, так что одна сущность Aggregate охватывает окружения, различающиеся набором развёртываемых частей, — и сущности Release не нужно объявлять ничего, чего не объявила сущность Aggregate.
Что удаляет ложный переключатель. Сущность отсекается до построения графа, и отсечение распространяется каскадом: компонент уносит с собой собственные рёбра uses: и присоединённые Features, а модуль — всё, что он внёс: свои компоненты, их рёбра, их присоединения. Ничего из того, что принесла отсечённая сущность, не рендерится. Отсечение не затрагивает ссылку на неё из уцелевшего места — об этом следующий абзац.
Уцелевший компонент, который всё ещё указывает на отсечённый, останавливает сборку. Если api объявляет ребро uses: на redis, а redis отключён, сборка останавливается, а не позволяет ребру исчезнуть, — иначе внедрённые значения api при развёртывании молча оказались бы пустыми. Решите, какой из двух компонентов нужен в этом окружении: снова включите целевой компонент, поставьте потребителя в зависимость от того же параметра, чтобы пара исчезала вместе, или удалите ребро из блока uses: потребителя.
Записанный переключатель должен разрешаться в булево значение, а пустое значение таковым не является. Переключатель читается строго после разрешения его шаблона, и литерал, который не разбирается как булево значение, останавливает сборку, а не принимает какое-либо значение по умолчанию. Особого внимания заслуживает случай, когда переключатель читает параметр без значения: он разрешается в ничто, и если прочитать ничто как «присутствует», развернулась бы та самая сущность, которую вы поставили в зависимость от этого параметра. Поэтому запись active: без значения после него — не то же самое, что отсутствие ключа: по умолчанию присутствие даёт только переключатель, который никто не записал. Задайте параметру default: в spec.parameters, чтобы у каждого окружения был ответ, или заполните его в сущности Release. Чтобы сущность присутствовала безусловно, удалите ключ active:, а не оставляйте его пустым. Эта остановка описана в разделе «An active: toggle does not resolve to true or false (Переключатель active: не разрешается в true или false)» в справочнике условий остановки.
Отключённый компонент по-прежнему можно назвать из сущности Release. Сущность Release может по-прежнему указывать его в границе, и это сделано намеренно: отключение компонента — это действие автора, и не предполагается, что сущность Release, которая его настраивает, будет переписана в той же правке.
Аннотации на подсистемах и компонентах
И подсистемы, и экземпляры компонентов имеют поле annotations:. Аннотации, написанные разработчиком в Aggregate, запускают каскад аннотаций на стороне Aggregate: аннотация подсистемы распространяется на все вложенные подсистемы и все содержащиеся в ней компоненты, причём более близкий уровень переопределяет значения с гранулярностью до отдельного ключа. Словарь mappings.features.annotations в Manifest объявляет привязки, которые во время сборки преобразуют ключи аннотаций в синтетические присоединения Feature. Инвариант «Aggregate как поверхность авторинга» ограничивает маршрутизацию этих аннотаций путями maps.values привязки; привязка, объявляющая только пути maps.infra, срабатывает со стороны Release, а не со стороны Aggregate.
Формы значений
Каждый ключ аннотации принимает одну из четырёх форм, различающих «я молчу», «я объявляю значение» — скаляр или структурированный объект — и «я отказываюсь»:
- Отсутствующий ключ — область не объявляет значения для этой аннотации. Вложенные подсистемы и содержащиеся компоненты наследуют любую привязку от области-предка.
- Скалярная строка — одно значение. Привязка в Manifest должна объявлять ровно один путь в сумме; скаляр направляется по этому пути.
- Структурированный объект — словарь «подключ — подзначение». Каждый подключ объекта направляется через
mapsпривязки в Manifest в соответствующее поле схемы Feature на объявленной опоре. - Явный YAML
null— область удаляет из своего поддерева любую унаследованную привязку для этого ключа. Соседние компоненты и соседние подсистемы сохраняют наследование; привязку теряет только отказавшаяся область.
spec: subsystems: data: annotations: feature.myco/db-pool: "shared-pool" # scalar value — propagates to api and worker components: api: type: core/server:1.0.0 # inherits feature.myco/db-pool: "shared-pool" worker: type: core/server:1.0.0 annotations: feature.myco/db-pool: null # opts out for this component only special: type: core/server:1.0.0 annotations: feature.myco/db-pool: "vip-pool" # closer-level overrideСтруктурированные значения для многополевых Features
Feature с несколькими настраиваемыми полями предполагает структурированное значение аннотации: один ключ аннотации несёт значения для нескольких полей схемы Feature в одном объявлении. Сторона Aggregate срабатывает только для подключей, опора которых в словаре привязки — values; подключи, направляемые в infra, относятся к аннотациям на стороне Release.
spec: subsystems: data: annotations: feature.myco/db-pool: db_name: "prod-db" read_replicas: 5 components: api: type: core/server:1.0.0 annotations: feature.myco/db-pool: db_name: "api-override" # closer-level override at subkey granularity # read_replicas not listed → inherits 5 from parent analytics: type: core/server:1.0.0 annotations: feature.myco/db-pool: read_replicas: null # per-subkey opt-outСтруктурированные значения распространяются каскадом с глубоким слиянием по подключам: подключи более близкого уровня переопределяют подключи родителя; явный null у подключа подавляет унаследованный подключ для этой области, а соседние подключи остаются в силе. Полное описание структурированных значений — композиция между сторонами с подключами infra на стороне Release, проверка типов по подключам, ослабленная дисциплина значений по умолчанию для полей схемы без объявленного type — см. в providers/well-known-annotations.md, §«Structured annotation values».
Независимость по ключам
Каждый ключ аннотации наследуется, переопределяется и отключается независимо. Компонент, объявляющий annotations.feature.myco/db-pool: null, отказывается только от этого ключа; другие ключи, унаследованные от охватывающей подсистемы, по-прежнему распространяются на этот компонент. Соседние компоненты в той же подсистеме независимо сохраняют собственные словари аннотаций — отказ одного компонента не затрагивает соседей.
Аннотации компонентов верхнего уровня
Компоненты верхнего уровня (объявленные непосредственно в spec.components, а не внутри подсистемы) не имеют унаследованного каскада. Их поле annotations: объявляет значения непосредственно в области компонента; раскрытие синтезирует присоединения Feature из каждой объявленной аннотации, для которой в Manifest есть соответствующая привязка.
Правило каскада на стороне Aggregate применительно к привязкам, разделение «сторона — опора» и полный сквозной пример преобразования аннотаций привязками в синтетические присоединения Feature см. в providers/well-known-annotations.md, §«Aggregate-side annotation cascade».
Шаблоны якорей YAML (блок defs:)
Схема Aggregate допускает необязательный блок defs: на корневом уровне — список строк YAML, который служит исключительно местом размещения стандартных якорей YAML (&anchor) и ссылок на них (*anchor). Компилятор никогда не читает содержимое этого блока; он существует для того, чтобы авторы могли объявлять определения якорей в одном месте и ссылаться на них в остальной части Aggregate, избегая повторения значений (принцип DRY) и не теряя плоский словарь O(1), по которому проходит компилятор. Этот механизм повторяет аналогичный блок defs: в сущности Manifest.
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: anchored-app version: 1.0.0defs: - &default_log_level "info"spec: components: primary: type: core/compute/api-server:1.0.0 values: log_level: *default_log_level secondary: type: core/compute/python:1.0.0 values: log_level: *default_log_levelЯкоря разрешаются на этапе разбора YAML, поэтому к моменту, когда компилятор читает блок значений, *default_log_level уже является строкой "info". Блок defs: — место, где по соглашению размещаются определения якорей; YAML позволяет объявлять якоря где угодно, но их размещение в одном месте сохраняет читаемость остальной части Aggregate. Блок необязателен — в Aggregates, которым не нужны якоря, он полностью опускается.