Перейти до вмісту
AggregaAggrega
Обрати мову: Українська
Цю сторінку перекладено машинним способом. Читати оригінал англійською.

Схема Aggrega Infrastructure Base (FeatureRecipe)

Згенерований довідник. Не редагуйте вручну — згенеруйте повторно з опублікованої JSON Schema.

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

Визначення, які створюють Ops-інженери і які зіставляють абстрактну сутність Feature з каталогу з конкретною версіонованою реалізацією для однієї можливості провайдера. Строго 1:1 з фізичним провайдером і функцією каталогу.

Див. довідник з написання FeatureRecipe, де описано, як створювати сутності FeatureRecipe; ця сторінка документує структурну схему, яку описує той довідник.

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

Властивості

ВластивістьТипОбов’язковаОпис
apiVersionconst “aggrega.ai/v1beta1”такКонстанта: "aggrega.ai/v1beta1"
kindconst “FeatureRecipe”такКонстанта: "FeatureRecipe"
metadataobjectтак
specobjectтакПрив’язка до можливості провайдера, мапінг, конвеєр і мапінг ін’єкцій для сутності FeatureRecipe. Містить ті самі три види вхідних даних, що й Recipe (sourced, synthesized, artifacts), а також injectMapping, наявний лише у FeatureRecipe; FeatureRecipe лише для зв’язування, що оголошує тільки capability та implements, є коректною і нічого не рендерить.

Додаткові властивості не дозволені.

featurerecipe.metadata

ВластивістьТипОбов’язковаОпис
namestringтакЩонайменше 1 символ.
versionstringтакСтрога семантична версія сутності 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-]+)*))?$.
descriptionstringніЩо це за сутність і для чого вона призначена — для того, хто вирішує, чи використовувати її. Почніть із речення, що називає її, а потім додайте те, що потрібно читачеві, щоб вибрати її та правильно використовувати: чого вона очікує від сутності Release, яка її розгортає, і все несподіване в її поведінці. Зазвичай достатньо короткого абзацу.
maintainersobject[]ніСписок супровідників, яким належить ця сутність.
licensestringніІдентифікатор SPDX ліцензії програмного забезпечення, яке описує ця сутність, наприклад MIT або AGPL-3.0. Він фіксує умови цього програмного забезпечення, а не умови цього файлу.
repositorystringніURL репозиторію Git, де зберігаються вихідні файли.
homestringніURL домашньої сторінки, вікі або документації цієї сутності.
keywordsstring[]ніСписок описових ключових слів для зручного пошуку в інтерфейсі.

Додаткові властивості не дозволені.

featurerecipe.metadata.maintainers[]
ВластивістьТипОбов’язковаОпис
namestringтак
emailstringні
urlstringні

Додаткові властивості не дозволені.

featurerecipe.spec

Прив’язка до можливості провайдера, мапінг, конвеєр і мапінг ін’єкцій для сутності FeatureRecipe. Містить ті самі три види вхідних даних, що й Recipe (sourced, synthesized, artifacts), а також injectMapping, наявний лише у FeatureRecipe; FeatureRecipe лише для зв’язування, що оголошує тільки capability та implements, є коректною і нічого не рендерить.

