Контракт контексту шаблону
На цій сторінці описано представлення часу виконання, яке компілятор впроваджує в Go-шаблони сутностей Recipe і FeatureRecipe: структуру контексту шаблону, доступність кожного поля на різних етапах конвеєра компіляції, а також канонічний контракт, потрібний досвідченим авторам під час написання шаблонів, що використовують стан інших компонентів. Доступність для кожного місця шаблону (які поля присутні в якому місці обчислення) описано в expansion-matrix.md; на цій сторінці описано структуру полів та їхню семантику.
Огляд
Під час рендерингу компілятор збирає контекст шаблону для кожного вузла й передає його в кожен шаблон Go, який рендерер обчислює для цього вузла. Контекст існує лише в пам’яті — він ніколи не зберігається на диск і ніколи не передається через Wasm ABI як єдине корисне навантаження. Кожне місце шаблону отримує подання того самого об’єкта контексту; деякі поля заповнюються пізно (.workload з’являється під час синтезу робочого навантаження; .source — під час розв’язання джерела; .steps заповнюється виконанням pipeline: у міру завершення кожного кроку, див. Стан мови → Фази конвеєра компіляції).
Схема для цієї структури під час виконання — template-context-v1beta1.schema.json (постачається разом із дистрибутивом схем Aggrega).
Поля верхнього рівня
Поля верхнього рівня розташовані в корені контексту шаблону — усередині шаблону до них звертаються як .field.
.values(map). Когнітивне навантаження, яке пише розробник, із сутності Aggregate. Значення окремих компонентів передаються в це поле відрендереної сутності Recipe. Під час розв’язання перевіряється заschema:каталогу (оголошенням JSON Schema 2020-12 сутності Component або Feature). Коли записане значення поля — нуль, порожнє чи false — семантично відрізняється від відсутності поля, використовуйтеoptional(див.sprig-functions.md), а неdefault..infra(map). Фізичні розміри, які пише команда експлуатації, із сутності Release. Під час розв’язання перевіряється заschema:каталогу (оголошенням JSON Schema 2020-12 сутності Component або Feature). Застосовується та сама порада щодоoptionalіdefault, що й для.values: віддавайте перевагуoptional, коли записаний нуль або false є легітимним наміром (масштабування до нуля, без повторних спроб, вимкнений прапорець функції)..locals(map зі значеннями-рядками). Приватний стан сутності Recipe — імена, оголошені в блоціlocals:сутності Recipe, розв’язані в преамбулі locals і опубліковані в цей стовп під час розв’язання джерела. Записи розв’язуються в авторському порядку, і запис може читати сусідній запис, визначений вище, тож порядок має значення скрізь, де один запис читає інший. Доступні лише в шаблонах самої сутності Recipe; ніколи не відкриваються викликачам..provides(map зі значеннями-рядками). Публічні вихідні рядки сутності Recipe — контракт, щодо якого блокиinject:викликачів розв’язують посиланняfrom:. Заповнюється під час обчислення provides..features(map прикріплень). Перебирає Features, прикріплені до цієї сутності Component (на рівні Aggregate, на рівні підсистеми, на рівні Release і за анотаціями Manifest, згідно з 5-рівневою моделлю цибулини), з ключами за іменем екземпляра, яке автор дав прикріпленню. Кожен запис має ті самі поля — див. форму прикріплення нижче. Прикріплення, записане на одному зі з’єднань сутності Component, до них не входить: його читають у цьому з’єднанні, за адресою.context.uses.<alias>.features.<slot>, тож шаблон, що перебирає.features, бачить лише власні прикріплення сутності Component..metadata(struct). Ідентичність сутності Release для детермінованого іменування:release_name,release_version,environment,aggregate_name. Заповнюється для кожного рендерингу; значення походять із блокуmetadata:сутності Release..source.source:сутності Recipe, розв’язане обчисленням шаблону розв’язання джерела.nilдля Recipes без джерела;nilдо виконання розв’язання джерела. У шаблонах сутності FeatureRecipe це власнеsource:цієї сутності FeatureRecipe, ніколи не компонента-хоста, — див. Інструмент вкладення FeatureRecipe..workload. Розібраний об’єкт Workload, що заповнюється, щойно відрендерений документworkload:декодовано і він пройшов перевірку, яка його допускає: схему Workload,featuresSchemaсутності Component для кожного прикріплення, оголошеного її контейнерами, і розв’язуваність того, на що посилається кожне прикріплення.nilдля несинтезованих Recipes;nilдо виконання синтезу workload..steps(map виходів кроків). Заповнюється виконаннямpipeline:у міру роботи плагінів Wasm і відкриває повернені виходи завершеного кроку наступним крокам через.steps.<id>.outputs. Крок читає виходи попереднього кроку зі свого шаблонуwith;outputsкроку стають видимими лише крокам, оголошеним після нього. Порожнє, коли вузол не оголошує конвеєра, і до завершення першого кроку вузла.
Поле верхнього рівня, яке для цього вузла нічого не містить, — .workload у сутності Recipe, яка нічого не синтезує, .source у сутності Recipe без джерела, .features у сутності Component без приєднань, — у шаблоні значень читається як порожнє, точно так само, як невстановлений ключ у .values: {{ .workload }} нічого не рендерить, default над ним підставляє своє резервне значення, а if чи with над ним переходить до гілки false. range по ньому нічого не перебирає. Читання під ним — {{ .workload.containers }} — і далі зупиняє збирання, бо спускатися нікуди. А шаблон, який і виводить таке поле там, де він завжди виконується, — поза кожним if, with і range, — і перебирає його, зупиняє збирання, називаючи це поле, як і для будь-якого шляху, що нічого не містить і читається обома способами, бо жодне значення не виводиться як ніщо й водночас не перебирається як ніщо: див. A template reads and iterates a path that holds nothing (Шаблон читає й перебирає шлях, який нічого не містить).
Форма прикріплення
.features.<name> і .features.<slot> мають однакову форму — одне прикріплення, що читається одним способом:
.type(рядок). URI каталогу прикріпленої сутності Feature..resolved_version(рядок). Версія прикріпленої сутності Feature після розв’язання Manifest — версія, фактично зв’язана для цієї збірки, а не закріплення, повторене на боці споживача. Відповідає.context.uses.<alias>.resolved_version. Порожнє, колиtypeприкріплення не розв’язується в жодну сутність каталогу..labels(мапа рядкових значень). Мітки каталогу прикріпленої сутності Feature, передані дослівно в порядку, у якому Feature їх оголошує, — нічого не відфільтровано, не перейменовано й не позбавлено префікса, тож шаблон читає саме те, що написав автор Feature. Відповідає.context.uses.<alias>.labels. Відсутнє, коли Feature не оголошує міток, а також колиtypeприкріплення не розв’язується в жодну сутність каталогу..values(мапа). Власна опора наміру розробника для прикріплення, задана в оголошенні прикріплення в Aggregate. Відрізняється від.valuesверхнього рівня компонента-хоста..infra(мапа). Власна опора операційного розміру для прикріплення, задана в оголошенні прикріплення в Release. Відрізняється від.infraверхнього рівня компонента-хоста..provides(мапа рядкових значень). Розв’язаний публічний контракт сутності FeatureRecipe, зв’язаної з цим прикріпленням, — ім’я згенерованого ресурсу, його ключ даних, хмарна ідентичність і будь-які додаткові ключі, які публікує FeatureRecipe. Читається як.features.<name>.provides.<key>, аналогічно до.context.uses.<alias>.provides: споживач читає те, що опублікував виробник, замість того щоб виводити це заново. Прикріплення, зв’язана FeatureRecipe якого нічого не публікує, взагалі не має ключаprovides, а не порожньої мапи, тож перевіряйте його наявність, перш ніж звертатися до окремого ключа.
Саме .provides робить прикріплення придатним до споживання, а не просто присутнім. Для сутності Feature, що оголошує контракт schema.provides, цей контракт перевіряється щодо FeatureRecipe, яка її реалізує, — FeatureRecipe має опублікувати кожен оголошений ключ, — а споживач читає результат тут. Тож Feature ідентичності, яка генерує ServiceAccount і публікує його ім’я, дає змогу Recipe-споживачу зв’язатися з ним:
workload: | serviceAccount: "{{ .features.identity.provides.name }}"Згенероване ім’я вказує один раз виробник, а споживач його використовує — воно ніколи не повторюється на боці споживача, де ці два значення могли б розійтися. Приклад workload-identity-binding рендерить це від початку до кінця.
Саме .labels дає змогу шаблону адаптуватися до того, чим є прикріплення, без зіставлення за його іменем чи розбору його URI. Компілятор не читає жодної з них — він передає рядки, а автор шаблону вирішує, що вони означають.
Сутність Feature, яка не оголошує міток, взагалі не має .labels, а не порожньої мапи, тож перевіряйте наявність, перш ніж звертатися до окремої мітки, — звернення через ключ, якого немає, зупиняє збірку. Мітку, яку Feature може не оголошувати, читайте через optional, оскільки index зупиняє збірку із зазначенням ключа, коли мапа його не містить:
{{ if .features.db.labels }}{{ if eq (optional .features.db.labels "feature.aggrega.ai/kind" "") "secret" }}...{{ end }}{{ end }}Оскільки мітки надходять дослівно, власний простір імен автора каталогу доходить до шаблону незмінним, і Recipe читає той самий ключ, який оголошує Feature.
Блок .context
.context — це зібраний компілятором контекст виконання для одного вузла: дані ідентичності, топології та каналу доставки, які рендерер передає через кожне місце шаблону. Його поля:
.context.instance_id(рядок). Ідентичність вузла як ім’я — значення, яким сама збірка називає й позначає мітками те, що вона створює, тож шаблон, який складає з нього ім’я ресурсу або адресу всередині кластера, передбачає ім’я, яке збірка справді створює. Для вузла, який оголошує ваша власна сутність Aggregate, це ім’я, яке ви написали. Для вузла, який додає імпортована сутність Aggregate, це сплощена ідентичність із розділювачем модуля, записаним явно (data-layer.main-dbстаєdata-layer-zdmain-db), бо крапка не є символом, який може містити ім’я ресурсу, а в адресі кластера вона відокремлює сервіс від його простору імен. Форму з крапками використовують ваші документи та діагностика збірки, щоб звертатися до цього вузла; див. Домовленості щодо іменування..context.rendered_name(рядок). Ім’я, яке провайдер вузла дає ресурсам, що він рендерить для вузла, — з наданого вами вихідного коду, як-от ім’я релізу, яке читає чарт, і з робочого навантаження, яке він синтезує, коли називає ресурси цього навантаження власним іменем, як це робитьhelmз тим самим ім’ям релізу. Присутнє лише там, де цей провайдер його виводить. У шаблонах прикріплення Feature це ім’я компонента-хоста, так само як.context.instance_idтам є ідентичністю хоста; див. Іменування відрендереного ресурсу..context.labels(мапа рядкових значень). Мітки, задані в каталозі, плюс будь-які доповненняlabel-transform, зроблені під час побудови топології..context.annotations(три кошики, див. нижче). Каскадні анотації, згруповані за походженням..context.inject(мапа механізмів, див. нижче). Попередньо наповнений, перехоплений канал доставки — стандартна поверхня, з якої шаблони Recipe читають значення інших компонентів..context.uses(мапа з’єднань, див. нижче). JOIN-проєкція вихідних топологічних ребер..context.self_inject(мапа механізмів, див. нижче). Для кожного імені, яке розробник записав у власному блоціinject:компонента, — власний ключ provides, який доставляє цей запис, або єдине власне значення, яке читає його шаблон..context.used_by(список, див. нижче). Компоненти, записиusesяких вказують на цей. Читається сутністю FeatureRecipe, прикріпленою до компонента, у шаблонах, що створюють власні ресурси прикріплення; порожній усюди інде..context.render_facts(мапа списків, див. нижче). Те, що провайдер компонента повідомив про відрендерений ним вивід, з ключами за назвою факту. Читається сутністю FeatureRecipe, прикріпленою до компонента, у кожному з її шаблонів, що виконується після рендерингу компонента; відсутній усюди інде.
.context.annotations — три кошики
Анотації каскадно потрапляють у три кошики з ключами за походженням:
.context.annotations.release— анотації межі Release (домен 4). Використовуються для керування фізичними реаліями; рендерери спрямовують їх у поляinfra:, де це доречно. Загальновідомі анотаціїaggrega.ai/*містяться в цьому кошику..context.annotations.catalog— анотації метаданих Component із домену 2. Незмінні внутрішні риси, задані архітектором; переважно використовуються плагінами політик Wasm..context.annotations.aggregate— анотації підсистеми Aggregate з домену 1. Когнітивні метадані; рендерери спрямовують їх у корисні навантаженняvalues:, де це доречно.
Кожен кошик — плоска мапа «рядок → рядок». Згідно з правилами розділення в архітектурі, кошики призначені для різних застосувань; рушій не примушує до цього розділення, тож відповідність кошиків їхній задуманій семантиці забезпечує дисципліна авторів. Див. розділ 6 §2 Потік 5, де описано дизайн каскадних анотацій.
.context.inject — канал доставки
Канал — це попередньо розв’язана мапа доставки компілятора. На момент, коли шаблон Recipe виконується під час базового рендерингу, кожне джерело ін’єкції (задані розробником літерали самоін’єкції, посилання самоін’єкції from:, розв’язані щодо власних provides, посилання між компонентами uses[].inject, розв’язані щодо provides цілі, перехоплення injectMapping сутностей FeatureRecipe) вже розв’язане в кінцеве рядкове значення та злите в цю мапу.
Поля:
.context.inject.env— мапа рядкових значень «ім’я змінної середовища → розв’язане значення»..context.inject.file— мапа рядкових значень «шлях до файлу → розв’язане значення»..context.inject.arg— мапа рядкових значень «прапорець аргументу → розв’язане значення»..context.inject.all— мапа рядкових значень, що поєднує механізмиenv/file/arg/власні в один плоский словник; корисна для серіалізації всього каналу ({{ toJson .context.inject.all }}).
Механізм присутній у каналі лише тоді, коли через нього щось доставляється. Шаблон, що читає механізм, через який нічого не доставляється, — .context.inject.file без доставки файлів, — читає його як порожній, так само як шаблон значень читає будь-який відсутній ключ, а range по ньому нічого не рендерить; це читання підставляє порожнє значення для всього шаблону, тож {{ toJson .context.inject }} у тому самому шаблоні показує "file": "". Чи доставляється через механізм щось, показує hasKey .context.inject "file".
- Власні механізми (наприклад,
ssm_param) — читаються під власною назвою поля,.context.inject.<mechanism>.<key>, так само як три основні. Значення власного механізму потрапляють у канал із самоін’єкції рівня компонента, з ребраuses[].inject, з відображенняinject:прикріплення Feature та з виводуinjectMappingсутності FeatureRecipe. Для самоін’єкції рівня компонента список дозволенихspec.injectсутності Component має називати механізм, а механізм, якого список не називає, зупиняє збірку. Записи власного механізму також з’являються в.context.inject.allпоряд із трьома основними. Власний механізм може мати будь-яку назву, крімall: ця назва — це саме об’єднане подання, тож механізм із такою назвою ніколи не можна було б прочитати окремо. Блок inject, що називає механізмall, і список дозволених сутності Component або сутності Feature (spec.inject,injectсокета), що його містить, зупиняють збірку під час завантаження документа, а відмова пояснює, що ця назва належить цьому об’єднаному поданню. Назви чутливі до регістру, тожALL— звичайний власний механізм.
Канал — це стан після перехоплення: на момент, коли шаблони Recipe його читають, блоки injectMapping сутностей FeatureRecipe вже глибоко злили свої перевизначення поверх цього каналу під час відображення ін’єкцій. Відображення може замінити ключ, який доставив власний блок inject: компонента, блок inject: одного з його з’єднань або блок inject: його власного прикріплення; ключ, який доставляють обидві прикріплені сутності Features — через свої блоки inject: або свої відображення, — зупиняє збірку, а не потрапляє в цей канал з одним із двох значень. Сутність Feature, прикріплена до межі Release, досягає компонента тим самим шляхом — через injectMapping своєї FeatureRecipe, яке виконується у власному контексті компонента за будь-якого executionScope сутності FeatureRecipe; переписування мостом compose змінної хоста споживача — одне з таких відображень, що підпорядковується тому самому правилу.
.context.self_inject — яке власне значення доставляє кожне з імен розробника
Якщо сутність Component оголошує spec.inject, розробник може записати блок inject: на самому компоненті й вибрати імена, під якими доставляються власні значення та provides компонента. .context.inject містить те, у що розв’язалися ці записи, а .inject_raw містить їх у записаному вигляді; .context.self_inject вказує для кожного з них власний ключ provides компонента, який він доставляє, або єдине власне значення, яке читає його шаблон. Він має ту саму форму, що й .context.uses.<alias>.inject з’єднання, — механізм, потім ім’я розробника, потім ключ, — де ключ називає одне з власних provides або значень компонента:
provides.<key>— запис, написаний ізfrom: <key>, який доставляє одне з власних provides компонента.values.<key>— запис, шаблонvalue:якого читає рівно одне з власних значень компонента й нічого іншого, причому<key>є ключем верхнього рівня цього значення. Текст або функції навколо читання не мають значення, як і те, наскільки глибоко шаблон читає значення:'{{ .values.role }}','role={{ .values.role | upper }}'і'{{ with .values.role }}{{ . }}{{ end }}'усі зіставляються зvalues.role, а'{{ .values.config.port }}','{{ index .values.config "port" }}'і'{{ (default dict .values.config).port }}'усі зіставляються зvalues.config.- порожній рядок — будь-який інший запис: літерал, шаблон, що читає два значення, шаблон, що читає будь-що, крім значень (
.infra,.metadata,.context), і шаблон, чиє читання значень текст не відносить до одного ключа верхнього рівня, — значення, передані функції через їхній корінь (index .values "role"), значення, прочитані цілком (toJson .valuesабо поле, прочитане всередині{{ with .values }}чи через змінну, прив’язану до.values), або весь контекст, переданий далі (toJson .).
# The developer's block on the component, in the Aggregateinject: env: - { in: SERVICE_HOST, from: host } - { in: AGENT_ROLE, value: '{{"{{"}} .values.role }}' } - { in: MODE, value: batch } - { in: ROLE_AND_GOAL, value: '{{"{{"}} .values.role }}-{{"{{"}} .values.goal }}' } ssm_param: - { in: /app/goal, value: '{{"{{"}} .values.goal }}' }
# What the Recipe reads at .context.self_injectenv: SERVICE_HOST: provides.host AGENT_ROLE: values.role MODE: "" ROLE_AND_GOAL: ""ssm_param: /app/goal: values.goalУ сутності Aggregate кожен шаблон value: починається з {{"{{"}}, а не з {{, оскільки весь текст сутності Aggregate один раз читається як шаблон для інтерполяції параметрів, перш ніж обчислюються власні шаблони блоку; шаблони, наведені в списку вище, показано так, як вони читаються після цього екранування. Див. Текст, що містить власні подвійні фігурні дужки.
Саме це дає змогу сутності Recipe, яка запускає власний образ розробника, вважати свої імена змінних для власних значень компонента типовими — це домовленість каталогу стандартної бібліотеки, і корпоративний каталог може вибрати інакше. Перш ніж доставити власне значення під власним іменем, така сутність Recipe перевіряє, чи блок розробника вже доставляє це значення, і пропускає своє типове значення, якщо так, — тож розробник, який перейменовує одне значення, зберігає всі інші типові значення:
workload: | containers: main: variables: {{- range $name, $value := .context.inject.env }} {{ $name }}: {{ $value | quote }} {{- end }} {{- $named := dict }} {{- with .context.self_inject.env }}{{ range $name, $key := . }}{{ $_ := set $named $key true }}{{ end }}{{ end }} {{- if not (hasKey $named "values.role") }} APP_ROLE: {{ .values.role | quote }} {{- end }}.context.self_inject присутній під час кожного рендерингу й порожній там, де розробник не записав жодного блоку. Механізм з’являється лише тоді, коли блок його називає, тож захищайте читання механізму, якого блок може не називати, як це робить with вище. Шаблон отримує імена відсортованими, хоч би як він їх читав, як і будь-яку мапу. Мапа читається з тексту, який записав розробник; ніщо в ній не є розв’язаним значенням, і компілятор не вкладає жодного сенсу ні в імена, ні в ключі.
.context.uses — JOIN-проєкція
.context.uses — це збагачене компілятором подання кожного вихідного топологічного ребра поточного вузла. Кожен запис мапи має ключем локальний псевдонім сокета (наприклад, databases.primary стає .context.uses.primary, коли в Aggregate записано uses: { databases: { primary: { target: ... } } }) і містить JOIN-проєкцію розв’язаного стану цілі, а також контракт доставки з боку викликача:
.target(рядок) — ідентифікатор екземпляра цільового вузла..socket(рядок) — ім’я сокета з боку викликача (ключusesSchema)..provides(мапа рядкових значень) — розв’язані ключіprovides:цілі (публічні вихідні рядки, які цільовий Recipe експортував під час обчислення provides)..inject(мапа механізм → мапа ключ → значення) — директиви inject з боку викликача для цього ребра (блокinject:в оголошенніuses[].inject). Ключі механізмів —env/file/arg/власні; записи мапи кожного механізму — посилання локальний ключ → ключ provides цілі..labels(мапа рядкових значень) — мітки цілі, а ніколи не компонента-споживача: набір, який містить власний.context.labelsцілі, тобто її мітки, записані в каталозі, плюс будь-які доповненняlabel-transform, зроблені під час побудови топології..annotations(три групи) — групи анотацій ціліrelease/catalog/aggregate..component(рядок) — URI типу сутності Component цілі..resolved_version(рядок) — версія сутності Component цілі після розв’язання Manifest..boundary_path(рядок) — шлях межі Release цілі; задається незалежно від того, чи ціль розташована в межі викликача, чи в іншій..origin_feature(рядок) — задається, коли ребро синтезовано приєднанням Feature (наприклад, sidecar Feature, що додає реброusesдо облікової Feature)..values(мапа) — розв’язана конфігурація розробника для цього з’єднання на рівні ребра, записана в записіusesв Aggregate. Присутня лише тоді, коли ребро містить значення на рівні ребра..infra(мапа) — розв’язана конфігурація оператора для цього з’єднання на рівні ребра, записана в записіusesу Release. Присутня лише тоді, коли ребро містить infra на рівні ребра..origin_release(булеве) —true, коли це з’єднання підключив Release, а не оголосив Aggregate; відсутнє для з’єднання, яке оголошує Aggregate..features(мапа приєднань) — приєднання, записані на цьому з’єднанні, з ключем за ім’ям слота, який оголошує сокет; див. нижче. Присутня лише тоді, коли з’єднання має хоча б одне..render_facts(мапа списків) — те, що рендери цілі повідомили про вивід, який вони створили, з ключем за іменем факту, у тій самій формі, що й.render_factsвикликача в.context.used_by: кожен факт — список, спершу власні виклики провайдера цілі, а потім кожна з її Features у порядку рендерингу, причому списки, отримані одним іменем від кожного, об’єднуються в один. Присутня лише для FeatureRecipe, що задаєreadsTargetRenderFacts: true— її приєднання рендеряться, коли відрендерено всі компоненти, тож рендер кожної цілі завершено, — і тоді на кожному з’єднанні, порожня для цілі, провайдери якої нічого не повідомляють. Читається лише вvaluesMapping:,workload:іartifacts:цієї FeatureRecipe; відсутня у власних шаблонах Recipe компонента, вinjectMapping:, уwith:іwhen:крокуpipeline:, а також у кожній FeatureRecipe, яка не задає цей ключ, — шаблон такої FeatureRecipe, що її читає, зупиняє збірку ще до будь-якого рендерингу.
Обидві мапи конфігурації на рівні ребра мають область споживача: вони потрапляють лише в контекст рендерингу вузла-споживача, ніколи не цілі.
Надане значення читається за .provides.<name> — надані імена вкладені під .provides, а не розташовані безпосередньо на ребрі, тому .context.uses.<alias>.<name> не адресує жодного поля й нічого не повертає.
На з’єднанні, два кінці якого рендеряться в різні виводи, .provides містить замінники, а не значення. Якщо провайдер з’єднує таке з’єднання власним посиланням після того, як обидва виводи зібрано, — наприклад, стек CloudFormation читає значення іншого стека, — кожне значення, яке несе .context.uses.<alias>.provides, є заповнювачем, який провайдер згодом замінює міжстековим посиланням або самим значенням, як описано на його власній сторінці. Таке значення слід копіювати, а не порівнювати — це те саме правило, якому підпорядковується значення, що його таке з’єднання доставляє каналом inject і яке також є заповнювачем того самого роду. Записуйте його цілим, усередині довшого рядка або через функцію, що залишає його як є, наприклад quote. Шаблон, який порівнює значення, прочитане з .provides, розгалужується за ним, вимірює його чи змінює, ухвалював би рішення щодо заповнювача, тож натомість збирання зупиняється, називаючи шаблон і кожне прочитане ним значення; розгалужуйтеся за власним значенням компонента-споживача. Зупинка охоплює кожен шаблон, що читає .provides з’єднання, зокрема injectMapping: приєднаної FeatureRecipe, а також FeatureRecipe з областю межі, що читає ті самі з’єднання під .boundary. З’єднання, обидва кінці якого рендеряться в один вивід, несе свої значення як є.
Один псевдонім називає одне з’єднання, тому мапа містить запис для кожного з’єднання, яке створює компонент. Ключ мапи — лише псевдонім, незалежно від того, до якого сокета підключено з’єднання, і жодні два з’єднання одного компонента не мають спільного псевдоніма — ні на одному сокеті, ні на двох, хоч би який документ чи приєднання створили кожне з них. Збірка відхиляє таку пару, називаючи обидва з’єднання й місце, де записано кожне, ще до будь-якого рендерингу. Список, що двічі називає одну ціль, є такою парою, оскільки псевдонім запису списку — це його ціль; такою є й з’єднання local на сокеті models поряд зі з’єднанням local на сокеті databases.
Шаблони Recipe використовують цю проєкцію, щоб отримувати стан цілі без обходу графа IR. Шаблони injectMapping у FeatureRecipe використовують її, щоб звертатися до анотацій цілі для рішень про маршрутизацію між межами (шаблон розв’язувача DNS для K8s, задокументований у entities/featurerecipe.md, є канонічним розібраним прикладом).
Шаблон, що перебирає .context.uses, бачить з’єднання в порядку ключів — відсортованими за псевдонімом, — а не в порядку, у якому їх записав Aggregate. Так обходиться кожна мапа, яку перебирає шаблон, зокрема .features і .features з’єднання, тож шаблон ніколи не відновлює записаний порядок, перебираючи мапу; там, де порядок має значення, поверхня написання моделює його як список. У будь-якому разі відрендерений вивід побайтово однаковий між збірками одного й того самого входу.
Приєднання з’єднання — .context.uses.<alias>.features
Приєднання, записане на з’єднанні — під features: у записі uses компонента в Aggregate або в записі Release для цього з’єднання, — заповнює слот, який оголошує сокет. Для всього, що збірка з ним робить, це приєднання компонента-споживача: Manifest прив’язує його реалізацію, його FeatureRecipe рендериться на боці споживача, його контракт provides застосовується. Шаблон читає його під з’єднанням, на якому його записано:
{{- range $alias, $edge := .context.uses }}- name: {{ $alias }} api_base: {{ $edge.provides.endpoint }} {{- with $edge.features }}{{ with .credential }} api_key_secret: {{ .provides.name }} api_key_key: {{ .provides.key }} {{- end }}{{ end }}{{- end }}- Ключ — слот.
.context.uses.<alias>.features.<slot>називає слот, який оголошує сокет з’єднання, — вище цеcredential, — тож споживач, що звертається до кількох цілей, читає власні облікові дані кожної цілі під псевдонімом цієї цілі. З’єднання без приєднання не має.features, тому читання захищене перевіркою. - Форма приєднання. Кожен запис містить саме те, що містить
.features.<name>для одного з власних приєднань компонента, —.type,.resolved_version,.labels,.values,.infraі розв’язані.providesприв’язаної до нього FeatureRecipe, — див. форму приєднання. Прочитані тут provides — це ті, з якими рендериться власна FeatureRecipe приєднання, тож ім’я, на яке посилається споживач, і ім’я ресурсу, який створює ця FeatureRecipe, — одне обчислене значення. - Ніколи не в
.features. Власна.featuresкомпонента містить лише приєднання, записані в його власному блоці. Тому Recipe, що перебирає.featuresі вибирає приєднання за типом —{{ range $name, $f := (default dict .features) }}{{ if eq $f.type "core/referenced-secret" }}…, — ніколи не зустрічає облікових даних з’єднання, навіть тієї самої Feature: шаблон дістається до приєднання з’єднання через його з’єднання, ніколи через.features. Те саме стосується кожної поверхні, що показує приєднання компонента, зокрема контекстуassertions.
Компоненти, що використовують цей — .context.used_by
.context.uses дивиться назовні, на з’єднання, які створює компонент. .context.used_by дивиться всередину, на компоненти, чиї записи uses вказують на цей. Його читає FeatureRecipe, приєднаний до компонента, — саме там місце ресурсу, що описує або обмежує ці з’єднання, наприклад мережевої політики, яка допускає лише компоненти, оголошені як такі, що викликають цей:
artifacts: callers.yaml: | apiVersion: v1 kind: ConfigMap metadata: name: {{ .context.rendered_name }}-{{ .attachment_name }} data: callers: | {{- range .context.used_by }} - component: {{ .component_id }} socket: {{ .socket }} selector: {{ .provides.selector }} {{- with .source_namespace }} namespace: {{ . }} {{- end }} {{- end }}Кожен запис містить:
.component_id(рядок) — ідентифікатор екземпляра компонента, що під’єднується, у сплощеній формі (frontend,data-layer.etl); це значення, яке шаблон шляхуsubDirectory:читає як.component_id..socket(рядок) — сокет, який з’єднання заповнює на компоненті, що під’єднується (його ключusesSchema)..provides(мапа рядкових значень) — те, що публікує компонент, що під’єднується, звужене до ключів, які оголошує його сутність Component: ті самі значення, які споживач цього компонента читає в.context.uses.<alias>.provides. Ключа, який Recipe компонента публікує, не оголошений у його сутності Component, серед них немає..source_namespace(рядок) — простір імен, у якому розміщено компонент, що під’єднується: анотаціяaggrega.ai/namespace, що до нього застосовується, каскадована вниз його межами, причому пріоритет має його власний запис у сутності Release. Компонент, чий запис у сутності Release задає простір імен або очищає його за допомогоюnull, має власне налаштування, а не налаштування своєї межі, тож значення називає простір імен, у який рендеряться власні ресурси компонента. Відсутнє, коли до компонента не застосовується жоден простір імен; читайте його черезwithабоif, як у прикладі, а не виводьте напряму..source_boundary_path(рядок) — шлях межі Release, що містить компонент, що під’єднується, із вкладеними межами, з’єднаними через/(edge,edge/inner)..render_facts(мапа списків) — те, що рендери компонента, що під’єднується, повідомили про згенерований ними вивід, з ключами за назвою факту, у тій самій формі, що й.context.render_facts. Кожен факт є списком, тож шаблон завжди ітерує по ньому, навіть коли він містить один запис. Його записи можуть походити з власного рендеру компонента, що під’єднується, і з рендерів приєднаних до нього Features: списки, які одна назва отримує від кожного, об’єднуються в один — спершу власні виклики провайдера компонента, потім кожна з його Features у порядку рендерингу. Присутнє лише для FeatureRecipe, що задаєreadsCallerRenderFacts: true, — його приєднання рендеряться після рендерингу всіх компонентів, тож рендер кожного викликача завершено, — і тоді на кожному записі, порожнє для викликача, чиї провайдери нічого не повідомляють. FeatureRecipe, що не задає цей ключ, не бачить.render_factsна жодному записі, а його шаблон, що їх читає, зупиняє збирання, перш ніж щось буде відрендерено.
Два значення розміщення — ті самі, які FeatureRecipe рівня межі читає як source_namespace і source_boundary_path у записі того самого з’єднання у своїх списках ребер .boundary: обидва подання однаково визначають, де розміщено компонент, тож вони ніколи не розходяться щодо цього. Ребро в цих списках також несе шлях збирання кожної кінцевої точки — source_assembly_path і target_assembly_path, каталог у вихідному каталозі збирання, у який її збирає провайдер кінцевої точки, — чого запис .context.used_by не містить.
FeatureRecipe, що задає readsCallerRenderFacts: true, читає факти кожного викликача так само, як і факти хоста. Для провайдера, який документує факт із назвою ports, кожен запис якого містить port:
artifacts: callers.yaml: | callers: {{- range .context.used_by }} - component: {{ .component_id }} ports: {{- range .render_facts.ports }} - {{ .port }} {{- end }} {{- end }}Викликач, чий провайдер не повідомляє ports, рендерить порожній ports: замість збою, бо назва, про яку ніхто не повідомив, читається як ніщо.
Як поводиться список:
- У порядку написання. Записи йдуть у порядку, у якому написано компоненти, що під’єднуються, а потім у порядку власних записів
usesкожного з них. Компонент, що під’єднується двічі, з’являється двічі, по разу на з’єднання. Оскільки це список, а не мапа,rangeзустрічає викликачів у цьому порядку — нічого не сортується. - Лише там, де приєднання рендерить власні ресурси. Його читають
valuesMapping:,workload:іartifacts:сутності FeatureRecipe. Він порожній у власних шаблонах Recipe компонента, вinjectMapping:і вwith:таwhen:крокуpipeline:, бо те, що створює кожен із них, може потрапити до власного відрендереного виводу компонента:injectMapping:записує канал доставки компонента, а крок конвеєра може переписати документи компонента. Саме це зберігає власний вивід компонента незмінним незалежно від того, хто його використовує: під’єднання ще одного викликача до компонента змінює вивід приєднаної до нього сутності Feature, яка читає його викликачів, і нічого з того, що рендерить сам компонент. - Нічого про саме з’єднання. Запис не містить
valuesчиinfraокремого з’єднання і жодного з приєднань з’єднання; вони залишаються в компонента-споживача, у його.context.uses.<alias>. - Порожній, коли компонент ніхто не використовує. Тоді
rangeпо ньому нічого не рендерить. - Передається, ніколи не інтерпретується. Ідентичність, сокет, опубліковані значення та розміщення — це рядки, які компілятор передає далі, а факти рендеру — це те, що повідомили провайдери кожного викликача, з ключами за назвою. Компілятор нічого не виводить із назви, нічого не отримує і нічого не вирішує щодо того, яких викликачів має допускати ресурс; вирішує шаблон.
Що провайдер повідомив про рендер — .context.render_facts
Провайдер компонента може повідомляти факти про відрендерений ним вивід — властивості записаних ним документів, які може побачити лише його власне знання свого формату. Які факти повідомляє провайдер, під якими назвами і що міститься в кожному записі, — це власний задокументований контракт цього провайдера; див. Reporting facts about what a guest emitted щодо боку провайдера. Провайдер helm, наприклад, повідомляє мітки згенерованих ним шаблонів подів, селектори своїх контролерів і Services та порти своїх контейнерів — див. його факти рендеру. FeatureRecipe, приєднаний до компонента, читає те, що повідомив провайдер компонента, у .context.render_facts, з ключами за назвою факту. Для провайдера, який документує факт із назвою ports, кожен запис якого містить name і port:
artifacts: ports.yaml: | ports: {{- range .context.render_facts.ports }} - name: {{ .name }} port: {{ .port }} {{- end }}- Кожен факт є списком. Провайдер повідомляє кожен факт як список, навіть коли він містить один запис, тож шаблон завжди ітерує по ньому — окремого одиничного значення для читання немає.
- Один список на назву, об’єднаний у межах рендеру компонента. Рендеринг компонента може потребувати кількох викликів його провайдера — наприклад, рендеру чарту та розміщення артефактів, — і кожен виклик повідомляє за себе. Списки, які одна назва отримує від цих викликів, об’єднуються в один у порядку виконання викликів. Того, що відрендерили приєднані до компонента Features, тут серед них немає: Feature читає в
.context.render_factsлише власний рендер компонента, що б не згенерували інші Features компонента. - У кожному шаблоні приєднаного FeatureRecipe. Його читають
valuesMapping:,workload:іartifacts:, а такожwith:іwhen:його кроківpipeline:— факти походять із власного рендеру компонента, тож їх читання не робить нічого залежним від того, хто під’єднується до компонента. Він відсутній у власних шаблонах Recipe компонента та вinjectMapping:, які виконуються до рендерингу компонента. - Порожній, а не відсутній. Там, де провайдер компонента нічого не повідомляє,
.context.render_facts— порожня мапа, а назва, про яку ніхто не повідомив, читається як ніщо, тожrangeпо ній нічого не рендерить замість збою. - Порядок. Список зберігає свої записи в тому порядку, у якому їх повідомив провайдер. Запис-об’єкт є мапою з ключами, як і будь-яка інша в контексті, тож шаблон, що ітерує по ньому, зустрічає його ключі в порядку ключів.
- Передається, ніколи не інтерпретується. Компілятор перевіряє лише те, що значення кожного факту є списком. Він нічого не читає з того, що означає назва чи запис; що з цим робити, вирішує шаблон.
.uses у твердженні — ключі за сокетом, потім за псевдонімом
Шаблон assertions: читає ті самі з’єднання через власне вужче подання: .uses у корені, а не під .context, і без нічого, що опублікувала ціль з’єднання, оскільки обидві фази тверджень обчислюються до рендерингу. Воно віддзеркалює авторську форму uses: <socket>: <alias>: { target: … } — ключі за сокетом, а під кожним сокетом — за псевдонімом кожного з’єднання на ньому; з’єднання, записане як елемент списку, бере свою ціль як псевдонім. Запис кожного з’єднання містить target, alias і, для з’єднання, яке створило приєднання Feature, origin_feature, а також три з фактів, які містить .context.uses, під тими самими іменами й з тими самими значеннями: .labels — мітки цілі; .values — значення, записані на з’єднанні; і .features — приєднання, записані на ньому, з ключами за слотом. Кожен із трьох присутній у кожному записі й порожній там, де з’єднання їх не має. Приєднання під .features містить лише свої type, resolved_version і values — форму, у якій твердження читає кожне приєднання, зокрема власні приєднання компонента, оскільки FeatureRecipe приєднання ще не розв’язав свої provides, коли виконується твердження.
Сокет з одним з’єднанням і сокет із кількома мають однакову форму, тож твердження читає їх однаково. Для компонента, запис якого в сутності Aggregate містить uses: { models: { local: { target: llama }, fast: { target: turbo } } }:
assertions: two-models-wired: | {{- if lt (len (optional .uses "models" dict)) 2 -}} {{- fail "wire two models to the models socket" -}} {{- end -}} local-is-llama: | {{- if and (hasKey .uses "models") (hasKey .uses.models "local") (ne .uses.models.local.target "llama") -}} {{- fail (printf "the local connection must point at llama; it points at %s" .uses.models.local.target) -}} {{- end -}}hasKey .uses "models" перевіряє, чи під’єднано сокет, len рахує його з’єднання, range по ньому обходить кожне в алфавітному порядку їхніх псевдонімів, а .uses.models.local.target читає одне з’єднання. .uses.models.target не адресує жодного з’єднання й зупиняє збирання через missingkey=error середовища тверджень. Кожне з’єднання має власний запис з тієї ж причини, що й у мапі контексту рендерингу: два з’єднання одного компонента ніколи не мають спільного псевдоніма, бо збирання відхиляє таке ще до виконання будь-якого твердження. Повний контекст тверджень задокументовано в assertions-block.md.
Інструменти, пов’язані з inject
Контекст шаблону містить ці поля у формі inject, кожне зі своєю семантикою. Авторам Recipe і FeatureRecipe слід знати, який інструмент читати.
| Інструмент | Тип | Коли заповнюється | Застосування |
|---|---|---|---|
.context.inject | мапа механізмів (присутня завжди) | Під час кожного рендерингу | Стандартний попередньо заповнений канал доставки — читайте його в шаблонах valuesMapping:/workload:/artifacts: і в будь-якому місці шаблону FeatureRecipe. |
.inject (верхній рівень) | мапа механізмів (допускає null) | Рендеринг FeatureRecipe приєднання, коли приєднання задає блок inject: | Власні записи inject: прикріплення, під кожним механізмом, який називає його блок, — env, file, arg або власним, як-от vault_ref, — де кожна локальна назва зіставлена з ключем, який називає її from:. Цей ключ — або той, що сутність FeatureRecipe публікує у своїх provides: і який компілятор також доставляє в .context.inject компонента, або ключ, який сама споживає сутність FeatureRecipe, що читає .inject: запис, що називає ключ, якого сутність FeatureRecipe не публікує, зупиняє збірку, якщо тільки шаблон, який сутність FeatureRecipe обчислює щодо цього контексту, — її valuesMapping:, workload:, artifacts:, omits: або with: чи when: кроку конвеєра, — не читає .inject за шляхом, який називає шаблон: .inject, .inject.env, {{ with .inject }} тощо, а не через передавання всього контексту, як-от toJson .. Її injectMapping: не враховується, бо він обчислюється щодо контексту компонента, де .inject відсутній. Блок прикріплення не містить літералів: запис value: у ньому зупиняє збірку, а літерал, потрібний компоненту, записується у власному блоці inject: компонента. Власний механізм читається в .inject.<mechanism> так само, як .inject.env, а його записи з’являються в .inject.all поряд із трьома основними. Читання через крапку механізму, якого прикріплення не задає, зупиняється як невідомий ключ, навіть усередині if або with, де .context.inject.<mechanism> читається як порожній; механізм, якого прикріплення може не задавати, слід читати через {{ with .inject }}{{ if hasKey . "<mechanism>" }}{{ index . "<mechanism>" "<key>" }}{{ end }}{{ end }}, що збирається незалежно від того, чи задає прикріплення цей механізм або будь-який блок inject:. Відсутній у шаблонах базової сутності Recipe та в прикріпленні, яке не задає жодного блоку inject:. |
.inject_raw (верхній рівень) | мапа механізмів (допускає null) | Встановлюється, коли розробник написав блок inject: у батьківському компоненті | Незмінений намір розробника до будь-якого перехоплення через inject-mapping. Кожен механізм, який називає блок, — env, file, arg або власний, як-от ssm_param, — розміщено під його власним ім’ям, і він містить записи точно в тому вигляді, як їх написано (in разом із from або value), у порядку написання: .inject_raw.ssm_param читає власний механізм так само, як .inject_raw.env читає базовий. Використовуйте для логічних перевірок на кшталт «чи запитував розробник спочатку цей ключ доставки?»; не зазнає впливу перезапису через injectMapping у FeatureRecipe. nil, якщо розробник пропустив блок inject:. |
.context.self_inject | мапа механізмів (присутня завжди) | Кожен рендеринг; порожній там, де розробник не записав блок inject: на компоненті | Кожне ім’я з власного блоку inject: компонента, зіставлене з власним ключем, який доставляє його запис, — provides.<key>, values.<key> або порожній. Використовуйте, щоб пропустити типове ім’я для власного значення, яке розробник уже доставляє; див. вище. |
Авторам, яким потрібна остаточна доставка після перехоплення, слід читати .context.inject. Авторам, яким потрібен незмінний початковий намір (наприклад, щоб виявити перехоплення або забезпечити резервну поведінку, коли розробник пропустив блок inject), слід читати .inject_raw. Авторам, яким потрібно знати, які з власних значень компонента розробник уже назвав, слід читати .context.self_inject.
Інструмент вкладення FeatureRecipe
Коли рендерер обчислює шаблони вкладення FeatureRecipe, встановлюється додаткове поле верхнього рівня:
.attachment_name(рядок) — ім’я екземпляра вкладення: слот, який воно заповнює уfeaturesSchemaсутності-власника, або довільне ім’я, яке дав йому автор.locals:,provides:,injectMapping:,valuesMapping:іartifacts:сутності FeatureRecipe читають його, щоб вивести детермінований ідентифікатор ресурсу —{{ .context.rendered_name }}-{{ .attachment_name | replace "_" "-" }}, де провайдер хоста повідомляє відрендерене ім’я, як це робитьhelm, і{{ .context.instance_id }}-{{ .attachment_name }}, де він його не повідомляє, — а також щоб назвати вкладення, що обробляється.
Власні шаблони базової сутності Recipe не розв’язують вкладення, тому це поле не входить до їхнього контексту: шаблон provides:, locals: або source: сутності Recipe, який на нього посилається, зупиняє збирання з указанням цього посилання, а не рендерить порожнє значення. FeatureRecipe з executionScope: boundary рендериться один раз для межі, а не один раз для кожного компонента, тому це поле недоступне й шаблонам, що виконуються для межі; її injectMapping: виконується для кожного компонента, якого досягає вкладення, і читає поле там.
У шаблонах, що створюють власні ресурси вкладення, — його valuesMapping:, workload: і artifacts: — контекст вкладення також містить перелік компонентів, які використовують його хост, у .context.used_by, а там, де його FeatureRecipe встановлює readsTargetRenderFacts: true, містить те, що відрендерив кожен компонент, з яким з’єднано його хост, у .context.uses.<alias>.render_facts. Ці шаблони та кроки його pipeline: також читають те, що провайдер хоста повідомив про рендеринг хоста, у .context.render_facts. FeatureRecipe з областю межі рендерить свої ресурси без хост-компонента і без .context; натомість вона читає кожне з’єднання всередині своєї межі в .boundary.internal_uses_edges і .boundary.incoming_cross_boundary_uses_edges. Її injectMapping: — єдиний шаблон, який вона пише і який виконується в контексті компонента — кожного компонента, якого досягає вкладення, зокрема .context.*, — і посилання на .boundary там зупиняє збирання.
Це поле — єдиний спосіб отримати ім’я екземпляра вкладення. .context.instance_id — це хост-компонент, для якого розв’язується вкладення, — він позначає хост на кожному інструменті шаблонів, який обчислює компілятор, зокрема у власних locals: сутності FeatureRecipe, — тож ці два імені не взаємозамінні, і жодне з них не заступає інше.
.source належить самому приєднанню. Шаблон source: сутності FeatureRecipe обчислюється перед її valuesMapping:, так само як шаблон сутності Recipe — перед її власним, і те, що він створив, і є вмістом .source у шаблонах, що створюють ресурси приєднання, — її valuesMapping:, omits:, workload: і artifacts:, — а також у її кроках pipeline:. Це ніколи не джерело компонента-хоста: сутність FeatureRecipe, яка не оголошує source: або чий шаблон нічого не створює, нічого там не читає, навіть на хості, чия сутність Recipe оголошує джерело. Сутність FeatureRecipe з областю дії межі читає власне джерело в тих самих шаблонах. Єдиний виняток — injectMapping:, який виконується до обчислення джерела приєднання і читає .source так само, як власна сутність Recipe компонента-хоста.
.context.rendered_name також належить хост-компоненту: у кожному шаблоні покомпонентного вкладення воно містить ім’я, яке власний провайдер хоста повідомляє для хоста, — значення, яке читає власна Recipe хоста, — тож вкладення називає ресурс за своїм хостом через {{ .context.rendered_name }}-{{ .attachment_name }} і отримує ім’я, яке приймає платформа, навіть якщо ідентичність хоста містить підкреслення або велику літеру. Воно присутнє там, де провайдер хоста повідомляє ім’я, і відсутнє там, де не повідомляє, а його читання на такому хості зупиняє збирання з будь-якого шаблону, який FeatureRecipe пише вбудовано, окрім її injectMapping:; див. Іменування відрендереного ресурсу.
Доступність за місцями
Доступність полів залежить від місця шаблону. Шаблони provides: у Recipe виконуються під час обчислення provides із самодостатнім контекстом (без .context.inject/.context.uses); valuesMapping: у Recipe виконується під час базового рендерингу з повним контекстом шаблону; injectMapping: у FeatureRecipe виконується під час відображення inject з повним контекстом шаблону, включно з inject-каналом, який перехоплюється. Повна таблиця доступності за кожним місцем міститься в expansion-matrix.md; ця сторінка документує форми полів, на які вказує стовпець «доступні посилання» цієї матриці.
Перехресні посилання
05-templates.md— огляд шаблонізації.expansion-matrix.md— матриця обчислення для кожного місця шаблону.sprig-functions.md— допоміжні функції Sprig, підключені до рушія шаблонів.../entities/recipe.md— поверхня створення сутності Recipe.../entities/featurerecipe.md— поверхня створення сутності FeatureRecipe (зокрема розібраний приклад DNS-резолвера K8s для обходу.context.uses).../vocabulary/topology-triad.md— специфікація контракту ін’єкції (охоплює контекст із подвійним станом, правила колізій ключів, розібрані приклади).../10-status.md#compilation-pipeline-phases— поточна готовність поверхонь відображення ін’єкцій, базового рендерингу та конвеєра плагінів.