Схема Aggrega Release
Сгенерированный справочник. Не редактируйте вручную — сгенерируйте заново из опубликованной JSON Schema.
Идентификатор схемы: https://aggrega.ai/schemas/release-v1beta1.schema.json
Описательные рекомендации по созданию сущностей Release см. в справочнике по созданию сущностей Release; на этой странице описана структурная схема, которую описывает этот справочник.
Тип верхнего уровня: object
Свойства
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
apiVersion | const “aggrega.ai/v1beta1” | да | Константа: "aggrega.ai/v1beta1" |
kind | const “Release” | да | Константа: "Release" |
metadata | object | да | |
spec | object | да | То, что сущность Release привязывает и маршрутизирует: Aggregate и Manifest, которые она развёртывает (или базовый релиз extends), выполнение параметров для конкретного окружения и границы, в которые направляются её компоненты. |
Дополнительные свойства не допускаются.
release.metadata
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
name | string | да | Не менее 1 символа. |
environment | string | да | |
version | string | да | Строгая семантическая версия релиза (например, 1.0.0). Шаблон: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$. |
description | string | нет | Что представляет собой эта сущность и для чего она нужна — для того, кто решает, использовать ли её. Начните с предложения, называющего её, затем добавьте то, что читателю нужно, чтобы выбрать её и правильно использовать: чего она ожидает от платформы, на которую развёртывается, и что в её поведении может оказаться неожиданным. Обычная длина — короткий абзац. |
maintainers | object[] | нет | Список сопровождающих, которым принадлежит эта сущность. |
license | string | нет | Идентификатор SPDX лицензии программного обеспечения, которое описывает эта сущность, например MIT или AGPL-3.0. Он фиксирует условия этого программного обеспечения, а не условия данного файла. |
repository | string | нет | URL Git-репозитория, в котором находятся исходные файлы. |
home | string | нет | URL домашней страницы, вики или документации этой сущности. |
keywords | string[] | нет | Список описательных ключевых слов для удобства поиска в интерфейсе. |
Дополнительные свойства не допускаются.
release.metadata.maintainers[]
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
name | string | да | |
email | string | нет | |
url | string | нет |
Дополнительные свойства не допускаются.
release.spec
То, что сущность Release привязывает и маршрутизирует: Aggregate и Manifest, которые она развёртывает (или базовый релиз extends), выполнение параметров для конкретного окружения и границы, в которые направляются её компоненты.
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
aggregate | string | нет | Ссылка на Aggregate (намерение разработчика), который развёртывает этот релиз. Простой токен разрешается по идентичности — по metadata.name соответствующей сущности Aggregate, поиск ведётся в собственном каталоге сущности Release, а затем в каталоге пакетов. Значение, начинающееся с ’./’ или ’../’, — явный локальный файл, разрешаемый относительно сущности Release (например, ’../shared/app.yaml’, чтобы использовать один Aggregate в нескольких вариантах релиза в подкаталоге). |
manifest | string | нет | Ссылка на Manifest, разрешающий абстрактные интерфейсы, относительно которых развёртывается этот релиз. Простой токен разрешается по идентичности — по metadata.name соответствующей сущности Manifest, поиск ведётся в собственном каталоге сущности Release. Значение, начинающееся с ’./’ или ’../’, — явный локальный файл, разрешаемый относительно сущности Release. Manifest относится к стороне развёртывания и не индексируется в каталоге, поэтому разрешается только из каталога сущности Release или по явному пути. |
extends | string | нет | Ссылка на базовую сущность Release, авторскую поверхность которой наследует этот Release: её дерево границ с привязками infra и Feature для каждого компонента, её параметры, её аннотации и её указатель на Manifest. Значение — путь к файлу рядом с этим Release, начинающийся с ’./’ или ’../’; простое имя и координата реестра отклоняются, поскольку Release относится к стороне развёртывания и не индексируется в каталоге. Унаследованное можно заменять ключ за ключом, вплоть до первого неделимого значения — скаляра, списка, шаблона, — которое заменяется целиком; ключ, записанный как null, удаляет унаследованное. Поля metadata не наследуются, поэтому дочерний релиз задаёт собственные имя, версию и окружение. Объявление ‘aggregate’ вместе с ‘extends’ отклоняется этой схемой, поэтому дочерний релиз развёртывает то же намерение разработчика, что и базовый; ‘manifest’ остаётся необязательным и может быть переопределён, чтобы заменить lock-файл зависимостей. |
parameters | object | нет | Контракт выполнения переменных для конкретного окружения с двумя режимами написания, выбираемыми по форме содержимого. Режим 1 (встроенный): YAML-словарь, непосредственно содержащий структурированные вложенные значения параметров. Режим 2 (импорт файла): YAML-словарь ровно с одним ключом, $import: ./relative/path.yaml, указывающим на один локальный файл со значениями параметров. В этом месте допускается только один источник — многофайловое наслоение реализуется цепочками extends: сущностей Release (родительский Release задаёт базовые параметры; дочерний расширяет и переопределяет их). |
boundaries | словарь boundary | нет | Корневые логические блоки, в которые направляются компоненты сущности Aggregate. Ключи: одна или несколько букв, цифр, подчёркиваний или дефисов. Точка не допускается. Шаблон: ^[a-zA-Z0-9_-]+$. |
components | словарь boundary_component | нет | Экземпляры компонентов верхнего уровня с инфраструктурой оператора для каждого компонента, для однообластного Release без именованных границ. Взаимоисключается с boundaries: объявляйте components для плоского Release или boundaries для маршрутизации в несколько целей, но не оба сразу. При использовании components компилятор синтезирует границу default, содержащую их, и выводит их артефакты в dist/ без вложенности. Ключи: одна или несколько букв, цифр, подчёркиваний или дефисов. Точка не допускается. Шаблон: ^[a-zA-Z0-9_-]+$. |
Дополнительные свойства не допускаются.
Определения
boundary_component
Экземпляр компонента, направленный в границу, с необязательными физическими размерами и подключениями функций.
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
description | string | нет | Необязательная документация, описывающая роль этого компонента в данной границе сущности Release. |
subDirectory | string | нет | Переопределение подпути на уровне Component, добавляемое к каталогу родительской границы. Если оно опущено или пусто и у границы, и у компонента, по умолчанию используется ’{{ .capability }}’; пустая строка, записанная здесь, считается опущенным значением. Чтобы отключить создание подкаталогов, задайте ’.’ или шаблон, который вычисляется в пустую строку. |
annotations | map из string, object или null | нет | Аннотации оператора, специфичные для Component, которые переопределяют аннотации уровня границы для этого компонента. Глубоко объединяются поверх аннотаций границы (при совпадении ключей побеждает компонент; структурированные значения объединяются по подключам со структурированными родительскими значениями). Значения — строки, структурированные объекты или null. Используются для переопределения общеизвестных аннотаций провайдера на уровне компонента (например, aggrega.ai/namespace у провайдера helm). Явный null у ключа, унаследованного от родительской границы, удаляет унаследованную привязку из этого компонента (отказ от Feature через аннотации); соседние компоненты сохраняют унаследованную привязку. |
infra | object | нет | Физические размеры, строго локальные для этого компонента (например, реплики, IOPS диска). |
features | map of object | нет | Features, подключённые к этому компоненту через Release. Для функциональностей, также объявленных в Aggregate, предоставляется только infra (значения берутся из Aggregate). Для функциональностей, существующих только в Release (внедрённых оператором), type обязателен. Ключи — имена экземпляров функциональностей; они могут содержать полный URI типа функциональности (точки и слэши допускаются). Release НЕ ДОЛЖЕН предоставлять значения для функциональностей — это зона ответственности разработчика. Ключи: одна или несколько букв, цифр, подчёркиваний, точек, слэшей или дефисов. Шаблон: ^[a-zA-Z0-9_./-]+$. |
uses | release_uses_block | нет | Поверхность рёбер оператора. В пределах сокетов, объявленных архитектором, Release может связать объявленный, но не привязанный сокет с существующим компонентом (target) и/или задать infra для отдельного ребра. Никаких values (действует запрет values: для Release) и никакого создания вычислительных ресурсов; перенаправление ребра, объявленного разработчиком, останавливает сборку. |
Дополнительные свойства не допускаются.
release_uses_block
Поверхность uses для отдельных рёбер, задаваемая в Release, с ключами сначала по сокету, затем по псевдониму (повторяет форму топологии uses в Aggregate). Каждое соединение может задавать target (чтобы создать ребро в объявленный, но не привязанный сокет, указывающее на существующий компонент), infra (конфигурация оператора для ребра, проверяемая по infraSchema сокета при разрешении Release) и features (подключения, заполняющие слоты, объявленные сокетом), в любом сочетании. values запрещено (запрет values: для Release); перенаправление ребра, объявленного разработчиком, — явный защитный барьер при сборке.
Ключи: одна или несколько букв, цифр, подчёркиваний или дефисов. Точка не допускается. Шаблон: ^[a-zA-Z0-9_-]+$.
Значения — map of object.
Другие ключи не допускаются.
release_connection_attachment
Одно подключение, которое несёт запись соединения Release: Feature, заполняющая слот, объявленный сокетом соединения, вместе с заданными оператором размерами для неё.
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
type | string | нет | URI сущности Feature. Обязателен для подключения, которое делает только Release. Должен совпадать с типом в Aggregate, если его объявляют оба. |
description | string | нет | Необязательная документация, объясняющая, почему оператор подключил эту функцию к соединению. |
infra | object | нет | Эксплуатационные размеры для этого подключения, проверяемые по объявлению схемы сущности Feature. |
Дополнительные свойства не допускаются.
aggregate_routing
Направляет внутренние компоненты вложенного подмодуля Aggregate в эту границу. Повторяет структуру component/aggregate границы для рекурсивной композиции.
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
components | словарь boundary_component | нет | Экземпляры Component во вложенном агрегате, которые направляются в эту границу. Ключи — локальные имена, которые каждый компонент носит внутри этого подмодуля: ‘main-db’ для компонента, к которому собственная карта components границы обращается как ‘data.main-db’, — поскольку это единственное имя, которое у него там есть. Ключи: одна или несколько букв, цифр, подчёркиваний или дефисов. Точка не допускается. Шаблон: ^[a-zA-Z0-9_-]+$. |
aggregates | map of aggregate_routing | нет | Дальнейшие вложенные агрегаты внутри этого подагрегата (для глубоко вложенной модульной композиции). Ключи: одна или несколько букв, цифр, подчёркиваний или дефисов. Точка не допускается. Шаблон: ^[a-zA-Z0-9_-]+$. |
Дополнительные свойства не допускаются.
boundary
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
description | string | нет | Необязательная документация, описывающая назначение этой границы и её физическую цель (например, ‘Primary production EKS cluster in us-east-1, PCI-DSS compliant’). |
directory | string | нет | Физический выходной путь для генерации артефактов GitOps. Поддерживает переменные шаблонов Go ({{ .capability }}, {{ .boundary_name }}, {{ .parameters.X }}). Объединяется с subDirectory как соединение путей, чтобы получить итоговый путь артефакта. |
subDirectory | string | нет | Подпуть уровня границы, добавляемый к directory. Если он опущен или пуст и у границы, и у компонента, по умолчанию используется ’{{ .capability }}’ для автоматического разбиения CI/CD; пустая строка, записанная здесь, считается опущенным значением. Чтобы отключить, задайте ’.’ или шаблон, который вычисляется в пустую строку. |
syncWave | integer | нет | Необязательная волна развёртывания для границы (целое число со знаком, по умолчанию 0). Каждый компонент этой границы наследует волну границы в свой узел. Допускаются отрицательные значения (выполняются раньше всего остального); большие значения выполняются после меньших. В K8s и Helm именно волна задаёт порядок развёртывания: она становится аннотацией argocd.argoproj.io/sync-wave, а на ресурсе, который чарт уже помечает как хук Helm, она также становится helm.sh/hook-weight этого хука. В compose волна и записывается как метка сервиса, и упорядочивает сервисы файла, в который она рендерится, через depends_on между ними — поэтому она действует на каждый сервис в этом одном файле и ни на что за его пределами. В cloudformation волна упорядочивает выделение ресурсов стека, в который собирается граница: каждый ресурс волны объявляется зависимым от ресурсов предыдущей волны, что фиксирует порядок их создания и, в обратном порядке, порядок их удаления. Это только порядок создания и удаления — шаблон стека не выражает понятия готовности ресурса, поэтому ничто не ждёт, пока ресурс станет пригодным к работе. В terraform волна упорядочивает блоки module корневой конфигурации, в которую собирается граница: каждый модуль волны объявляется зависимым от модулей предыдущей волны, что фиксирует порядок, в котором движок выполняет свои действия. Это только порядок действий — конфигурация не выражает понятия готовности ресурса, поэтому ничто не ждёт, пока ресурс станет пригодным к работе, — и значение также записывается вместе с происхождением сборки узла. Компилятор переносит то же значение на каждый узел границы как sync_wave этого узла, где поведение для каждой цели описано ещё раз со стороны узла. Вложенные границы не наследуют волну неявно — каждая объявляет собственную волну. |
annotations | map из string, object или null | нет | Аннотации оператора для всей границы, каскадно передаваемые в раздел .context.annotations.release. Значения — строки, структурированные объекты или null. Структурированное значение несёт конфигурацию по подключам, которая глубоко сливается со структурированными родительскими значениями (по подключам, дочернее побеждает) и проходит через управляемое аннотациями развёртывание Feature; в контексте рендеринга появляются только скалярные значения. Явный null на ключе, унаследованном от родительской границы, удаляет унаследованную привязку из эффективного набора аннотаций этой границы (управляемый аннотациями отказ от Feature) и распространяется на каждый компонент, направленный в эту границу, если только более глубокое переопределение не вводит привязку заново. |
features | map of object | нет | Возможности на уровне всей границы, применяемые ко всем вложенным компонентам (например, сетка безопасности по умолчанию). Блок uses возможности проецируется на каждый компонент границы, так что общая зависимость объявляется один раз на границе, а не повторяется в каждом компоненте. Ключи — имена экземпляров возможностей; они могут содержать полный URI типа возможности (точки и косые черты допускаются). Ключи: одна или несколько букв, цифр, подчёркиваний, точек, косых черт или дефисов. Шаблон: ^[a-zA-Z0-9_./-]+$. |
boundaries | словарь boundary | нет | Вложенные логические границы (например, пространства имён внутри кластера). Ключи: одна или несколько букв, цифр, подчёркиваний или дефисов. Точка не допускается. Шаблон: ^[a-zA-Z0-9_-]+$. |
components | словарь boundary_component | нет | Какие компоненты из Aggregate размещаются в этой границе. Ключи — имена экземпляров компонентов; компонент вложенного агрегата адресуется своим квалифицированным путём через точку (например, ‘data.main-db’ — имя экземпляра агрегата, точка, имя компонента). Ключи: одна или несколько букв, цифр, подчёркиваний, точек или дефисов. Шаблон: ^[a-zA-Z0-9_.-]+$. |
aggregates | map of aggregate_routing | нет | Направляет компоненты вложенных подмодулей Aggregate в эту границу. Ключи — имена экземпляров агрегатов, соответствующие карте spec.aggregates сущности Aggregate. Если границы определены, каждый экземпляр агрегата должен быть размещён ровно в одной границе. Ключи: одна или несколько букв, цифр, подчёркиваний или дефисов. Точка не допускается. Шаблон: ^[a-zA-Z0-9_-]+$. |
Дополнительные свойства не допускаются.
uses_block
Структурная топология — во владении разработчика. Объявляет логические сетевые рёбра и зависимости.
Ключи: одна или несколько букв, цифр, подчёркиваний или дефисов. Точка не допускается. Шаблон: ^[a-zA-Z0-9_-]+$.
Значения: string[] or map of object.
Другие ключи не допускаются.
inject_block
Агностичная маршрутизация инъекции на соединении. Сопоставляет локальные переменные с ключами provides цели. Каждый механизм доставки (env, file, arg или custom) записывается как массив записей {in, from} — с явным ‘from’ для ссылок на provides. Пользовательский механизм может носить любое имя, кроме all: шаблон читает все механизмы, объединённые в одно представление, в .context.inject.all, поэтому механизм с таким именем был бы им скрыт, а указание такого имени останавливает сборку.
| Свойство | Тип | Обязательно | Описание |
|---|---|---|---|
env | inject_delivery | нет | Один механизм доставки, записываемый как массив записей. Каждая запись содержит ‘in’ (локальный идентификатор — имя переменной окружения, путь к файлу, флаг аргумента или ключ, специфичный для пользовательского механизма) и ровно одно из ‘from’ (ключ provides для разрешения) или ‘value’. В сущности Release каждая запись находится на соединении, поэтому ‘from’ разрешается относительно provides цели, а запись, содержащая ‘value’, отклоняется. |
file | inject_delivery | нет | Один механизм доставки, записываемый как массив записей. Каждая запись содержит ‘in’ (локальный идентификатор — имя переменной окружения, путь к файлу, флаг аргумента или ключ, специфичный для пользовательского механизма) и ровно одно из ‘from’ (ключ provides для разрешения) или ‘value’. В сущности Release каждая запись находится на соединении, поэтому ‘from’ разрешается относительно provides цели, а запись, содержащая ‘value’, отклоняется. |
arg | inject_delivery | нет | Один механизм доставки, записываемый как массив записей. Каждая запись содержит ‘in’ (локальный идентификатор — имя переменной окружения, путь к файлу, флаг аргумента или ключ, специфичный для пользовательского механизма) и ровно одно из ‘from’ (ключ provides для разрешения) или ‘value’. В сущности Release каждая запись находится на соединении, поэтому ‘from’ разрешается относительно provides цели, а запись, содержащая ‘value’, отклоняется. |
inject_delivery
Один механизм доставки, записываемый как массив записей. Каждая запись содержит ‘in’ (локальный идентификатор — имя переменной окружения, путь к файлу, флаг аргумента или ключ, специфичный для пользовательского механизма) и ровно одно из ‘from’ (ключ provides для разрешения) или ‘value’. В сущности Release каждая запись находится на соединении, поэтому ‘from’ разрешается относительно provides цели, а запись, содержащая ‘value’, отклоняется.
Тип: object[]