Композиція вихідних даних
Одна збірка Aggrega створює вихідні файли в окремих для кожної межі каталогах у dist/ за допомогою шести різних механізмів: рендеринг із джерела, синтез робочого навантаження, FeatureRecipe Resource Generation, патчі конвеєра плагінів FeatureRecipe, композиція на рівні Release та пряме виведення артефактів. Механізми виконуються у визначеному порядку; коли два механізми створюють файл з однаковою назвою в одному каталозі межі, вихідні дані детерміновано конфліктують; у разі виявлення конфлікту збірка зупиняється до виведення, називаючи кожного учасника, з категорією, яку називає правило для цього конфлікту.
Ця сторінка описує шість механізмів в одному місці та визначає порядок рендерингу між ними. Довідники окремих розділів і сутностей охоплюють власні частини; правила виявлення конфліктів для всіх шести механізмів зібрано тут.
Шість механізмів, що створюють вивід
Кожен механізм розташований на певній поверхні авторингу Recipe / FeatureRecipe і створює файли за певними домовленостями іменування. Механізми накопичуються для кожного вузла — один екземпляр компонента може запускати кілька механізмів одночасно (базовий Recipe з джерелом + супутній файл, синтезований із Workload + CRD ExternalSecret, виданий FeatureRecipe + патч конвеєра плагінів, застосований до синтезованого Deployment).
1 — Рендеринг Recipe з джерела (source: + valuesMapping:)
Поверхня авторингу. Recipe оголошує source: <path> разом із valuesMapping: (поле приймає вбудований шаблон Go, файловий $import: або бібліотечний $import: до запису MappingLibrary — див. entities/recipe.md «Поле valuesMapping — три режими авторингу»). Джерело вказує на Helm-чарт на диску, YAML-файл docker-compose або інший нативний для провайдера артефакт.
Місце в конвеєрі. Базовий рендеринг, після того як розв’язано locals і provides сутності Recipe.
Форма виводу. Залежить від Provider:
- Провайдер helm — пласкі YAML-файли Kubernetes, названі за ідентичністю компонента, а потім за самим ресурсом:
<component-id>-<kind>[-<namespace>]-<name>.yaml; документ без kind або без name натомість називається за шляхом свого шаблону. Ім’я береться з ресурсу, а не з шаблону, тож два шаблони в різних підкаталогах з однаковим іменем файлу залишаються двома файлами. Helm SDK рендерить чарт з об’єднаними значеннями; Aggrega додає мітки й анотації походження після рендерингу. - Провайдер helm-chart — файли підчартів, скопійовані в
charts/<instance_id>/дослівно, за винятком власногоnameчарта, який umbrella-чарт встановлює в закодовану ідентичність екземпляра, щоб два компоненти, які вендорять чарти з однаковим іменем, залишалися розрізнюваними (див.providers/helm-chart.md); поруч видаються umbrella-файлиChart.yaml+values.yamlдля кожної межі. - Провайдер compose — проміжні файли
<nodeID>.compose-fragment.yaml, які переходять у композицію на рівні Release (механізм 5).
2 — Синтез Workload у Recipe (workload:)
Поверхня авторингу. Recipe оголошує workload: з документом Workload. Поле приймає вбудований вміст (блоковий скаляр) або $import: (шлях до файлу).
Місце в конвеєрі. Базовий рендеринг, після того як розв’язано valuesMapping сутності Recipe (тіло Workload саме є рядком із шаблоном Go, що обчислюється з повним контекстом шаблону).
Форма виводу. Залежить від Provider:
- Провайдер helm — один об’єкт контролера, вибраний за
formсутності Workload (Deployment для stateless, StatefulSet для stateful, DaemonSet для daemon, Job для task, CronJob для scheduled) + Service для кожного сервісу + один PVC на кожен томpersistent. Дві форми іменування, і вони різні: об’єкт контролера названо за назвою релізу вузла та його kind —<release name>-deployment.yaml,<release name>-statefulset.yaml,<release name>-daemonset.yaml,<release name>-job.yaml,<release name>-cronjob.yaml, — тоді як файл окремого ресурсу названо за ресурсом, який він містить, з kind наприкінці:<release name>-<svcName>-service.yamlі<release name>-<volName>-pvc.yaml, бо кожен названо за власнимmetadata.nameцього ресурсу. Назва релізу — це ідентичність вузла, записана в алфавіті, який допускає назва Kubernetes, тож вона збігається з ID вузла скрізь, де той не містить підкреслень і великих літер: вузолmy_apiзаписуєmy-zuapi-deployment.yaml(див.entities/workload.md«Synthesized-name convention»). Workload, єдиним способом відкриття якого є зовнішнє ім’я, натомість видає<release name>-service.yaml, оскільки немає ключа сервісу. - Провайдер compose — проміжні файли
<nodeID>.compose-fragment.yaml, які переходять у композицію на рівні Release. - Провайдер helm-chart — не підтримується; роль helm-chart — лише композиція чартів у режимі з джерелом. Recipe, що націлюється на helm-chart з
workload:, відхиляється під час рендерингу (провайдер helm-chart не повідомляє про можливість синтезу).
3 — Генерація ресурсів FeatureRecipe (режим із джерелом для FeatureRecipes)
Поверхня авторингу. FeatureRecipe оголошує source: разом із valuesMapping: (або еквівалентом) — той самий шаблон, що й рендеринг Recipe з джерела, але для прикріплень Feature, а не для основних Components.
Місце в конвеєрі. Базовий рендеринг, поряд із базовим рендерингом Recipe для батьківського Component. Кожне прикріплення Feature виконує власний прохід рендерингу FeatureRecipe.
Форма виводу. Визначається провайдером батьківського Component, бо вивід прикріплення входить до групи збирання цього Component, а не до власної, — і випливає з того, як цей провайдер об’єднує групу, оскільки саме це визначає, чи є взагалі місце для прикріплення. Три форми, по одній на кожен спосіб об’єднання:
- Провайдер, який дає кожному учаснику власну позицію — один чарт, що містить чарт для кожного учасника, одна коренева конфігурація, що містить модуль для кожного учасника, — дає власну позицію і прикріпленню, поруч із компонентом, до якого воно прикріплене, а не всередині нього. Дві координати утворюють єдиний сегмент каталогу цієї позиції,
<component-id>--<feature-instance-id>, тож компонентapiіз прикріпленнямauxрозташовується вapi--auxпоруч ізapi, у тому каталозі, який цей провайдер називає для своїх учасників. Поруч, а не всередині, бо ціль такого провайдера знаходить своїх учасників саме в наданих їм позиціях: каталог на рівень нижче однієї з цих позицій є вмістом, що належить цьому учаснику, а не окремим учасником, тож ніщо його не адресує й ніщо не читає. Прикріплення, оголошене на межі, не має компонента-господаря, ім’я якого можна вказати, тож його сегментом є лише ім’я екземпляра. Кожну координату кодують перед об’єднанням, тож координату, яка сама містить послідовність з’єднання, неможливо сплутати зі з’єднанням. - Провайдер, який записує кожен документ безпосередньо в каталог межі, такого місця не має, бо саме це він і оголошує про свою ціль: читаються лише файли, розташовані безпосередньо в каталозі. Тому ті самі дві координати переходять із сегментів каталогу в ім’я файлу, і файли прикріплення опиняються поруч із власними файлами компонента як
<component-id>--<feature-instance-id>--<file>. Дві координати кодуються, бо ім’я файлу не має роздільника, на який можна покластися, і приєднуються до власного імені файлу на двосимвольній межі, якої не може містити жодна закодована координата, — саме це зберігає два прикріплення, що видають одне ім’я файлу, двома різними файлами. - Провайдер, який згортає учасників своєї групи в один документ, згортає в цей документ і вивід прикріплення, де кожен ресурс несе власну ідентичність прикріплення, щоб залишалося зрозуміло, що звідки походить. Якщо такий провайдер несе прикріплення, відрендерене для іншої цілі, цей вміст не можна згорнути в документ, до якого він не належить, тож його записують поруч зі зібраним документом — у формі з префіксом імені файлу, описаній вище, з тієї самої причини.
Поширені форми:
- CRD
ExternalSecret/VaultSecret, згенерований Fetcher облікового FeatureRecipe. - CRD
ServiceMonitor/PrometheusRule, згенерований Feature спостережуваності. - CRD
HTTPRoute/Gateway, згенерований Feature маршрутизації.
4 — Конвеєр плагінів FeatureRecipe (патчі RFC 6902 + випуск ресурсів)
Поверхня авторингу. FeatureRecipe оголошує pipeline: — масив кроків Wasm-плагінів (Two-Part Plugin Principle: Fetcher + Injector для Features облікових даних; довільні конвеєри плагінів для Features, не пов’язаних з обліковими даними).
Місце в конвеєрі. Конвеєр плагінів, після завершення базового рендерингу та рендерингу FeatureRecipe із джерела.
Форма виводу. Залежить від Plugin (Plugin-specific). Крок повертає два класи виводу:
- Патчі RFC 6902, які рушій застосування застосовує до адресованих документів у відрендереному наборі (наприклад, додавання контейнера sidecar, монтування тому із секретом, переписування змінної середовища в синтезованому Deployment).
- Побічні ефекти — повні нові ресурси, що випускаються разом із патчем через
side_effectsкроку (зазвичай CRD отримання з vault від Fetcher, на який потім посилається Injector).
Стан на сьогодні: доступно згідно з Стан мови → Фази конвеєра компіляції. Кожен оголошений крок виконується під час aggrega build: хост запускає плагін Wasm цього кроку над відрендереним набором, застосовує повернені патчі та випускає побічні ефекти кроку. Поверхню контракту плагіна описано в plugins/plugin-contract.md.
5 — Композиція на рівні Release (збирання меж для кожного провайдера)
Поверхня створення. Визначається формою Release — без створення на рівні окремого Recipe. Можливість, що збирає межу, робить це один раз, після того як відрендерено кожен вузол цієї межі: можливість compose збирає всі фрагменти вузлів в один docker-compose.yaml на межу, а можливість helm-chart збирає копії підчартів вузлів в один парасольковий чарт на межу.
Місце в конвеєрі. Після базового рендерингу, коли для межі накопичено вивід кожного вузла за його Recipe.
Форма виводу. Залежить від провайдера:
- Провайдер compose — один
docker-compose.yamlу корені межі, що об’єднує сервіси, томи та мережі кожного вузла-учасника. Проміжні файли<nodeID>.compose-fragment.yaml(механізми 1 + 2) зливаються в єдиний вивід; фрагменти не з’являються в остаточному каталозі межі. - Провайдер helm-chart — один парасольковий
Chart.yaml+values.yamlу корені межі, а також каталоги підчартів для кожного вузла вcharts/<instance_id>/.
6 — Прямий випуск артефактів Recipe (artifacts:)
Поверхня створення. Recipe оголошує artifacts: як мапу іменованих записів; кожен запис — це або вбудований вміст (шаблонний рядок із тілом файлу), або посилання $import: на шлях до файлу шаблону — прямий випуск файлів без участі провайдера.
Місце в конвеєрі. Обчислення артефактів, у межах базового рендерингу.
Форма виводу. Один файл на запис артефакту, названий за ключем запису в мапі artifacts:. Автор Recipe безпосередньо задає ім’я файлу та вміст.
Стан на сьогодні: доступно згідно з Стан мови → Види вхідних даних Recipe. Кожен запис обчислюється з повним контекстом шаблону після синтезу робочого навантаження та розв’язання джерела, а отриманий файл випускається під ключем запису. Що ціль робить із випущеним артефактом, залежить від можливості: провайдер, який приймає окремий артефакт, випускає його як окремий файл, тоді як той, що приймає артефакти лише разом з іншим видом вхідних даних, вбудовує запис у те, що збирає, — тож тіло, форма якого не відповідає очікуванням цього збирача, зупиняє компіляцію в категорії TRANSLATION_ERROR, а не випускається дослівно. Перш ніж створювати артефакт для можливості, перегляньте таблицю за можливостями в architecture/16-recipe-input-composition.md.
Порядок рендерингу
Шість механізмів виконуються у визначеному порядку, щоб подальші механізми могли читати результати попередніх. Порядок:
- Обчислення provides — для кожного вузла спершу розв’язується блок
locals:сутності Recipe, у порядку автора, причому кожен запис читає записи над ним; потім обчислюються шаблониprovides:вузла, у довільному порядку між собою (самодостатні:.context.instance_id,.context.rendered_name, якщо провайдер вузла його повідомляє,.values,.infra, розв’язані.locals, статичний текст). Саме порядок «locals перед provides» дає змогу записуprovides:читати локальне значення й отримувати розв’язане значення. - Публікація locals і розв’язання джерела — ці locals публікуються в
.locals, і шаблон URIsource:сутності Recipe обчислюється на їх основі (розв’язуючи вказівник джерела, якщо він шаблонний). Поверхня джерела спільно використовує контекст locals, тож вона читає.locals, а не.provides. - Відображення ін’єкцій — обчислюються блоки
injectMapping:сутності FeatureRecipe (конвеєр ін’єкцій перехоплюється до рендерингу сутності Recipe). - Відображення значень — обчислюється
valuesMapping:сутності Recipe (режим із джерелом і режим без джерела створюють словники значень). - Синтез Workload — синтез Workload сутності Recipe (механізм 2 видає маніфести для синтезованого режиму).
- Обчислення артефактів — обчислення
artifacts:сутності Recipe (механізм 6). - Provider render — провайдер виконує рендеринг (механізм 1 — режим із джерелом створює пласкі маніфести; режим без джерела створює генеративні маніфести).
- Рендеринг Feature — рендеринг FeatureRecipe для кожного приєднання Feature на вузлі (механізми 3 + 4 — тут виконується генерування ресурсів; конвеєр плагінів виконується пізніше, на кроці 9).
- Конвеєр плагінів — мутація після рендерингу: кроки плагінів
pipeline:сутності FeatureRecipe застосовують патчі RFC 6902 і видають додаткові ресурси (механізм 4). - Композиція на рівні Release — збирання меж можливості об’єднує фрагменти окремих вузлів у результати для кожної межі (механізм 5).
Порядок важливий, бо подальші механізми можуть читати результати попередніх — наприклад, крок конвеєра плагінів може застосувати патч до Deployment, відрендереного провайдером, а компонувальник на рівні Release може об’єднати фрагменти, видані рендерингом провайдера, рендерингом функцій і конвеєром плагінів.
Набір правил виявлення колізій
Коли два механізми створюють файл з однаковою назвою в одному каталозі межі, збірка зупиняється й називає кожного учасника, з категорією, яку називає кожне з наведених нижче правил. Набір правил:
Правило форми Recipe: колізія ключів записів artifacts:
Сутність Recipe оголошує два записи в artifacts: з однаковим ключем (ключ визначає назву створюваного файлу незалежно від того, чи тіло запису написано inline, чи завантажено через $import:). Виявляється під час завантаження Recipe згідно з errors/fatal-halts.md «artifacts: entry keys must be unique (ключі записів мають бути унікальними)».
Правило форми Recipe: колізія між видами вхідних даних під час видачі
Три види вхідних даних Recipe — sourced, synthesized та artifacts — кожен видають файли в той самий каталог межі. Якщо вивід, відрендерений із джерела, синтезований із workload або виданий як артефакт, створює файл, назву якого вже створив інший вид вхідних даних, збірка зупиняється під час видачі. Виявляється під час видачі згідно з errors/fatal-halts.md «Emission-time filename collision across input kinds (Колізія назв файлів між видами вхідних даних під час видачі)».
Колізія назв сервісів compose (рівень Release)
Коли два різні вузли (у будь-якій комбінації меж) додають до об’єднаного виводу compose сервіси з однаковою назвою, provider compose зупиняється під час компонування межі з категорією TRANSLATION_ERROR і називає кожен кортеж-учасник (boundary, node, serviceName). Виявляється під час компонування на рівні Release згідно з розділом про вивід на рівні Release у providers/compose.md.
Сервіс відхиляється лише за назвою, без порівняння того, що оголосили два вузли. Сервіс compose — це один запущений контейнер, тож два вузли, кожен з яких хотів свій, отримують один на двох, і намір одного з учасників втрачається, хоч би якими ідентичними були два визначення.
Конфлікт назв томів і конфігурацій compose (рівень Release)
Коли два різні вузли додають до об’єднаного виводу compose запис верхнього рівня volumes: або configs: з однаковою назвою і ці два оголошення відрізняються, provider compose зупиняється з категорією TRANSLATION_ERROR і називає запис та кожен кортеж-учасник (boundary, node). Виявляється під час компонування на рівні Release згідно з розділом про вивід на рівні Release у providers/compose.md.
На відміну від правила для сервісів вище, це правило порівнює оголошення, і спільна назва допустима там, де учасники узгоджені. Іменований том чи конфігурація — це один об’єкт, тож два вузли, що оголошують його однаково, обидва запросили саме той запис, який зрештою потрапляє в об’єднаний документ, і нічого не втрачається. Два вузли, що оголошують його по-різному, розходяться щодо цього одного об’єкта, і збереження будь-якого з оголошень відкинуло б інше зі збірки, яка інакше завершилася б успішно. Два оголошення вважаються узгодженими, коли вони описують той самий запис у зібраному файлі, тож тіло, записане як порожнє відображення, і тіло, пропущене зовсім, узгоджені.
Псевдонім і каталог підчарту helm-chart
Підчарт helm-chart розміщується в charts/<instance_id>/, а його значення обмежені його псевдонімом, яким є ідентифікатор екземпляра, закодований для позиції псевдоніма. Два екземпляри не можуть отримати один псевдонім, якщо їхні ідентифікатори екземплярів не є тим самим рядком, бо кодування виписує символи, яких псевдонім не приймає, а не замінює їх, — тож псевдонім ідентифікує рівно один підчарт, і значення, записані під ним, потрапляють лише до цього підчарту. Ідентифікатори екземплярів, своєю чергою, унікальні в межах межі згідно з правилами сплощення Aggregate, тож каталог також не може зіткнутися. Обидві половини структурні: жодна не спирається на перевірку.
Колізія назв відрендерених ресурсів Helm
У межах однієї межі два вузли, що рендеряться в однакову назву ресурсу Kubernetes, створюють два файли YAML з полями metadata.name, що перетинаються. Назви файлів відрізняються, бо кожна має префікс власної основи іменування, тоді як metadata.name у них усе ще може збігатися, — тож збірка перевіряє назви, які несуть відрендерені ресурси, і якщо два учасники виводять одну назву для одного kind в одному просторі імен, збірка зупиняється з категорією TRANSLATION_ERROR ще до запису будь-чого, називаючи цю назву та кожен компонент і кожне прикріплення, що її вивели (див. errors/fatal-halts.md).
Найбільший випадок закрито побудовою, а не перевіркою. Sourced-чарт, що називає свої ресурси за назвою релізу, більше не може спричинити це між двома компонентами, бо дві основи іменування, які хоч трохи відрізняються, дають дві назви релізу, — див. providers/helm.md «How the release name is derived». Залишаються два випадки, і саме про них повідомляє наведена вище перевірка. Перший — чарт, що буквально записує назву ресурсу у свої шаблони, і жодне виведення не може відрізнити таку назву від будь-якого іншого літерала. Другий — два прикріплення Feature до одного компонента, кожне з яких постачає чарт, написаний його автором: обидва за задумом рендеряться з назвою релізу цього компонента, тож два чарти, що називають ресурс за .Release.Name, там збігаються, — дайте ресурсам двох чартів різні назви або прикріпіть їх до різних компонентів.
Кожна синтезована назва починається з власної ідентичності вузла — назва об’єкта-контролера, а також кожна назва окремого ресурсу через домовленість про синтезовані назви Service <release name>-<svcName> (згідно з entities/workload.md «Synthesized-name convention»), — що робить колізії між вузлами структурно неможливими за побудовою. Авторам, чия збірка зупиняється на назві Deployment / Service, слід спершу перевірити, чи не видають дві різні Recipes однаково названі ресурси різними шляхами рендерингу (наприклад, templates/deployment.yaml sourced-чарту, що зіткнувся з metadata.name синтезованого з workload Deployment).
Шаблони взаємодії між механізмами
Синтез через Workload + патч конвеєра плагінів
Канонічний шаблон: механізм 2 (синтез робочого навантаження) створює базовий Deployment; механізм 4 (плагін Injector) застосовує патч RFC 6902, який монтує том із секретом у Deployment. Обидва механізми поєднуються — Deployment є тим самим ресурсом K8s, а патч накладає посилання на ConfigMap / Secret на синтезовану основу.
Це основний шаблон для впровадження облікових даних у синтезовані робочі навантаження. Fetcher (механізм 3, генерація ресурсів) створює CRD ExternalSecret, який кластер отримує під час виконання; Injector (механізм 4, патч конвеєра плагінів) змінює Deployment, щоб змонтувати отриманий Secret K8s.
Джерельний рендеринг + синтез через Workload на різних межах
Одна сутність Aggregate може мати один компонент, прив’язаний до джерельного helm-рецепта Recipe (механізм 1) на межі A, і сусідній компонент, прив’язаний до helm-рецепта Recipe із синтезом через Workload (механізм 2) на межі B. Каталог кожної межі містить відповідну форму виводу; іменування файлів між межами не конфліктує, оскільки каталоги dist/ кожної межі ізольовані один від одного.
Злиття compose на рівні Release для кожного вихідного каталогу
Складання можливості compose збирає фрагменти окремих вузлів усіх меж, каталог яких обчислюється в той самий шлях, в один docker-compose.yaml за цим шляхом; дві межі одного Release, націлені на compose, записують два файли, якщо їхні каталоги різні, і один об’єднаний файл, якщо каталог у них спільний.
Тому конфлікти імен сервісів виявляються для кожного файлу під час його злиття на рівні Release згідно з наведеним вище правилом. Дві межі, націлені на compose, у різних каталогах, кожна з яких оголошує сервіс з назвою api, не конфліктують: файл кожної межі містить власний сервіс. Дві межі зі спільним каталогом записують один файл, і збірка зупиняється, називаючи обох учасників.
Перехресні посилання
entities/recipe.md— поверхня авторингу сутності Recipe (механізми 1 + 2 + 6 генерують вивід із вмісту Recipe).entities/featurerecipe.md— поверхня авторингу сутності FeatureRecipe (механізми 3 + 4 генерують вивід із вмісту FeatureRecipe).providers/helm.md— форми виводу провайдера helm для кожного механізму та домовленості щодо іменування.providers/helm-chart.md— композиція парасолькового чарту й субчартів провайдера helm-chart (механізм 5).providers/compose.md— фрагментація за вузлами й композиція на рівні Release у провайдері compose (механізм 5).errors/fatal-halts.md— правила форми Recipe щодо унікальних ключів записівartifacts:і щодо колізій імен файлів між різними видами вхідних даних.templates/expansion-matrix.md— момент обчислення кожного місця шаблону в порядку рендерингу.plugins/plugin-contract.md— поверхня контракту конвеєра плагінів (механізм 4).10-status.md— поточний стан готовності механізму 6 (artifacts:) і середовища виконання конвеєра плагінів механізму 4.architecture/10-compilation-pipeline.md— повний конвеєр компіляції, зокрема порядок етапів рендерингу.architecture/16-recipe-input-composition.md— три види вхідних даних сутності Recipe (вихідне обґрунтування для механізмів 1 + 2 + 6).