Матриця розгортання шаблонів
Довідник із розгортання шаблонів — повна матриця
DSL Aggrega підтримує розгортання шаблонів Go text/template (з попередньо зареєстрованою бібліотекою Sprig) у багатьох місцях YAML-сутностей. Кожне місце має власний набір доступних посилань, який визначається тим, коли дані стають конкретними під час компіляції. Ця сторінка є довідником щодо того, на що і де можна посилатися.
1. Дерево часу конвеєра (коли дані стають конкретними)
Щоб зрозуміти, які посилання доступні, слід зрозуміти, коли розв’язується кожна частина даних. Етапи нижче наведено в порядку їх виконання, і кожен названо за тим, що він робить, — саме цією назвою решта сторінки на нього посилається:
Resolution — resolver and syntax validator ├── .parameters → Interpolated into the Aggregate's text; the merged map │ then stays readable to path templates only ├── .values → schema-validated against the Component's pillar schema, concrete ├── .infra → Release-merged into target components/features, concrete └── Catalog entities → Resolved (extends merged, pillar schemas composed, usesSchema extracted)
Topology construction ├── .context.instance_id → Node identity, written as a name (e.g., "data-layer-zdmain-db") └── .context.labels → From Catalog + label-transform mutations
Graph finalization ├── .context.annotations.release → Cascaded from boundary hierarchy ├── .context.annotations.catalog → From Component metadata.annotations ├── .context.annotations.aggregate → Cascaded from subsystem hierarchy └── feature_values_mapping → 5-Tier Onion Model normalized
Rendering begins. Provides evaluation — locals preamble, then provides ├── .context.rendered_name → Asked of each node's provider before the preamble; present only where │ that provider derives a name for the node's output ├── .locals (per node) → Block resolved in author order; an entry reads earlier siblings └── .provides (all nodes) → Self-contained templates evaluated (any order), reading .locals
Inject hydration — self-inject resolution └── component.inject → value: literals expanded, from: own provides resolved
Inject hydration — uses-inject resolution └── uses[].inject → from: target provides resolved
Inject mapping — injectMapping interception └── .context.inject → Fully populated pipe, intercepted by FeatureRecipe injectMappings
Base rendering └── Full template context → Everything available
The plugin pipeline — post-render mutation └── Full template context + .steps → Inter-step pipeline outputs available2. Матриця розгортання шаблонів
Кожне місце в DSL, де обчислюються вирази шаблонів Go, і точний перелік доступних посилань:
| # | Location | Сутність | Де обчислюється | Доступні посилання |
|---|---|---|---|---|
| 1 | {{ .parameters.X }} у рядках YAML сутності Aggregate | Aggregate | Розв’язання (інтерполяція) | Лише .parameters. Усі інші дані ще не розв’язано. |
| 2 | {{ .parameters.X }} у рядках YAML сутності Release | Release | Не обчислюється | Немає. Рядки сутності Release читаються так, як записані: {{ .parameters.X }} під infra:, в анотації або як значення parameters: доходить до місця призначення як цей літеральний текст. Release надає значення параметрів (вбудована мапа parameters: і значення, завантажені через $import:, поєднуються в об’єднану мапу параметрів); їх читають рядки сутності Aggregate (#1), а також шаблони шляхів (#3). |
| 3 | Шаблони directory / subDirectory | Межа сутності Release | Рендеринг (обчислення шляхів) | .capability, .boundary_name, .parameters.X, .manifest.recipe_name, .parent_boundary.* і .component_id (лише subDirectory: — шаблон directory: його відхиляє). |
| 4 | Рядки value: в inject сутності Component | Компонент сутності Aggregate | Розв’язання self-inject | .values, .infra, .context.instance_id, .context.labels, .context.annotations.* (усі 3 групи), .metadata.* (release_name, release_version, environment, aggregate_name). ЗАБОРОНЕНО: .context.inject (циклічність — канал саме будується), .context.uses (для зв’язування між компонентами використовуйте натомість uses[].inject). Шаблон розташований у тексті сутності Aggregate, який першою читає інтерполяція параметрів із #1, тож, щоб він дійшов до цього етапу, записуйте його екранованим — value: '{{"{{"}} .metadata.release_name }}'; записаний як є, він обчислюється інтерполяцією і зупиняє збирання, оскільки текст сутності Aggregate не визначає жодного кореня, крім .parameters. |
| 5 | Рядки поля source (рядок верхнього рівня АБО рядкові підполя структурованої мапи source:) | Recipe / FeatureRecipe | Розв’язання джерела | Дві поверхні, залежно від того, що називає джерело. Віддалена координата — version, chart, ref і module_subdir структурованого блоку, що називає реєстр, репозиторій чартів або git-репозиторій, — обчислюється, коли aggrega pull розв’язує артефакт, щоб закріпити його: лише .values, .infra, .locals і статичні рядки, з власними допоміжними функціями Aggrega (optional, capitalizedWords, index) і без жодної функції Sprig, а також без кореня .context. Записи .locals, що обчислюються там, — це ті, які читають ці поля, безпосередньо або через інший запис (усі записи, якщо поле читає .locals так, що не називає жодного окремого запису), тож запис, який не читає жодне поле, лишається для рендерингу. Джерело, що називає шлях у робочому просторі, обчислюється під час рендерингу сутності: .context.instance_id, .values, .infra, .locals (увесь розв’язаний блок сутності, що оголошує), статичні рядки. Там джерело FeatureRecipe додатково читає .attachment_name — розв’язується саме приєднання, — а його .context.instance_id називає компонент-хост, поряд із .context.rendered_name, повідомленою назвою компонента-хоста (див. #9); FeatureRecipe рівня межі читає .boundary.* і жодного з покомпонентних стовпів. ЗАБОРОНЕНО на обох: .context.inject, .context.uses, .provides (інваріант самодостатності — поверхня джерела з робочого простору ділить контекст із власними locals сутності, що оголошує, тож обидві приймають і відхиляють ті самі посилання, а віддалена координата читає підмножину цього контексту; розв’язання джерела має завершитися до наповнення каналу топології і до завантаження будь-якого чарту, модуля чи тіла артефакту). |
| 6 | Шаблони provides сутності Recipe | Recipe | Обчислення provides | .context.instance_id, .context.rendered_name (назва, яку провайдер вузла дає виводу, що він рендерить для вузла, — з джерела, наданого автором, або з робочого навантаження, яке він синтезує; читання її на вузлі, провайдер якого не повідомляє такої назви, зупиняє збірку — див. Іменування відрендереного ресурсу), .values, .infra, .locals (увесь розв’язаний блок вузла — locals розв’язуються в преамбулі цього етапу, перед provides), статичні рядки. ЗАБОРОНЕНО: усі інші корені — .context.inject, .context.uses (між вузлами), .context.annotations.*, .context.labels, .context.metadata, .metadata.* (пов’язані з розміщенням/розгортанням) і .attachment_name (під час обчислення provides базової сутності Recipe жодне приєднання не розв’язується). Перевірка — це позитивний список дозволених: посилання на будь-який корінь, якого контекст provides не надає, зупиняє збірку (інваріант самодостатності — дає змогу паралельного обчислення без топологічного сортування). .locals.<key>, що називає ключ, не оголошений у блоці locals, теж зупиняє збірку, оскільки цей стовп — відкрита мапа з ключами, яку сама лише перевірка коренів не може контролювати. |
| 7 | valuesMapping сутності Recipe (вбудований, файловий $import: або бібліотечний $import:) | Recipe | Базовий рендеринг | Повний контекст шаблону: .values, .infra, .context.* (instance_id, rendered_name, labels, annotations, inject, uses), .locals, .provides, .features, .metadata. Вбудоване посилання .context.rendered_name зупиняє збірку на вузлі, провайдер якого не повідомляє такої назви, як у #6; посилання всередині тіла, завантаженого через $import:, не перевіряється і на такому вузлі рендериться порожнім. |
| 8 | injectMapping сутності FeatureRecipe | FeatureRecipe | Відображення inject | Повний контекст шаблону: .values, .infra, .context.* (зокрема .context.inject — канал, що перехоплюється, — і .context.uses). .context.used_by тут порожній: вивід відображення потрапляє у власний канал доставки хоста. .context.render_facts відсутній: відображення виконується до рендерингу хоста. .context.rendered_name — повідомлена назва компонента-хоста, як у #9; відображення, що її читає, не перевіряється і рендерить її порожньою на хості, провайдер якого її не повідомляє. Контекст той самий за будь-якого executionScope сутності FeatureRecipe: відображення FeatureRecipe з областю межі виконується один раз для кожного компонента, якого досягає приєднання, читає .context.* цього компонента, а .features.<attachment>.provides і .locals читає як результат єдиного обчислення для межі. ЗАБОРОНЕНО: .boundary, якого не містить контекст жодного компонента, — посилання на нього зупиняє збирання. |
| 9 | valuesMapping сутності FeatureRecipe (а також його workload: і artifacts:) | FeatureRecipe | Базовий рендеринг | Повний контекст шаблону + .attachment_name, .inject (власні записи inject: приєднання, якщо приєднання задає блок inject:), .context.render_facts — те, що провайдер хоста повідомив про рендеринг хоста, — і .context.used_by — компоненти, що використовують хост, кожен із власними фактами рендерингу, якщо FeatureRecipe задає readsCallerRenderFacts: true. Кожне з’єднання в .context.uses несе факти рендерингу своєї цілі в .render_facts, якщо FeatureRecipe задає readsTargetRenderFacts: true. .context.instance_id і .context.rendered_name — ідентичність компонента-хоста і назва, яку для нього повідомляє власний провайдер хоста, — те саме значення, яке читає Recipe хоста, також у locals: і provides: сутності FeatureRecipe, — а вбудоване посилання на .context.rendered_name зупиняє збірку на хості, провайдер якого не повідомляє такої назви. .source — це власне обчислене source: сутності FeatureRecipe, ніколи не компонента-хоста, і воно нічого не містить, якщо сутність FeatureRecipe його не оголошує. |
| 10 | Блоки with: конвеєра | Recipe / FeatureRecipe | Конвеєр плагінів | Повний контекст шаблону + .steps (проміжні виводи попередніх кроків конвеєра). .context.used_by тут порожній, і жодне з’єднання в .context.uses не несе факти рендерингу своєї цілі: крок може переписувати власні документи хоста. Крок приєднаної FeatureRecipe читає .context.render_facts, власні факти рендерингу хоста, як і #9. |
| 11 | Тіло workload: сутності Recipe (кожне шаблонне поле всередині, вбудоване чи завантажене через $import:) | Recipe | Базовий рендеринг | Повний контекст шаблону. Кожне поле всередині тіла Workload — replicas, containers.<name>.image, containers.<name>.variables.<KEY>, containers.<name>.ports.<port>, services.<name>.ports.<port>, volumes.<name>.*, health.* — є частиною того самого обчислення шаблону, що опрацьовує весь рядок Workload. Вміст Workload — це єдиний шаблон Go, що обчислюється один раз щодо повного контексту шаблону; шаблони рівня полів усередині розв’язуються в тому самому обчисленні, а не в окремому. |
Примітка щодо самодостатності. Рядки source (#5) поділяють інваріант самодостатності provides (#6): обидві поверхні відхиляють посилання .context.inject і .context.uses. Розв’язання джерела виконується до гідратації inject, яка заповнює .context.inject, і до того, як будь-що далі за конвеєром використає розв’язане джерело, тож правило та його обґрунтування поширюються на обидві поверхні. Відмінність між ними — стовп provides: source у робочому просторі поділяє контекст із locals сутності, що його оголошує, а віддалена координата читає підмножину цього контексту, тому обидві відмовляють .provides, тоді як provides сам є поверхнею, що розв’язується. Обидві читають .locals. Правило поширюється на source сутності FeatureRecipe на тих самих умовах, що й на сутність Recipe, і кожну перевіряють щодо власної поверхні locals цієї сутності.
Примітка щодо шаблонів у тілі Workload (#11). Тіло Workload — це один шаблонний рядок, який рендерер обчислює цілком, а потім розбирає результат як документ Workload. Шаблони на рівні полів усередині (тут replicas: {{ .infra.replicas | default 1 }}, там LOG_LEVEL: "{{ .values.log_level }}" усередині containers.app.variables) не є окремими місцями обчислення шаблонів — усі вони беруть участь у єдиному обчисленні базового рендерингу, яке створює Workload. Авторам не потрібне окреме правило доступності для внутрішніх полів Workload; правило для Workload загалом (#11) охоплює кожен шаблон на рівні полів усередині.
Запасне значення з урахуванням дискримінатора в тілі Workload. Наведений вище приклад replicas: {{ .infra.replicas | default 1 }} змішує випадки «автор не задав replicas» і «автор задав replicas рівним 0» — default спрацьовує в обох. Коли сутність Release правомірно задає infra.replicas: 0, щоб виразити масштабування до нуля (поширений патерн Knative / KEDA), форма | default 1 непомітно перекриває цей намір. Форма з урахуванням дискримінатора — replicas: {{ optional .infra "replicas" 1 }}: optional перевіряє наявність ключа й повертає задане автором значення (зокрема заданий нуль), коли ключ задано, і повертається до 1 лише тоді, коли ключа немає. Повну семантику та рекомендації щодо того, коли якій формі надавати перевагу, див. у sprig-functions.md.
3. Заборонені посилання та обґрунтування
| Location | Заборонене посилання | Обґрунтування |
|---|---|---|
inject value: сутності Component (#4) | .context.inject | На цьому етапі конвеєр inject ще будується — шаблон self-inject value: не може читати з конвеєра, до якого сам додає дані. |
inject value: сутності Component (#4) | .context.uses | Зв’язування між компонентами розміщується в uses[].inject. Шаблони self-inject value: компонента замкнені на власних даних компонента. |
provides сутності Recipe (#6) | .context.inject | Шаблони provides обчислюються в будь-якому порядку й замкнені лише на власних даних вузла (.values, .infra, .locals, .context.instance_id, .context.rendered_name). Конвеєр inject не заповнюється до гідратації inject, яка виконується після обчислення provides кожного вузла. |
provides сутності Recipe (#6) | .attachment_name | Прохід provides базової сутності Recipe не розв’язує жодного приєднання, тож ім’я було б порожнім. Корінь відхиляється, а не передається порожнім. |
source (#5) | .provides | Жодна з поверхонь джерела не має стовпа provides: поверхня джерела робочого простору поділяє контекст із власними locals сутності, що її оголошує, де його немає, а віддалена координата читає підмножину цього контексту. Locals розв’язуються раніше за provides, щоб provides: міг читати .locals; шаблон джерела читає ті самі locals, а не звертається назад до provides. |
locals сутності Recipe (преамбула #6) | .provides | Locals розв’язуються до provides, тож власних provides вузла ще не існує, коли обчислюється локальне значення. Локальне значення, якому потрібне значення, яке також публікують provides, обчислює його безпосередньо з .values / .infra, а запис provides потім читає це локальне значення. |
locals сутності Recipe (преамбула #6) | .context.rendered_name | Locals сутності Recipe поділяють контекст із її шаблоном source (#5), а ця поверхня не надає імені: те, чи постачає вузол джерело, що вирішує шаблон source, — одна з речей, від яких залежить ім’я. Посилання зупиняє збірку діагностикою невідомого кореня, яка вказує .context.instance_id як те, що .context визначає там. Натомість читайте цей ключ у записі provides або в шаблоні етапу базового рендерингу. |
provides сутності Recipe (#6) | .context.uses | .context.uses посилається на provides інших вузлів, а обчислення provides виконує їх у довільному порядку. Шаблони provides залишаються самодостатніми, щоб обчислення не залежало від порядку. |
locals, provides, source (#5) та вбудовані шаблони рендерингу (#9, #10) сутності FeatureRecipe на хості, provider якого не повідомляє імені | .context.rendered_name | У приєднанні Feature ключ містить повідомлене ім’я компонента-хоста, а хост, який розміщує лише набір артефактів або рендерить через provider, що не виводить такого імені, не має що передати. Посилання зупиняє збірку діагностикою невідомого кореня, яка вказує .context.instance_id серед того, що .context визначає там; натомість читайте ідентифікатор, за яким на такому хості названо власні ресурси хоста. |
source (#5) | .context.inject | Розв’язання джерела виконується до гідратації inject, яка заповнює .context.inject. Коли обчислюється URI джерела, конвеєр ще не заповнено. |
source (#5) | .context.uses | Розв’язання джерела має завершитися до того, як будь-що далі за конвеєром завантажить чарт, модуль або тіло артефакту сутності, що його оголошує. Дозвіл посилань між вузлами пов’язав би розв’язання джерела з порядком обходу топології, чого воно навмисно уникає. |
| Параметри (усюди, крім шаблонів шляхів) | Будь-яка поверхня шаблонів значень після інтерполяції | Інтерполяція споживає кожне посилання {{ .parameters.X }} в авторському YAML і записує на його місце розв’язане значення, тож поверхня шаблонів значень отримує розв’язаний літерал, а не стовп параметрів. Шаблони шляхів, написані оператором, — єдиний виняток: вони читають .parameters.X безпосередньо. |
4. Шлях розв’язання self-inject
Розв’язання self-inject — перша половина гідратації inject, і воно виконується після обчислення provides кожного вузла. Коли компонент оголошує блок inject: на рівні компонента, компілятор обчислює його на цьому етапі:
- Літеральні рядки
value:: якщо значення містить вирази шаблонів Go, компілятор обчислює їх із контекстом із рядка #4 матриці (.values,.infra,.context.instance_id,.metadata.*тощо), записаними в екранованому вигляді, як показано в рядку #4. Звичайні рядки проходять без змін. - Посилання
from:: компілятор шукає ключ у власному словникуprovidesвузла, на той момент уже розв’язаному. Якщо ключа немає, компілятор зупиняє збірку з помилкою недійсного ключа inject. - Перевірка колізій: перед злиттям у конвеєр
.context.injectкомпілятор перевіряє, що жоден ключ не збігається з ключами uses-inject, які розв’язує друга половина гідратації inject. Колізії зупиняють збірку з помилкою дубльованого ключа доставки.
Отримані рядки зливаються в .context.inject.env, .context.inject.file, .context.inject.arg (та будь-які власні механізми) разом із результатами розв’язання uses-inject. На момент запуску inject mapping (injectMapping) конвеєр містить усі задані розробником значення inject з обох джерел.