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

Схема Aggrega Release

Сгенерированный справочник. Не редактируйте вручную — сгенерируйте заново из опубликованной JSON Schema.

Идентификатор схемы: https://aggrega.ai/schemas/release-v1beta1.schema.json

Описательные рекомендации по созданию сущностей Release см. в справочнике по созданию сущностей Release; на этой странице описана структурная схема, которую описывает этот справочник.

Тип верхнего уровня: object

Свойства

СвойствоТипОбязательноОписание
apiVersionconst “aggrega.ai/v1beta1”даКонстанта: "aggrega.ai/v1beta1"
kindconst “Release”даКонстанта: "Release"
metadataobjectда
specobjectдаТо, что сущность Release привязывает и маршрутизирует: Aggregate и Manifest, которые она развёртывает (или базовый релиз extends), выполнение параметров для конкретного окружения и границы, в которые направляются её компоненты.

Дополнительные свойства не допускаются.

release.metadata

СвойствоТипОбязательноОписание
namestringдаНе менее 1 символа.
environmentstringда
versionstringдаСтрогая семантическая версия релиза (например, 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-]+)*))?$.
descriptionstringнетЧто представляет собой эта сущность и для чего она нужна — для того, кто решает, использовать ли её. Начните с предложения, называющего её, затем добавьте то, что читателю нужно, чтобы выбрать её и правильно использовать: чего она ожидает от платформы, на которую развёртывается, и что в её поведении может оказаться неожиданным. Обычная длина — короткий абзац.
maintainersobject[]нетСписок сопровождающих, которым принадлежит эта сущность.
licensestringнетИдентификатор SPDX лицензии программного обеспечения, которое описывает эта сущность, например MIT или AGPL-3.0. Он фиксирует условия этого программного обеспечения, а не условия данного файла.
repositorystringнетURL Git-репозитория, в котором находятся исходные файлы.
homestringнетURL домашней страницы, вики или документации этой сущности.
keywordsstring[]нетСписок описательных ключевых слов для удобства поиска в интерфейсе.

Дополнительные свойства не допускаются.

release.metadata.maintainers[]
СвойствоТипОбязательноОписание
namestringда
emailstringнет
urlstringнет

Дополнительные свойства не допускаются.

release.spec

То, что сущность Release привязывает и маршрутизирует: Aggregate и Manifest, которые она развёртывает (или базовый релиз extends), выполнение параметров для конкретного окружения и границы, в которые направляются её компоненты.

СвойствоТипОбязательноОписание
aggregatestringнетСсылка на Aggregate (намерение разработчика), который развёртывает этот релиз. Простой токен разрешается по идентичности — по metadata.name соответствующей сущности Aggregate, поиск ведётся в собственном каталоге сущности Release, а затем в каталоге пакетов. Значение, начинающееся с ’./’ или ’../’, — явный локальный файл, разрешаемый относительно сущности Release (например, ’../shared/app.yaml’, чтобы использовать один Aggregate в нескольких вариантах релиза в подкаталоге).
manifeststringнетСсылка на Manifest, разрешающий абстрактные интерфейсы, относительно которых развёртывается этот релиз. Простой токен разрешается по идентичности — по metadata.name соответствующей сущности Manifest, поиск ведётся в собственном каталоге сущности Release. Значение, начинающееся с ’./’ или ’../’, — явный локальный файл, разрешаемый относительно сущности Release. Manifest относится к стороне развёртывания и не индексируется в каталоге, поэтому разрешается только из каталога сущности Release или по явному пути.
extendsstringнетСсылка на базовую сущность Release, авторскую поверхность которой наследует этот Release: её дерево границ с привязками infra и Feature для каждого компонента, её параметры, её аннотации и её указатель на Manifest. Значение — путь к файлу рядом с этим Release, начинающийся с ’./’ или ’../’; простое имя и координата реестра отклоняются, поскольку Release относится к стороне развёртывания и не индексируется в каталоге. Унаследованное можно заменять ключ за ключом, вплоть до первого неделимого значения — скаляра, списка, шаблона, — которое заменяется целиком; ключ, записанный как null, удаляет унаследованное. Поля metadata не наследуются, поэтому дочерний релиз задаёт собственные имя, версию и окружение. Объявление ‘aggregate’ вместе с ‘extends’ отклоняется этой схемой, поэтому дочерний релиз развёртывает то же намерение разработчика, что и базовый; ‘manifest’ остаётся необязательным и может быть переопределён, чтобы заменить lock-файл зависимостей.
parametersobjectнетКонтракт выполнения переменных для конкретного окружения с двумя режимами написания, выбираемыми по форме содержимого. Режим 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

