Перейти к содержимому
AggregaAggrega
Выберите язык: Русский
Эта страница переведена машинным способом. Читать оригинал на английском.

Матрица раскрытия шаблонов

Справочник по раскрытию шаблонов — полная матрица

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 available

2. Матрица раскрытия шаблонов

Все места DSL, где вычисляются выражения шаблонов Go, и точный перечень доступных ссылок:

#LocationСущностьГде вычисляетсяДоступные ссылки
1{{ .parameters.X }} в строках YAML сущности AggregateAggregateРазрешение (интерполяция)Только .parameters. Все остальные данные ещё не разрешены.
2{{ .parameters.X }} в строках YAML сущности ReleaseReleaseНе вычисляетсяНет. Строки сущности 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 сущности RecipeRecipeВычисление 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, тоже приводит к остановке, поскольку этот столп — открытая карта с ключами, которую одна проверка корней проконтролировать не может.
7valuesMapping сущности Recipe (встроенный, через файловый $import: или библиотечный $import:)RecipeБазовый рендерингПолный контекст шаблона: .values, .infra, .context.* (instance_id, rendered_name, labels, annotations, inject, uses), .locals, .provides, .features, .metadata. Встроенная ссылка .context.rendered_name приводит к остановке на узле, провайдер которого такого имени не сообщает, как в #6; ссылка внутри тела, загруженного через $import:, не проверяется и на таком узле отрисовывается пустой.
8injectMapping сущности FeatureRecipeFeatureRecipeОтображение 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, который не несёт контекст ни одного компонента, — ссылка на него останавливает сборку.
9valuesMapping сущности 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Запрещённая ссылкаОбоснование
value: в inject сущности Component (#4).context.injectВ этот момент канал inject ещё строится — шаблон value: самоинъекции не может читать из канала, в который сам вносит вклад.
value: в inject сущности Component (#4).context.usesСвязывание между компонентами задаётся в uses[].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).providesLocals разрешаются до provides, поэтому собственных provides узла ещё не существует, когда вычисляется local. Local, которому нужно значение, также публикуемое в provides, вычисляет его напрямую из .values / .infra, а запись provides затем читает этот local.
locals сущности Recipe (преамбула #6).context.rendered_nameLocals сущности 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Разрешение источника должно завершиться до того, как что-либо далее по конвейеру загрузит chart, модуль или тело артефакта объявляющей сущности. Разрешение ссылок между узлами связало бы разрешение источника с порядком обхода топологии, чего оно намеренно избегает.
Parameters (везде, кроме шаблонов путей)Любая поверхность шаблонов значений после интерполяцииИнтерполяция поглощает каждую ссылку {{ .parameters.X }} в авторском YAML и записывает на её место разрешённое значение, поэтому поверхность шаблонов значений получает разрешённый литерал, а не столп параметров. Шаблоны путей, написанные оператором, — единственное исключение: они читают .parameters.X напрямую.

4. Путь разрешения самоинъекции

Разрешение самоинъекции — первая половина гидратации inject, и оно выполняется после вычисления provides всех узлов. Когда компонент объявляет блок inject: уровня компонента, компилятор вычисляет его на этом этапе:

  1. Литеральные строки value:: если значение содержит выражения шаблонов Go, компилятор вычисляет их с контекстом из строки #4 матрицы (.values, .infra, .context.instance_id, .metadata.* и т. д.), записанными в экранированном виде, как показано в строке #4. Обычные строки проходят без изменений.
  2. Ссылки from:: компилятор ищет ключ в собственном словаре provides узла, к этому моменту уже разрешённом. Если ключа нет, компилятор останавливает сборку с ошибкой недопустимого ключа inject.
  3. Проверка коллизий: перед слиянием в канал .context.inject компилятор проверяет, что ни один ключ не совпадает с ключами uses-inject, которые разрешает вторая половина гидратации inject. Коллизии останавливают сборку с ошибкой дублирующегося ключа доставки.

Полученные строки сливаются в .context.inject.env, .context.inject.file, .context.inject.arg (и любые пользовательские механизмы) вместе с результатами разрешения uses-inject. К моменту запуска сопоставления inject (injectMapping) канал содержит все заданные разработчиком значения inject из обоих источников.