ВластивістьТипОбов’язковаОпис
capabilitystringтакЯвна можливість провайдера, до якої прив’язується цей рецепт (наприклад, ‘helm’, ‘terraform’, ‘compose’), — вид провайдера, що його рендерить.
implementsstringтакОголошує, який тип каталогу Feature цей рецепт здатен реалізувати (зокрема облікові Features з міткою feature.aggrega.ai/kind: secret; точна версія, діапазон, сумісний за мажорною версією, ’^’, або без версії). Компілятор використовує це для перевірки мапінгів Manifest і для пропонування кандидатів у діагностиці та автодоповненні редактора; збірку він цим ніколи не розв’язує. Мапінг у Manifest — це явний вибір реалізації користувачем, зафіксований у lock-файлі сутності Release.
localsmap of stringніПриватний стан Ops. Внутрішні результати обчислень, доступні лише в шаблонах цієї FeatureRecipe як ‘.locals.*’. Кожен запис сам є шаблоном Go, що обчислюється відносно самодостатнього контексту: ‘.context.instance_id’ (ХОСТОВИЙ КОМПОНЕНТ, для якого розв’язується це приєднання, — саме це позначає таке посилання на кожній поверхні шаблонів), ‘.attachment_name’ (екземпляр приєднання, що розв’язується, і єдиний шлях до цієї назви з локального запису), власні ‘.values’ та ‘.infra’ приєднання, а також записи цього самого блоку, розв’язані на цей момент. Записи розв’язуються в порядку, у якому їх написано, і запис МОЖЕ читати сусідній запис, визначений ВИЩЕ за нього, отримуючи розв’язане значення цього запису, а не текст його шаблону. Порядок автора є частиною контракту скрізь, де один запис читає інший: перенесення визначення нижче за запис, що його читає, ламає збірку, і блок ніколи не переупорядковується, щоб посилання розв’язалося. Посилання ‘.locals.’ на запис, який цей блок визначає ПІЗНІШЕ, зупиняє збірку з назвою помилки порядку; посилання на ключ, якого блок узагалі не оголошує, зупиняє збірку з назвою ключа. Обидві перевірки читають шлях, до якого посилання РОЗВ’ЯЗУЄТЬСЯ, а не набраний текст, тож однаково охоплюють пряму форму, читання всередині блоку ’{{ with .locals }}’, читання через змінну, прив’язану безпосередньо до ‘.locals’, і ключ, прочитаний із блоку в дужках, ‘(.locals).’ або ’($.locals).’. Одного написання вони не охоплюють: посилання, шлях якого не визначається текстом шаблону, — досягнутого через функцію, як-от ‘index .locals’ або ‘(default dict .locals).’, або через блок ‘with’ чи прив’язку змінної, конвеєр яких застосовує таку функцію, адже те, що дає такий конвеєр, визначається під час обчислення, а не його текстом. Воно не аналізується, і відсутній ключ, досягнутий у такий спосіб, не зупиняє збірку: він рендерить буквальний текст '', а не порожнечу. Єдиний виняток — сам ‘index’: на кожній поверхні шаблонів він зупиняє збірку з назвою ключа, коли мапа, яку він читає, не містить запитаного ключа, тож відсутній ключ, досягнутий через ‘index .locals’, зупиняє збірку. Локальні записи цієї FeatureRecipe розв’язуються ДО її provides, тож шаблон provides може читати ‘.locals’ і отримує розв’язані значення, тоді як шаблон provides, що називає ключ, якого цей блок не оголошує, зупиняє збірку. Це ті самі правила, яких дотримується блок locals у Recipe. Коли executionScope має значення boundary, блок обчислюється один раз для приєднання до межі, відносно контексту шаблонів області межі, а не компонента, і кожен компонент, якого досягає приєднання, читає ці розв’язані записи, включно з ‘.locals’, які читає його injectMapping. Використовується для експорту фізичних реалій (наприклад, цільових контейнерів, шляхів JSON) для подальших плагінів Wasm. Ніколи не відкривається викликачам — для публічного API використовуйте provides.
providesmap of stringніПублічний API розробника. Контрактні вихідні змінні, доступні для розв’язання inject викликачем нижче за потоком. Коли executionScope має значення boundary, provides обчислюються один раз для приєднання до межі, відносно контексту шаблонів області межі, і кожен компонент, якого досягає приєднання, читає це одне обчислення за шляхом ‘.features..provides’, як і з’єднання, яке несе приєднання; контракт provides, оголошений реалізованою сутністю Feature, перевіряється один раз, на цьому обчисленні, із зазначенням приєднання до межі.
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._-]*$.
omitsobject[]ніЩо вилучити з того, що рендерить 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 запис.
injectMappingstringніНеобов’язковий inline-шаблон Go, що обчислюється у фазі Pre-Render Interception один раз для кожного компонента, якого досягає приєднання, у контексті шаблону цього компонента: він читає ‘.context’ і ‘.features’ компонента та ‘.attachment_name’, ‘.values’, ‘.infra’ і ‘.locals’ приєднання, хоч би що вказував executionScope, а посилання на ‘.boundary’, якого не містить контекст жодного компонента, зупиняє збірку. Виводить словник JSON/YAML, який компілятор Go нативно глибоко зливає поверх каналу пам’яті ‘.context.inject’ викликача. Використовується для зміни змінних середовища та контрактів доставки на боці викликача без Wasm.
pipelineobject[]ніПослідовний список кроків конвеєра Wasm, що виконуються після рендерингу над набором відрендерених документів; кожен крок повертає патчі RFC 6902 і побічні ефекти.
executionScopestring (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
assertionsmap 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[]
ВластивістьТипОбов’язковаОпис
kindstringтакВид одиниці, яку слід вилучити, у термінах провайдера, що рендерить джерело: для чарту — власний kind відрендереного документа, наприклад Secret; для compose-файлу — service, volume або config; для шаблону CloudFormation — Type ресурсу, наприклад AWS::S3::Bucket. Він називає вид, який рендерить джерело, і не пов’язаний із kind:, який містить структурований source:. Шаблон.
namestringтакІм’я одиниці, яку слід вилучити, у термінах провайдера, що рендерить джерело: для чарту — власне metadata.name відрендереного документа; для compose-файлу — ключ одиниці в services:, volumes: або configs:; для шаблону CloudFormation — логічний ідентифікатор ресурсу, його ключ у Resources. Шаблон.
namespacestringніПростір імен, у якому розташована одиниця, яку слід вилучити, коли запис має збігатися лише з одиницею в цьому просторі імен, — для провайдера, вихідні дані якого мають простори імен, як відрендерені документи чарту. Якщо поле відсутнє або рендериться в порожній рядок, запис збігається з одиницею свого виду та імені незалежно від її простору імен. Compose-файл і шаблон CloudFormation не мають просторів імен, і їхні провайдери відхиляють запис, який його вказує. Шаблон.
subchartstringніСубчарт, з якого походить одиниця, що вилучається, — коли запис має відповідати лише копії, яку рендерить один субчарт, — для source, зібраного з вкладених source, як chart збирається зі своїх субчартів. Для chart — власне ім’я субчарта або псевдонім, який йому дає залежність батька; імена вкладеного субчарта з’єднуються через /, починаючи із зовнішнього: operator або operator/webhooks. Тоді запис відповідає документу, відрендереному з власних templates/ або crds/ цього субчарта, і не відповідає ні документу, який рендерить сам chart, ні документу, який рендерить вкладений у нього субчарт. Якщо поле відсутнє або рендериться в порожній рядок, запис відповідає одиниці свого виду й імені, хоч би звідки вона походила. Chart, який не рендерить субчарт із таким ім’ям, зупиняє збірку з назвою запису. Compose-файл і шаблон CloudFormation не мають субчартів, і їхні провайдери відхиляють запис, що його називає. Шаблон.
whenstringніВбудований шаблон Go, що обчислюється перед іншими полями запису. Коли він рендерить хибне значення, запис відкидається: його інші поля не обчислюються, через нього нічого не вилучається, і він не зобов’язаний ні з чим збігатися. Порожній або відсутній when зберігає запис. Істинність визначається за стандартною домовленістю для булевоподібного виводу шаблону: рядки true/True/TRUE, будь-яке ненульове число та будь-який інший непорожній рядок є істинними, а false/False/FALSE, порожній рядок і нуль — хибними. when, який не вдається відрендерити, зупиняє збірку.

Додаткові властивості не дозволені.

featurerecipe.spec.pipeline[]
ВластивістьТипОбов’язковаОпис
idstringтакПрограмний ідентифікатор цього кроку, унікальний серед кроків цього конвеєра: документ, що оголошує один ідентифікатор у двох своїх кроках, відхиляється під час читання. Пізніший крок того самого конвеєра читає виходи цього кроку як .steps.<id>.outputs. Шаблон: ^[a-zA-Z0-9_]+$.
pluginstringтакПосилання на сутність Plugin, яку виконує цей крок, завжди з областю за власним типом сокета плагіна: <pluginType>/<name> з необов’язковою версією, як у parser/yaml або parser/yaml:1.0.0. Область обов’язкова, а не одна з кількох форм: посилання без області name:version відхиляється, оскільки два сокети можуть містити плагін з однаковим ім’ям, і саме область робить сутність розв’язуваною. Збірка розв’язує сутність до її адресованого за вмістом артефакту .wasm — розташування якого визначається за ідентичністю плагіна та налаштованим реєстром, а дайджест закріплено в lock-файлі — і завантажує байти. Просте посилання на .wasm або артефакт тут не приймається.
functionstringтакЕкспортована функція Wasm, яку слід викликати.
withstringніВбудований шаблон Go, що обчислюється в мапу JSON/YAML, яка строго відповідає явній схемі вхідних даних цього плагіна.
optionalбулеваніЯкщо true, збій цього кроку (пастка гостя, патч, спрямований на документ, якого немає в наборі, некоректний патч або діагностика з рівнем зупинки) знижується до гучного попередження: набір документів до кроку відновлюється, вихідні дані цього кроку відкидаються, а конвеєр продовжує роботу. Якщо false або відсутнє, будь-який збій кроку зупиняє збірку після відновлення набору документів до кроку.
whenstringніВбудований шаблон Go, що обчислюється під час обходу конвеєра. Коли він рендерить хибне значення, крок пропускається — як прохідний: набір документів переходить до наступного кроку без змін, не додаючи патчів, побічних ефектів чи запису кроку. Порожній або відсутній when завжди виконує крок. Істинність визначається за стандартною домовленістю для булевоподібного виводу шаблону: рядки true/True/TRUE, будь-яке ненульове число та будь-який інший непорожній рядок є істинними, а false/False/FALSE, порожній рядок і нуль — хибними. when і optional незалежні: крок може оголошувати обидва.

Додаткові властивості не дозволені.