Экземпляр компонента, направленный в границу, с необязательными физическими размерами и подключениями функций.

СвойствоТипОбязательноОписание
descriptionstringнетНеобязательная документация, описывающая роль этого компонента в данной границе сущности Release.
subDirectorystringнетПереопределение подпути на уровне Component, добавляемое к каталогу родительской границы. Если оно опущено или пусто и у границы, и у компонента, по умолчанию используется ’{{ .capability }}’; пустая строка, записанная здесь, считается опущенным значением. Чтобы отключить создание подкаталогов, задайте ’.’ или шаблон, который вычисляется в пустую строку.
annotationsmap из string, object или nullнетАннотации оператора, специфичные для Component, которые переопределяют аннотации уровня границы для этого компонента. Глубоко объединяются поверх аннотаций границы (при совпадении ключей побеждает компонент; структурированные значения объединяются по подключам со структурированными родительскими значениями). Значения — строки, структурированные объекты или null. Используются для переопределения общеизвестных аннотаций провайдера на уровне компонента (например, aggrega.ai/namespace у провайдера helm). Явный null у ключа, унаследованного от родительской границы, удаляет унаследованную привязку из этого компонента (отказ от Feature через аннотации); соседние компоненты сохраняют унаследованную привязку.
infraobjectнетФизические размеры, строго локальные для этого компонента (например, реплики, IOPS диска).
featuresmap of objectнетFeatures, подключённые к этому компоненту через Release. Для функциональностей, также объявленных в Aggregate, предоставляется только infra (значения берутся из Aggregate). Для функциональностей, существующих только в Release (внедрённых оператором), type обязателен. Ключи — имена экземпляров функциональностей; они могут содержать полный URI типа функциональности (точки и слэши допускаются). Release НЕ ДОЛЖЕН предоставлять значения для функциональностей — это зона ответственности разработчика. Ключи: одна или несколько букв, цифр, подчёркиваний, точек, слэшей или дефисов. Шаблон: ^[a-zA-Z0-9_./-]+$.
usesrelease_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, заполняющая слот, объявленный сокетом соединения, вместе с заданными оператором размерами для неё.

СвойствоТипОбязательноОписание
typestringнетURI сущности Feature. Обязателен для подключения, которое делает только Release. Должен совпадать с типом в Aggregate, если его объявляют оба.
descriptionstringнетНеобязательная документация, объясняющая, почему оператор подключил эту функцию к соединению.
infraobjectнетЭксплуатационные размеры для этого подключения, проверяемые по объявлению схемы сущности Feature.

Дополнительные свойства не допускаются.

aggregate_routing

Направляет внутренние компоненты вложенного подмодуля Aggregate в эту границу. Повторяет структуру component/aggregate границы для рекурсивной композиции.

СвойствоТипОбязательноОписание
componentsсловарь boundary_componentнетЭкземпляры Component во вложенном агрегате, которые направляются в эту границу. Ключи — локальные имена, которые каждый компонент носит внутри этого подмодуля: ‘main-db’ для компонента, к которому собственная карта components границы обращается как ‘data.main-db’, — поскольку это единственное имя, которое у него там есть. Ключи: одна или несколько букв, цифр, подчёркиваний или дефисов. Точка не допускается. Шаблон: ^[a-zA-Z0-9_-]+$.
aggregatesmap of aggregate_routingнетДальнейшие вложенные агрегаты внутри этого подагрегата (для глубоко вложенной модульной композиции). Ключи: одна или несколько букв, цифр, подчёркиваний или дефисов. Точка не допускается. Шаблон: ^[a-zA-Z0-9_-]+$.

Дополнительные свойства не допускаются.

boundary

