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

Release

Концептуальная роль сущности Release (домен 4 — маршрутизатор развёртывания, связывающий сущность Aggregate с сущностью Manifest и распределяющий компоненты по физическим границам) описана в architecture/04-entity-taxonomy.md. Механизм временной последовательности (syncWave для каждой границы), Dynamic Addressing Polyfill и шаблон Parameter Hoisting описаны в architecture/12-day-two-lifecycles.md. На этой странице рассматривается то, как создаётся сущность Release.

Роль сущности Release

Сущность Release связывает aggregate с manifest и сопоставляет компоненты физическим границам развёртывания (например, aws-eks-production). Это единственная точка входа для компиляции: aggrega build --release release.yaml.

Сущность Release выполняет абстрактный контракт агрегата, внедряя физические реалии строго в блок parameters, а физические размеры (например, число CPU или порты) внедряет через параллельное пространство имён infra.

Каждая сущность Release объявляет поле manifest:, указывающее её сущность Manifest (если только Release не использует extends:, который наследует указатель на манифест от родителя). CLI aggrega build читает это поле напрямую; флага CLI --manifest не существует, поэтому спецификация зависимостей хранится в Git вместе с самой сущностью Release, и историю развёртываний можно проверить по собственной истории Git этой сущности Release.

Поля aggregate: и manifest: разрешаются по идентификатору или по файлу с относительным путём — так же, как остальная часть языка разрешает ссылки, — и никогда как основа имени файла относительно сущности Release. Значение ./ или ../ — это явный локальный файл, читаемый напрямую относительно сущности Release. Простой токен — это идентификатор: metadata.name сущности, на которую указывает ссылка. Идентификатор в manifest: разрешается просмотром собственного каталога сущности Release (сущность Manifest — это конфигурация оператора на стороне развёртывания, поэтому у неё нет уровня каталога или реестра). Идентификатор в aggregate: разрешается по полному каскаду — каталог сущности Release, затем каталог (catalog), затем реестр, — поэтому Release может указать опубликованную сущность Aggregate по идентификатору, и один и тот же опубликованный модуль разрешается независимо от того, является ли он spec.aggregate верхнего уровня сущности Release или вложенным агрегатом внутри другой сущности Aggregate. Эта модель «идентификатор или путь» позволяет общей сущности Aggregate лежать в основе многих вариантов Release без привязки ссылки к имени файла, а опубликованную сущность Aggregate — развёртывать напрямую по имени.

Путь остаётся внутри рабочего пространства. Значение ./ или ../ указывает на файл в рабочем пространстве, как и любой другой путь, который записывает Release, — его extends: и $import: в parameters, см. ниже. Путь, который в том виде, как он записан, выходит за пределы рабочего пространства или который выводит за его пределы символическая ссылка на пути, отклоняется до того, как из указанного им файла что-либо будет прочитано. Чтобы развернуть сущность Aggregate, хранящуюся вне рабочего пространства, укажите её по идентификатору и добавьте содержащий её каталог в конфигурацию рабочего пространства как каталог catalog; сущность Manifest, сущность Release, указанная в extends:, и файл параметров читаются рядом с сущностью Release и никогда не ищутся по имени, поэтому они хранятся внутри рабочего пространства. Сущность Release вне рабочего пространства, которую вы указываете в командной строке или которую указывает конфигурация рабочего пространства, является самостоятельным корнем: каждый записанный в ней путь — и каждый путь, записанный в сущности Release, к которой ведёт её цепочка extends:, — должен вести к файлу внутри каталога, содержащего эту сущность Release, а путь, выходящий за пределы этого каталога или выводимый за них ссылкой, отклоняется так же. Храните то, на что указывает такая сущность Release, рядом с ней или собирайте её в рабочем пространстве, содержащем и то и другое. См. errors/fatal-halts.md §“A reference to another file leads out of the directory it must stay inside (Ссылка на другой файл выводит за пределы каталога, внутри которого она должна оставаться)”.

Сущность Release определяет место назначения скомпилированных артефактов; диспетчеризация провайдеров относится к сущности Manifest, на которую указывает Release (о разделении ролей см. Manifest и Release: разделение ответственности).

Метаданные окружения

Блок метаданных каждой сущности Release принимает поле environment: — строку произвольного вида, идентифицирующую окружение, в которое развёртывается Release (типичные значения: production, staging, dev). Поле носит информационный характер: у него нет перечисления, нет шаблона на уровне схемы и нет межсущностной проверки помимо type: string. Компилятор выводит его значение как метку aggrega.ai/environment в каждом манифесте Kubernetes, который рендерит провайдер helm, вместе с остальным набором меток происхождения Aggrega — в записанном виде, если это допустимое значение метки Kubernetes, а иначе переписанным в допустимое значение, причём точное значение передаётся в аннотации aggrega.ai/environment (так, eu/prod получает метку eu-prod); провайдер helm-chart добавляет те же метки к каждому загруженному через $import: артефакту, который он помещает в сабчарт, тогда как собственные шаблоны сабчарта содержат то, что написал их автор. Провайдер compose передаёт то же значение как метку aggrega.ai/environment на каждом сервисе, который он выводит.

Написание environment: определяют пять практических сценариев:

  1. Атрибуция затрат OTel/FinOps. Панели облачных затрат (AWS Cost Explorer, Datadog Cloud Cost Management, CloudHealth) фильтруют поды Kubernetes по тегу окружения. Метка aggrega.ai/environment: production попадает в метки подов через внедрение меток провайдером Helm; отчёты о затратах группируют расходы по aggrega.ai/environment без ручного тегирования каждого ресурса.

  2. Фильтрация трассировок и логов OTel. Панели наблюдаемости (Datadog, New Relic, Honeycomb, Grafana Tempo) фильтруют телеметрию по метке окружения. aggrega.ai/environment: staging позволяет операторам ограничить запросы к логам и поиск трассировок окружением staging без фильтрации по соглашениям об именовании пространств имён или по именам чартов — единая каноническая метка во всём отрисованном результате.

  3. Нацеливание операторов Kubernetes. GitOps-контроллеры (ArgoCD, Flux) и операторы политик (Kyverno, OPA Gatekeeper) иногда фильтруют ресурсы по метке окружения для политик, специфичных для окружения (например, «ресурсы только для production должны иметь метку approved-image-source»). Метка aggrega.ai/environment даёт стабильный селектор, независимый от соглашений о пространствах имён и шаблонов именования.

  4. Различение production в нескольких регионах. Команда, использующая сущность Release production-us-east наряду с сущностью Release production-eu-west — обе с metadata.environment: production, — получает одну и ту же метку aggrega.ai/environment: production во всех регионах. В сочетании с отдельной меткой региона это позволяет сводить затраты по регионам («общие расходы production») и детализировать их по каждому региону.

  5. Ограничение области соответствия требованиям. Сбор свидетельств для SOC 2, PCI и HIPAA ограничивается по окружению (аудит только production и т. п.). Метку aggrega.ai/environment используют инструменты сбора свидетельств соответствия (Vanta, Drata) для фильтрации ресурсов по области аудита.

