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

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/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"

Родительская сущность Aggregate:

apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: parent-app
version: 1.0.0
spec:
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/v1beta1
kind: Aggregate
metadata:
name: web-app
version: 1.0.0
spec:
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 }} и т. д.

Проверка контракта параметров

Сначала при чтении проверяется сам контракт — проверки границ длины и шаблонов, описанные выше в разделе «Словарь слотов параметров». Затем при обработке параметров компилятор выполняет три подэтапа:

  1. Заполнение значений по умолчанию — слоты, для которых определён default: и для которых сущность Release не передала значение, получают своё значение по умолчанию. Для параметров с вложенными объектами действует семантика из трёх случаев для опущенного, явно пустого и частично заданного родительского слота: если родитель опущен, заполняются значения по умолчанию дочерних элементов; если родитель задан как {}, явная пустота сохраняется (значения по умолчанию дочерних элементов подавляются); если родитель задан как непустая карта, заполняются только те дочерние элементы, которые сущность Release не передала. Примеры YAML и руководство по выбору «когда использовать каждую форму» см. в templates/parameters-context.md.
  2. Проверка контракта — каждое значение в объединённой карте, переданное сущностью Release или заполненное из default:, проверяется на соответствие объявленным ограничениям type / enum / min / max / pattern / вложенной структуры. При неудачной проверке сборка останавливается с понятной ошибкой, в которой указаны проблемный слот, переданное значение и нарушенное ограничение. Отсутствующие обязательные параметры без default: вызывают аналогичную остановку с именем слота.
  3. Интерполяция — компилятор вычисляет весь текст сущности 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/v1beta1
kind: Aggregate
metadata:
name: anchored-app
version: 1.0.0
defs:
- &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, которым не нужны якоря, он полностью опускается.