СвойствоТипОбязательноОписание
descriptionstringнетНеобязательная документация, описывающая назначение этой границы и её физическую цель (например, ‘Primary production EKS cluster in us-east-1, PCI-DSS compliant’).
directorystringнетФизический выходной путь для генерации артефактов GitOps. Поддерживает переменные шаблонов Go ({{ .capability }}, {{ .boundary_name }}, {{ .parameters.X }}). Объединяется с subDirectory как соединение путей, чтобы получить итоговый путь артефакта.
subDirectorystringнетПодпуть уровня границы, добавляемый к directory. Если он опущен или пуст и у границы, и у компонента, по умолчанию используется ’{{ .capability }}’ для автоматического разбиения CI/CD; пустая строка, записанная здесь, считается опущенным значением. Чтобы отключить, задайте ’.’ или шаблон, который вычисляется в пустую строку.
syncWaveintegerнетНеобязательная волна развёртывания для границы (целое число со знаком, по умолчанию 0). Каждый компонент этой границы наследует волну границы в свой узел. Допускаются отрицательные значения (выполняются раньше всего остального); большие значения выполняются после меньших. В K8s и Helm именно волна задаёт порядок развёртывания: она становится аннотацией argocd.argoproj.io/sync-wave, а на ресурсе, который чарт уже помечает как хук Helm, она также становится helm.sh/hook-weight этого хука. В compose волна и записывается как метка сервиса, и упорядочивает сервисы файла, в который она рендерится, через depends_on между ними — поэтому она действует на каждый сервис в этом одном файле и ни на что за его пределами. В cloudformation волна упорядочивает выделение ресурсов стека, в который собирается граница: каждый ресурс волны объявляется зависимым от ресурсов предыдущей волны, что фиксирует порядок их создания и, в обратном порядке, порядок их удаления. Это только порядок создания и удаления — шаблон стека не выражает понятия готовности ресурса, поэтому ничто не ждёт, пока ресурс станет пригодным к работе. В terraform волна упорядочивает блоки module корневой конфигурации, в которую собирается граница: каждый модуль волны объявляется зависимым от модулей предыдущей волны, что фиксирует порядок, в котором движок выполняет свои действия. Это только порядок действий — конфигурация не выражает понятия готовности ресурса, поэтому ничто не ждёт, пока ресурс станет пригодным к работе, — и значение также записывается вместе с происхождением сборки узла. Компилятор переносит то же значение на каждый узел границы как sync_wave этого узла, где поведение для каждой цели описано ещё раз со стороны узла. Вложенные границы не наследуют волну неявно — каждая объявляет собственную волну.
annotationsmap из string, object или nullнетАннотации оператора для всей границы, каскадно передаваемые в раздел .context.annotations.release. Значения — строки, структурированные объекты или null. Структурированное значение несёт конфигурацию по подключам, которая глубоко сливается со структурированными родительскими значениями (по подключам, дочернее побеждает) и проходит через управляемое аннотациями развёртывание Feature; в контексте рендеринга появляются только скалярные значения. Явный null на ключе, унаследованном от родительской границы, удаляет унаследованную привязку из эффективного набора аннотаций этой границы (управляемый аннотациями отказ от Feature) и распространяется на каждый компонент, направленный в эту границу, если только более глубокое переопределение не вводит привязку заново.
featuresmap 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_.-]+$.
aggregatesmap 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, поэтому механизм с таким именем был бы им скрыт, а указание такого имени останавливает сборку.

СвойствоТипОбязательноОписание
envinject_deliveryнетОдин механизм доставки, записываемый как массив записей. Каждая запись содержит ‘in’ (локальный идентификатор — имя переменной окружения, путь к файлу, флаг аргумента или ключ, специфичный для пользовательского механизма) и ровно одно из ‘from’ (ключ provides для разрешения) или ‘value’. В сущности Release каждая запись находится на соединении, поэтому ‘from’ разрешается относительно provides цели, а запись, содержащая ‘value’, отклоняется.
fileinject_deliveryнетОдин механизм доставки, записываемый как массив записей. Каждая запись содержит ‘in’ (локальный идентификатор — имя переменной окружения, путь к файлу, флаг аргумента или ключ, специфичный для пользовательского механизма) и ровно одно из ‘from’ (ключ provides для разрешения) или ‘value’. В сущности Release каждая запись находится на соединении, поэтому ‘from’ разрешается относительно provides цели, а запись, содержащая ‘value’, отклоняется.
arginject_deliveryнетОдин механизм доставки, записываемый как массив записей. Каждая запись содержит ‘in’ (локальный идентификатор — имя переменной окружения, путь к файлу, флаг аргумента или ключ, специфичный для пользовательского механизма) и ровно одно из ‘from’ (ключ provides для разрешения) или ‘value’. В сущности Release каждая запись находится на соединении, поэтому ‘from’ разрешается относительно provides цели, а запись, содержащая ‘value’, отклоняется.

inject_delivery

Один механизм доставки, записываемый как массив записей. Каждая запись содержит ‘in’ (локальный идентификатор — имя переменной окружения, путь к файлу, флаг аргумента или ключ, специфичный для пользовательского механизма) и ровно одно из ‘from’ (ключ provides для разрешения) или ‘value’. В сущности Release каждая запись находится на соединении, поэтому ‘from’ разрешается относительно provides цели, а запись, содержащая ‘value’, отклоняется.

Тип: object[]