跳转到内容
AggregaAggrega
选择语言: 简体中文
本页面由机器翻译。阅读英文原文。

模板展开矩阵

模板展开参考——完整矩阵

Aggrega DSL 在 YAML 实体的多个位置支持 Go text/template 展开(预先注册了 Sprig 库)。每个位置都有一组特定的可用引用,取决于数据在编译过程中何时变为具体值。本页是关于在何处可以引用什么的参考。

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实体求值阶段可用引用
1Aggregate YAML 字符串中的 {{ .parameters.X }}Aggregate解析(插值)仅 .parameters。其他所有数据尚未解析。
2Release YAML 字符串中的 {{ .parameters.X }}Release不求值无。Release 的字符串按原样读取:位于 infra: 下、注解中或作为 parameters: 值的 {{ .parameters.X }} 会以该字面文本到达其目的地。Release 提供参数值(内联的 parameters: 映射与通过 $import: 加载的值合并为合并后的参数映射);Aggregate 的字符串读取这些值(#1),路径模板也是如此(#3)。
3directory / subDirectory 模板Release 边界渲染(路径求值).capability、.boundary_name、.parameters.X、.manifest.recipe_name、.parent_boundary.* 以及 .component_id(仅限 subDirectory:——directory: 模板会拒绝它)。
4Component inject value: 字符串Aggregate 组件自注入解析.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 外不定义任何根。
5source 字段字符串(顶层字符串,或结构化 source: 映射中字符串类型的子字段)Recipe / FeatureRecipe源解析**两个表面,由源所指向的对象决定。**远程坐标——结构化块中指向注册表、chart 仓库或 git 仓库的 version、chart、ref 和 module_subdir——在 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 共享上下文,因此两者接受和拒绝相同的引用,而远程坐标读取该上下文的一个子集;源解析必须在拓扑管道注入数据之前、在加载任何 chart、模块或制品主体之前完成)。
6Recipe provides 模板RecipeProvides 求值.context.instance_id、.context.rendered_name(节点的 provider 为其为该节点渲染的输出所起的名称——来自作者提供的源,或来自它合成的 workload;在 provider 不上报此类名称的节点上读取它会中止——参见为渲染资源命名)、.values、.infra、.locals(节点的完整已解析块——locals 在本阶段的前导步骤中解析,先于 provides)、静态字符串。**禁止:**其他所有根——.context.inject、.context.uses(跨节点)、.context.annotations.*、.context.labels、.context.metadata、.metadata.*(与放置/部署耦合),以及 .attachment_name(基础 Recipe 的 provides 求值期间不解析任何附加项)。该检查是正向白名单:引用 provides 上下文未暴露的任何根都会中止(自包含不变式——使求值可并行且无需拓扑排序)。.locals.<key> 指向 locals 块未声明的键时同样会中止,因为该支柱是开放的键控映射,仅靠根检查无法约束。
7Recipe valuesMapping(内联、文件 $import: 或库 $import:)Recipe基础渲染完整模板上下文:.values、.infra、.context.*(instance_id、rendered_name、labels、annotations、inject、uses)、.locals、.provides、.features、.metadata。内联写入的 .context.rendered_name 引用在 provider 不上报此类名称的节点上会中止,与 #6 相同;通过 $import: 加载的主体中的引用不受检查,在此类节点上渲染为空。
8FeatureRecipe injectMappingFeatureRecipe注入映射完整模板上下文:.values、.infra、.context.*(包括 .context.inject——被拦截的管道——以及 .context.uses)。此处 .context.used_by 为空:映射的输出落在宿主自身的交付管道上。.context.render_facts 不存在:映射在宿主渲染之前运行。.context.rendered_name 是宿主组件上报的名称,与 #9 相同;读取它的映射不受检查,在 provider 不上报名称的宿主上将其渲染为空。无论 FeatureRecipe 的 executionScope 如何,上下文都相同:边界作用域 FeatureRecipe 的映射会针对附件所到达的每个组件各运行一次,读取该组件的 .context.*,并将 .features.<attachment>.provides 和 .locals 作为唯一一次边界求值来读取。禁止:.boundary,任何组件的上下文都不携带它——引用它会中止构建。
9FeatureRecipe valuesMapping(及其 workload: 和 artifacts:)FeatureRecipe基础渲染完整模板上下文 + .attachment_name、.inject(附件自身的 inject: 条目,在附件编写了 inject: 块时)、.context.render_facts——宿主的 provider 关于宿主渲染所上报的信息——以及 .context.used_by——使用该宿主的组件,在 FeatureRecipe 设置 readsCallerRenderFacts: true 时,每个组件都携带其自身的渲染事实。在 FeatureRecipe 设置 readsTargetRenderFacts: true 时,.context.uses 上的每个连接都在 .render_facts 处携带其目标的渲染事实。.context.instance_id 和 .context.rendered_name 是宿主组件的标识以及宿主自身的 provider 为其上报的名称——与宿主的 Recipe 读取的值相同,在 FeatureRecipe 的 locals: 和 provides: 上也是如此——内联写入的 .context.rendered_name 引用在 provider 不上报此类名称的宿主上会中止。.source 是 FeatureRecipe 自身经求值的 source:,绝不是宿主组件的;在 FeatureRecipe 未声明时不包含任何内容。
10流水线 with: 块Recipe / FeatureRecipe插件流水线完整模板上下文 + .steps(来自前序流水线步骤的步骤间输出)。此处 .context.used_by 为空,.context.uses 上的连接也不携带其目标的渲染事实:步骤可能重写宿主自身的文档。附加的 FeatureRecipe 的步骤读取 .context.render_facts,即宿主自身的渲染事实,与 #9 相同。
11Recipe workload: 主体(其中每个模板化字段,无论是内联还是通过 $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 引用。源解析在填充 .context.inject 的 inject 注水之前运行,也在任何下游环节使用已解析的源之前运行——因此该规则及其设计动机同时适用于两个表面。两者的区别在于 provides 支柱:工作区 source 与声明实体的 locals 共享上下文,远程坐标读取其子集,因此两者都拒绝 .provides,而 provides 本身就是正在解析的表面。两者都读取 .locals。该规则对 FeatureRecipe 的 source 的适用条件与对 Recipe 的相同,各自依据该实体自身的 locals 表面进行检查。

Workload 主体模板说明(#11)。 Workload 主体是一个模板化字符串,渲染器将其作为整体求值,然后把结果解析为 Workload 文档。其中的字段级模板(此处的 replicas: {{ .infra.replicas | default 1 }},彼处 containers.app.variables 中的 LOG_LEVEL: "{{ .values.log_level }}")并不是独立的模板求值位置——它们都参与生成 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禁止的引用设计动机
Component inject value:(#4).context.inject此时 inject 管道正在构建——自注入的 value: 模板无法读取它所参与构建的管道。
Component inject value:(#4).context.uses跨组件连接位于 uses[].inject 中。组件的自注入 value: 模板只封闭于该组件自身的数据。
Recipe provides(#6).context.injectProvides 模板以任意顺序求值,且仅封闭于节点自身的数据(.values、.infra、.locals、.context.instance_id、.context.rendered_name)。inject 管道要到 inject 注水时才会填充,而 inject 注水在所有节点的 provides 求值完成后才运行。
Recipe provides(#6).attachment_name基础 Recipe 的 provides 阶段不解析任何附件,因此该名称会渲染为空。该根被拒绝,而不是以空值交付。
source (#5).provides两个源表面都不带 provides 支柱:工作区源表面与声明实体自身的 locals 共享上下文,而后者没有该支柱;远程坐标读取该上下文的子集。Locals 在 provides 之前解析,以便 provides: 能读取 .locals;源模板读取同样的 locals,而不是回头去读取 provides。
Recipe locals(#6 前置阶段).providesLocals 在 provides 之前解析,因此在对某个 local 求值时,节点自身的 provides 尚不存在。若某个 local 需要的值 provides 也会发布,则直接从 .values / .infra 计算——然后由 provides 条目读取该 local。
Recipe locals(#6 前置阶段).context.rendered_nameRecipe 的 locals 与其 source 模板(#5)共享上下文,而该表面不提供此名称:节点是否提供源(由 source 模板决定)正是该名称所依赖的因素之一。该引用会以未知根诊断终止,诊断会列出 .context.instance_id 作为 .context 在此处定义的内容。请改为在 provides 条目或基础渲染阶段的模板中读取该键。
Recipe provides(#6).context.uses.context.uses 引用其他节点的 provides,而 provides 求值以任意顺序运行它们。Provides 模板保持自包含,使求值与顺序无关。
FeatureRecipe 的 locals、provides、source(#5)及内联渲染模板(#9、#10),且宿主的 provider 不报告名称.context.rendered_name在 Feature 附件上,该键携带宿主组件报告的名称;而仅放置制品集的宿主,或通过不派生此类名称的 provider 渲染的宿主,没有可携带的名称。该引用会以未知根诊断终止,诊断会列出 .context.instance_id 作为 .context 在此处定义的内容之一;请改为读取标识,在这类宿主上,宿主自身的资源正是以它命名的。
source (#5).context.inject源解析在填充 .context.inject 的 inject 注水之前运行。对源 URI 求值时,该管道尚未填充。
source (#5).context.uses源解析必须在任何下游环节加载声明实体的 chart、模块或制品主体之前完成。允许跨节点引用会使源解析与拓扑迭代顺序耦合,而这正是其有意避免的。
Parameters(路径模板以外的所有位置)插值之后的任何值模板表面插值会消耗所编写 YAML 中的每个 {{ .parameters.X }} 引用,并在原处写入解析后的值,因此值模板表面收到的是解析后的字面量,而不是 parameter 支柱。运维人员编写的路径模板是唯一的例外,可直接读取 .parameters.X。

4. 自注入解析路径

自注入解析是 inject 注水的前半部分,在所有节点的 provides 求值完成后运行。当组件声明了组件级 inject: 块时,编译器在此阶段对其求值:

  1. 字面量 value: 字符串: 如果值包含 Go 模板表达式,编译器使用矩阵第 4 行的上下文(.values、.infra、.context.instance_id、.metadata.* 等)对其求值,并按第 4 行所示以转义形式编写。普通字符串原样通过。
  2. from: 引用: 编译器在节点自身的 provides 字典(此时已解析)中查找该键。如果键不存在,编译器以 invalid-inject-key 错误终止构建。
  3. 冲突检查: 在合并到 .context.inject 管道之前,编译器会验证没有任何键与 inject 注水后半部分所解析的 uses-inject 键冲突。冲突会以 duplicate-delivery-key 错误终止构建。

生成的字符串与这些 uses-inject 解析结果一起,合并到 .context.inject.env、.context.inject.file、.context.inject.arg(以及任何自定义机制)中。到 inject 映射(injectMapping)运行时,管道已包含来自两个来源的所有开发者编写的 inject 值。