Схема требует environment: в каждой сущности Release; значение носит информационный характер, и компилятор читает его только для того, чтобы записать метку aggrega.ai/environment.

Ограничения на уровне схемы

Две структурные гарантии защищают сущность Aggregate как единый источник истины:

  • values: запрещён. Чтобы защитить Aggregate как единый источник истины, схема Release механически запрещает блок values: — оператор не может объявить values ни для одного Component или Feature из Release. Запрет распространяется и на рёбра uses: запись uses для отдельного ребра в Release содержит infra и вложения, которые она записывает на соединении, и они тоже содержат infra — но никогда values (значения для разработчика на уровне ребра и значения вложения на соединении остаются в Aggregate). Различия значений для разработчика между окружениями передаются через подъём параметров (Parameter Hoisting): разработчик объявляет в Aggregate типизированное поле parameters.*, шаблон values сущности Component ссылается на него, а Release заполняет параметр для своего окружения. Явная формулировка запрета на уровне схемы приведена в architecture/06-data-taxonomy-and-composition.md §8 Constraint 4. Поверхность рёбер uses сущности Release — что она может настраивать и связывать — описана ниже в разделе Конфигурация соединения для отдельного ребра.
  • extends + aggregate: отклоняется. Чтобы предотвратить неотслеживаемые сущности Releases, «изменяющие aggregate», схема Release отклоняет объявление указателя aggregate, когда сущность Release использует extends. Дочерний release должен соответствовать в точности тому же намерению разработчика, что и родительский. Однако manifest становится необязательным, что открывает «позднее связывание» (Late Binding): оператор может унаследовать всю физическую топологию целиком, но точечно заменить сущность Manifest.

Блок parameters:

Сущность Release выполняет типизированный контракт параметров, который объявляет сущность Aggregate. spec.parameters: — это поверхность для написания: YAML-словарь, ключи которого соответствуют объявлениям parameters.* в сущности Aggregate, а значения задают их заполнение для конкретного окружения.

# Aggregate declares the typed contract
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: my-app
version: 1.0.0
spec:
parameters:
db_size: { type: string, required: true }
timeout_seconds: { type: integer, default: 30 }
region: { type: string, enum: [us-east-1, eu-west-1], required: true }
# Release fulfills the contract for this environment
apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: prod-release
version: 1.0.0
environment: production
spec:
aggregate: my-app
manifest: prod-manifest
parameters:
db_size: "100Gi"
timeout_seconds: 60
region: "us-east-1"

Каждое значение проходит проверку по схеме, объявленной в сущности Aggregate, на уровне контракта параметров, и сборка останавливается, когда сущность Release не указывает обязательный параметр (E0165, parameter-missing) или передаёт значение, которое отклоняет контракт его слота (E0164, parameter-contract-violation). Параметры, объявленные с default:, получают значение по умолчанию, если сущность Release не заполняет слот; типизированный контракт — единственный словарь для написания.

Два режима написания — выбор по форме содержимого. parameters: принимает либо встроенный YAML-словарь (режим 1, показан выше), либо единственный ключ $import:, указывающий на локальный файл (режим 2):

spec:
aggregate: my-app
manifest: prod-manifest
parameters:
$import: ./prod-parameters.yaml

Относительный путь $import: разрешается от каталога, в котором находится записывающая его сущность Release, откуда бы ни запускалась команда, поэтому командная строка и редактор читают один и тот же файл; абсолютный путь сам указывает своё место, и любой из них должен вести к файлу внутри рабочего пространства, а для сущности Release, указанной вне рабочего пространства, — внутри каталога, в котором она находится. В этом месте два режима взаимоисключающие, и импортировать можно только один файл. Многофайловое наслоение параметров — задача цепочек extends: сущностей Release: родительская сущность Release задаёт базовый набор параметров, а дочерняя расширяет и переопределяет его для каждого окружения. Этот шаблон описан ниже в разделе Составная сущность Release и наследование extends:.

Граница между parameters и infra. Параметры несут когнитивное намерение разработчика, выраженное в виде типизированных слотов, которые объявляет сущность Aggregate; сущность Release их заполняет. infra: в сущности Release несёт физические размеры от оператора (число реплик, ограничения CPU/памяти, классы хранилища), привязанные к конкретным компонентам или привязкам сущностей Feature. Параметры попадают в шаблоны values: сущности Aggregate через .parameters.X; infra: попадает в шаблон valuesMapping: сущности Recipe через .infra.X. Таксономию столпов данных см. в architecture/06-data-taxonomy-and-composition.md §3, а жизненный цикл параметров в конвейере — в templates/parameters-context.md.

Границы и область по умолчанию

Сущность Release группирует компоненты в границы — физические единицы развёртывания, у каждой из которых свой выходной каталог и свой каскад аннотаций. Случай с одной границей наиболее распространён, поэтому он не требует лишних церемоний.

Одна область (по умолчанию). Опишите компоненты непосредственно в spec.components: и опустите блок boundaries:. Компилятор сворачивает их в синтезированную границу default, вывод которой плоский — артефакты попадают непосредственно в dist/ (по каждому провайдеру, через безопасное значение subDirectory по умолчанию, описанное ниже: dist/compose/, dist/helm/, …), без сегмента с именем границы в пути. Это простейшее развёртывание: aggrega build для плоской цели Compose или цели с одним кластером без именования границ.

spec:
aggregate: aggregate
manifest: manifest
components:
db:
infra:
engine_version: "11.4"
web:
infra:
port: 8080

Несколько областей. Если сущность Release охватывает более одной физической группы — отдельные кластеры, регионы или волны синхронизации, — объявите именованные границы в boundaries:. Каждая граница несёт собственные directory:, каскад аннотаций и syncWave:, а компоненты адресуются в пределах своей границы.

