Схема 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 | ні | Екземпляри компонентів верхнього рівня з infra оператора для кожного компонента, для сутності Release з однією областю без іменованих меж. Взаємовиключне з boundaries: оголошуйте components для пласкої сутності Release або boundaries для маршрутизації в кілька цілей, але ніколи обидва. Коли використовується components, компілятор синтезує межу default, що їх містить, і виводить їхні артефакти в dist/ пласко. Ключі: одна або більше літер, цифр, підкреслень чи дефісів. Крапка не допускається. Шаблон: ^[a-zA-Z0-9_-]+$. |
Додаткові властивості не дозволені.
Визначення
boundary_component
Екземпляр компонента, спрямований у межу, з необов’язковим фізичним розміром і прикріпленими функціями.
| Властивість | Тип | Обов’язкова | Опис |
|---|---|---|---|
description | string | ні | Необов’язкова документація, що описує роль цього компонента в цій межі сутності Release. |
subDirectory | string | ні | Перевизначення підшляху на рівні Component, що додається до каталогу батьківської межі. Якщо його пропущено або воно порожнє і в межі, і в компоненті, типово використовується ’{{ .capability }}’; порожній рядок, записаний тут, вважається пропущеним. Щоб вимкнути створення підкаталогів, задайте ’.’ або шаблон, який обчислюється в порожній рядок. |
annotations | map of string or object or null | ні | Анотації оператора, специфічні для Component, що перевизначають анотації рівня межі для цього компонента. Глибоко зливаються поверх анотацій межі (у разі збігу ключів перемагає компонент; структуровані значення зливаються за підключами зі структурованими батьківськими). Значення — рядки, структуровані об’єкти або null. Використовуються для перевизначення добре відомих анотацій провайдера для окремих компонентів (наприклад, aggrega.ai/namespace у провайдера helm). Явний null на ключі, успадкованому від батьківської межі, вилучає успадковану прив’язку з цього компонента (відмова від Feature через анотації); сусідні компоненти зберігають успадковану прив’язку. |
infra | object | ні | Фізичний розмір, суворо локальний для цього компонента (наприклад, репліки, IOPS диска). |
features | map of object | ні | Features, прикріплені до цього компонента через Release. Для функцій, також оголошених в Aggregate, надається лише infra (значення беруться з Aggregate). Для функцій лише з Release (впроваджених Operator) type є обов’язковим. Ключі — імена екземплярів функцій, і вони можуть містити повний URI типу функції (крапки й скісні риски дозволено). Release НЕ ПОВИНЕН надавати values для функцій — це сфера розробника. Ключі: одна або більше літер, цифр, підкреслень, крапок, скісних рисок чи дефісів. Шаблон: ^[a-zA-Z0-9_./-]+$. |
uses | release_uses_block | ні | Поверхня ребер для Operator. У межах сокетів, оголошених Architect, 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. Має збігатися з type в Aggregate, якщо його оголошують обидва. |
description | string | ні | Необов’язкова документація, що пояснює, чому Operator прикріпив цю функцію до з’єднання. |
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 hook, вона також стає helm.sh/hook-weight цього хука. У compose хвиля і записується як мітка сервісу, і впорядковує сервіси файлу, у який вона рендериться, через depends_on між ними — тож вона охоплює кожен сервіс у цьому одному файлі й нічого поза ним. У cloudformation хвиля впорядковує підготовку стека, до якого збирається межа: кожен ресурс хвилі оголошується залежним від ресурсів попередньої хвилі, що фіксує порядок їх створення і, у зворотному напрямку, порядок їх видалення. Це лише порядок створення й видалення — шаблон стека не виражає поняття готовності ресурсу, тож ніщо не чекає, поки ресурс стане придатним до роботи. У terraform хвиля впорядковує блоки module кореневої конфігурації, до якої збирається межа: кожен модуль хвилі оголошується залежним від модулів попередньої хвилі, що фіксує порядок, у якому рушій виконує свої дії. Це лише порядок дій — конфігурація не виражає поняття готовності ресурсу, тож ніщо не чекає, поки ресурс стане придатним до роботи, — а значення також записується разом із походженням збірки вузла. Компілятор переносить те саме значення на кожен вузол межі як sync_wave цього вузла, де поведінку для кожної цілі описано ще раз з боку вузла. Вкладені межі не успадковують неявно — кожна оголошує власну хвилю. |
annotations | map of string or object or 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[]