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

Шаблонний контекст параметрів

Стовп parameters: містить значення параметрів, надані сутністю Release і перевірені за контрактом. Їхню доступність визначають дві паралельні ментальні моделі:

  • Поверхні шаблонів значень (рядки values: компонентів / функцій / вкладених агрегатів усередині сутності Aggregate, а також valuesMapping сутності Recipe, injectMapping і provides сутності FeatureRecipe, тіла сутностей Workload) споживають значення параметрів як уже інтерпольовані літерали. Прохід інтерполяції під час розв’язання обчислює весь текст сутності Aggregate як шаблон і замінює кожне посилання {{ .parameters.<slot> }} розв’язаним значенням; подальші поверхні шаблонів значень ніколи не бачать .parameters безпосередньо у своєму контексті шаблону.
  • Поверхні шаблонів шляхів (шаблони directory: і subDirectory:, які пише оператор, на межах сутностей Release) читають .parameters.<slot> безпосередньо під час обчислення шаблонів шляхів на етапі рендерингу. Об’єднана мапа параметрів лишається доступною для читання до кінця рендерингу, щоб шаблон шляху міг читати .parameters відповідно до закритого списку дозволених змінних.

Асиметричний доступ — шаблони шляхів читають .parameters безпосередньо, а шаблони значень ні — дає кожному рівню володіти тим, що йому потрібно: values: на боці розробника передають шаблонам значень уже розв’язані дані, специфічні для середовища; шаблони шляхів на боці оператора посилаються на параметри регіону / середовища / ідентифікатора облікового запису без проходження через схему values сутності Aggregate.

На цій сторінці описано прохід інтерполяції, форми значень для кожного слота, шаблони доступу всередині рядків YAML сутності Aggregate, виняток для шаблонів шляхів, а також те, як довго об’єднана мапа лишається доступною для читання. Загальну форму шаблонного контексту Recipe / FeatureRecipe (.values, .infra, .uses тощо) див. у template-context-contract.md. Доступність у кожному місці шаблону на всьому конвеєрі компіляції див. у expansion-matrix.md. Форму оголошення контракту типізованих параметрів у сутності Aggregate див. у entities/aggregate.md §«Typed parameter contracts». Список дозволених змінних шаблонів шляхів, що містить .parameters.<slot> під час обчислення directory: / subDirectory: на межі, див. у path-template-variables.md.

Життєвий цикл параметрів