Взаимоисключаемость. spec.components: и spec.boundaries: взаимоисключающие в корне сущности Release — в Release описывается одно или другое, но никогда оба. Документ, объявляющий оба, останавливается при загрузке с ошибкой конверта. Поверхность components верхнего уровня несёт ту же операторскую структуру для каждого компонента, что и components границы (infra:, annotations:, uses:).

Объявленная граница с именем default. Плоский вывод — свойство синтезированной границы по умолчанию, а не имени. Если в сущности Release в boundaries: явно объявлена граница с именем default, это обычная именованная граница: её вывод следует её directory: (по умолчанию dist/boundaries/default/), точно так же, как у любой другой объявленной границы.

Шаблон области по умолчанию описан в architecture/06-data-taxonomy-and-composition.md §7.

Пространственное разделение и выходные пути

Каждая граница объявляет физический выходной каталог directory для своих скомпилированных артефактов; компоненты внутри границы могут переопределить его через subDirectory на уровне компонента. Компилятор вычисляет итоговый путь артефакта, соединяя их в форме с косыми чертами на любой платформе: Final_Path = Clean(Join(Evaluated(directory), Evaluated(subDirectory))).

  • Один каталог — одно написание. Вычисленный путь нормализуется один раз, поэтому out/a, out//a, ./out/a и out/a/ — это один каталог. Границы, пути которых после нормализации указывают на один каталог и которые рендерятся через один провайдер, собираются вместе — точно так же, как границы, записанные с одинаковыми путями.
  • Путь остаётся внутри выходного корня. Путь, выходящий за пределы выходного корня (.., ../escape, a/../..), абсолютный путь или путь, не указывающий ни на какой каталог, — пустой или сводящийся после нормализации к самому выходному корню, — останавливает сборку до того, как что-либо будет записано. Сообщение называет сущность Release, границу, ошибочное поле (directory: или subDirectory:) и значение, в которое оно вычислилось, поскольку это значение часто является результатом шаблона.
  • Безопасное значение по умолчанию. Если subDirectory опущен или пуст, компилятор автоматически применяет subDirectory: "{{ .capability }}" — артефакты каждой возможности рендеринга (Helm, Helm-chart, Compose, Terraform, CloudFormation) попадают в собственную подпапку, что предотвращает конфликты смешанных артефактов в последующих инструментах CI/CD. Явно записанный subDirectory: "" читается точно так же, как опущенный, поэтому к нему тоже применяется это значение по умолчанию.
  • Плоское переопределение. Чтобы полностью отключить подкаталоги (все артефакты непосредственно в directory), задайте subDirectory: ".". Шаблон subDirectory, который вычисляется в пустую строку — например, "{{ .parameters.sub }}" при sub, равном "", — также отключает их.
  • Переменные шаблонов. directory вычисляется с {{ .capability }}, {{ .boundary_name }}, {{ .parameters.X }}, {{ .manifest.recipe_name }} и {{ .parent_boundary.* }} для каскадных данных из объемлющей границы. subDirectory вычисляется с тем же набором плюс {{ .component_id }} (только для переопределений на уровне компонента). Компилятор вычисляет шаблоны путей с missingkey=error — обращение к необъявленной переменной останавливает сборку с точной диагностикой. Матрица по контекстам и правила каскада родительской границы описаны в разделе переменные шаблонов путей.

Аннотации границы каскадно передаются вниз каждому вложенному компоненту; infra остаётся строго локальным для компонента, на который он нацелен. Рекурсивная карта boundaries допускает произвольную вложенность (граница внутри границы внутри границы), при этом инварианты каскада аннотаций и локального infra соблюдаются на каждом уровне.

Рабочий пример:

apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: spatial-release
version: 1.0.0
environment: production
spec:
aggregate: spatial-app
manifest: prod-manifest
boundaries:
eu-prod:
directory: "deploy/eu-prod"
# Scenario A: Safe Default. Compiler automatically applies `subDirectory: "{{ .capability }}"`.
annotations:
"aggrega.ai/namespace": "finance-frontend" # Merges downwards as annotations
components:
api-server:
infra: { replicas: 5 } # Strictly local
aws-rds:
# Scenario B: Bespoke Enterprise Naming.
subDirectory: provisioning
postgres-db:
# Scenario C: The Flat Directory Override.
subDirectory: "." # not "", which takes the default

Аннотации, переданные каскадом этим механизмом, появляются в последующих шаблонах Recipe через .context.annotations.release; о том, как их используют рендереры, см. написание Recipe и матрицу раскрытия шаблонов.

Структурированные значения аннотаций. Если привязка Manifest объявляет несколько путей маршрутизации по столпу infra для одного ключа аннотации, значение аннотации на стороне Release может быть структурированным объектом, несущим значения для нескольких полей схемы Feature в одном объявлении:

boundaries:
prod:
annotations:
feature.myco/db-pool:
pool_size: 20
max_connections: 100
components:
api:
annotations:
feature.myco/db-pool:
max_connections: 200 # closer-level override
# pool_size not listed → inherits 20 from boundary

Структурированные значения передаются каскадом с глубоким слиянием по подключам; подключи более близкого уровня переопределяют родительские. null для подключа исключает один подключ, а соседние подключи сохраняются. Сторона Release применяет только те подключи, столп которых в карте привязки — infra; подключи, маршрутизируемые в values, относятся к аннотациям на стороне Aggregate. Полное описание структурированных значений — композиция между сторонами, проверка типов по подключам, дисциплина ослабленных значений по умолчанию — см. в providers/well-known-annotations.md §«Structured annotation values».

Общеизвестные аннотации. Помимо произвольных ключей, стандартная библиотека Aggrega определяет набор общеизвестных аннотаций в пространствах имён aggrega.ai/ и feature.aggrega.ai/, сгруппированных по категориям размещения, сети, безопасности и наблюдаемости. Авторам, добавляющим аннотации к границе Release, следует обратиться к providers/well-known-annotations.md, где приведены полная матрица и правила использования для каждого провайдера: страница описывает, какие провайдеры применяют каждый общеизвестный ключ и какое поведение они порождают при наличии ключа.

Настройка соединений для каждого ребра

