Схема Aggrega Infrastructure Base (FeatureRecipe)
Згенерований довідник. Не редагуйте вручну — згенеруйте повторно з опублікованої JSON Schema.
Ідентифікатор схеми: https://aggrega.ai/schemas/featurerecipe-v1beta1.schema.json
Визначення, які створюють Ops-інженери і які зіставляють абстрактну сутність Feature з каталогу з конкретною версіонованою реалізацією для однієї можливості провайдера. Строго 1:1 з фізичним провайдером і функцією каталогу.
Див. довідник з написання FeatureRecipe, де описано, як створювати сутності FeatureRecipe; ця сторінка документує структурну схему, яку описує той довідник.
Тип верхнього рівня: object
Властивості
| Властивість | Тип | Обов’язкова | Опис |
|---|---|---|---|
apiVersion | const “aggrega.ai/v1beta1” | так | Константа: "aggrega.ai/v1beta1" |
kind | const “FeatureRecipe” | так | Константа: "FeatureRecipe" |
metadata | object | так | |
spec | object | так | Прив’язка до можливості провайдера, мапінг, конвеєр і мапінг ін’єкцій для сутності FeatureRecipe. Містить ті самі три види вхідних даних, що й Recipe (sourced, synthesized, artifacts), а також injectMapping, наявний лише у FeatureRecipe; FeatureRecipe лише для зв’язування, що оголошує тільки capability та implements, є коректною і нічого не рендерить. |
Додаткові властивості не дозволені.
featurerecipe.metadata
| Властивість | Тип | Обов’язкова | Опис |
|---|---|---|---|
name | string | так | Щонайменше 1 символ. |
version | string | так | Строга семантична версія сутності FeatureRecipe (наприклад, 1.2.5). Шаблон: ^(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[] | ні | Список описових ключових слів для зручного пошуку в інтерфейсі. |
Додаткові властивості не дозволені.
featurerecipe.metadata.maintainers[]
| Властивість | Тип | Обов’язкова | Опис |
|---|---|---|---|
name | string | так | |
email | string | ні | |
url | string | ні |
Додаткові властивості не дозволені.
featurerecipe.spec
Прив’язка до можливості провайдера, мапінг, конвеєр і мапінг ін’єкцій для сутності FeatureRecipe. Містить ті самі три види вхідних даних, що й Recipe (sourced, synthesized, artifacts), а також injectMapping, наявний лише у FeatureRecipe; FeatureRecipe лише для зв’язування, що оголошує тільки capability та implements, є коректною і нічого не рендерить.
| Властивість | Тип | Обов’язкова | Опис |
|---|---|---|---|
capability | string | так | Явна можливість провайдера, до якої прив’язується цей рецепт (наприклад, ‘helm’, ‘terraform’, ‘compose’), — вид провайдера, що його рендерить. |
implements | string | так | Оголошує, який тип каталогу Feature цей рецепт здатен реалізувати (зокрема облікові Features з міткою feature.aggrega.ai/kind: secret; точна версія, діапазон, сумісний за мажорною версією, ’^’, або без версії). Компілятор використовує це для перевірки мапінгів Manifest і для пропонування кандидатів у діагностиці та автодоповненні редактора; збірку він цим ніколи не розв’язує. Мапінг у Manifest — це явний вибір реалізації користувачем, зафіксований у lock-файлі сутності Release. |
locals | map of string | ні | Приватний стан Ops. Внутрішні результати обчислень, доступні лише в шаблонах цієї FeatureRecipe як ‘.locals.*’. Кожен запис сам є шаблоном Go, що обчислюється відносно самодостатнього контексту: ‘.context.instance_id’ (ХОСТОВИЙ КОМПОНЕНТ, для якого розв’язується це приєднання, — саме це позначає таке посилання на кожній поверхні шаблонів), ‘.attachment_name’ (екземпляр приєднання, що розв’язується, і єдиний шлях до цієї назви з локального запису), власні ‘.values’ та ‘.infra’ приєднання, а також записи цього самого блоку, розв’язані на цей момент. Записи розв’язуються в порядку, у якому їх написано, і запис МОЖЕ читати сусідній запис, визначений ВИЩЕ за нього, отримуючи розв’язане значення цього запису, а не текст його шаблону. Порядок автора є частиною контракту скрізь, де один запис читає інший: перенесення визначення нижче за запис, що його читає, ламає збірку, і блок ніколи не переупорядковується, щоб посилання розв’язалося. Посилання ‘.locals. |
provides | map of string | ні | Публічний API розробника. Контрактні вихідні змінні, доступні для розв’язання inject викликачем нижче за потоком. Коли executionScope має значення boundary, provides обчислюються один раз для приєднання до межі, відносно контексту шаблонів області межі, і кожен компонент, якого досягає приєднання, читає це одне обчислення за шляхом ‘.features. |
source | рядок або об’єкт | ні | Необов’язковий шлях до коду інфраструктури. Приймає рядок URI або відкритий структурований об’єкт. Якщо його задано разом із valuesMapping, компілятор рендерить його, і відрендерені документи долучаються до виводу FeatureRecipe до виконання її кроків конвеєра. |
valuesMapping | рядок або об’єкт | ні | Вміст мапінгу значень із трьома режимами написання через диспетчеризацію за формою вмісту. Режим 1 (вбудований): скалярний рядок шаблону Go, що створює очікуваний провайдером формат значень. Режим 2 (імпорт файлу): мапа YAML рівно з одним ключем, $import: ./relative/path.tmpl, що вказує на локальний файл шаблону Go. Режим 3 (імпорт бібліотеки): мапа YAML рівно з одним ключем, $import: <Library>#/mappings/<entry>, що посилається на запис MappingLibrary за ідентичністю голої назви (версію надає lock-файл кожної Release; хост реєстру в посиланні не вказується). В об’єктній формі $import не повинен відповідати ^oci://; значення, яке відповідає, відхиляється. |
workload | рядок або об’єкт | ні | Генератор YAML для Workload із трьома режимами написання через диспетчеризацію за формою вмісту. Режим 1 (вбудований): скалярний рядок шаблону Go, вихід якого розбирається як ‘aggrega.ai/v1beta1 Workload’. Режим 2 (імпорт файлу): мапа YAML рівно з одним ключем, $import: ./relative/path.yaml, що вказує на локальний файл шаблону Go. Режим 3 (імпорт бібліотеки): мапа YAML рівно з одним ключем, $import: <Library>#/workloads/<entry>, що посилається на запис WorkloadLibrary за ідентичністю голої назви (версію надає lock-файл кожної Release; хост реєстру в посиланні не вказується). Цільовий Provider має підтримувати синтез навантаження; каталог стандартної бібліотеки оголошує workloadSchema на таких провайдерах як задокументований контракт. FeatureRecipe з workload:, прив’язана до провайдера, що не вміє синтезувати, явно зупиняє збірку під час рендерингу. Синтезоване навантаження FeatureRecipe видає свої нативні для провайдера маніфести у вихідному каталозі функції. В об’єктній формі $import не повинен відповідати ^oci://; значення, яке відповідає, відхиляється. |
artifacts | мапа рядків або об’єктів | ні | Мапа з імені запису на вміст артефакту. Значення кожного запису має один із трьох режимів, які розрізняються за формою вмісту. Режим 1 (inline): скалярний рядок шаблону Go, вивід якого є тілом артефакту. Режим 2 (імпорт файлу): YAML-мапа рівно з одним ключем, $import: ./relative/path.yaml, що вказує на локальний файл шаблону Go. Режим 3 (імпорт бібліотеки): YAML-мапа рівно з одним ключем, $import: <Library>#/artifacts/<entry>, що посилається на пакет ArtifactLibrary за ідентичністю простого імені (версію надає lockfile кожного Release; хост реєстру в посиланні не з’являється). Пакет розгортається в один вивід на кожен файл, кожен вкладений під ключ запису як <key>/<filename>. Ключ називає вивід запису: ключ запису режиму 1 або режиму 2 є іменем його вихідного файлу й використовується як написано, а імпортований файл запису режиму 2 надає вміст, не називаючи вивід, тож два записи, що імпортують різні файли з однаковою назвою, — це два окремі виводи. Допоміжні ресурси, які створює FeatureRecipe, що генерує ресурси (ConfigMap, ServiceMonitor, NetworkPolicy, ExternalSecret CRD тощо), мають форму артефактів; artifacts: — основний механізм генерування ресурсів. Колізії між записами артефактів, файлами пакетів, виводом source і синтезом workload зупиняють збірку, коли вузол рендериться. Блок artifacts пишеться однаково в Recipe і у FeatureRecipe — ті самі три режими, те саме правило відповідності ключа виводу й та сама поведінка при колізіях, — тому ця частина опису однакова для обох видів; приклад, написаний для одного, без змін переноситься на інший. В об’єктній формі $import не повинен відповідати ^oci://; значення, яке відповідає, відхиляється. Ключі: ключ називає вивід запису, тому обмежений одним іменем файлу: він починається з літери або цифри й продовжується літерами, цифрами, крапками, дефісами чи підкресленнями. Крапки після першого символу зберігають розширення, які мають ключі артефактів (main.tf, template.yaml, serviceaccount.yaml). Символ / зробив би ключ назвою шляху, а не файлу, а початкова . допустила б .., що називає розташування поза вихідним каталогом, — клас першого символу відкидає обидва. Для імпорту бібліотеки ключ називає каталог, під яким вкладаються файли пакета, тож діє те саме обмеження. Шаблон: ^[A-Za-z0-9][A-Za-z0-9._-]*$. |
omits | object[] | ні | Що вилучити з того, що рендерить source цього FeatureRecipe, — для source, узятого як є, який рендерить щось, чого Release не повинен постачати: документ, який рендерить завантажений chart, як-от Secret із ключем, що chart генерує заново при кожному рендерингу, service, volume чи config, які містить завантажений compose-файл, або ресурс, який оголошує завантажений шаблон CloudFormation. Більшості FeatureRecipes це ніколи не потрібно. Кожен запис називає одну одиницю, яку рендерить source, за її видом, іменем і, якщо запис їх вказує, простором імен і субчартом, з якого вона походить, кожне — у словнику провайдера, що рендерить source: для chart — документ за його власними kind і metadata.name; для compose-файлу — service, volume або config за ключем у services:, volumes: або configs:; для шаблону CloudFormation — ресурс за його Type і логічним ID. Цей провайдер вилучає кожну одиницю, якій відповідає запис, а те, чому відповідає запис і що провайдер відхиляє через запис, є власним задокументованим контрактом цього провайдера. Провайдер, який не може нічого вилучати, відхиляє FeatureRecipe з цим ключем ще до будь-якого рендерингу. Фільтрується лише те, що рендерить source:, — запис workload: чи artifacts: ніколи, — тож ключ вимагає source. Кожне значення — шаблон, що обчислюється в тому самому контексті, що й valuesMapping. Першим обчислюється when запису, і запис, чий when рендерить хибне значення, відкидається. Кожен активний запис мусить щось вилучати: активний запис, що не відповідає нічому з відрендереного source, зупиняє збірку з назвою запису. Source однаково рендериться повністю — кожен шаблон chart усе одно виконується, тож шаблон, що зазнає збою, усе одно зриває збірку, — і вилучається лише його вивід. Ключ пишеться однаково в Recipe і у FeatureRecipe. Щонайменше 1 запис. |
injectMapping | string | ні | Необов’язковий inline-шаблон Go, що обчислюється у фазі Pre-Render Interception один раз для кожного компонента, якого досягає приєднання, у контексті шаблону цього компонента: він читає ‘.context’ і ‘.features’ компонента та ‘.attachment_name’, ‘.values’, ‘.infra’ і ‘.locals’ приєднання, хоч би що вказував executionScope, а посилання на ‘.boundary’, якого не містить контекст жодного компонента, зупиняє збірку. Виводить словник JSON/YAML, який компілятор Go нативно глибоко зливає поверх каналу пам’яті ‘.context.inject’ викликача. Використовується для зміни змінних середовища та контрактів доставки на боці викликача без Wasm. |
pipeline | object[] | ні | Послідовний список кроків конвеєра Wasm, що виконуються після рендерингу над набором відрендерених документів; кожен крок повертає патчі RFC 6902 і побічні ефекти. |
executionScope | string (enum) | ні | Чи виконується Resource Generation цього FeatureRecipe для кожного компонента (типово), чи один раз на приєднання до межі. FeatureRecipes з областю межі дедуплікуються за (boundary_path, екземпляр FeatureRecipe), і кожен шаблон, крім injectMapping, читає контекст шаблону з областю межі: стовпи .boundary.* замість покомпонентних стовпів .context.*, посилання на які зупиняє збірку. injectMapping виконується один раз для кожного компонента, якого досягає приєднання, незалежно від executionScope, тож він читає контекст цього компонента і ніколи не читає .boundary. Допустимі значення: "component", "boundary" Типово: "component" |
readsCallerRenderFacts | булева | ні | Оголошує, що шаблони цього FeatureRecipe читають те, що відрендерили Components, які під’єднуються до того, до якого його приєднано: факти рендерингу, які провайдер кожного з цих викликачів повідомляє про власний вивід. Якщо значення true і FeatureRecipe рендериться для кожного компонента, кожне його приєднання рендериться після того, як відрендерилися всі Component у збірці, а не одразу після Component, до якого його приєднано, тож рендеринг кожного викликача завершено до обчислення приєднання. Якщо значення false або відсутнє, жоден запис викликача в ‘.context.used_by’ не містить фактів рендерингу, приєднання рендериться одразу після свого Component, якщо readsTargetRenderFacts не true, а збірка зупиняється на шаблоні, написаному inline у цьому FeatureRecipe, який читає факти рендерингу викликача під ‘.context.used_by’. Типово: false |
readsTargetRenderFacts | булева | ні | Оголошує, що шаблони цього FeatureRecipe читають те, що відрендерили Components, з якими пов’язано той, до якого його приєднано: факти рендерингу, які провайдер кожної з цих цілей повідомляє про власний вивід, у кожному записі ‘.context.uses’. Якщо значення true і FeatureRecipe рендериться для кожного компонента, кожне його приєднання рендериться після того, як відрендерилися всі Component у збірці, а не одразу після Component, до якого його приєднано, тож рендеринг кожної цілі завершено до обчислення приєднання. Це той самий пізніший рендеринг, який спричиняє readsCallerRenderFacts, тож задання будь-якого з ключів або обох змушує приєднання рендеритися саме тоді. Якщо значення false або відсутнє, жоден запис у ‘.context.uses’ не містить фактів рендерингу, приєднання рендериться одразу після свого Component, якщо readsCallerRenderFacts не true, а збірка зупиняється на шаблоні, написаному inline у цьому FeatureRecipe, який читає факти рендерингу цілі під ‘.context.uses’. Типово: false |
assertions | map of string | ні | Міжпольова валідація під час збірки. Кожен запис — іменоване твердження: ключ — стабільний ідентифікатор правила, що показується в повідомленнях про помилки; значення — рядок шаблону Go із семантикою зупинки {{ fail "message" }}. Кілька іменованих тверджень на сутність обчислюються для кожного екземпляра в порядку, оголошеному автором; перше хибне твердження зупиняє збірку. Твердження FeatureRecipe обчислюються після прив’язки рецепта й після обчислення provides, до рендерингу, і виражають інваріанти реалізації конкретного chart чи модуля, який бере FeatureRecipe. Контекст шаблону: .values / .infra / .uses / .features / .metadata, а також .provides / .locals / .recipe. Обчислювач використовує missingkey=error: посилання на невизначені ключі зупиняються з діагностикою no-such-key. Оскільки просте посилання зупиняється раніше, ніж може спрацювати будь-який запасний варіант, звичайний default не дає запасного значення для необов’язкового поля на цій поверхні — захистіть посилання за допомогою hasKey або скористайтеся помічником optional, який сам перевіряє наявність. Читання ключа через index теж його не дає: index зупиняється на ключі, якого немає в мапі, називаючи ключ. |
Додаткові властивості не дозволені.
featurerecipe.spec.omits[]
| Властивість | Тип | Обов’язкова | Опис |
|---|---|---|---|
kind | string | так | Вид одиниці, яку слід вилучити, у термінах провайдера, що рендерить джерело: для чарту — власний kind відрендереного документа, наприклад Secret; для compose-файлу — service, volume або config; для шаблону CloudFormation — Type ресурсу, наприклад AWS::S3::Bucket. Він називає вид, який рендерить джерело, і не пов’язаний із kind:, який містить структурований source:. Шаблон. |
name | string | так | Ім’я одиниці, яку слід вилучити, у термінах провайдера, що рендерить джерело: для чарту — власне metadata.name відрендереного документа; для compose-файлу — ключ одиниці в services:, volumes: або configs:; для шаблону CloudFormation — логічний ідентифікатор ресурсу, його ключ у Resources. Шаблон. |
namespace | string | ні | Простір імен, у якому розташована одиниця, яку слід вилучити, коли запис має збігатися лише з одиницею в цьому просторі імен, — для провайдера, вихідні дані якого мають простори імен, як відрендерені документи чарту. Якщо поле відсутнє або рендериться в порожній рядок, запис збігається з одиницею свого виду та імені незалежно від її простору імен. Compose-файл і шаблон CloudFormation не мають просторів імен, і їхні провайдери відхиляють запис, який його вказує. Шаблон. |
subchart | string | ні | Субчарт, з якого походить одиниця, що вилучається, — коли запис має відповідати лише копії, яку рендерить один субчарт, — для source, зібраного з вкладених source, як chart збирається зі своїх субчартів. Для chart — власне ім’я субчарта або псевдонім, який йому дає залежність батька; імена вкладеного субчарта з’єднуються через /, починаючи із зовнішнього: operator або operator/webhooks. Тоді запис відповідає документу, відрендереному з власних templates/ або crds/ цього субчарта, і не відповідає ні документу, який рендерить сам chart, ні документу, який рендерить вкладений у нього субчарт. Якщо поле відсутнє або рендериться в порожній рядок, запис відповідає одиниці свого виду й імені, хоч би звідки вона походила. Chart, який не рендерить субчарт із таким ім’ям, зупиняє збірку з назвою запису. Compose-файл і шаблон CloudFormation не мають субчартів, і їхні провайдери відхиляють запис, що його називає. Шаблон. |
when | string | ні | Вбудований шаблон Go, що обчислюється перед іншими полями запису. Коли він рендерить хибне значення, запис відкидається: його інші поля не обчислюються, через нього нічого не вилучається, і він не зобов’язаний ні з чим збігатися. Порожній або відсутній when зберігає запис. Істинність визначається за стандартною домовленістю для булевоподібного виводу шаблону: рядки true/True/TRUE, будь-яке ненульове число та будь-який інший непорожній рядок є істинними, а false/False/FALSE, порожній рядок і нуль — хибними. when, який не вдається відрендерити, зупиняє збірку. |
Додаткові властивості не дозволені.
featurerecipe.spec.pipeline[]
| Властивість | Тип | Обов’язкова | Опис |
|---|---|---|---|
id | string | так | Програмний ідентифікатор цього кроку, унікальний серед кроків цього конвеєра: документ, що оголошує один ідентифікатор у двох своїх кроках, відхиляється під час читання. Пізніший крок того самого конвеєра читає виходи цього кроку як .steps.<id>.outputs. Шаблон: ^[a-zA-Z0-9_]+$. |
plugin | string | так | Посилання на сутність Plugin, яку виконує цей крок, завжди з областю за власним типом сокета плагіна: <pluginType>/<name> з необов’язковою версією, як у parser/yaml або parser/yaml:1.0.0. Область обов’язкова, а не одна з кількох форм: посилання без області name:version відхиляється, оскільки два сокети можуть містити плагін з однаковим ім’ям, і саме область робить сутність розв’язуваною. Збірка розв’язує сутність до її адресованого за вмістом артефакту .wasm — розташування якого визначається за ідентичністю плагіна та налаштованим реєстром, а дайджест закріплено в lock-файлі — і завантажує байти. Просте посилання на .wasm або артефакт тут не приймається. |
function | string | так | Експортована функція Wasm, яку слід викликати. |
with | string | ні | Вбудований шаблон Go, що обчислюється в мапу JSON/YAML, яка строго відповідає явній схемі вхідних даних цього плагіна. |
optional | булева | ні | Якщо true, збій цього кроку (пастка гостя, патч, спрямований на документ, якого немає в наборі, некоректний патч або діагностика з рівнем зупинки) знижується до гучного попередження: набір документів до кроку відновлюється, вихідні дані цього кроку відкидаються, а конвеєр продовжує роботу. Якщо false або відсутнє, будь-який збій кроку зупиняє збірку після відновлення набору документів до кроку. |
when | string | ні | Вбудований шаблон Go, що обчислюється під час обходу конвеєра. Коли він рендерить хибне значення, крок пропускається — як прохідний: набір документів переходить до наступного кроку без змін, не додаючи патчів, побічних ефектів чи запису кроку. Порожній або відсутній when завжди виконує крок. Істинність визначається за стандартною домовленістю для булевоподібного виводу шаблону: рядки true/True/TRUE, будь-яке ненульове число та будь-який інший непорожній рядок є істинними, а false/False/FALSE, порожній рядок і нуль — хибними. when і optional незалежні: крок може оголошувати обидва. |
Додаткові властивості не дозволені.