Компілятор розв’язує параметри у чотири впорядковані фази:

  1. Читання контракту — блок spec.parameters: сутності Aggregate перевіряється сам по собі ще до того, як розглядається будь-яке значення з Release, тож слот, який не може нічого обмежити, зупиняє збирання навіть тоді, коли жоден Release його не надає. Від’ємне значення minLength або maxLength у власному оголошенні параметра відхиляється під час завантаження Aggregate із зазначенням параметра й ключа. Кожен pattern — як у самому слоті, так і в будь-якому вкладеному контракті під items, properties або valuesType — компілюється як регулярний вираз, а той, що не компілюється, відхиляється із зазначенням параметра, шаблону й причини. Обмеження довжини у вкладеному контракті не підлягає цій нижній межі; див. entities/aggregate.md.
  2. Заповнення типовими значеннями — слоти, для яких визначено default: і немає значення, наданого Release, отримують своє типове значення. На цьому етапі мапа .parameters перебуває в області видимості.
  3. Валідація контракту параметрів — кожне значення в об’єднаній мапі, незалежно від того, чи його надав Release, чи заповнив default:, перевіряється на відповідність оголошеним в Aggregate обмеженням spec.parameters.<slot>: type / enum / min / max / pattern / вкладена структура; pattern зіставляється з виразом, скомпільованим під час читання контракту. Мапа .parameters існує в контексті валідатора в пам’яті як структуроване корисне навантаження, що перевіряється.
  4. Інтерполяція — компілятор обчислює весь текст Aggregate як шаблон, ще до читання його як YAML, і замінює кожне посилання {{ .parameters.<slot> }} розв’язаним значенням; будь-яке інше {{ у тексті також читається як синтаксис шаблону, тож значення, що містить власні подвійні фігурні дужки, записує кожне {{ як {{"{{"}} (див. Текст, що містить власні подвійні фігурні дужки). Інтерполяція — це шлях підстановки для поверхонь шаблонів значень: після цього проходу контексти шаблонів значень більше не містять .parameters; вони використовують розв’язані значення, записані в навколишні рядки values:. Об’єднана мапа залишається доступною для читання після інтерполяції, протягом усього рендерингу, саме для підтримки обчислення шаблонів шляхів. Час, протягом якого її можна читати, обмежений часом збирання: компілятор передає розв’язане представлення компіляції, яка його використовує, а не повертає його викликачеві, тож ніщо поза цим збиранням не може дістатися до мапи. Поверхня шаблонів шляхів (directory: / subDirectory: у Release) читає .parameters.<slot> під час рендерингу відповідно до закритого списку дозволених змінних, описаного в path-template-variables.md.

Шаблони в рядках YAML сутності Aggregate (values: компонента, values: функції, вирази наскрізної передачі parameters: підагрегата) читають мапу .parameters за допомогою стандартного синтаксису шаблонів Go під час проходу інтерполяції. Шаблони у файлах Recipe та FeatureRecipe НЕ отримують .parameters у своєму контексті шаблону (контракт для кожної поверхні див. нижче в розділі «Межа з подальшими контекстами шаблонів»).

Текст, що містить власні подвійні фігурні дужки

Оскільки весь текст є шаблоном, подвійні фігурні дужки, що належать значенню, а не шаблону, також читаються як дії шаблону. Типовий випадок — визначення flow-платформи, передане у values: компонента: n8n обгортає кожен вираз у параметрах вузла подвійними фігурними дужками, як-от ={{ $json.body.message }}, промпт Flowise називає змінну як {{question}}, а чатфлоу Flowise записує {{chatOpenAI_0.data.instance}} для кожного з’єднання між двома вузлами, а експорт Langflow містить вихідний код своїх компонентів, де дужки також можуть траплятися. Якщо записати їх в Aggregate як є, вони зупиняють збірку на Aggregate з E0158, описаною під заголовком «A {{ .parameters.* }} reference cannot be interpolated (Посилання неможливо інтерполювати)» на сторінці Фатальні зупинки; її причина називає рядок і перший токен, який рушій шаблонів не зміг прочитати, — undefined variable "$json" для виразу n8n. Коментар YAML також є текстом шаблону, тож {{, записані в коментарі, зупиняють збірку так само.

Записуйте кожні {{ у такому значенні як {{"{{"}}. Це дія шаблону, результатом якої є рядок {{, тож інтерполяція повертає дві дужки на місце. Закривні }} не потребують нічого, бо поза дією це звичайний текст. Інтерполяція виконується один раз, над текстом Aggregate, а шаблон Recipe записує прочитане з .values як дані, тож відновлені дужки потрапляють у результат рендерингу такими, якими їх було експортовано.

# Aggregate fragment — an n8n workflow definition carried as exported
spec:
components:
automation:
type: core/ai-agent/n8n
values:
workflow_id: support-reply
flow_definition: |
{
"name": "Support reply",
"nodes": [
{
"name": "Set reply",
"type": "n8n-nodes-base.set",
"parameters": {
"value": "={{"{{"}} $json.body.message }} for {{"{{"}} $env.SUPPORT_TEAM }}"
}
}
],
"connections": {}
}

Платформа отримує "value": "={{ $json.body.message }} for {{ $env.SUPPORT_TEAM }}".

Зберігайте таке визначення в блоковому скалярі (|), як показано вище, де лапки екранування є звичайними символами. Текст Aggregate також читається як YAML перед інтерполяцією, а всередині YAML-рядка в подвійних лапках символ " екранування закриває рядок, тож файл більше не розбирається, і збірка зупиняється з помилкою YAML.

Шаблон доступу .parameters.<slot>

Кожен оголошений слот параметра доступний як поле мапи .parameters. Доступ із коректним типом відповідає оголошеному type:

# Aggregate fragment — parameter declarations
spec:
parameters:
region: { type: string, enum: [us-east-1, us-west-2] }
cache_ttl_seconds: { type: integer, min: 1, max: 86400, default: 60 }
enable_debug: { type: boolean, default: false }
components:
web:
type: core/web-server:1.0.0
values:
region: "{{ .parameters.region }}" # string
cache_ttl_seconds: {{ .parameters.cache_ttl_seconds }} # integer
debug: {{ .parameters.enable_debug }} # boolean

Прохід інтерполяції виконує обчислення шаблону Go над мапою .parameters; результат замінює вираз шаблону безпосередньо в документі. Потім схема values: сутності Component / Feature перевіряє отримане значення на етапі перевірки схеми після інтерполяції під час розв’язання.

Лапки визначають піднятий тип

Беріть у лапки посилання, спрямоване на рядковий лист; залишайте його без лапок для будь-якого іншого оголошеного типу. Це правило самого YAML, а не додане Aggrega: інтерполяція підставляє виконане значення в байти документа й нічого більше не робить, тож наступний розбір читає результат так само, як будь-який інший скаляр. Посилання без лапок {{ .parameters.cache_ttl_seconds }} несе власний тип виконаного значення, і саме це дає змогу цілочисловому параметру потрапити в цілочисловий лист, а булевому — в булевий. Посилання в лапках "{{ .parameters.cache_ttl_seconds }}" несе рядок, і лист, оголошений як integer або boolean, його відхиляє: написане значення не проходить схему values: своєї сутності Component або Feature за типом, і діагностика називає невідповідність типу, а не будь-яке обмеження простору значень, якому рядок також не відповідав би.

Посилання, що ділить свій скаляр з іншим текстом, є рядком незалежно від того, як його записано, бо документ після підстановки має один скаляр для читання — image: app:{{ .parameters.tag }} дає app:1.4.0. Саме до цієї форми слід вдаватися, коли нерядковий параметр має потрапити в рядковий лист.

Доступ до слотів типу object і array

Слоти параметрів типу object надають свої оголошені властивості як вкладені поля мапи .parameters.<slot>. Слоти типу array надають семантику зрізів шаблонів Go (range, index, len).

# Aggregate fragment — object-typed parameter
spec:
parameters:
database_config:
type: object
properties:
host: { type: string, required: true }
port: { type: integer, min: 1, max: 65535, default: 5432 }
ssl_mode: { type: string, enum: [disable, require, verify-full] }
components:
api:
type: core/compute/api:1.0.0
values:
db_host: "{{ .parameters.database_config.host }}"
db_port: {{ .parameters.database_config.port }}
db_ssl: "{{ .parameters.database_config.ssl_mode }}"

Слоти параметрів типу array підтримують ітерацію через range:

# Aggregate fragment — array-typed parameter
spec:
parameters:
allowed_hosts:
type: array
items: { type: string, format: hostname }
min: 1
components:
ingress:
type: core/ingress:1.0.0
values:
# Compose a comma-separated list from the parameter array
hosts: "{{ range $i, $h := .parameters.allowed_hosts }}{{ if $i }},{{ end }}{{ $h }}{{ end }}"

Кожен елемент, який надає сутність Release, перевіряється на відповідність контракту items до інтерполяції, тож значення, що не є іменем хоста, — наприклад, *, — зупиняє збірку із зазначенням параметра, елемента та формату. Імена, які приймає format, і те, що кожне з них перевіряє, наведено в vocabulary/compact-form-authoring.md.

Під час інтерполяції доступна бібліотека шаблонів Sprig, яка надає допоміжні функції, як-от join, для компактного перетворення масивів на рядки:

hosts: "{{ join `,` .parameters.allowed_hosts }}"

Семантика заповнення типовими значеннями

Слот параметра з оголошенням default: отримує своє типове значення, коли сутність Release пропускає цей слот. Типове значення застосовується до запуску проходу перевірки контракту, тож перевірка бачить розв’язане значення (надане сутністю Release або типове):

# Aggregate
spec:
parameters:
timeout_seconds:
type: integer
min: 1
max: 300
default: 30
components:
api:
type: core/compute/api:1.0.0
values:
timeout: {{ .parameters.timeout_seconds }}
# Release omits timeout_seconds — interpolation uses default: 30
# Release supplies timeout_seconds: 60 — interpolation uses 60
# Release supplies timeout_seconds: 0 — validation rejects (below min: 1)
# Release supplies timeout_seconds: 500 — validation rejects (above max: 300)
# Release supplies timeout_seconds: "thirty" — validation rejects (type mismatch)

Слот, позначений required: true і без default:, спричиняє помилку під час збирання, коли сутність Release його пропускає (E0165). Помилка називає слот і його розташування в контракті, щоб автор міг це виправити. Слот, який не має ні required: true, ні default:, є необов’язковим: якщо його пропущено, кожне посилання на нього інтерполюється як порожнє, а результат потім оцінює схема values: сутності Component.

Параметри з вкладеними об’єктами

Коли параметр оголошує type: object із properties:, дочірні елементи яких самі мають значення default:, три випадки авторування дають різні результати. Розуміти цю різницю важливо, коли оголошення параметра є структурованим об’єктом — конфігурацією бази даних, набором прапорців функцій, політикою тайм-аутів і повторних спроб, — а не окремим скалярним значенням.

Випадок 1 — Release пропускає батьківський слот. Заповнюються типові значення дочірніх елементів із контракту. Автор сутності Aggregate, який оголосив вкладені типові значення, отримує задуману поведінку: коли ops не надає слот, конфігурація використовує задокументовані типові значення.

# Aggregate
spec:
parameters:
database:
type: object
properties:
host: { type: string, default: "localhost" }
port: { type: integer, default: 5432 }
# Release (parent omitted)
spec:
parameters: {}
# Resolved at template-interpolation time
parameters:
database:
host: "localhost"
port: 5432

Випадок 2 — Release задає батьківський елемент як явну порожню мапу. Явне порожнє значення враховується як навмисна відмова. Типові значення дочірніх елементів НЕ заповнюються; слот лишається порожнім. Використовуйте цю форму, коли ops хоче придушити вкладені типові значення контракту, не надаючи перевизначень, — наприклад, коли подальший споживач очікує, що слот присутній, але порожній.

# Release (parent explicit empty)
spec:
parameters:
database: {}
# Resolved at template-interpolation time
parameters:
database: {}

Відмінність від випадку 1 навмисна: ops може виразити і «використати типові значення» (пропустивши слот), і «придушити типові значення» (задавши слот як {}). Це відповідає тому, як Aggrega обробляє явний null в анотаціях: анотація, задана як aggrega.ai/<key>: null, є навмисною відмовою, відмінною від повного пропуску анотації.

Випадок 3 — Release частково задає батьківський елемент. Дочірні елементи, які надала сутність Release, отримують задані значення; дочірні елементи, яких сутність Release не надала, заповнюються типовими значеннями.

# Release (partial)
spec:
parameters:
database:
host: "db.prod.example.com"
# Resolved at template-interpolation time
parameters:
database:
host: "db.prod.example.com" # Release-supplied
port: 5432 # filled from default

Це типовий випадок для авторів сутностей Release, які хочуть перевизначити вибрані поля, залишивши решту з типовими значеннями контракту.

Коли використовувати кожну форму

  • Пропустіть слот, коли хочете, щоб застосувалися типові значення контракту.
  • Задайте {}, коли навмисно хочете, щоб слот був присутній, але порожній, — коли типові значення контракту не підходять для вашого середовища, а перевизначень у вас немає.
  • Задайте частково, коли хочете деякі перевизначення, а для решти — типові значення контракту.

Автор сутності Release, який пише database: {}, очікуючи «дайте мені типові значення», буде здивований: розв’язане значення порожнє, а не заповнене типовими значеннями. Щоб отримати типові значення, повністю пропустіть слот.

Вибір між трьома випадками відбувається окремо для кожного сусіднього елемента на кожному рівні вкладеності. Батьківський елемент, заданий як { connection: {}, other_field: "x" }, дає розв’язане дерево, у якому connection порожній (випадок 2 на глибині 1), а other_field має значення, надане сутністю Release (випадок 3 на глибині 0), — випадки визначаються незалежно для кожного сусіднього елемента, а не одним рішенням для всього піддерева.

Межа з подальшими контекстами шаблонів

Асиметричний доступ — шаблони шляхів читають .parameters безпосередньо, шаблони значень — ні — є ключовою відмінністю на цій межі. Семантика межі для кожної поверхні:

  • Шаблон values: компонента в сутності Aggregate, що містить {{ .parameters.X }}, коректно розв’язується під час інтерполяції. Розв’язаний літерал записується безпосередньо в рядок YAML.
  • Шаблон valuesMapping: у сутності Recipe, що містить {{ .parameters.X }}, є поверхнею шаблону значень; контекст шаблону не містить .parameters. Автори, яким потрібна варіативність залежно від середовища у valuesMapping:, виражають її через шлях споживання розв’язаного .values.<key>: сутність Aggregate оголошує параметр, посилається на нього з values: сутності Component, сутність Release його заповнює, і значення після інтерполяції передається до сутності Recipe.
  • Шаблон injectMapping:, provides: або pipeline.with: у сутності FeatureRecipe є поверхнею шаблону значень; так само, як valuesMapping: у сутності Recipe. .parameters немає в контексті шаблону.
  • Шаблон тіла Workload (вміст workload: усередині сутності Recipe) є поверхнею шаблону значень; так само.
  • Шаблон шляху (directory: / subDirectory: межі сутності Release) є винятком. Контекст шаблону шляху містить .parameters.<slot> відповідно до закритого списку дозволених; посилання розв’язуються, коли рендеринг розміщує вивід кожної межі. Повну матрицю змінних шаблонів шляхів див. у path-template-variables.md.

Межа володіння чотирма доменами зберігається завдяки тому, яка поверхня отримує параметри, а не тому, чи існує мапа параметрів у пам’яті на певному етапі конвеєра. Шаблони шляхів створюють і контролюють оператори; надання їм прямого доступу до параметрів утримує операторські питання (розміщення артефактів залежно від середовища) в межах операторської поверхні. Шаблони значень створюються в каталогах; заборона прямого доступу до параметрів зберігає слабку зв’язаність авторингу на боці каталогу з контрактом Aggregate-as-Single-Source-of-Truth.

Об’єднана мапа параметрів залишається доступною для читання, доки не завершаться всі фази рендерингу, і не довше: вона доступна лише з тієї компіляції, для якої її було розв’язано, тож час її життя обмежений часом життя збірки.

Перехресне з’єднання стовпів

Під час розв’язання параметри інтерполюються в навколишні рядки значень. Інтерпольовані значення можуть потрапити в будь-який стовп, який сутність Aggregate задає у своїй області: рядки values: компонентів, рядки values: функцій, наскрізні оголошення parameters: вкладених агрегатів (де значення параметра батьківської сутності Aggregate розв’язується, а потім передається в слот параметра дочірньої сутності Aggregate), а також рядки метаданих name: / labels:.

З’єднання однонапрямлене: значення параметра передається з наданого сутністю Release (або взятого за замовчуванням) .parameters.<slot> у рядок YAML у місці посилання. У зворотному напрямку параметри не передаються — параметр не може прочитати поле values:, поле provides: чи вміст будь-якого іншого стовпа. Однонапрямленість є частиною гарантії контракту параметрів, що він діє лише під час компіляції.

Перехресні посилання

  • Форму оголошення контракту типізованих параметрів у сутності Aggregate описано в entities/aggregate.md §«Typed parameter contracts».
  • Ширший контекст шаблонів, який Recipes використовують під час базового рендерингу (.values, .infra, .uses, .context.* тощо), описано в template-context-contract.md.
  • Доступність полів на кожному місці шаблону в конвеєрі компіляції (які поля присутні на якому місці обчислення) описано в expansion-matrix.md.
  • Контрольний список підняття параметрів (чотири послідовні точки авторингу — оголошення в сутності Aggregate, посилання у values, заповнення в сутності Release, використання в сутності Recipe) наведено в vocabulary/data-pillars.md §«The parameter-hoisting checklist».
  • Ширший набір стовпів даних (values:, infra:, provides:, uses:, features:, locals:, parameters:) описано в vocabulary/data-pillars.md.