Схема Aggrega Catalog (Feature)
Згенерований довідник. Не редагуйте вручну — згенеруйте повторно з опублікованої JSON Schema.
Ідентифікатор схеми: https://aggrega.ai/schemas/feature-v1beta1.schema.json
Модульна операційна функція, яка динамічно прив’язується до компонентів.
Описові вказівки щодо створення сутностей Feature див. у довідці зі створення сутностей Feature; ця сторінка документує структурну схему, яку описує та довідка.
Тип верхнього рівня: object
Властивості
| Властивість | Тип | Обов’язкова | Опис |
|---|---|---|---|
apiVersion | const “aggrega.ai/v1beta1” | так | Константа: "aggrega.ai/v1beta1" |
kind | const “Feature” | так | Константа: "Feature" |
metadata | object | так | |
spec | object | так | Контракт валідації, націлювання та сумісності для сутності Feature з каталогу: стовпи довільної форми (values, infra, provides), що описуються через schema, стовпи фіксованої форми (гнізда залежностей usesSchema, слоти прикріплення featuresSchema), націлювання на компоненти (appliesTo і appliesToAnyOf) та елементи керування сумісністю. |
Додаткові властивості не дозволені.
feature.metadata
| Властивість | Тип | Обов’язкова | Опис |
|---|---|---|---|
name | string | так | Щонайменше 1 символ. |
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 | ні | Що це за сутність і для чого вона призначена — для того, хто вирішує, чи використовувати її. Почніть із речення, що називає її, а потім додайте те, що потрібно читачеві, щоб вибрати її та правильно використовувати: чого вона очікує від сутності Release, яка її розгортає, і все несподіване в її поведінці. Зазвичай достатньо короткого абзацу. |
maintainers | object[] | ні | Список супровідників, яким належить ця сутність. |
license | string | ні | Ідентифікатор SPDX ліцензії програмного забезпечення, яке описує ця сутність, наприклад MIT або AGPL-3.0. Він фіксує умови цього програмного забезпечення, а не умови цього файлу. |
repository | string | ні | URL репозиторію Git, де зберігаються вихідні файли. |
home | string | ні | URL домашньої сторінки, вікі або документації цієї сутності. |
keywords | string[] | ні | Список описових ключових слів для зручного пошуку в інтерфейсі. |
labels | object | ні | Мітки качиної типізації для сутності Feature. Зарезервована мітка ‘feature.aggrega.ai/kind’ зі значенням ‘secret’ позначає її як сутність Feature з обліковими даними для автора та для інструментів, що її відображають. Сутність Feature з обліковими даними і звичайна сутність Feature прикріплюються однаково, через ту саму поверхню прикріплення; результат прикріплення визначає сутність FeatureRecipe, на яку Manifest відображає його тип, а не мітка. |
annotations | map of string | ні | Незмінні, внутрішні характеристики функції, які задає архітектор платформи в домені 2. Каскадно передаються до сегмента .context.annotations.catalog. |
Додаткові властивості не дозволені.
feature.metadata.maintainers[]
| Властивість | Тип | Обов’язкова | Опис |
|---|---|---|---|
name | string | так | |
email | string | ні | |
url | string | ні |
Додаткові властивості не дозволені.
feature.metadata.labels
Мітки качиної типізації для сутності Feature. Зарезервована мітка ‘feature.aggrega.ai/kind’ зі значенням ‘secret’ позначає її як сутність Feature з обліковими даними для автора та для інструментів, що її відображають. Сутність Feature з обліковими даними і звичайна сутність Feature прикріплюються однаково, через ту саму поверхню прикріплення; результат прикріплення визначає сутність FeatureRecipe, на яку Manifest відображає його тип, а не мітка.
| Властивість | Тип | Обов’язкова | Опис |
|---|---|---|---|
feature.aggrega.ai/kind | string (enum) | ні | Мітка виду функції. Значення ‘secret’ позначає її як сутність Feature з обліковими даними. Допустимі значення: "secret" |
feature.spec
Контракт валідації, націлювання та сумісності для сутності Feature з каталогу: стовпи довільної форми (values, infra, provides), що описуються через schema, стовпи фіксованої форми (гнізда залежностей usesSchema, слоти прикріплення featuresSchema), націлювання на компоненти (appliesTo і appliesToAnyOf) та елементи керування сумісністю.
| Властивість | Тип | Обов’язкова | Опис |
|---|---|---|---|
extends | string | ні | Посилання на базову сутність Feature, від якої успадковується ця Feature. Воно називає базову сутність за її metadata.name, а не за координатою реєстру, під якою публікується Feature, і приймає ті самі три форми версії, що й будь-яке посилання на каталог: без версії (core/queue) — для найвищого доступного випуску, точну (core/queue:1.0.0) або діапазон із кареткою (core/queue:^1.0.0). Успадковуються не лише метадані: metadata.labels і metadata.annotations базової сутності, її селектори appliesTo і appliesToAnyOf, її блок interoperability, її usesSchema і featuresSchema зливаються вниз, а її оголошення JSON Schema 2020-12 у schema автоматично зливаються. Для спільного ключа перевагу має власне значення дочірньої сутності, а поля ідентичності ніколи не успадковуються. |
featuresSchema | map of object | ні | Декларативні визначення слотів приєднання: іменовані точки прив’язки, у яких ця Feature очікує приєднання ще однієї сутності Feature. Слот обмежує, яке заповнення може його прив’язати (selector) і як може доставлятися матеріал заповнення (inject); власна Feature заповнення володіє своїм контрактом values та infra. Оголошення слота ніколи не закриває блок приєднань — автор може приєднати Feature під ім’ям, якого не оголошує жоден слот. Слот — це точка прив’язки, а не сокет залежності: usesSchema оголошує окрему поверхню топології. |
appliesTo | string | ні | Рядок селектора міток у стилі Kubernetes, що зіставляється з сутностями Components. Розділені комами вимоги мають виконуватися всі (AND). Підтримувані форми: key=value, key!=value, key in (v1, v2), key notin (v1, v2), ключ без значення (мітка присутня), !key (мітка відсутня). Приклад: “tier in (critical, production), !legacy”. Порожній або відсутній селектор не оголошує жодного обмеження. Селектор зчитується згідно з цими формами щоразу, коли обчислюється приєднання цієї Feature, а вимога поза ними зупиняє збирання з її зазначенням: порожня вимога (початкова, кінцева або подвоєна кома) або ключ, що містить пробіли чи будь-який із символів = ! ( ) і кому, — тож “!tier=frontend” відхиляється, а значення виключається так: tier!=frontend. Значення — це текст після його оператора, хоч які символи він містить. Шаблон цього поля відхиляє лише кілька неправильно сформованих форм, до обчислення будь-якого приєднання. Шаблон: ^(?:[^()]*[()][\s\S]*|[ \t]*(?:![ \t]*[^,]*[^ \t,][^,]*|[^ \t,!][^,]*)?(?:,[ \t]*(?:![ \t]*[^,]*[^ \t,][^,]*|[^ \t,!][^,]*)?)*)$. |
appliesToAnyOf | string або map of string[] | ні | Список селекторів; Feature застосовується, якщо збігається БУДЬ-ЯКИЙ елемент (логіка OR). Кожен елемент — це або рядок селектора міток (та сама граматика, що й у appliesTo; вимоги всередині рядка поєднуються через AND), або пласка мапа ключ-значення, у якій мають збігатися всі пари (лише рівність). |
interoperability | object | ні | Розширені засоби керування операційною безпекою та сумісністю. |
usesSchema | map of object | ні | Сокети залежностей, які оголошує ця сутність, з назвою сокета як ключем; кожне з’єднання, проведене через сокет, перевіряється щодо оголошення цього сокета — його селектора та дозволених механізмів inject. Ключі: одна або більше літер, цифр, підкреслень чи дефісів. Крапка не дозволена. Шаблон: ^[a-zA-Z0-9_-]+$. |
schema | object | ні | Вміст JSON Schema 2020-12, що охоплює стовпи вільної форми: values (домен розробника — параметри форми застосунку, які розробник налаштовує для кожного приєднання Feature в Aggregate); infra (домен оператора — регулятори фізичного розміру, які надає Release); і provides (ключі контексту нижчого рівня, які ця Feature відкриває споживачам через канал топології). Приймає три режими створення через диспетчеризацію за формою вмісту: (1) вбудований вміст (мапа YAML у компактній формі, JSON Schema YAML або змішана); (2) заміна файлом через {$import: |
assertions | map of string | ні | Перехресна валідація полів під час збирання. Кожен запис — це іменоване твердження: ключ — стабільний ідентифікатор правила, що показується в повідомленнях про помилки; значення — рядок шаблону Go із семантикою зупинки {{ fail "message" }}. Кілька іменованих тверджень на сутність обчислюються для кожного екземпляра в порядку, оголошеному автором; перше хибне твердження зупиняє збирання. Твердження Feature обчислюються після розв’язання та статичного аналізу, до рендерингу, й виражають архітектурні інваріанти контракту. Контекст шаблону: .values / .infra / .uses / .features / .metadata. Обчислювач використовує missingkey=error: посилання на невизначені ключі зупиняють збирання з діагностикою no-such-key. Оскільки просте посилання зупиняє збирання до того, як може спрацювати будь-який резервний варіант, звичайний default не забезпечує резервного значення для необов’язкового поля на цій поверхні — обмежте посилання за допомогою hasKey або скористайтеся помічником optional, який виконує перевірку присутності безпосередньо. Читання ключа через index теж його не забезпечує: index зупиняє збирання на ключі мапи, якого мапа не містить, зазначаючи цей ключ. |
Додаткові властивості не дозволені.
feature.spec.interoperability
Розширені засоби керування операційною безпекою та сумісністю.
| Властивість | Тип | Обов’язкова | Опис |
|---|---|---|---|
conflictsWith | string[] | ні | Імена сутностей Features, разом з якими ця Feature не може потрапити до компонента, кожне записане так, як тип приєднання називає Feature. Збирання зупиняється до рендерингу, коли один компонент у підсумку містить цю Feature і названу тут Feature — незалежно від того, чи кожну з них приєднано до компонента, до підсистеми чи межі, що його містить, до запису компонента в Release, чи через розгортання на основі анотацій. Достатньо одного оголошення: для зупинки не потрібно, щоб інша Feature перелічувала цю. Імена порівнюються без версії, тож запис збігається з кожною версією Feature, яку він називає. Дві сутності Features, приєднані до сусідніх меж без спільного компонента, ніколи не зустрічаються і зупинки не спричиняють. |
Додаткові властивості не дозволені.