Компонент границы может содержать блок uses:, который настраивает или связывает рёбра топологии в пределах сокетов, объявленных в usesSchema каталога сущности Component. Это поверхность оператора для настройки каждого соединения, ограниченная так, чтобы разработчик сохранял владение архитектурой, которую он создал:

  • Настройка существующего ребра. Задайте infra для ребра, которое разработчик уже объявил. Запись указывает псевдоним разработчика и задаёт infra; она либо указывает ту же цель, которую связал разработчик, либо опускает цель. infra проверяется по infraSchema сокета.
  • Связывание несвязанного сокета. Создайте ребро в сокет, который объявлен в usesSchema сущности Component, но оставлен разработчиком несвязанным, указывающее на существующий компонент. Созданное ребро также может содержать infra для этого ребра.
  • Подключение на соединении. Подключения размещаются в features: записи с ключом по слоту, который сокет объявляет в своей featuresSchema, — тем же слотам, которые заполняет запись соединения разработчика. Каждое содержит type, необязательное description и infra, но никогда не содержит values. В слоте, который разработчик уже заполнил на том же соединении, запись задаёт размер этого подключения: пишите только infra, поскольку тип и значения берутся из сущности Aggregate (указанный здесь type должен совпадать с типом в сущности Aggregate, иначе сборка останавливается на этой записи с указанием обоих). В слоте, который разработчик оставил пустым, подключение принадлежит самой сущности Release, и type обязателен. В обоих случаях заполнение проверяется по selector слота и учитывается для слота required точно так же, как заполнение разработчика.

Эта поверхность работает по принципу «создавать, но не перенаправлять»: Release может добавить ребро в несвязанный сокет, но не может перенаправить ребро, уже объявленное разработчиком. Запись для ребра, указывающая другую цель, чем ребро разработчика, останавливает сборку; запись, указывающая ту же цель (или опускающая её), настраивает это ребро. Кроме того, Release не может объявлять values на ребре или на подключении, которое оно там записывает (значения, предназначенные для разработчика, остаются в сущности Aggregate), связывать сокет, не объявленный в usesSchema, или направлять ребро на несуществующий компонент — каждое из этих действий вызывает фатальную остановку. Как и запись, задающая infra или features для соединения, которого не существует после построения всех рёбер, если только потребляющий компонент не отключён через active: false. См. errors/fatal-halts.md §«When building the topology».

Ещё три остановки удерживают подключения соединения на этом соединении:

  • Имя, для которого сокет не объявляет слота, вызывает остановку — точно так же, как в записи соединения сущности Aggregate, — на этой записи в сущности Release, с перечислением слотов, объявленных сокетом, и тех из них, от которых имя отличается на одну правку.
  • Подключение, которое делает только сущность Release, записанное без type, вызывает остановку на записи соединения с указанием слота. Подключение, созданное сущностью Release, не содержит values, поэтому подходит для сущности Feature, чьи values ничего не требуют; если же схема требует значение, сборка останавливается из-за отсутствующего значения на той же записи. Сущности Features стандартной библиотеки для учётных данных, содержащие локатор вызывающей стороны, ничего не требуют в values: каждая принимает его также в infra (см. ниже).
  • Составное имя, записанное где-либо, кроме соединения, вызывает остановку. Подключение соединения становится подключением потребляющего компонента с именем <alias>.<slot> (см. запись соединения сущности Aggregate), а ключи собственных features: записи компонента и ключи границы допускают точку. Запись компонента, использующая это имя, или граница, использующая его так, что оно достигает компонента, соединение которого его содержит, — компонента, размещённого в этой границе или во вложенной в неё, включая компоненты маршрутизированного подмодуля, — вызывает остановку с указанием обоих написаний, по одному разу для каждого затронутого компонента. Слот сокета заполняется на каждом соединении и никогда — подключением, каскадно наследуемым из более широкой области.
spec:
components:
router:
uses:
models:
# Size the attachment the Aggregate declared on the "gpt" connection: infra only.
gpt:
features:
credential:
infra: { rotation: hourly }
# Attach on a connection the developer left without one: the type is required.
plain:
features:
credential:
type: core/generated-secret

Учётные данные на соединении, которое связывает сущность Release, указывают свой секрет в infra. У соединения, связанного сущностью Release, нет записи в сущности Aggregate, поэтому там ничто не задаёт values учётных данных, а сущность Release нигде не пишет values. Поэтому каждая сущность Feature стандартной библиотеки для учётных данных, содержащая локатор вызывающей стороны, — core/referenced-secret, core/referenced-secret-set, core/secret-value и core/secret-provided, — принимает его как в infra, так и в values: origin или entries для core/referenced-secret-set, с той же формой и тем же объявлением sensitive: true в обоих столпах. Каждая реализация читает тот столп, который его содержит.

spec:
components:
router:
uses:
models:
gpt:
target: gpt # wire the socket the developer left unbound
features:
credential:
type: core/referenced-secret
infra:
origin: openai-team-a # the secret the operator names

Локатор записывается ровно в одном столпе для каждого подключения. Подключение, содержащее его в обоих — в values сущности Aggregate и в infra сущности Release для одного слота, — или ни в одном, останавливается на собственной проверке сущности Feature (E0033) с указанием сущности Feature, подключения и компонента, а также того, какой из двух случаев произошёл. Это правило принадлежит каталожным сущностям этих Features, а не компилятору, который вычисляет их проверку так же, как проверку любой сущности Feature. Поля, кроме локатора, остаются в своём столпе: key остаётся листом values, поэтому подключение, которое делает только сущность Release, читает ключ данных сущности Feature по умолчанию, value. Запрет values: не меняется — локатор оператора находится в infra.

core/secret-provided — единственная из них, которая не подходит для соединения: она публикует своё значение для доставки собственным блоком inject: вложения, а вложение соединения не несёт блока inject: ни в одном из документов, поэтому на соединении её не доставляет никакой блок inject:. Используйте там core/referenced-secret или core/secret-value.

spec:
aggregate: spatial-app
manifest: prod-manifest
boundaries:
eu-prod:
components:
api-server:
uses:
databases:
# Configure the developer-declared edge "primary": add per-edge infra.
# The target matches what the Aggregate wired (or is omitted) — a configure, not a retarget.
primary:
infra: { storage_class: fast-ssd }
caches:
# Wire an edge into the declared-but-unbound "caches" socket to an existing component.
main:
target: redis-prod
infra: { storage_class: standard }

Итоговое infra ребра попадает в контекст рендеринга потребляющего компонента по пути .context.uses.<alias>.infra.<key>; оно никогда не появляется в контексте целевого компонента, поэтому результат рендеринга цели не зависит от потребителей, настраивающих рёбра к нему. Подключение на соединении также попадает в потребляющий компонент как одно из его подключений: его infra объединяется с values сущности Aggregate для того же слота, и его FeatureRecipe рендерится с учётом обоих. Recipe потребляющего компонента читает его под соединением, по пути .context.uses.<alias>.features.<slot>, а его Workload доставляет его, указывая соединение рядом со слотом, — см. Доставка учётных данных, которые несёт соединение.

