FeatureRecipe
Концептуальна роль сутності FeatureRecipe (Домен 3 — реалізація інтерфейсу Feature на основі Wasm-плагінів) описана в architecture/04-entity-taxonomy.md. Ця сторінка описує поверхню авторингу каталогу FeatureRecipe.
Розташування в каталозі
Сутності FeatureRecipes упорядковано так, що провайдер стоїть у першому сегменті шляху (за тим самим шаблоном, що й Recipes):
aggrega-catalog/└── feature-recipe/ └── {provider}/ # e.g., `helm`, `compose` └── {feature-recipe-name}/ └── {version}/ └── recipe.yamlURI OCI: hub.aggrega.ai/featurerecipe/{provider}/{name}:{version} (наприклад, hub.aggrega.ai/featurerecipe/helm/k8s-secret-from-parameter:1.0.0).
Контракт створення
Сутності FeatureRecipes прив’язуються до інтерфейсу Feature через implements і оголошують конкретний provider. Їхня поверхня створення — це повний набір видів вхідних даних базової сутності Recipe плюс два блоки, специфічні для FeatureRecipe:
- Три види вхідних даних —
source+valuesMapping(джерельний),workload(синтезований) іartifacts: за формою ідентичні базовому Recipe (див. Композиція вхідних даних Recipe іentities/recipe.md). FeatureRecipe, що містить будь-який із них, є ресурсогенерувальним — він рендерить ресурси поруч із базовим компонентом. Місце, куди потрапляють ці ресурси, несе компонент, до якого приєднано Feature, а потім ім’я, під яким його приєднано, в тій із двох форм, яку допускає власна структура цілі: як каталог{component}--{instance}/поруч із каталогом хоста, у тому каталозі, який ця ціль відводить для своїх учасників, — на цілі, чий провайдер дає кожному учаснику власну позицію; як префікс імені файлу{component}--{instance}--поруч із власними файлами компонента — на цілі, яка читає лише файли, що лежать безпосередньо в каталозі. На провайдері, який компонує своїх учасників в один документ, ресурси натомість вбудовуються в цей документ — хоч би до якого сімейства належала Feature: CRDServiceMonitorчиExternalSecretяк вбудовані або$importartifacts:; зовнішній chart чи модуль черезsource:+valuesMapping:; або власні обчислення (наприклад, Deployment агента-sidecar) черезworkload:.valuesMapping:має ті самі три режими створення, що й базовий Recipe (вбудований блочний скаляр, файловий$import:, бібліотечний$import:до запису MappingLibrary) — див.entities/recipe.md«ПолеvaluesMapping— три режими створення». За домовленістю FeatureRecipe модифікує базовий компонент або додає ресурси поруч із ним, але схема не обмежує, які види вхідних даних він може використовувати — компілятор рендерить усе, що оголошує FeatureRecipe, обмежуючись лише можливостями прив’язаного провайдера, і залишається без власної позиції щодо того, чи є певний вид «придатним для модифікатора» (див. засадничі інваріанти). Синтез (workload:) потребує провайдера, який його підтримує; інакше збірка зупиняється на рендерингу з діагностикою можливостей провайдера. injectMapping(перехоплення перед рендерингом): нативний блок шаблону Go, що виконується до рендерингу базового Recipe. Він виводить словник JSON або YAML, який компілятор нативно глибоко зливає поверх каналу пам’яті.context.injectвикликача, дозволяючи змінювати змінні середовища та рядки підключення на боці викликача без Wasm.pipeline: послідовний масив кроків плагінів WebAssembly (Wasm) для мутації Workload після рендерингу (наприклад, впровадження sidecar Envoy через JSONPatch або монтування тома із секретом). Полеpluginкожного кроку називає сутністьPluginза її URI, завжди в межах власного типу сокета плагіна (<pluginType>/<name>, за потреби з версією, як уparser/yamlабоparser/yaml:1.0.0); збірка розв’язує сутність до її артефакту.wasmз адресацією за вмістом, знайденого за ідентичністю плагіна та налаштованим реєстром, а голий файл.wasmчи посилання на артефакт тут не приймаються. Див. посібник розробника плагінів Wasm щодо створення плагіна й посилання на нього, а також architecture/04-entity-taxonomy.md §«Domain 3: Infrastructure Base» щодо принципу двочастинного плагіна (Fetcher / Injector). Компілятор виконує кожен крок в оголошеному порядку: він викликає гостьовий експорт названого плагіна над відрендереним виводом і застосовує повернені JSON Patch та випущені побічні ефекти; стан виконання кожної поверхні конвеєра див. у Стан мови.pipeline:самодостатній: FeatureRecipe може оголосити його без жодного виду вхідних даних, і тоді вона не випускає власних ресурсів, а весь її ефект — те, що її кроки вносять патчами в документи, уже відрендерені збіркою, або випускають поруч із ними.
FeatureRecipe може також не містити жодного з цих блоків: суто з’єднувальна Feature, ефектом якої є ребро uses, що вона його несе, нічого не рендерить, а її FeatureRecipe існує лише для задоволення розв’язання — кожен екземпляр feature розв’язується до FeatureRecipe так само, як кожен компонент розв’язується до Recipe. Серед наведених блоків injectMapping — єдине поле без відповідника в базовій Recipe; три види вхідних даних і pipeline спільні з базовою Recipe.
Поряд із FeatureRecipe закріплюється те саме, що й поряд із Recipe: дайджест кожного файлу, який імпортує запис artifacts, і кожного віддаленого source:, координати якого записано повністю, — у файлі entity.lock у власному каталозі FeatureRecipe, який записує aggrega pin і який ви комітите поряд із нею. Pull над FeatureRecipe, lock-файл якої не фіксує цих закріплень, зупиняється й називає цей крок, якщо pull не попросили його виконати. Збірка зупиняється, коли імпортований файл більше не відповідає своєму дайджесту, і коли дайджест джерела розходиться з тим, що фіксує lock-файл сутності Release (джерело, записане з git ref:, фіксується на коміті, до якого воно розв’язалося, і не порівнюється); сам файл FeatureRecipe ніколи не перезаписується. aggrega pull описує цей файл і як реагувати на кожну зупинку.
Шаблонізація поля source
Поле source: сутності FeatureRecipe є поверхнею шаблонізації на тих самих умовах, що й у сутності Recipe: шаблон обчислюється під час розв’язання джерела, і те, що він створив, збірка потім і розв’язує. Обидві форми приймають шаблони Go — універсальну рядкову форму та структуровану об’єктну форму, рядкові підполя якої обчислюються як шаблони, а нерядкові підполя передаються без змін. Перелік форм, обробка схем і тлумачення прив’язки — ті самі, що описано в entities/recipe.md «Source field templating», «Source field scheme inventory» і «How a source: path is anchored»; цей розділ описує лише те, що відрізняється для прикріплення.
locals: chart_dir: ./charts/exportersource: "{{ .locals.chart_dir }}"Відносно чого розв’язується відносний результат. Відносно каталогу, що містить документ FeatureRecipe, який його оголосив, — власного файлу прикріплення, а не компонента, — і результат має залишатися в межах цього каталогу, так само як для Recipe: результат, що виходить за його межі або є абсолютним шляхом, вказує на файл, який не переміщуватиметься разом із FeatureRecipe, і зупиняє збірку. Результат зі схемою транспорту завантажується, а не приєднується до каталогу. FeatureRecipe, розв’язана з реєстру, читається з файлів, які містить її опублікований архів, розміщених у кеші вмісту, тож відносний результат розв’язується всередині опублікованого так само, як він розв’язується поруч із FeatureRecipe у каталозі, з тим самим обмеженням.
Що може читати шаблон. Набір посилань — той самий, з яким перевіряються власні записи locals: сутності FeatureRecipe; він відрізняється від набору Recipe у двох аспектах, які випливають із того, що розв’язується прикріплення, а не компонент:
.attachment_nameдоступне й називає екземпляр, під яким прикріплено Feature. Шаблон джерела Recipe його відхиляє, бо джерело Recipe розв’язується для вузла і жодне прикріплення не задіяне..context.instance_idназиває компонент-хост, для якого розв’язується прикріплення, а не саме прикріплення, а.context.rendered_nameмістить ім’я, яке власний провайдер хоста повідомляє для хоста, — воно присутнє лише там, де цей провайдер його повідомляє, а там, де ні, збірка зупиняється. Див. Іменування відрендереного ресурсу.
.locals містить набір, який читають інші шаблони цієї FeatureRecipe: її власний розв’язаний блок, під яким лежить блок Recipe хоста, тож ключ, оголошений прикріпленням, переважає ключ хоста з тим самим іменем. Посилання на ключ, якого цей набір не містить, зупиняє збірку й називає цей ключ, а не рендерить його в порожнечу. .provides, .context.inject і .context.uses відхиляються з тих самих міркувань самодостатності, з яких їх відхиляє поверхня джерела Recipe.
FeatureRecipe з областю межі натомість читає межу. Feature, чия FeatureRecipe оголошує executionScope: boundary, рендериться один раз для межі, а не один раз на кожен компонент, тож її шаблон джерела не має компонента-хоста, який можна було б прочитати. Він читає .boundary.* — ті самі опори, що їх читають її locals: і provides:, — а опори рівня компонента (.context, .workload, .attachment_name, .inject) їй недоступні.
Порожній результат. Шаблон, який нічого не створює, залишає прикріплення без джерела, тобто в режимі без джерела, — таке саме тлумачення, як і для джерела Recipe, і це відрізняється від того, щоб самостійно написати source: "".
Що згодом читає .source. Джерело обчислюється перед valuesMapping:, так само як джерело сутності Recipe обчислюється перед її власним зіставленням, і те, що воно дало, стає .source у кожному шаблоні, який виконується після нього: у valuesMapping:, в omits:, у тілах workload: і artifacts: та в кроках pipeline:. Отже, valuesMapping:, що читає .source, читає власне джерело цієї сутності FeatureRecipe, а ніколи не джерело компонента, до якого її приєднано, і не читає нічого, якщо ця сутність FeatureRecipe не оголошує джерела або її шаблон нічого не дає. Сутність FeatureRecipe з областю межі читає власне джерело так само. injectMapping: виконується до обчислення джерела приєднання, тож .source там належить компоненту-хосту.
Ексклюзивність injectMapping
Поле injectMapping притаманне виключно FeatureRecipes — його навмисно немає в базовій схемі Recipe. Ця ексклюзивність ізолює перехоплення змінних від valuesMapping: valuesMapping базового Recipe, сам того не знаючи, споживає переписані рядки .context.inject, згенеровані блоками injectMapping у FeatureRecipe, тож обидва залишаються розділеними. Про те, як працює цей механізм, див. розділ про перехоплення inject-mapping нижче, а повну семантику перехоплення перед рендерингом — у architecture/10-compilation-pipeline.md у частині про inject mapping.
Перехоплення inject-mapping: як працює injectMapping
Коли викликачеві потрібен рядок підключення до цілі в іншій формі, ніж незмінений .provides.host цілі, — з доданим простором імен для міжмежового DNS Kubernetes, з префіксом коду регіону для багаторегіонального шлюзу або з суфіксом режиму SSL у DSN, — injectMapping виконує цю мутацію на боці викликача, ще до того, як valuesMapping базового Recipe побачить канал inject.
Поле injectMapping — це шаблон Go text/template, який рендерер обчислює на етапі inject mapping, до запуску рендерингу базового Recipe. Шаблон виводить словник JSON або YAML з необов’язковими ключами механізмів (env, file, arg або власний механізм, який Recipe компонента читає за шляхом .context.inject.<name>) — або плоску мапу, яка за замовчуванням відповідає env, — і рендерер глибоко зливає це накладання з каналом .context.inject вузла-викликача. Маршрутизація на боці викликача через injectMapping виконується на етапі inject mapping без запуску пісочниці Wasm для простих операцій з рядками; Wasm-плагіни залишаються для структурних змін AST через масив pipeline.
Записуйте кожне значення через toJson. Рендерер читає вивід шаблону як YAML, тож значення, підставлене між лапками як є, або ламає цей вивід, або зчитується назад зміненим, щойно містить подвійну лапку чи зворотну скісну риску, — типовий випадок це пароль. toJson записує значення як рядок JSON, який YAML зчитує назад точно, тож значення доставляється з усіма символами, які воно містить:
injectMapping: | env: {{ .values.key }}: {{ .values.origin | toJson }}Значення, складене з кількох частин, спочатку складається, а потім один раз записується через toJson, як у прикладах нижче.
Вивід, який не вдається прочитати, зупиняє збірку. Коли вивід шаблону не читається в жодній із двох форм — типова причина в скалярі в лапках, зіпсованому значенням усередині нього, — жоден із його ключів не може бути доставлений, тож збірка зупиняється з назвою приєднання та FeatureRecipe, а не рендерить компонент так, ніби нічого не було доставлено; див. fatal-halts.md «An attached Feature’s injectMapping output cannot be read (Не вдається прочитати вивід injectMapping приєднаної сутності Feature)». Причина, яку наводить зупинка, приховується, якщо залежить від значення, оголошеного чутливим. Порожній вивід або вивід, що розбирається як словник, який нічого не доставляє, нічого не доставляє і не є помилкою.
Ключ верхнього рівня — це механізм, і all ним не є. Кожен ключ верхнього рівня виводу у вигляді словника називає механізм, через який доставляються його записи: env, file і arg або будь-яке інше ім’я, яке доставляється як окремий механізм під цим ім’ям. .context.inject.all будується з цих механізмів після злиття й ніколи не зливається з виводу, тож записи під all: нікуди б не потрапили; натомість збірка зупиняється з назвою приєднання, ключа та FeatureRecipe і повідомляє, які ключі може містити вивід, — див. fatal-halts.md «An attached Feature’s injectMapping output writes deliveries under a key nothing delivers (Вивід injectMapping приєднаної сутності Feature записує доставки під ключем, який ніщо не доставляє)». Записуйте такі записи під механізмом, з якого їх читає компонент.
Мутація суворо локальна для викликача. FeatureRecipe змінює лише канал inject вузла, до якого його приєднано, і ніколи — вивід .provides цілі. .provides.host цілі потенційно споживає багато викликачів у кластері; injectMapping на боці викликача зливається лише в канал конкретного викликача, тож мутації маршрутизації обмежені тим ребром, яке їх запросило.
Що може переписувати відображення. На момент рендерингу відображень кожен блок inject: уже виконав доставку, тож вихід відображення завжди зливається поверх ключів, які вже записало щось інше, — і те, хто записав ключ, визначає, що відбудеться. Ключ, який доставив власний блок inject: викликача або один із блоків inject: його з’єднань, відображення може переписати: це перехоплення, і значення відображення замінює цей один запис. Ключ, який власне приєднання відображення доставило через свій блок inject:, так само можна переписати. Ключ, який уже доставила інша приєднана сутність Feature — через власний блок inject: або injectMapping своєї FeatureRecipe, — переписати не можна: збірка зупиняється із зазначенням обох приєднань, замість того щоб дозволити відображенню, яке виконалося останнім, вирішувати, яке значення прочитає викликач. Отже, дві маршрутизаційні сутності Features можуть кожна уточнювати власний ключ, але дві сутності Features не можуть обидві доставити один ключ — зокрема, коли дві маршрутизаційні сутності Features переписують ключ того самого з’єднання, адже перше переписування є перехопленням, а друге натрапляє на доставку першого; див. fatal-halts.md «Two attached Features deliver one key, the later through its FeatureRecipe’s injectMapping (Дві приєднані сутності Features доставляють один ключ, пізніша — через injectMapping своєї FeatureRecipe)».
Виведення цілі без зв’язності
Оскільки компілятор вбудовує каскадні анотації кожної цілі в канал .context.uses викликача, шаблон injectMapping може отримати координати маршрутизації без того, щоб Ops жорстко прописували ідентичність цілі в infra сутності Feature:
- Шаблон шукає в
.context.usesточне топологічне ребро, яке інжектувало змінну, запитану розробником. - Він отримує каскадні
release_annotationsцілі (наприклад,aggrega.ai/namespace). - Він форматує повне доменне ім’я (FQDN) або рядок підключення.
- Він видає словник перевизначень.
Компілятор залишається агностичним щодо мережевої семантики — просторів імен Kubernetes, хмарних регіонів, топологій bridge-proxy — і просто виконує глибоке злиття з тим, що створив шаблон. Коли згодом запускається valuesMapping базового Recipe, він споживає перехоплені, переписані рядки з .context.inject.env так, ніби це оригінали розробника.
Робочий приклад: DNS-резолвер K8s
Стандартний каталог постачає це як core/k8s-dns-resolver з helm FeatureRecipe. Оскільки імена змінних середовища мають бути унікальними в межах контейнера, target_var (наприклад, API_HOST) слугує глобально унікальним ідентифікатором конкретного контракту інжекції в межах викликача. Перебираючи явні ребра в .context.uses і перевіряючи, яке ребро заявило target_var, шаблон знаходить правильний цільовий вузол і читає його простір імен. Єдиний параметр — змінна, яку слід переписати; ціль і її простір імен виявляються, а не прописуються жорстко.
Схема маршрутизаційної Feature (core/k8s-dns-resolver):
infra: { target_var: string # Ops dictates WHICH injected var to rewrite}Реалізація FeatureRecipe:
injectMapping: | # 1. Grab the atomic base host directly from the flattened pipe, or an # empty value when nothing was injected under target_var {{ $base_host := optional .context.inject.env .infra.target_var "" }}
# 2. Dynamically locate the specific edge that injected this variable {{ $target_edge := dict }} {{ range $alias, $edge := .context.uses }} {{ if hasKey $edge.inject.env $.infra.target_var }} {{ $target_edge = $edge }} {{ end }} {{ end }}
# 3. Read the target's namespace from its cascaded release annotation, # coalescing an absent namespace to "default" {{ $ns := "default" }} {{ if $target_edge.annotations }}{{ if $target_edge.annotations.release }} {{ $raw := optional $target_edge.annotations.release "aggrega.ai/namespace" "" }} {{ if $raw }}{{ $ns = $raw }}{{ end }} {{ end }}{{ end }}
# 4. Qualify the host with the namespace — but only when a target connection # and a base host were actually found, so a target_var that matches no # connection injects nothing instead of a spurious variable. An unset # namespace resolves to "default", where the helm provider deploys an # unannotated workload, so the qualified host always matches the service's # actual location and is never malformed. {{ if and $target_edge $base_host }} {{ $resolved_host := printf "%s.%s" $base_host $ns }}
# 5. Emit the precise override dictionary for the compiler to deep-merge env: {{ .infra.target_var | toJson }}: {{ $resolved_host | toJson }} {{ end }}Сценарії використання поза маршрутизацією
injectMapping найчастіше використовують для розв’язання адрес через межі (як-от K8s DNS resolver вище), але ця мутація на боці викликача застосовна до будь-якого сценарію, де потрібно перехопити й відформатувати намір розробника до рендерингу інфраструктури. Ще два шаблони ілюструють діапазон можливостей.
Динамічне форматування безпеки (додавання SSL). Якщо підприємство вимагає, щоб усі зовнішні підключення до баз даних використовували сувору перевірку TLS, Feature може перехопити запитаний розробником DB_URL і додати потрібний режим SSL, щоб застосунок запускався з правильними параметрами безпеки.
# Inside force-ssl-featureinjectMapping: | {{ $base_url := index .context.inject.env .infra.target_var }} env: {{ .infra.target_var | toJson }}: {{ printf "%s?sslmode=verify-full" $base_url | toJson }}Префіксування для багаторегіонального шлюзу. Якщо загальний компонент API розгорнуто глобально, регіональна маршрутизаційна Feature може самостійно знаходити анотації меж власного середовища, щоб додавати префікс до впроваджених рядків підключення для своїх викликачів.
# Inside regional-routerinjectMapping: | {{ $base_host := index .context.inject.env .infra.target_var }} {{ $region_code := index .context.annotations.release "cloud.aggrega.ai/region" }} env: {{ .infra.target_var | toJson }}: {{ printf "%s.%s" $region_code $base_host | toJson }}Межа injectMapping. Механізм обмежено мутацією конвеєра пам’яті .context.inject (Delivery Contract). Він не може додавати нові контейнери, монтувати томи чи змінювати вихід valuesMapping базового Recipe. Будь-яка мутація, що потребує структурних змін у відрендереному AST (як-от масивів JSON чи YAML), належить до масиву pipeline сутності FeatureRecipe і виконується через плагіни WebAssembly.
Межа цілей патчування pipeline. Крок pipeline патчить лише той вихід, який провайдер рендерить у структуроване дерево. Вихід у формі YAML і JSON є структурованим — зокрема модулі Terraform .tf.json, написані в JSON, — тому JSONPatch кроку редагує адресовані значення на місці, не торкаючись жодного іншого байта (коментарів, порядку, форматування). Вихід, який провайдер видає як непрозоре тіло, як-от конфігурація Terraform на нативному HCL, не є ціллю патчування: патч до непрозорого тіла зупиняє збірку з діагностикою, а не змінює текст, який не можна адресувати структурно. Тож написання кроку pipeline для непрозорого виходу — це помилка проєктування, яка проявляється гучною зупинкою, а не мовчазною бездіяльністю.
Вхідні дані вендореного модуля Terraform не є ціллю патчування, і цю відсутність варто зазначити. Це аргументи блоку module відповідного компонента, які провайдер terraform записує в кореневу конфігурацію межі: нативний HCL, тобто непрозорий за правилом вище, і артефакт усієї межі, а не вузла, вихід якого патчить крок. Отже, немає позиції, з якої крок pipeline міг би їх адресувати, і він ніяк не може змінити те, що отримує підключений модуль Terraform. Ці значення формуються там, де їх написано, — у valuesMapping: базового Recipe.
Умовні кроки — when:
Крок pipeline може містити необов’язкове поле when:: вбудований шаблон Go, який компілятор обчислює під час обходу конвеєра з тим самим контекстом шаблону й тим самим обчислювачем, що й тіло with: цього кроку. Відрендерений результат визначає, чи виконується крок.
- Хибний результат пропускає крок як наскрізний: набір документів переходить до наступного кроку без змін, а пропущений крок нічого не додає — жодного патча, жодного побічного ефекту, жодного запису про виконання.
- Порожнє або відсутнє поле
when:завжди запускає крок.
when: і optional: незалежні. when: визначає, чи виконується крок узагалі; optional: пом’якшує збій кроку, який виконується. Крок може оголосити обидва — when: контролює вхід, а якщо крок таки виконується, optional: визначає, як обробляється збій усередині нього. Шаблон when:, який не вдається відрендерити, є дефектом авторингу й зупиняє збірку незалежно від optional:.
Відрендерений текст when: оцінюється за спільним правилом булевих шаблонів: рядки true, True і TRUE, будь-яке ненульове число та будь-який інший непорожній рядок є істинними; рядки false, False і FALSE, порожній рядок і нульове число є хибними.
Шаблон облікових даних у FeatureRecipe
Коли сутність FeatureRecipe реалізує облікову сутність Feature (позначену міткою feature.aggrega.ai/kind: secret), вона може дотримуватися принципу Plugin з двох частин: pipeline, що послідовно з’єднує плагін Fetcher (який генерує CRD, специфічний для сховища секретів) і плагін Injector (який монтує секрет у цільовий контейнер), — форма, яку описує examples/04-secrets. Облікові сутності FeatureRecipes зі стандартної бібліотеки не оголошують pipeline: і самі рендерять ресурс секрету; див. examples/05-credential-features.
FeatureRecipe облікових даних рендериться в тому самому проході генерації ресурсів, що й FeatureRecipe будь-якого іншого підключення, і його pipeline: виконується на тих самих умовах: компілятор обходить кожне підключення, яке має роботу в цьому проході, як одну впорядковану послідовність і запускає оголошений конвеєр кожного з них з тією самою семантикою наборів документів /own і /host. Підключення потрапляє до цієї послідовності з однієї з двох причин: його FeatureRecipe оголошує вхідний тип, тож генерує власні ресурси, або оголошує pipeline:, тож переписує вже згенеровані документи. Тому підключення облікових даних може втручатися в згенеровані документи компонента-хоста — монтувати том із секретом, додавати посилання у змінній середовища — так само, як і операційне підключення, і єдина відмінність між ними полягає в тому, куди потрапляють його власні згенеровані файли.
На компоненті оголошення чутливості у Feature слідує за valuesMapping: у FeatureRecipe точно так само, як оголошення в сутності Component слідує за мапінгом її Recipe. Якщо FeatureRecipe рендериться з source: без valuesMapping:, значення, які отримує його ціль, мають ключі за шляхами листків, оголошеними у Feature, тож листок, оголошений як sensitive: true, позначає свій згенерований ключ. Якщо FeatureRecipe оголошує valuesMapping:, ключі — власний винахід цього шаблону, жодне оголошення їх не називає, і збірка виводить по одному попередженню на кожен такий листок із зазначенням підключення, листка та FeatureRecipe. Feature, підключений до межі, не викликає жодного: його .values завжди порожній, тож жоден оголошений листок не має значення, яке можна позначити, — див. A declared-sensitive value reaches the target through a values mapping (Значення, оголошене чутливим, потрапляє до цілі через мапінг значень).
Блок provides: — публікація для споживача
Блок provides: сутності FeatureRecipe — це її опублікований вихід: мапа рядкових значень із шаблонів Go, які обчислюються в межах власної області видимості прикріплення (.values, .infra, повністю розв’язані .locals сутності FeatureRecipe, а також .context.instance_id і .context.rendered_name вузла-хоста). Локальні значення розв’язуються першими, тож запис provides: читає їх і отримує розв’язані значення; звернення до ключа, який блок locals: не оголошує, зупиняє збирання. Саме так прикріплення повідомляє споживачу, що воно створило — ім’я згенерованого ресурсу, згенерований ключ даних, хмарну ідентичність, — без того, щоб споживач заново виводив цю ідентичність з тих самих вхідних даних.
Споживач читає її за шляхом .features.<instance-name>.provides.<key> (або .features.<slot>.provides.<key> для облікового прикріплення), що віддзеркалює .context.uses.<alias>.provides для ребра uses. Якщо прикріплення записане на одному зі з’єднань споживача, споживач читає ту саму мапу в межах цього з’єднання, за шляхом .context.uses.<alias>.features.<slot>.provides.<key>, і прикріплення не входить до його .features (див. Прикріплення з’єднання). Власний блок inject: прикріплення розв’язує свої посилання from: щодо тієї самої мапи, тож автор може обрати будь-який канал: provides для читання в шаблоні, inject для доставки в змінну середовища, файл або аргумент.
# FeatureRecipe: emits a ServiceAccount and publishes its name.provides: name: "{{ .infra.service_account_name }}"# Consuming Recipe: binds the pod to what the attachment published.workload: | serviceAccount: "{{ .features.identity.provides.name }}"Коли сутність Feature, яку ця FeatureRecipe implements, оголошує контракт schema.provides, цей контракт перевіряється щодо FeatureRecipe: кожен ключ, оголошений у Feature, має бути присутнім у provides: сутності FeatureRecipe, інакше збирання зупиняється із зазначенням відсутнього ключа. Додаткові опубліковані ключі дозволені — контракт є нижньою межею, а не верхньою. Значення ніколи не перевіряються; це непрозорі детерміновані вказівники, які розв’язує середовище виконання.
Розв’язання відбувається один раз для кожного прикріплення, до рендерингу споживача, і та сама розв’язана мапа живить читання споживача, перевірку контракту та власну генерацію ресурсів прикріплення — тож те, що читає споживач, і те, що генерує прикріплення, не можуть розходитися.
Provider і implements
spec.capability є обов’язковим і називає провайдера, чий Wasm-плагін рендерингу рендерить вихідні дані сутності FeatureRecipe (helm, helm-chart, compose тощо), на тих самих умовах, що й spec.capability сутності Recipe (див. entities/recipe.md): закріплення версії вибирає, яка версія цього плагіна виконує рендеринг, і не є частиною імені FeatureRecipe — Manifest зіставляє FeatureRecipe, що оголошує capability: "compose:1.2.3", як compose/<name>:<version>, а значення зіставлення, яке записує закріплення в ім’я, відхиляється як некоректне посилання на рецепт (E0095) ще до будь-якого пошуку. Поле implements прив’язує сутність FeatureRecipe до її інтерфейсу Feature і підтримує точне зіставлення, зіставлення за діапазоном, сумісним за мажорною версією, або зіставлення без версії — семантику зіставлення версій implements див. у vocabulary/inheritance-and-interface.
Область виконання — spec.executionScope
Необов’язковий перелік spec.executionScope вибирає модель диспетчеризації для Resource Generation. Приймаються два значення; якщо поле пропущено, типовим є component.
component(типово). Resource Generation сутності FeatureRecipe виконується один раз для кожного приєднаного екземпляра компонента. Кожен виклик отримує окремий для компонента контекст шаблону з коренем у.context.*:.context.instance_id,.context.inject,.context.uses,.context.annotationsтощо. ЇїvaluesMapping:,workload:іartifacts:також читають.context.used_by— компоненти, чиї записиusesвказують на хост, кожен зі своєю ідентичністю, своїм сокетом, тим, що він публікує, а також простором імен і межею, у яких він розміщений, — чого не бачить жоден шаблон, який рендерить сам хост.boundary. Resource Generation виконується один раз для кожної приєднаної межі, незалежно від того, скільки компонентів у піддереві межі споживають функцію. Кожен виклик отримує контекст шаблону області межі з коренем у.boundary.*замість.context.*.
Описане вище перехоплення injectMapping завжди виконується для кожного споживача окремо, незалежно від executionScope. Кожен компонент, що використовує функцію, і далі отримує власне переписування .context.inject на боці того, хто викликає. Лише крок Resource Generation (source/valuesMapping і масив pipeline) дедуплікується в області межі.
Тому шаблони FeatureRecipe з областю межі виконуються у двох областях. Її injectMapping виконується один раз для кожного компонента, якого досягає приєднання, у контексті цього компонента — тому самому, який читає injectMapping FeatureRecipe з областю компонента: .context.*, .attachment_name, .features і власні .values, .infra та .locals приєднання. Її .infra — це блок infra: приєднання до межі, а її .locals — блок, обчислений один раз для межі. Усі інші шаблони, які вона містить, — серед них її locals:, provides:, source:, valuesMapping: і artifacts:, а також with: і when: кроків її конвеєра — виконуються один раз для межі, у контексті області межі, описаному нижче. Кожен шаблон перевіряється щодо області, в якій він виконується: valuesMapping:, що читає .context.instance_id, зупиняє збірку, а injectMapping, що читає його, рендерить ідентичність цього компонента. .boundary не задається в жодному контексті компонента, тож injectMapping, що читає його, зупиняє збірку з назвою посилання, яким би не був executionScope сутності FeatureRecipe.
Контекст шаблону області межі
Коли задано executionScope: boundary, шаблони FeatureRecipe, крім її injectMapping, обчислюються щодо подання .boundary.* межі, до якої приєднано функцію. Подання надає:
.boundary.path— шлях межі Release, до якої приєднано функцію: імена меж від найзовнішньої всередину, з’єднані через/(bridge,bridge/frontend). Він називає межу, а не каталог, у який записуються її вихідні дані, — його задаєdirectory:(замінює.context.instance_id)..boundary.assembly_path— каталог відносно вихідного каталогу збірки, у який збираються власні вихідні дані приєднання: обчисленіdirectory:іsubDirectory:межі, тобто каталог, до якого збірка спрямовує ці вихідні дані (bridge/compose). Він дорівнюєsource_assembly_pathабоtarget_assembly_pathкінцевої точки з’єднання саме тоді, коли ця кінцева точка рендериться в той самий зібраний файл, тож FeatureRecipe порівнює їх, щоб відрізнити з’єднання всередині власного файлу від з’єднання в іншому файлі..boundary.boundary_name— ім’я межі, задане автором у сутності Release..boundary.components— словник із ключами за ID екземпляра, що містить кожен компонент у піддереві межі (instance_id,component,resolved_version,boundary_path)..boundary.internal_uses_edges— ребраuses:, обидва кінці яких перебувають у піддереві цієї межі (шаблон compose-bridge перебирає їх, залишаючи ребра, обидва кінці яких зібрано в його власний файл compose і розміщено в різних мережах цього файлу, щоб вивести свою конфігурацію проксі для кожного ребра). Кожне ребро несе розв’язані provides своїх кінців, впроваджені змінні середовища та розміщення кожного кінця:source_namespaceіtarget_namespace— анотаціюaggrega.ai/namespace, що застосовується до цього кінця (налаштування його власного запису в сутності Release, якщо воно є, інакше — налаштування його межі);source_boundary_pathіtarget_boundary_path— шлях межі Release, що його містить; таsource_assembly_pathіtarget_assembly_path— каталог у вихідному каталозі збірки, у який його збирає провайдер, складений з обчисленихdirectory:іsubDirectory:його межі (bridge/compose). Два кінці з одним шляхом збирання рендеряться в один зібраний файл, а провайдер compose вважає шлях збирання мережею кінця, якщо жоден простір імен не застосовується..boundary.outgoing_cross_boundary_uses_edges— ребра, джерело яких усередині піддерева, а ціль — поза ним..boundary.incoming_cross_boundary_uses_edges— ребра, ціль яких усередині піддерева, а джерело — поза ним (використовуються агрегаторами на кшталт ingress)..boundary.cross_boundary_uses_edges— об’єднання вхідних і вихідних міжмежових ребер, коли FeatureRecipe потрібне повне міжмежове подання..boundary.labels— об’єднання міток піддерева зі збереженням авторського порядку..boundary.annotations— власні анотації межі разом із каскадом..boundary.feature_attachments— кожна функція, приєднана до цієї межі (щоб FR області межі могла за потреби інспектувати сусідні).
Стовп .infra у FR області межі розв’язується в блок infra: функції, приєднаної до межі (задані автором на боці Release фізичні розміри для цього приєднання до межі). .values завжди порожній для FR області межі: правило розділення стовпів у схемі Release забороняє values: у приєднаннях сутностей Feature на рівні Release, тож функція, приєднана до межі, не несе значень для проєкції. FR області межі, яким потрібні дані у формі параметрів, мають отримувати їх через .infra (поверхню, на якій оператор задає конфігурацію функції межі) або через .boundary.annotations (рядкові значення з каскадним розв’язанням, задані на межі або будь-якому предку); .parameters не входить до подання, і шаблон, що читає його, зупиняється з назвою коренів, які визначає подання. .locals і далі є власним блоком locals FR. .steps і .metadata лишаються без змін.
Список дозволених полів шаблону в області межі
FR області межі в усіх шаблонах, крім injectMapping, можуть посилатися лише на поля, доступні в поданні області межі. Якщо створити такий шаблон, що посилається на поле, доступне лише для окремого компонента (наприклад, .context.instance_id, .context.inject, .context.uses), коли задано executionScope: boundary, FeatureRecipe не проходить валідацію під час розбору з помилкою, що називає FR, проблемне поле та поля, які визначає подання області межі. Дзеркальне правило діє і в протилежному напрямку: FR області компонента, що посилається на поля .boundary.*, не проходить той самий валідатор. injectMapping в обох областях перевіряється щодо контексту компонента, у якому він виконується, тож він може читати .context.*, а посилання на .boundary у ньому зупиняє збірку з назвою посилання та коренів, які визначає цей контекст.
Валідатор виконує той самий обхід AST шаблону, що й список дозволених змінних шаблону шляху, але з іншим набором посилань для кожної області.
Дедуплікація та вихід Resource Generation
Для executionScope: boundary компілятор дедуплікує Resource Generation за кортежем (boundary_path, FR-instance). Два компоненти в тому самому піддереві межі, що обидва споживають ту саму приєднану до межі функцію, запускають один виклик FR, а не два. Міжмежові приєднання тієї самої функції виконуються незалежно для кожної межі.
FR області межі видає один набір непроміжних файлів для кожного кортежу (boundary_path, FR-instance), а їхнє розташування випливає з того, як провайдер поєднує вихід своєї межі. Координатою тут є лише ім’я екземпляра, тоді як приєднання області компонента несе ще й свій компонент: функцію області межі приєднано до межі, а не до компонента, тож каталог охопної межі вже каже все, що сказав би сегмент компонента, і компонента, який треба назвати, немає.
Провайдер, що записує кожен документ безпосередньо в каталог межі, оголошує, що його ціль читає лише файли, які лежать безпосередньо в каталозі. Тому охопного каталогу для приєднання немає, і ім’я екземпляра натомість стає префіксом імені файлу: <boundary_directory>/<fr-provider>/<feature-instance>--<file>, поруч із власними файлами межі. Ім’я екземпляра кодується, бо в імені файлу немає роздільника, на який можна спертися, і воно зустрічається з власним ім’ям файлу на двосимвольній межі, якої не може містити жодна закодована координата, — тож два приєднання, що видають одне ім’я файлу, все одно дають два файли.
Провайдер, що компонує вихід своєї межі в охопну структуру — один чарт, що містить чарт для кожного учасника, одна коренева конфігурація, що містить модуль для кожного учасника, — розміщує кожного учасника у власному підкаталозі, а приєднання до межі є таким самим учасником, як і будь-який інший. Тоді його вихід лежить у <boundary_directory>/<fr-provider>/<contributors-directory>/<feature-instance>/, де <contributors-directory> — це те, як ця ціль називає місце, де живуть її дочірні одиниці. Підкаталог несе ім’я екземпляра приєднання, тобто ім’я, під яким ви записали його в блоці features: межі, тож каталог, який створює збірка, можна знайти в тому, що ви написали.
Проміжний вихід надходить до збирача межі для кожної пари (шлях, провайдер) за обчисленим шляхом FR під власною spec.capability FR — саме цей механізм використовує Feature core/compose-bridge, щоб об’єднати сервіс-міст із compose-учасниками окремих компонентів за тим самим шляхом збирання. Такий вихід записується лише як частина файлу, що збирається там із компонентів межі, тож коли жоден із них не потрапляє за цим шляхом — скажімо, кожен компонент спрямовано деінде його subDirectory:, — збірка зупиняється з назвою межі, Feature, шляху, до якого спрямовано її вихід, і провайдера, замість записувати вихід у нікуди (див. «A boundary-level Feature’s output reaches no assembled file (вихід Feature рівня межі не потрапляє в жоден зібраний файл)» у fatal-halts.md).
Розв’язання provides: з урахуванням каскаду
FR рівня межі створюють один набір provides: на кожен кортеж (boundary_path, FR-instance) і обчислюють його один раз. Шаблон provides: у FR обчислюється з контекстом шаблону рівня межі (тож він може посилатися на .boundary.components, .boundary.path, .infra, але не на поля окремого споживача і не на .values). Значення provides є константами відносно споживачів — кожен споживач у піддереві межі бачить ті самі надані значення.
Розв’язання provides boundary-scope FR на боці споживача скрізь читає це єдине обчислення. Кожен компонент, якого досягає приєднання, читає його в .features.<instance-name>.provides.<key> — у шаблонах власного Recipe та у власному injectMapping сутності FeatureRecipe, який виконується в контексті цього компонента. Сутність Component-споживач, що читає через ребро uses, яке несе приєднання, у .context.uses.<feature-alias>.provides.<provided-name>, отримує ті самі значення: компілятор розв’язує це значення до блоку provides: boundary-scope FeatureRecipe для межі, у якій розташований споживач, проходячи від ребра uses споживача, яке несе ідентичність екземпляра функції для кожного приєднання, до блоку provides: boundary-scope FR. Попередній прохід обчислює ці provides до збирання споживача, тож значення вже наявні, коли будується конвеєр споживача.
Ефект для кожного споживача — це таблиця в provides:, яку читає injectMapping. FeatureRecipe з областю межі, якій потрібно щось змінити для кожного споживача, один раз обчислює у своєму provides: таблицю з ключами за споживачами на основі з’єднань межі, а її injectMapping читає рядки поточного компонента — (index .features .attachment_name).provides з ключем .context.instance_id — і доставляє їх через власний канал споживача за правилом, якого дотримується кожне зіставлення (див. Що може переписати зіставлення). Компілятор передає таблицю, яку написала FeatureRecipe, і нічого в ній не читає.
Шаблон compose-bridge
FeatureRecipe compose-bridge — канонічний шаблон boundary-scope FR, і це вміст каталогу, написаний за допомогою описаних вище механізмів: ні компілятор, ні провайдер compose не містять жодної логіки моста, тож каталог може реалізувати Feature core/compose-bridge інакше. Функцію core/compose-bridge приєднано до батьківської межі, що містить дві підмежі (наприклад, services-net і data-net) зі спільним directory:, кожна з яких несе власну анотацію aggrega.ai/namespace (aggrega.ai/namespace: services-net, aggrega.ai/namespace: data-net), щоб кожна потрапила до власної мережі; без анотацій обидві поділяють одну мережу, названу за шляхом їхнього файлу compose, і досягають одна одної без моста. Її executionScope: boundary запускає FR один раз для кожного приєднання до батьківської межі.
Її provides: один раз обчислює таблицю моста. З .boundary.internal_uses_edges вона залишає ребра, обидва кінці яких зібрано в її власний файл compose — source_assembly_path і target_assembly_path обидва дорівнюють .boundary.assembly_path — і розміщено в різних мережах цього файлу; мережа кінця — це його aggrega.ai/namespace, а за його відсутності — його шлях збирання. Ребро між двома файлами compose не з’єднується мостом, і його споживач зберігає власне ім’я цілі. Кожне з’єднане ребро отримує порт прослуховування — власний порт цілі або, якщо попереднє ребро вже прослуховує його, перший вільний порт, не менший за portBase приєднання (типово 10000), — і upstream: опублікований хост цілі (поле provides, яке називає providesField приєднання, типово host) та її port; upstream виводиться з ребра й ніколи не пишеться вручну. З тієї самої таблиці вона обчислює перезапис для кожного споживача: змінна, яку ребро доставляє з поля хоста, стає aggrega-gw:<listen port>, або aggrega-gw, якщо те саме ребро доставляє ще й змінну з port, яка тоді стає портом прослуховування.
Її injectMapping доставляє рядки кожного споживача. Виконуючись у контексті кожного споживача, він читає рядки таблиці цього споживача в .features.<attachment>.provides і доставляє їх поверх значень, які доставило власне з’єднання споживача (наприклад, DB_HOST), — це перехоплення; споживач без рядка нічого не отримує. Там, де цей ключ доставила інша сутність Feature, приєднана до споживача, — через свій блок inject: або свій injectMapping, — збірка зупиняється з назвою обох Features замість заміни цієї доставки (див. «Two attached Features deliver one key, the later through its FeatureRecipe’s injectMapping (дві приєднані Features доставляють один ключ, пізніша — через injectMapping своєї FeatureRecipe)» у fatal-halts.md). listen шлюзу і перезапис споживача читаються з однієї таблиці, тож за побудовою узгоджуються для кожного ребра, зокрема для колізій, перепризначених через portBase.
Її valuesMapping пише шлюз. Власний фрагмент compose сутності FeatureRecipe оголошує сервіс aggrega-gw. Якщо щось з’єднується мостом, її valuesMapping додає один блок nginx stream server для кожного з’єднаного ребра (listen <port>; set $uN <target-host>:<target-port>; proxy_pass $uN;, під директивою resolver, щоб кожен upstream розв’язувався в момент з’єднання, а не один раз під час запуску; символ $ у цих змінних записується як $$, щоб $-інтерполяція Docker Compose залишала для nginx буквальний $), що доставляється як змонтована конфігурація compose — запис верхнього рівня configs: із вбудованим content:, на який посилається aggrega-gw і який змонтовано в /etc/nginx/nginx.conf (тож nginx завантажує її без написаної вручну command:). Вбудований configs.content потребує Docker Compose ≥ 2.23.1. Вона також перелічує кожен з’єднаний кінець у x-aggrega-networks-of шлюзу, яке провайдер compose розв’язує в мережі, де розміщено ці кінці, тож шлюз приєднується до кожної мережі, яку охоплюють його з’єднані ребра (мережі споживача й мережі цілі), — під час виконання споживач може досягти aggrega-gw:<port>, а шлюз може виконати proxy_pass до цілі. Якщо нічого не з’єднується мостом, шлюз, оголошений фрагментом, однаково рендериться, але простоює: без конфігурації, без додаткової мережі й без перезапису.
Збирач compose для кожної пари (шлях, провайдер) об’єднує шлюз з учасниками на рівні компонентів за тим самим обчисленим шляхом: один docker-compose.yaml, що містить кожен компонент плюс шлюз-міст. Якщо жоден із компонентів межі не збирається у файл шлюзу, збірка зупиняється замість записувати шлюз у нікуди. Upstream — детермінований вказівник на сервіс compose під час компіляції; його розв’язує DNS compose під час виконання (жодного розв’язання часу виконання під час компіляції).
Рендеринг після викликачів — spec.readsCallerRenderFacts
Необов’язковий ключ spec.readsCallerRenderFacts (булевий, за замовчуванням false) оголошує, що шаблони цього FeatureRecipe читають те, що відрендерили компоненти, які під’єднуються до його хоста: факти рендерингу, які провайдер кожного з цих викликачів повідомляє про виведений ним результат. Що саме повідомляє провайдер і під якими назвами — це власний контракт цього провайдера; у розділі Reporting facts about what a guest emitted описано факти, які провайдер може повідомляти.
Коли рендериться таке приєднання. Збірка рендерить свої компоненти по одному, у фіксованому порядку, і приєднання зазвичай рендериться одразу після компонента, до якого його приєднано. Компонент, що під’єднується до хоста й іде далі в цьому порядку, на той момент ще не відрендерився, тож нічого з виведеного ним ще не існує для читання. Натомість приєднання, FeatureRecipe якого задає readsCallerRenderFacts: true, рендериться після того, як відрендерилися всі компоненти збірки, разом з усіма приєднаннями, що не задають ні цього ключа, ні readsTargetRenderFacts, — тож рендеринг кожного викликача завершено до того, як обчислюється приєднання. Його вивід потрапляє туди, куди потрапив би, і під тими самими назвами; ключ змінює те, коли приєднання рендериться, а не те, що воно рендерить. Із пізнішого рендерингу випливає один порядок: якщо FeatureRecipe містить pipeline, що переписує документи свого хост-компонента, а провайдер хоста записує окремі документи, ці кроки виконуються після конвеєрів інших приєднань хоста, а не в порядку їх приєднання.
Що він читає. Коли ключ задано, кожен запис .context.used_by містить .render_facts: факти рендерингу викликача, з ключами за назвою факту. Кожен факт рендерингу — це список, тож шаблон завжди перебирає його через range — навіть коли в ньому один запис. Його записи можуть походити з власного рендерингу викликача та з рендерингів сутностей Features, приєднаних до викликача: списки, які одна назва отримує від кожного з них, об’єднуються в один — спершу виклики власного провайдера викликача, потім кожна з його сутностей Features у порядку, в якому вони рендерилися. Сутність Feature викликача, яка сама задає цей ключ, теж рендериться після всіх компонентів, тож те, що вона повідомила, серед них відсутнє. Викликач, провайдери якого нічого не повідомляють, містить порожній .render_facts, тож назва, яку ніхто не повідомив, читається як порожнє значення:
artifacts: callers.yaml: | callers: {{- range .context.used_by }} - component: {{ .component_id }} ports: {{- range .render_facts.ports }} - {{ .port }} {{- end }} {{- end }}Які назви фактів існують і що містить кожен запис — це задокументований контракт провайдера викликача: наприклад, для провайдера helm це його факти рендерингу, що називають мітки відрендерених ним подів. Факти викликачів містяться на з’єднаннях, які читають valuesMapping:, workload: і artifacts: цього FeatureRecipe; with: і when: кроку pipeline: взагалі не бачать компонентів, що під’єднуються до хоста, тож крок читає лише власні факти хоста. Кожен FeatureRecipe, приєднаний до компонента, — незалежно від того, чи задає він цей ключ, — читає власні факти компонента в .context.render_facts, у тій самій формі; обидва випадки описано в контексті шаблону.
Оголошуйте його щоразу, коли шаблон читає факти. Шаблон, написаний inline у FeatureRecipe, що не задає цей ключ, — у його valuesMapping:, його workload: або записі artifacts:, — який читає render_facts під .context.used_by, зупиняє збірку до будь-якого рендерингу, називаючи посилання та поле, в якому його написано (див. «A template reads its callers’ render facts without declaring it (Шаблон читає факти рендерингу своїх викликачів, не оголосивши цього)» у fatal-halts.md). Перевірка читає шаблон у тому вигляді, як його написано, тож не бачить посилання, побудованого під час виконання шаблону, або написаного у вмісті, імпортованому з файлу чи бібліотеки, — а шаблон, що поряд із .context.used_by читає поле з назвою render_facts з якогось іншого списку або читає власні факти хоста як .render_facts усередині {{ with .context }}, вважається таким, що читає факти викликачів; власні факти хоста записуйте повністю як .context.render_facts. Саме ключ, а не перевірка, визначає, коли рендериться приєднання, тож задавайте його на кожному FeatureRecipe, шаблони якого читають факти рендерингу своїх викликачів, хоч би як вони до них діставалися; задання ключа не коштує нічого, крім пізнішого рендерингу.
Крок конвеєра читає лише власні факти свого хоста. Крок може переписувати власні документи хост-компонента, а власний вивід компонента лишається тим самим, хоч би хто до нього під’єднувався, тож with: і when: кроку ніколи не бачать компонентів, що під’єднуються до хоста, — незалежно від того, чи задає FeatureRecipe цей ключ, який визначає, коли рендериться приєднання, і нічого не визначає щодо того, що бачить крок. Тому написаний inline with: або when: кроку, що читає render_facts під .context.used_by, зупиняє збірку до будь-якого рендерингу з коротким кодом E0326, називаючи посилання та поле кроку, — замість того щоб відрендерити порожнє значення. Власні факти хоста в кроці читайте в .context.render_facts, записаному повністю, а факти викликачів — у valuesMapping:, workload: або artifacts: цього FeatureRecipe. Ця перевірка читає шаблон у тому вигляді, як його написано, з тими самими обмеженнями, що й наведена вище.
Область дії. Ключ стосується FeatureRecipe, що рендериться один раз на компонент, — executionScope: component, значення за замовчуванням. FeatureRecipe, що оголошує executionScope: boundary, рендериться там, де й завжди, незалежно від того, чи задає він цей ключ, а шаблони, що створюють його ресурси, читають .boundary, а не .context.
Рендеринг після цілей — spec.readsTargetRenderFacts
Необов’язковий ключ spec.readsTargetRenderFacts (boolean, типово false) оголошує, що шаблони цього FeatureRecipe читають те, що відрендерили компоненти, до яких під’єднано його хост: факти рендерингу, які провайдер кожної з цих цілей повідомляє про згенерований ним вивід. Він читає інший кінець з’єднання, ніж readsCallerRenderFacts, — компоненти, на які вказують записи uses хоста, а не компоненти, чиї записи uses вказують на хост, — а все, що стосується самих фактів, читається так само.
Будь-який із ключів змушує прикріплення рендеритися після кожного компонента. Прикріплення, FeatureRecipe якого задає readsCallerRenderFacts: true, readsTargetRenderFacts: true або обидва, рендериться, щойно відрендерено кожен компонент збірки, як описано в розділі вище, — такий пізніший рендеринг один, і те, як він впливає на місце, куди потрапляє результат прикріплення, та на порядок кроків його конвеєра, однакове незалежно від того, який ключ переніс туди прикріплення. Два ключі відрізняються лише тим, які з’єднання несуть факти в контексті прикріплення: ціль, що йде після хоста в порядку збірки, на той момент уже відрендерена, тож те, що вона вивела, доступне для читання.
Що він читає. Коли ключ задано, кожен запис .context.uses містить .render_facts: факти рендерингу цілі, з ключами за назвою факту, у тій самій формі, що й запис викликача. Кожен факт рендерингу — це список, тож шаблон завжди ітерує по ньому. Його записи можуть походити з власного рендерингу цілі та з рендерингів Features, приєднаних до цілі: спершу виклики власного провайдера цілі, потім кожна з її Features у порядку їхнього рендерингу; Feature цілі, яка сама рендериться після всіх компонентів, серед них відсутня. Ціль, провайдери якої нічого не повідомляють, містить порожній .render_facts. Шаблон читає факти одного з’єднання за його псевдонімом, .context.uses.<alias>.render_facts.<name>, або факти кожного з’єднання по черзі:
artifacts: targets.yaml: | targets: {{- range .context.uses }} - component: {{ .target }} ports: {{- range .render_facts.ports }} - {{ .port }} {{- end }} {{- end }}FeatureRecipe, який не задає ключ, не бачить .render_facts на жодному з’єднанні, що б іще він не задавав. Які назви фактів існують — це задокументований контракт провайдера кожної цілі: для провайдера helm це його факти рендерингу, що називають мітки, селектори контролерів і порти контейнерів відрендерених ним подів, а отже, те, що потрібно політиці egress, щоб вибрати саме ті поди, до яких може звертатися її хост.
Оголошуйте його щоразу, коли шаблон читає факти. Шаблон, написаний безпосередньо у FeatureRecipe, що не задає ключ, — у його valuesMapping:, його workload: або в записі artifacts:, — який читає render_facts під .context.uses, зупиняє збірку ще до будь-якого рендерингу з коротким кодом E0347, називаючи посилання та поле, у якому його написано (див. «A template reads its targets’ render facts without declaring it (Шаблон читає факти рендерингу своїх цілей, не оголосивши цього)» у fatal-halts.md). Задання readsCallerRenderFacts цього не усуває. Перевірка читає шаблон у написаному вигляді, з тими самими обмеженнями, що й перевірка для викликачів: вона не бачить посилання, побудованого під час виконання шаблону, або написаного у вмісті, імпортованому з файлу чи бібліотеки, — а шаблон, який узагалі читає .context.uses і також читає поле з назвою render_facts з якогось іншого значення, зокрема із запису викликача всередині {{ range .context.used_by }}, вважається таким, що читає факти своїх цілей. Шаблон, що читає факти обох кінців, задає обидва ключі.
Крок конвеєра читає лише власні факти свого хоста. with: і when: кроку читають з’єднання, які створює хост, так, як їх читає власний Recipe хоста, і ніколи — факти рендерингу їхніх цілей, незалежно від того, чи задає FeatureRecipe ключ. Крок може переписувати власні документи компонента-хоста, а власний рендеринг хоста читає те, що публікують його цілі, а не те, що вони вивели. Тому записані inline with: або when: кроку, що читають render_facts під .context.uses, зупиняють збірку ще до будь-якого рендерингу з коротким кодом E0348, називаючи посилання та поле кроку, — замість рендерингу порожнього значення. Читайте факти цілей у valuesMapping:, workload: або artifacts: FeatureRecipe.
Область дії. Як і для ключа викликачів: він застосовується до FeatureRecipe, який рендериться один раз на компонент. FeatureRecipe, що оголошує executionScope: boundary, рендериться там само, де й завжди, незалежно від того, чи задає він ключ, а з’єднання, які він читає під .boundary, не містять фактів рендерингу.
Блок locals:
FeatureRecipe.spec.locals: — це необов’язкова мапа іменованих рядків шаблонів Go, відрендерений вивід якої надає мапу .locals.* кожному іншому шаблону в тій самій FeatureRecipe. Це приватний для FeatureRecipe відповідник locals: у Recipe — місце, щоб один раз обчислити похідні рядки й посилатися на них з injectMapping, valuesMapping, pipeline[].with і provides без повторного обчислення. Блок assertions: сутності FeatureRecipe їх не читає: .locals твердження належать сутності Recipe компонента-хоста, як зазначено в assertions-block.md. Відрендерений вивід кожного запису зберігається без початкових і кінцевих пробільних символів. Блок є мапою, а не одним тілом шаблону; скалярне значення в цій позиції схема відхиляє.
apiVersion: aggrega.ai/v1beta1kind: FeatureRecipemetadata: name: regional-routerspec: implements: core/regional-router:^1.0.0 capability: helm locals: region_prefix: "{{ .infra.region | lower }}" fqdn_suffix: "{{ printf \"%s.svc.cluster.local\" .infra.namespace }}" injectMapping: | env: "{{ .infra.target_var }}": "{{ .locals.region_prefix }}.{{ .infra.target_var | lower }}.{{ .locals.fqdn_suffix }}".locals.* діє в межах одного виклику: кожен виклик FR розв’язує власний блок locals:, і результат видно лише подальшим шаблонам цього виклику. Блок розв’язується до обчислення інших шаблонів авторської поверхні FR, тож кожен із них бачить розв’язані значення.
Кожен запис обчислюється в самодостатньому контексті: .context.instance_id, .context.rendered_name, .attachment_name, .values, .infra і вже розв’язані записи цього самого блоку. Це навмисно вужче, ніж контекст, який читають інші шаблони FR, — запис locals: не може звернутися до .context.annotations, .context.inject, .context.uses або .provides, а посилання на будь-яке з них зупиняє збірку з назвою посилання. Похідним значенням, яким потрібні ці стовпи, місце в шаблоні, що їх читає, а не в locals:.
Імена в цьому контексті відповідають на різні запитання, і запис locals: читає їх так само, як інші шаблони FeatureRecipe:
.context.instance_id— це хост-компонент, для якого розв’язується приєднання. Воно означає хост-компонент на кожній поверхні шаблонів, яку обчислює компілятор, тож те саме посилання читається однаково, блок якої б сутності ви не писали..context.rendered_name— це ім’я хост-компонента в тому вигляді, як його повідомляє власний provider хоста — уhelmце ім’я релізу, тобто ідентичність хоста, записана в алфавіті, який допускає ім’я Kubernetes. Воно наявне лише там, де provider хоста повідомляє ім’я, а його читання на хості, provider якого імені не повідомляє, зупиняє збірку..attachment_name— це екземпляр приєднання, що розв’язується, — слот, який він заповнює вfeaturesSchemaсутності-власника, або довільне ім’я, яке ви йому дали.
Тож запис locals:, який виводить ім’я для створюваного ресурсу, поєднує хост і приєднання, так само як це зробив би шаблон artifacts::
spec: locals: scrape_name: "{{ .context.instance_id }}-{{ .attachment_name }}" # api-scrape_targetДе ім’я має бути таким, яке приймає платформа, а provider хоста повідомляє ім’я, складайте його натомість з .context.rendered_name: для хоста з іменем my_api у helm і приєднання scrape вираз {{ .context.rendered_name }}-{{ .attachment_name }} дає my-zuapi-scrape, тоді як ідентичність дала б my_api-scrape, яке ім’я Kubernetes відхиляє. Див. Іменування відрендереного ресурсу.
.values і .infra у записі locals: — це власні стовпи приєднання, задані в оголошенні приєднання, а не стовпи хост-компонента.
Авторський порядок має значення
Записи розв’язуються в порядку написання, і запис може читати сусідній запис, визначений вище, отримуючи його розв’язане значення:
spec: locals: region_prefix: "{{ .infra.region | lower }}" # defined first bucket: "{{ .locals.region_prefix }}-artifacts" # reads the entry aboveЛанцюжки працюють лише донизу. Де один запис читає інший, порядок записів визначає, чи збірка вдасться: перемістіть region_prefix нижче bucket — і збірка зупиниться. Компілятор ніколи не переупорядковує блок, щоб посилання розв’язалося, тож зміна порядку в блоці locals: — це зміна поведінки, а не косметична.
Посилання на запис, який блок визначає пізніше, зупиняє збірку з указанням помилки порядку (перемістіть визначення вище місця читання); посилання на ключ, який блок узагалі не оголошує, зупиняє збірку з назвою ключа (виправте написання). Перевірка відстежує псевдонім блоку: ключ, досягнутий через крапку, яку перевизначає тіло with .locals, або через змінну, прив’язану до .locals, зупиняє збірку на тих самих умовах, що й пряме написання, як і ключ, прочитаний з блоку в дужках, — {{ (.locals).nope }} або {{ ($.locals).nope }}. Одне написання її оминає: ключ, досягнутий через виклик, результат якого текст шаблону не може назвати, — {{ index .locals "nope" }} або {{ (default dict .locals).nope }}. Поле, прочитане з результату такого виклику, не зупиняє збірку й рендерить буквальний текст <no value>; читання через index зупиняє збірку з назвою ключа, бо index зупиняє збірку на кожній поверхні шаблонів, коли мапа, яку він читає, не містить ключа, — див. errors/fatal-halts.md «A template indexes a map with a key the map does not hold (Шаблон індексує мапу ключем, якого мапа не містить)». provides: читає повністю розв’язаний блок, бо locals цієї FeatureRecipe розв’язуються до її provides; шаблон provides:, що називає неоголошений ключ, зупиняє збірку. Це ті самі правила, яких дотримується блок locals: у Recipe, — див. entities/recipe.md «Блок locals:».
Поведінка залежно від області. Для executionScope: component (типово) locals: обчислюється для кожного приєднаного екземпляра компонента в самодостатньому контексті, описаному вище. Для executionScope: boundary locals: обчислюється для кожного приєднання межі в поданні області межі з коренем .boundary.*; поля рівня компонента (.context.instance_id, .context.inject, .context.uses) і .attachment_name недоступні, бо FeatureRecipe виконується один раз для межі, а не один раз для кожного компонента. Список дозволених полів шаблонів області межі застосовується до locals: так само, як до інших шаблонів авторської поверхні FR. injectMapping, який виконується для кожного компонента, якого досягає приєднання, читає це єдине обчислення для межі як свої .locals. Контракт обчислення — авторський порядок, читання сусідніх записів лише донизу, дві зупинки — однаковий в обох областях; відрізняється лише форма навколишнього контексту.
Відмінність від накладань injectMapping і відображень pipeline[].with. locals: створює видиму в контексті мапу для подальших шаблонів; він не додає виводу. injectMapping записує в канал .context.inject споживача (зміна на боці викликача). pipeline[].with надає корисне навантаження args для Wasm-плагіна. Ці три поверхні ортогональні — FeatureRecipe зазвичай використовує всі три разом, причому locals: містить спільні похідні рядки, на які посилаються дві інші.
Блок assertions:
FeatureRecipe.spec.assertions: — це необов’язкова мапа іменованих правил, що виражають інваріанти реалізації FeatureRecipe: міжпольові правила, які виконуються з огляду на конкретний конвеєр Wasm-плагінів, чарт або механізм, на якому побудовано FeatureRecipe. Кожен ключ — це ідентифікатор правила, що з’являється в повідомленні про збій; кожне значення — тіло шаблону Go. Як і твердження Recipe, твердження FeatureRecipe є властивостями конкретної реалізації; правила контракту рівня Feature застосовуються незалежно, на ранішій фазі конвеєра.
spec: implements: core/referenced-secret:^1.0.0 pipeline: - id: fetch_secret plugin: pipeline-step/aws-secrets-manager:1.2.0 function: step assertions: # aws-secrets-manager plugin 1.x requires an explicit region when none is # implied through the Aggregate's infra block. region-supplied-for-secrets-manager: | {{- if not .values.region -}} {{- if not .infra.aws.region -}} {{- fail "aws-secrets-manager plugin 1.x requires either values.region or infra.aws.region to be set" -}} {{- end -}} {{- end -}}Наведене вище правило стосується лише плагіна aws-secrets-manager версії 1.x; воно не застосовується, якщо прив’язується інший FeatureRecipe для core/referenced-secret. Правила контракту рівня Feature з визначення Feature при цьому все одно застосовуються.
Твердження FeatureRecipe обчислюються після прив’язування FeatureRecipe і перед генерацією ресурсів. Контекст шаблону для FR з областю компонента відповідає контексту тверджень Recipe (поля екземпляра сутності плюс .provides, .locals, .recipe.metadata, .recipe.source); для FR з областю межі (executionScope: boundary) твердження обчислюються щодо подання області межі (поля .boundary.* доступні, поля окремих компонентів — ні). Повну граматику написання та розібрані приклади див. у templates/assertions-block.md.
Поле omits: — вилучення відрендерених документів із джерела
Більшості FeatureRecipes це ніколи не знадобиться. Поле призначене для FeatureRecipe, чиє source: — чарт, який ви використовуєте як є (найчастіше завантажений із реєстру) і який рендерить документ, що його підключення не повинно видавати: Secret, який чарт генерує заново під час кожного рендерингу, або об’єкт, який уже надає хост-компонент чи оператор. omits: вилучає такий документ із того, що генерує FeatureRecipe, — а для файлу compose, який FeatureRecipe використовує як джерело, вилучає сервіс, том або конфігурацію, яких підключення не повинно додавати, і для шаблону CloudFormation, який він використовує як джерело, — ресурс.
spec: capability: helm implements: core/observability/collector:1.0.0 source: kind: helm-oci-chart url: oci://registry.example.com/charts/collector version: "0.9.1" omits: # The collector chart ships its own ServiceAccount; the host supplies one. - kind: ServiceAccount name: collector - when: "{{ .infra.without_dashboards }}" kind: ConfigMap name: collector-dashboardsУ сутності Recipe цей ключ задається так само, і Recipe → Поле omits: — вилучення відрендерених документів із джерела є його повним довідником: що вибирає кожне поле запису; що when: обчислюється першим і хибне значення відкидає запис; що кожен застосовний запис повинен щось вилучити, інакше збірка зупиняється з його назвою; що джерело все одно рендериться повністю і фільтрується лише його вивід; і які постачальники враховують цей ключ. У FeatureRecipe відрізняється лише те, де обчислюються шаблони:
- Шаблони кожного запису обчислюються в тому самому контексті, у якому обчислюється
valuesMapping:цього FeatureRecipe, в області, яку вибирає йогоexecutionScope. Записи FeatureRecipe з областю компонента обчислюються один раз для кожного підключення, з.valuesта.infraцього підключення; записи FeatureRecipe з областю межі — один раз для кожної межі, з поданням області межі та.infraпідключення межі. Правила щодо того, що можуть читати шаблони підключення, застосовуються до записів так само, як до йогоvaluesMapping:. - Фільтрується лише те, що рендерить власне
source:цього FeatureRecipe. Йогоworkload:таartifacts:не фільтруються, як і вивід хост-компонента: записи підключення стосуються лише його власного чарту, його власного файлу compose або його власного шаблону CloudFormation і нічого іншого — сервіс compose, який хост оголошує під тим самим ключем уdocker-compose.yaml, куди збираються обидва, не зачіпається, так само як і ресурс, який хост оголошує під тим самим логічним ID у стеку, куди збираються обидва. Щоб змінити документ, який рендерить хост, запис оголошує Recipe хоста, або його змінює крокpipeline:.
Зупинка через запис називає вузол, постачальника, цей FeatureRecipe і позицію запису в його списку omits:; для FeatureRecipe з областю межі рядок над повідомленням називає підключення та його межу.
Робочий приклад цього ключа, заданого в сутності Recipe, — вилучений згенерований Secret завантаженого чарту, а також зупинки без запису та на записі, який нічого не збігається, — див. у ai-gateway-own-webhook-certificate.