Змінні шаблонів шляхів
Поля directory: і subDirectory: межі в сутності Release — це шаблони Go, що обчислюються під час збирання. Вони визначають, куди на диску потрапляють згенеровані артефакти, а отже, і які артефакти збираються разом: дві межі, що обчислюються в однаковий кортеж (path, provider), спільно використовують один асемблер і створюють один об’єднаний результат (один Chart.yaml, один docker-compose.yaml). Ця сторінка — довідник для авторів щодо змінних, на які можуть посилатися ці шаблони, суворої семантики обчислення та правил каскаду, що дають змогу межам успадковувати значення від батьківських меж.
Концептуальний опис просторового розділення та диспетчеризації за (path, provider) див. у architecture/16-recipe-input-composition.md. Опис засобів створення сутності Release на рівні сутності див. у entities/release.md. Наслідки на боці провайдера описано в providers/architecture.md і на сторінках окремих провайдерів.
Сувора обробка: missingkey=error
Шаблони шляхів обчислюються в режимі Go missingkey=error. Посилання на неоголошене поле, невстановлений ключ parameters.X або друкарська помилка на кшталт {{ .parmaeters.region }} спричиняє явну помилку, а не непомітну підстановку порожнього рядка в шлях.
Ця суворість відрізняється від решти компілятора — valuesMapping, injectMapping та інші поверхні рендерингу значень використовують missingkey=zero згідно з домовленістю Helm/Sprig. Формування шляхів структурно відрізняється: шаблон рендерингу значень, що дає порожній рядок, потрапляє в поле маніфесту, де наслідки обмежені; шаблон шляху, що дає порожній рядок, потрапляє в структуру каталогів, де наслідки необмежені (колізії, зламане складання, фантомні шляхи). Суворий режим шаблонів шляхів існує для того, щоб виявляти такі збої під час збирання, а не під час розгортання.
Перевірка за списком дозволених змінних під час розбору
Окрім суворості під час виконання, шаблони шляхів перевіряються під час розбору за закритим списком дозволених імен змінних. Посилання на ім’я змінної, якого немає в цьому списку, зупиняє збирання ще до початку будь-якого рендерингу; діагностика називає проблемне поле та межу, у якій воно трапляється.
Список дозволених змінних закритий за задумом: такі поверхні, як .context.inject, .values і .locals, навмисно не доступні шаблонам шляхів. Формування шляхів — це структурне питання, а не питання рендерингу значень; прив’язка шляхів збирання до значень окремих компонентів зробила б граф шляхів залежним від даних і підірвала б інваріант детермінованого виводу.
Матриця змінних
| Змінна | directory: | subDirectory: | Опис |
|---|---|---|---|
{{ .capability }} | так | так | Можливість рендерингу (helm, helm-chart, compose, terraform, cloudformation), яку оголошує Recipe компонента-учасника, для артефактів, що виводяться за цим шляхом. |
{{ .boundary_name }} | так | так | Задане автором ім’я межі в сутності Release (наприклад, production, eu-prod). |
{{ .parameters.X }} | так | так | Будь-який типізований параметр, оголошений у сутності Aggregate і заповнений сутністю Release. Строгий доступ — звернення до .parameters.unknown зупиняє збірку. |
{{ .manifest.recipe_name }} | так | так | Ім’я Recipe, визначене через Manifest для компонента-учасника. Корисне для спрямування артефактів кожного Recipe в окремі підпапки. |
{{ .parent_boundary.* }} | так | так | Каскадний доступ до обчислених значень охопної межі. Див. Каскад батьківської межі нижче. |
{{ .component_id }} | — | так | ID екземпляра компонента, що робить внесок. Для сутності Feature, прикріпленої на межі, чия сутність FeatureRecipe виконується один раз для межі (executionScope: boundary), це складений ідентифікатор, який ресурси цього прикріплення несуть у своїй мітці aggrega.ai/component-id, — bfr--app--shared для прикріплення shared на межі app, скорочений там, де провайдер прикріплення обмежує довжину імен, — тож вивід прикріплення потрапляє в директорію, названу за цією міткою. Доступна лише в subDirectory:, оскільки directory: є властивістю рівня межі — рядок директорії обчислюється один раз для кожної межі, до будь-якої маршрутизації на рівні компонентів. |
Поле directory: за замовчуванням дорівнює boundaries/, за яким іде шлях межі (стабільний ідентифікатор часу збірки, отриманий із дерева меж); Release, що перелічує свої компоненти без оголошення меж, записує їх узагалі без сегмента каталогу. Поле subDirectory: за замовчуванням дорівнює {{ .capability }}, тож артефакти кожної можливості потрапляють в окрему підпапку в каталозі межі — незалежно від того, пропущено поле чи записано як subDirectory: "", що читається точно як пропущене. Значення subDirectory: "." або шаблон, що обчислюється в порожній рядок, скасовує це групування.
Чого ці шаблони не визначають: розміщення artifacts:
Один сегмент вихідного шляху не задається шаблоном шляху. Файл, названий у блоці artifacts: сутності Recipe, записується в каталог з іменем компонента, що його оголосив, усередині того, у що обчислюється subDirectory:. Цей сегмент фіксований і завжди присутній для цілі, яка записує файли своїх учасників поруч, а не вкладає кожного учасника в окремий chart чи модуль.
Причина в тому, що саме дає ім’я файлу. Маніфест, який ціль рендерить або синтезує, отримує від цілі ім’я за компонентом, якому він належить, тож він уже ідентифікує свій компонент. Артефакт названо ключем, який написав його автор, — app-config.yaml, netpol.yaml, — і цей ключ нічого не каже про компонент, бо Recipe, що його оголошує, не знає, які компоненти буде до нього прив’язано. Два компоненти в одній межі, прив’язані до одного Recipe, записали б один шлях, і ні автор Recipe, ні автор Release не мають способу їх розділити.
Додається лише каталог; ім’я файлу лишається заданим автором ключем, тож файл, який автор читає у виводі, має ім’я, яке він написав.
Що все ще дає subDirectory: і як вони поєднуються. subDirectory: переміщує кожен файл, який виводить учасник, — відрендерені маніфести, синтезовані маніфести й артефакти разом, — тож це інструмент, щоб дати одному компоненту власний каталог для подальших інструментів, що працюють із повним набором маніфестів одного компонента, або щоб спрямувати кілька компонентів в одну спільну папку. Сегмент artifacts: застосовується під тим, у що воно обчислюється. Тому запис subDirectory: "{{ .capability }}/{{ .component_id }}" для компонента, чий Recipe оголошує artifacts:, дає ім’я компонента двічі — артефакт потрапляє в <capability>/<component>/<component>/<key>, тоді як відрендерені маніфести цього компонента потрапляють у <capability>/<component>/<key>. Використовуйте це перевизначення, коли хочете зібрати весь вивід компонента, і не задавайте його, коли потрібно лише розділити артефакти, що вже робить значення за замовчуванням.
.capability визначається для кожного компонента, а directory: межі обчислюється з двома різними цілями. Обчислення на рівні межі, яке публікує .parent_boundary.directory для дочірніх меж, виконується до прив’язування будь-якого компонента, тож .capability там порожнє. Обчислення на рівні компонента, яке визначає, куди фактично потрапляють артефакти учасника, містить можливість цього компонента. Тому батьківська межа із записом directory: "d-{{ .capability }}" публікує вниз каскадом d-, тоді як її власні артефакти потрапляють у d-compose.
Каскад батьківської межі
Вкладені межі отримують подання .parent_boundary, яке надає обчислений шлях безпосередньої батьківської межі та її власні дані, розв’язані каскадом. Каскад має один рівень: .parent_boundary межі — це її безпосередній батько, а не дід. Щоб дістатися вище, сама батьківська межа використовує .parent_boundary у власних шаблонах, явно передаючи значення вниз деревом.
Доступні поля в .parent_boundary:
| Поле | Опис |
|---|---|
.parent_boundary.directory | Обчислене значення directory: батьківської межі (після застосування шаблону). |
.parent_boundary.boundary_name | Задане автором ім’я батьківської межі. |
.parent_boundary.parameters | Та сама мапа .parameters.*, яку бачила батьківська межа (значення параметрів глобальні для сутності Release, але псевдонім надано для симетрії). |
.parent_boundary.annotations | Анотації батьківської межі, розв’язані каскадом. |
Канонічний шаблон: батьківська межа, яка один раз задає directory:, плюс дочірні межі, які спрямовують свої артефакти під батьківську, оголошуючи directory: "{{ .parent_boundary.directory }}". Це зводить дочірні межі до шляху збирання батьківської, створюючи один об’єднаний результат, що містить учасників з кожної дочірньої межі. Саме на цьому ґрунтується сутність Feature core/compose-bridge: батьківська межа, що містить функцію мосту, дві дочірні межі (наприклад, services-net і data-net), які спільно використовують directory: батьківської, та один об’єднаний docker-compose.yaml, що містить кожен компонент плюс сервіс мосту.
Дзеркальний варіант протилежний: не вказуйте .parent_boundary.directory у дочірніх межах (або обчислюйте окремий шлях), і кожна дочірня межа отримає власне збирання. Обидві форми є повноправними.
Розібрані приклади структур
Структура 1 — типове розділення за межами
spec: boundaries: api-prod: directory: "deploy/api-prod" components: api: {} cache: {} data-prod: directory: "deploy/data-prod" components: db: {}Кожна межа обчислюється в окремий directory:, тож кожна отримує власне складання:
deploy/api-prod/<capability>/...deploy/data-prod/<capability>/...Типове значення subDirectory: "{{ .capability }}" розділяє артефакти за можливостями всередині каталогу кожної межі. Дві межі, по два результати складання на кожну можливість, без злиття.
Структура 2 — об’єднане складання через спільний батьківський каталог
spec: boundaries: cluster: directory: "deploy/cluster" annotations: aggrega.ai/chart-name: "cluster-umbrella" features: bridge: type: core/compose-bridge:1.0.0 boundaries: services-net: directory: "{{ .parent_boundary.directory }}" annotations: { aggrega.ai/namespace: services } components: api: {} data-net: directory: "{{ .parent_boundary.directory }}" annotations: { aggrega.ai/namespace: data } components: db: {}Обидві дочірні межі обчислюють directory: як deploy/cluster (каталог батьківської межі), тож усі внески зливаються за одним шляхом складання. З типовим subDirectory: "{{ .capability }}" внески compose від обох дочірніх меж потрапляють у deploy/cluster/compose/ і утворюють один об’єднаний docker-compose.yaml. Feature compose-bridge, приєднана до батьківської межі, виконується один раз (диспетчеризація в області межі) і додає сервіс мосту до того самого об’єднаного файлу.
Анотація батьківської межі aggrega.ai/chart-name: "cluster-umbrella" каскадно передається обом дочірнім межам; якби межі також містили внески helm-chart, підчарти helm-chart обох дочірніх меж компонувалися б під одним зонтичним чартом з назвою cluster-umbrella. Розбіжні значення chart-name у внесків за одним шляхом зупиняють збирання.
Структура 3 — маршрутизація за компонентами через subDirectory: і параметри
spec: parameters: region: "eu-west-1" boundaries: eu-prod: directory: "deploy/{{ .parameters.region }}" components: api: subDirectory: "{{ .capability }}/{{ .component_id }}" db: subDirectory: "{{ .capability }}/{{ .component_id }}" ingress: subDirectory: "shared"directory: межі обчислюється як deploy/eu-west-1 (підстановка параметра). Перевизначення subDirectory: для окремих компонентів спрямовують кожен внесок до окремої підтеки компонента, а компонент ingress перевизначає це на пласку підтеку shared для наскрізних артефактів:
deploy/eu-west-1/<capability>/api/...deploy/eu-west-1/<capability>/db/...deploy/eu-west-1/shared/...Цей шаблон підходить підприємствам, яким потрібні окремі каталоги артефактів для кожного компонента — для подальших інструментів, що працюють із маніфестами одного компонента. Якщо Recipe компонента також оголошує artifacts:, перш ніж обрати цю структуру, прочитайте розділ Що ці шаблони не визначають вище: ці файли вже містять сегмент компонента, тож таке перевизначення додає другий.
Діагностика
Підсистема шаблонів шляхів зупиняє збірку в кожній із наведених нижче ситуацій, а errors/fatal-halts.md документує їх під цими назвами. На тій сторінці наведено повідомлення, яке виводить кожна зупинка; звіряйте вивід збірки з цим текстом.
- Path-template references a variable outside the allowlist (Шаблон шляху посилається на змінну поза списком дозволених) — під час розбору: шаблон шляху посилається на змінну, якої немає у списку дозволених.
- Path collision (Колізія шляхів) — під час збирання: два внески меж обчислюються в той самий шлях, але розходяться щодо властивості, яка має бути однаковою для всіх внесків за цим шляхом.
- Instance-ID collision (Колізія ідентифікаторів екземплярів) — під час збирання: дві межі, що обчислюються в той самий кортеж
(path, provider), додають компоненти з однаковими ідентифікаторами екземплярів. - Chart-name mismatch (Невідповідність назв чартів) — під час збирання: об’єднана збірка helm-chart отримує внески з конфліктними анотаціями
aggrega.ai/chart-name, визначеними каскадом. - Missing template key (Відсутній ключ шаблону) — шаблон шляху посилається на поле відкритої змінної, яке не має значення (наприклад,
{{ .parameters.region }}, коли сутність Release не задаєregion, або ключ.parent_boundaryу межі верхнього рівня, яка не має батьківської);missingkey=errorвидає явне повідомлення, що називає межу, поле шаблону (directory:чиsubDirectory:) і відсутній ключ..parametersі.parent_boundaryвідкриті — їхні ключі є авторськими даними, — тоді як.manifestоголошує свої ключі, тож хибно написаний ключ у.manifestнатомість відхиляється під час розбору як невідоме посилання, а діагностика перелічує ключі, які визначає.manifest.
Перехресні посилання
entities/release.md— створення сутностей Release, зокрема просторове розділення та поляdirectory:/subDirectory:.providers/architecture.md— диспетчеризація провайдерів і модель збирання для кожної пари(path, provider).providers/compose.md— вихідні дані compose для кожної пари(path, provider), зокрема сценарій об’єднаного шляху.providers/helm-chart.md— парасолькова композиція helm-chart і правило каскаду імені чарту для об’єднаних шляхів.entities/featurerecipe.md— сутності FeatureRecipes з областю дії межі (сутність Featurecore/compose-bridgeспирається на описану тут модель збирання об’єднаних шляхів).errors/fatal-halts.md— повний каталог діагностик, зокрема перелічені вище зупинки диспетчеризації шляхів.