Поле aggregates: — маршрутизация вложенных подмодулей по границам

Когда Aggregate объявляет вложенные подмодули через spec.aggregates:, Release определяет, в какую границу попадут компоненты каждого подмодуля, объявляя aggregates: рядом с components: внутри целевой границы:

# Aggregate declares two sub-aggregates
apiVersion: aggrega.ai/v1beta1
kind: Aggregate
metadata:
name: platform
version: 1.0.0
spec:
aggregates:
finance:
type: finance-module:1.2.0
analytics:
type: analytics-module:2.0.0
components:
gateway:
type: core/ingress
---
# Release routes each sub-aggregate into a specific boundary
apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: prod-release
version: 1.0.0
environment: production
spec:
aggregate: platform
manifest: prod-manifest
boundaries:
eu-prod:
directory: "deploy/eu-prod"
aggregates:
finance: {}
components:
gateway: {}
us-prod:
directory: "deploy/us-prod"
aggregates:
analytics: {}

Поместите каждый подагрегат, перечисленный в Aggregate.spec.aggregates:, ровно в одну границу.

Маршрутизация размещает компоненты. Каждый компонент маршрутизированного подмодуля попадает в границу, которая его маршрутизирует, и получает её directory, subDirectory, syncWave и каскад аннотаций — тот же контекст, что получает компонент, названный непосредственно в components:, включая отметку происхождения aggrega.ai/boundary-path на сгенерированных артефактах. Поэтому маршрутизация подмодуля и адресация каждого из его компонентов по квалифицированному пути через точку с пустым телом дают идентичные артефакты; маршрутизация — более короткий способ выразить это и единственный способ сделать это, не зная содержимого подмодуля.

Компонент принадлежит ровно одной границе, и сборка останавливается, если документ размещает его дважды: один и тот же подмодуль маршрутизирован в две границы, подмодуль маршрутизирован в одну границу, а один из его компонентов назван в другой, или компонент назван и напрямую, и через запись маршрутизации. Диагностика называет оба места, потому что решать, какое оставить, должен автор. Маршрутизация подмодуля в границу и указание одного из его компонентов в той же границе не являются конфликтом: маршрутизация размещает компонент, а названная запись его настраивает.

Подагрегат, который Release нигде не размещает, останавливает сборку. Размещение учитывается по обоим способам записи, поэтому сборка останавливается, только когда ни один из них не достигает подмодуля: ни одна граница не маршрутизирует его в aggregates: и ни одна граница не называет ни один из его компонентов в components: по квалифицированному пути через точку. Любой из способов сам по себе размещает подмодуль, и подмодулю, все компоненты которого названы по отдельности, запись маршрутизации не нужна. Исправление относится к блоку aggregates: того Aggregate, который импортировал подмодуль: для подмодуля, импортированного напрямую, — к Aggregate, который развёртывает Release, а для вложенного — к собственному документу импортирующего подмодуля. Диагностика называет эту запись по ключу, которым её записывает импортирующий документ, поэтому для вложенного подмодуля она показывает локальное имя, а не путь через точку.

Два случая намеренно не приводят к остановке. Подмодулю, не добавляющему компонентов, нечего размещать. Подмодуль, у которого переключатель active: разрешается в false, никогда не компоновался, поэтому ни одного его компонента для размещения не существует.

Частичное размещение не останавливает сборку по этому правилу: подмодуль считается размещённым, как только любой из его компонентов достигает границы, поэтому указание одного из них удовлетворяет подмодуль. Из этого не следует, что остальные можно опустить. Каждый компонент, не названный границей, тогда ничем не размещён, и правило для компонентов ниже сообщает о нём по его собственному ключу, — поэтому частично размещённый подмодуль останавливает сборку по разу на каждый оставленный компонент, а не на уровне подмодуля. Два способа записи, размещающие весь подмодуль одной строкой, — это запись маршрутизации и указание каждого компонента; всё промежуточное размещает то, что названо, и не более.

Компонент, который Release нигде не размещает, тоже останавливает сборку — на уровень глубже. Правило выше спрашивает, достиг ли подмодуль границы; это правило спрашивает то же о каждом компоненте композиции. Компонент достигает границы, если он назван в components: этой границы или находится внутри подмодуля, который граница маршрутизирует. Компонент, не достигший ни того, ни другого, рендерится вне всех границ, объявленных Release, и берёт свои directory, subDirectory, syncWave, каскад аннотаций и покомпонентный infra: ниоткуда, — поэтому сборка останавливается и называет компонент, а не генерирует артефакты, до которых конфигурация границ так и не дошла.

Два правила делят область, спрашивая о подмодуле компонента, а не просто о том, есть ли он у компонента. Компонент подмодуля, который Release нигде не разместил, остаётся правилу для подмодулей, которое сообщает об этой одной ошибке автора один раз в записи aggregates:, а не по разу на каждый компонент модуля. Компонент подмодуля, который Release разместил частично, относится к этому правилу, потому что правило для подмодулей считает такой модуль размещённым и ничего о нём не сообщает, — поэтому о каждом компоненте, не названном границей, сообщается здесь, по его собственному ключу внутри объявляющего его документа. Таким образом, частичное размещение подмодуля называет ровно то, что вы хотели назвать, и сообщает вам о каждом компоненте, который вы не назвали.

И запись границы, называющая компонент, которого нет в развёртываемом Aggregate, останавливает сборку. Два правила выше оценивают размещение со стороны компонента: разместило ли его что-нибудь. Это правило оценивает его со стороны Release: разрешается ли имя. Запись, которая ни во что не разрешается, ничего не размещает, поэтому её subDirectory, аннотации, покомпонентный infra: и uses: настраивают несуществующий компонент, и сборка останавливается, а не генерирует развёртывание, до которого запись так и не дошла. Проверяются оба способа записи: имя в components: границы читается как id, который компонент получает после завершения композиции, а имя в components: записи маршрутизации — как локальное имя внутри этого подмодуля. Диагностика сообщает id, к которому обращалась запись; при маршрутизированном способе это не имя в файле — файл записывает локальную часть, а подмодуль добавляет свой префикс.

Имя отклоняется за то, что ни во что не разрешается, и никогда — за свою форму: имя с точкой обычно, потому что компонент на уровень глубже несёт префикс своего модуля. Компонент, у которого переключатель active: разрешается в false, по-прежнему можно называть: отключение компонента не требует правки настраивающего его Release.

Подсистема ничего не добавляет к квалифицированному пути, поэтому граница обращается к компоненту по его простому имени, как бы Aggregate его ни группировал. Квалифицирует id только композиция подмодулей. Компонент развёртываемого Aggregate называется store независимо от того, записал ли его автор на верхнем уровне или внутри подсистемы с именем data; компонент на один модуль глубже называется data.store, и data здесь — префикс модуля, а не подсистемы. Поэтому запись границы, записанная как data.store, для компонента, находящегося в подсистеме с именем data, ни на что не указывает: сама запись останавливает сборку по правилу выше, а компонент, для которого она предназначалась, тоже не попадает ни в одну границу. Исправление записи на store решает обе проблемы.

Поэтому размещение подмодуля требует boundaries:. У формы с единой областью нет поверхности маршрутизации — aggregates: является ключом границы, а не spec:, — а карта components: верхнего уровня принимает только неквалифицированные имена, поэтому Release, развёртывающий Aggregate, который импортирует подмодули, объявляет boundaries:.

Рекурсивная маршрутизация. aggregates: рекурсивен — каждая запись под aggregates: границы может сама объявлять вложенную карту aggregates: для глубоко вложенной композиции модулей.

Блок маршрутизации для отдельного агрегата. Запись маршрутизации принимает ровно два ключа и ничего больше: components: — для настройки отдельных компонентов этого подмодуля, и вложенный aggregates: — для модулей, вложенных глубже. annotations: принадлежит границе, а infra: для отдельного компонента принадлежит записи под собственным components: записи маршрутизации.

Внутри записи маршрутизации ключом компонента служит имя, которое он носит внутри своего подмодуля, — consumer, а не data.consumer, — потому что другого имени у него там нет. Квалифицированный путь через точку — это способ, которым к тому же компоненту обращается собственная карта components: границы; эти два способа записи не взаимозаменяемы, и запись маршрутизации отклоняет ключ с точкой.

boundaries:
eu-prod:
directory: "deploy/eu-prod"
annotations:
aggrega.ai/namespace: "finance-zone"
aggregates:
finance:
components:
ledger: # the component's name inside the finance module
infra:
replicas: 3
aggregates:
reporting: {} # a module nested inside finance

Собственные компоненты и Features подагрегата не объявляются повторно в Release: Release маршрутизирует их, а не переопределяет, и называет компонент только для того, чтобы его настроить.

Временная последовательность — syncWave на уровне границы

Каждая граница в сущности Release может объявить необязательное целочисленное поле syncWave:, которое даёт оператору явный контроль над порядком развёртывания, не затрагивая сущность Aggregate разработчика. Номер волны — свойство самой границы; каждый компонент в поддереве границы наследует значение волны своей границы при выпуске артефактов.

apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: prod-release
version: 1.0.0
environment: production
spec:
aggregate: my-app
manifest: prod-manifest
boundaries:
infra:
directory: "deploy/infra"
syncWave: 0
components:
core-vpc: {}
postgres-db: {}
migrations:
directory: "deploy/migrations"
syncWave: 1
components:
db-migration-task: {}
apps:
directory: "deploy/apps"
syncWave: 2
components:
web-server: {}
ai-agent: {}

Семантика значения волны. syncWave: — целое число со знаком (положительное, ноль или отрицательное). Если поле опущено, по умолчанию используется 0. Значения волны не наследуются от родительской границы: каждая граница, которой нужна волна, отличная от значения по умолчанию, объявляет её явно. Components не могут переопределить волну своей границы (волна — свойство пространственной единицы, а не отдельных компонентов).

Выпуск для каждого провайдера. Компилятор записывает значение волны границы в отрендеренный вывод в форме, родной для провайдера. Три из этих форм разобраны ниже; что волна делает на каждом провайдере стандартной библиотеки, включая terraform, сведено в таблицу в providers/reference-matrix.md, раздел «What a boundary’s syncWave does on each provider» («Что делает syncWave границы на каждом провайдере»).

  • Kubernetes (провайдер helm / helm-chart). Если волна не равна 0, каждый ресурс Kubernetes, который провайдер helm рендерит для границы, несёт стандартную для GitOps аннотацию argocd.argoproj.io/sync-wave: "<N>"; хуки Helm дополнительно несут аннотацию helm.sh/hook-weight: "<N>", чтобы то же значение волны управляло собственным порядком pre/post-install в Helm. ArgoCD читает аннотацию sync-wave, а Helm — вес хука, и каждый из них упорядочивает применение ресурсов соответственно. Провайдер helm-chart копирует шаблоны исходного чарта в том виде, в каком их написал автор, поэтому собственные ресурсы сабчарта несут волну, только если её записывают эти шаблоны; загруженный через $import: артефакт, который он добавляет, несёт argocd.argoproj.io/sync-wave и не несёт helm.sh/hook-weight (см. providers/helm-chart.md).
  • Compose. Каждый сервис в compose-файле, в который рендерится граница, ожидает через depends_on сервисы непосредственно предшествующей волны, попавшие в тот же файл, — по готовности (health) цели, если цель объявляет healthcheck, и по её запуску, если не объявляет. Таким образом, волна упорядочивает сервисы одного файла и ничего за его пределами: границы, рендерящиеся в отдельные файлы docker-compose.yaml, — это отдельные compose-проекты, и их упорядочивание — забота оператора. Рёбра uses: по-прежнему задают порядок для отдельных рёбер наряду с волной. См. providers/compose.md.
  • CloudFormation. Каждый ресурс в собранном шаблоне стека зависит, через DependsOn, от ресурсов непосредственно предшествующей волны, внёсших вклад в тот же стек, — поэтому волна задаёт порядок создания ресурсов и, в обратном порядке, порядок их удаления. Это не упорядочивание по готовности: в шаблоне стека нет понятия о том, что ресурс готов к обслуживанию. Собственный DependsOn фрагмента дополняется, а не заменяется. Components, собираемые в другой стек, находятся вне досягаемости, а упорядочивание двух стеков — забота оператора. См. providers/cloudformation.md.

Единица задания волн и единица развёртывания. Граница — единица задания волн. Единица развёртывания — тот путь сборки, в который выпускаются компоненты: по умолчанию он соответствует границе 1:1, но две соседние границы с общим directory: схлопываются в один собранный вывод (один Chart.yaml, один docker-compose.yaml). В этом случае собранный вывод может содержать ресурсы из нескольких волн; ArgoCD Application, читающее его, упорядочивает внутри Application каждый ресурс по аннотации sync-wave, которую несёт этот ресурс: в helm — каждый ресурс, отрендеренный для ненулевой волны, а в helm-chart — только загруженный через $import: артефакт, при этом собственные шаблоны сабчарта содержат то, что написал их автор. Упорядочивание между разными Application по разным путям — забота CI оператора.

Сценарии использования. Порядок волн важен всякий раз, когда запуск одной границы зависит от предварительного завершения другой. Канонический шаблон: граница infra на волне 0 (VPC + база данных), граница migrations на волне 1 (задание миграции схемы) и граница apps на волне 2 (приложение, использующее мигрированную схему). Без явных волн все три развёртываются одновременно, и приложение уходит в crash-loop, ожидая завершения миграции.

Полное архитектурное обоснование — модель выполнения DAG, причины размещения временной последовательности в сущности Release, а не в сущности Aggregate, и различие между единицей задания волн и единицей развёртывания — см. в architecture/12-day-two-lifecycles.md §1.

Подключение Feature

Release может подключать Features как на уровне границы (общая политика), так и на уровне конкретного компонента (точечное нацеливание); выполнение при этом следует пятиуровневой луковичной модели, описанной в architecture/10-compilation-pipeline.md. Features, объявленные в Release, вносят type, infra и uses; объявлять values они не могут (см. «Ограничения на уровне схемы» выше).

Feature, подключённая к границе, задаётся по выбранному вами имени экземпляра, и этим именем не может быть . или ... У провайдера, который выделяет каждому участнику собственный каталог, — terraform в modules/ и helm-chart в charts/ — файлы Feature уровня границы записываются в каталог, названный только по имени экземпляра, а ни одно из этих двух имён не является отдельным каталогом: сборка останавливается с указанием сущности Release, границы и экземпляра. Имя, которое лишь содержит точки, например audit.v2, является обычным именем.

features: — единственная поверхность подключения в Release, на обоих уровнях, как и в Aggregate. Учётные данные — это Feature с меткой feature.aggrega.ai/kind: secret, поэтому учётные данные, подключаемые оператором, подключаются в features: как любая другая Feature и указывают свой секрет в infra точно так же, как на соединении (см. Конфигурация соединений для отдельных рёбер), — на компоненте, который Aggregate оставил без них, или как параметры подключения, которое Aggregate объявил без указания секрета. Второго ключевого слова подключения нет ни на каком уровне; документ, который его объявляет, отклоняется при загрузке с ошибкой оболочки, называющей неожиданное свойство.

Фича, подключённая на всю границу, может содержать блок uses:, и этот блок проецируется на каждый компонент, направленный в границу: каждый компонент получает ребро зависимости к именованным целям фичи, и в него внедряются provides этих целей. Так общая зависимость выражается один раз на уровне границы — «каждый компонент в этой границе обращается к общему кэшу / сборщику / шине сообщений», — а не повторением одного и того же ребра uses: на каждом компоненте. Подключение Feature на уровне подсистемы в Aggregate точно так же проецирует свой uses: на компоненты подсистемы. uses — это объявление связывания топологии, а не значение, поэтому оно допустимо в Release. Проекция не зависит от области выполнения подключённой Feature: Feature, чей FeatureRecipe отрисовывается один раз на границу, всё равно проецирует свой uses: на каждый компонент, тогда как сам общий ресурс отрисовывается один раз.

Feature, подключённая к одному компоненту, содержит тот же блок uses: и проводит то же ребро от этого одного компонента: компонент получает ребро зависимости к каждой указанной цели, в него внедряются provides этих целей, и ребро записывает подключение как своё происхождение точно так же, как в форме для всей границы. Это одно объявление двух широт: подключение на границе связывает каждый её компонент, подключение на компоненте — только его, и выбор между ними — вопрос охвата, а не того, что делает связывание. Ни то, ни другое не создаёт вычислительных ресурсов: цель должна уже указывать на компонент, объявленный в Aggregate, а цель, которая этого не делает, останавливает сборку. Соединение, которое проводит Feature, не несёт собственных подключений: его запись принимает target и inject, а ключ features: в ней отклоняется при загрузке Release.

boundaries:
cluster:
directory: ./dist/cluster
components:
api:
features:
shared_backend:
type: core/shared-backend
uses:
backend:
primary:
target: db # a component of the assembled graph
inject:
env:
- in: DB_HOST
from: host # db's `host` provides reaches api as DB_HOST
db: {}

Как записывается цель. Цель ребра указывает на компонент собранного графа, поэтому она записывается квалифицированным путём через точку — data.store, а не store, — всякий раз, когда цель принадлежит направленному подмодулю. Это верно, даже когда само подключение находится в записи маршрутизации, ключи components: которой локальны для модуля: ключ говорит, на каком компоненте находится подключение, а цель — до какого компонента доходит ребро, и только второе является именем в масштабе графа. Цель, записанная локальным для модуля именем, не совпадает ни с одним компонентом и останавливает сборку с той же диагностикой, что и любое висячее ребро.

Составной Release и наследование через extends:

Сущность Release может объявить spec.extends:, указывающий на базовый Release, поверхность авторинга которого она наследует.

Ссылка — это путь к файлу рядом с объявляющим Release — ./base-release.yaml или ../shared/base-release.yaml. Release относится к стороне развёртывания и не индексируется в каталоге, поэтому ссылка extends: никогда не разрешается через каталог. Относительный путь — единственная допустимая форма: ссылка, записанная как координата реестра, отклоняется, как и голое имя, и в каждом случае диагностика называет форму относительного пути. extends: сущности Manifest — близкий сосед, который читается иначе: он принимает относительный путь или голое metadata.name сущности Manifest рядом с Release, — поэтому эти две формы не взаимозаменяемы, и голое имя, которое разрешилось бы для Manifest, здесь не разрешается. Каждое звено цепочки читается так же: родительский Release, хранящийся в другом каталоге, называет своего родителя путём относительно себя, где бы ни находился названный вами Release, — точно так же, как его параметры $import: разрешаются относительно него. Путь должен вести к Release внутри рабочего пространства, как и любой путь, который записывает Release, — или, для Release, названного вне рабочего пространства, внутрь каталога, содержащего этот Release, чему подчиняется каждое звено его цепочки: путь, который выходит наружу или который звено выводит наружу, отклоняется до чтения файла, который он называет.

Компилятор проходит по цепочке при загрузке Release — отклоняя цепочку, возвращающуюся к файлу, уже входящему в неё, цепочку, превышающую ограничение глубины, и ссылку, которая ничего не называет, — а затем сворачивает цепочку в единый разрешённый Release.

Унаследованное можно заменять ключ за ключом. Ваше значение побеждает на всех уровнях вложенности, пока вы не дойдёте до значения, которое является единым неделимым целым, — скаляра, списка, шаблона, — его вы берёте или заменяете целиком. Унаследованное удаляется записью null. Это то же правило, которому следуют расширяющие сущности Component, Feature и Manifest, так что автор, знакомый с одной, знаком со всеми.

Применительно к Release: boundaries объединяются по имени границы, а граница — по ключу, components — по имени компонента, infra — глубоко, features — по имени экземпляра, а затем по опоре; uses компонента — по сокету, а затем по соединению, где target, записанный потомком, заменяет унаследованный, infra соединения объединяется ключ за ключом, а его features объединяются по слоту, а затем по опоре по тому же правилу, которому следуют собственные features компонента; directory, subDirectory, syncWave и указатели на Aggregate и Manifest — скаляры, которые заменяются.

Две вещи не наследуются:

  • Идентичность и происхождение. Ни одно поле metadata не наследуется. Важно знать о metadata.environment: оно обязательно для каждого Release и по своей природе относится к конкретному Release, поэтому потомок рендерится со своим собственным окружением в метках происхождения, а не с окружением родителя.
  • Указатель на Aggregate наследуется, а не переопределяется. Потомок не может объявить aggregate: — схема отклоняет extends: и aggregate: в одном документе, — поэтому потомок развёртывает то же намерение разработчика (Developer Intent), что и его база.

Потомок может опустить manifest:, унаследовав его от базы, или переопределить его для позднего связывания (Late Binding).

Одна форма маршрутизации по всей цепочке. boundaries: и components: взаимоисключающие в пределах одного Release, и это действует и для цепочки: база, объявляющая именованные границы, и потомок, объявляющий компоненты верхнего уровня, отклоняются, а диагностика называет оба файла и оба ключа. Выберите одну форму маршрутизации и используйте её на всех уровнях.

Шаблон моста для локальной разработки. Типичный сценарий — разработчик запускает продакшн-Aggregate своей команды локально, не создавая форк Aggregate и не дублируя топологию границ. Команда публикует продакшн-Release; локальный Release выполняет extends: от него и переопределяет только указатель на Manifest, заменяя облачные Recipes локальными эквивалентами:

# production Release (committed; the source of truth for prod deployments)
apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: prod-release
environment: production
version: "1.0.0"
spec:
aggregate: my-app
manifest: prod-manifest
parameters:
region: us-east-1
db_size: 100Gi
out_dir: prod
boundaries:
prod:
# A directory is a TEMPLATE, not a fixed path. Writing it against a
# parameter is what lets a child render somewhere else without
# restating the boundary topology.
directory: deploy/{{ .parameters.out_dir }}
components:
api: { infra: { replicas: 5 } }
db: {}
---
# Local Release (developer-side; inherits everything, swaps the Manifest)
apiVersion: aggrega.ai/v1beta1
kind: Release
metadata:
name: local-release
environment: local
version: "1.0.0"
spec:
extends: ./prod-release.yaml
manifest: local-manifest # surgically overrides for local
parameters:
region: dev-local
db_size: 1Gi
out_dir: local # the inherited directory resolves here instead

local-release наследует топологию границ базы, подключения Feature и переопределения компонентов; разработчик хранит один local-release.yaml и запускает aggrega build --release local-release.yaml, не дублируя никакой продакшн-конфигурации.

Записывайте directory: через параметр. Поскольку каталог наследуется, как любой другой скаляр, потомок, унаследовавший каталог без шаблонной переменной, рендерится в тот же путь, что и его база, и никакой параметр командной строки его не перенаправляет. Это допустимо, если вы этого и хотели, — например, заменить только Recipes, чтобы сравнить их вывод, — поэтому сборка сообщает об этом и продолжается, а не отклоняется. Запись каталога через параметр, как показано выше, сохраняет топологию в одном месте и при этом направляет вывод каждого Release в собственное место.

Многофайловое наслоение параметров. Наследование Release — место для многофайлового наслоения параметров. Базовый Release задаёт общий набор параметров; потомки для каждого окружения выполняют extends: от базы и переопределяют отличающиеся слоты:

# base-release.yaml — common parameters
spec:
aggregate: my-app
parameters:
timeout_seconds: 30
feature_flags: { dark_mode: true }
---
# prod-release.yaml
spec:
extends: ./base-release.yaml
manifest: prod-manifest
parameters:
feature_flags: { dark_mode: false } # override one nested key
---
# staging-release.yaml
spec:
extends: ./base-release.yaml
manifest: staging-manifest

Каждый потомок видит унаследованные параметры базы, объединённые с его собственными. Параметры-словари объединяются глубоко, с приоритетом ключей потомка; скалярные параметры заменяются потомком; ключ, который потомок записывает как null, удаляется, а не устанавливается в пустое значение.

База может импортировать свои параметры, а потомок всё равно может переопределять отдельные ключи. Два режима авторинга, описанные выше в разделе parameters:, — встроенный или единственный $import: — это правило об одном документе, а не о цепочке: каждый Release в цепочке объявляет тот или иной режим, и импорт каждого разрешается относительно каталога, содержащего этот Release, до свёртки цепочки. Поэтому база, импортирующая общий файл, и потомок, записывающий несколько ключей встроенно, объединяются по ключу — точно так же, как два встроенных блока:

# base-release.yaml — parameters arrive from a shared file beside it
spec:
aggregate: my-app
parameters:
$import: ./shared-params.yaml # tier: prod, region: eu
---
# local-release.yaml — overrides one key, inherits the rest
spec:
extends: ./base-release.yaml
manifest: local-manifest
parameters:
tier: local # region stays eu, from the imported file

Режимы ошибок. Циклические цепочки extends:, отсутствующие указатели на родителя и объявления aggregate: на стороне потомка останавливают загрузку рабочего пространства с явной диагностикой, называющей проблемный Release и нарушение на уровне схемы. Формы сообщений для каждой ошибки см. в errors/fatal-halts.md.