模板上下文契约
本页说明编译器注入 Recipe 和 FeatureRecipe Go 模板的运行时视图:模板上下文的结构、各字段在整个编译流水线中的可用性,以及高级作者在编写使用跨组件状态的模板时所需的规范契约。按模板位置划分的可用性(哪些字段在哪个求值位置可用)见 expansion-matrix.md;本页说明字段的结构及其语义。
概述
编译器在渲染期间为每个节点组装一个模板上下文,并将其注入渲染器为该节点求值的每个 Go 模板中。该上下文仅存在于内存中——它从不持久化到磁盘,也从不作为单个负载跨越 Wasm ABI。每个模板位置接收的都是同一上下文对象的一个视图;某些字段填充较晚(.workload 在 workload 合成时到达;.source 在源解析时到达;.steps 由 pipeline: 执行在每个步骤完成时填充,参见语言状态 → 编译流水线阶段)。
该运行时结构的 schema 是 template-context-v1beta1.schema.json(随 Aggrega schema 发行包一同提供)。
顶层字段
顶层字段位于模板上下文的根部,在模板内以 .field 的形式访问。
.values(map)。 来自 Aggregate 的、由开发者编写的认知载荷。每个组件的 values 通过此字段传递到渲染后的 Recipe。在解析时由 Catalog 的schema:(Component 或 Feature 的 JSON Schema 2020-12 声明)校验。当某个字段被显式写成零值、空值或 false 在语义上不同于该字段缺失时,请使用optional(参见sprig-functions.md),而不是default。.infra(map)。 来自 Release 的、由运维编写的物理规格配置。在解析时由 Catalog 的schema:(Component 或 Feature 的 JSON Schema 2020-12 声明)校验。与.values相同的optional与default选用建议同样适用:当显式写出的零或 false 是合理意图时(缩容到零、不重试、关闭功能开关),优先使用optional。.locals(字符串值 map)。 Recipe 的私有状态:在 Recipe 的locals:块中声明的名称,在 locals 前置阶段解析,并在源解析时发布到此支柱上。各条目按编写顺序解析,一个条目可以读取定义在它上方的同级条目,因此只要一个条目读取另一个条目,顺序就至关重要。仅能在该 Recipe 自身的模板中访问,绝不向调用方公开。.provides(字符串值 map)。 Recipe 的公开输出字符串,即调用方的inject:块解析from:引用时所依据的契约。在 provides 求值阶段填充。.features(附件 map)。 遍历附加到此 Component 的 Features(按照五层洋葱模型,包括 Aggregate 级、子系统级、Release 级以及由 Manifest 注解驱动的附件),以作者为该附件指定的实例名称作为键。每个条目都带有相同的字段,参见下文的附件结构。写在该 Component 某个连接上的附件不在其中:它在该连接下读取,位于.context.uses.<alias>.features.<slot>,因此遍历.features的模板只会遇到该 Component 自身的附件。.metadata(struct)。 用于确定性命名的发布标识:release_name、release_version、environment、aggregate_name。每次渲染都会填充;其值来源于 Release 的metadata:块。.source。 Recipe 的source:,由源解析模板求值解析得到。对于无源的 Recipes 为nil;在源解析运行之前也为nil。在 FeatureRecipe 的模板上,它是该 FeatureRecipe 自身的source:,绝不是宿主组件的——参见附件 FeatureRecipe 界面。.workload。 解析后的 Workload 对象,在渲染出的workload:文档完成解码并通过其校验关卡后填充:校验内容包括 Workload schema、该 Component 针对其容器声明的每个附件的featuresSchema,以及每个附件所引用内容的可解析性。对于非合成的 Recipes 为nil;在 workload 合成运行之前也为nil。.steps(步骤输出 map)。 在 Wasm 插件运行时由pipeline:执行填充,通过.steps.<id>.outputs将已完成步骤返回的输出提供给后续步骤。步骤在自己的with模板中读取前面步骤的输出;一个步骤的outputs仅对在其之后声明的步骤可见。当节点未声明 pipeline 时,以及在节点的第一个步骤完成之前,该字段为空。
对该节点而言不包含任何内容的顶层字段——不合成任何工作负载的 Recipe 上的 .workload、没有源的 Recipe 上的 .source、没有附件的 Component 上的 .features——在值模板中读取为空,与 .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(字符串)。 所附加 Feature 的目录 URI。.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 使附件可被消费,而不仅仅是存在。声明了 schema.provides 契约的 Feature,其契约会针对实现它的 FeatureRecipe 强制执行——该 FeatureRecipe 必须发布每个声明的键——消费方则在此读取结果。因此,一个生成 ServiceAccount 并发布其名称的身份 Feature,可让消费方 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(字符串)。 节点的 provider 为其为该节点渲染的资源所取的名称——既来自你提供的源,例如 chart 读取的 release 名称,也来自它合成的 workload(当它以自己的某个名称命名该 workload 的资源时),正如helm使用同一个 release 名称那样。仅在该 provider 推导出名称时存在。在 Feature 附件的模板上,它是宿主 component 的名称,正如那里的.context.instance_id是宿主的身份;参见为渲染的资源命名。.context.labels(字符串值映射)。 目录编写的标签,加上在拓扑构建时由label-transform添加的标签。.context.annotations(三个分组,见下文)。 按来源分组的级联注解。.context.inject(机制映射,见下文)。 预先填充、经过拦截的交付管道——Recipe 模板读取跨 component 值的标准接口。.context.uses(连接映射,见下文)。 对出站拓扑边的 JOIN 投影。.context.self_inject(机制映射,见下文)。 对于开发者在组件自身的inject:块中写下的每个名称,给出该条目所交付的组件自身 provides 键,或其模板所读取的那一个自身值。.context.used_by(列表,见下文)。 其uses条目指向本 component 的各个 component。由附加到该 component 的 FeatureRecipe 在生成附件自身资源的模板上读取;在其他所有位置为空。.context.render_facts(列表映射,见下文)。 component 的 provider 针对其渲染输出所报告的内容,按事实名称作为键。由附加到该 component 的 FeatureRecipe 在其每个于 component 渲染之后运行的模板上读取;在其他所有位置不存在。
.context.annotations——三个分组
注解级联进入按来源作为键的三个分组:
.context.annotations.release——Release 边界注解(领域 4)。用于管理物理现实;渲染器在适当时将其路由到infra:字段。aggrega.ai/*知名注解位于此分组。.context.annotations.catalog——来自领域 2 的 Component 元数据注解。由架构师编写的不可变内在特征;主要由 Wasm 策略插件使用。.context.annotations.aggregate——来自领域 1 的 Aggregate 子系统注解。认知元数据;渲染器在适当时将其路由到values:载荷中。
每个分组都是扁平的字符串到字符串映射。按照架构的分离规则,这些分组用于不同用途;引擎不强制执行这种分离,因此要靠编写规范使各分组与其预期语义保持一致。级联注解的设计参见第 6 章 §2 流程 5。
.context.inject——交付管道
该管道是编译器预先解析的交付映射。当 Recipe 模板在基础渲染阶段运行时,每个注入来源(开发者编写的自注入字面量、针对自身 provides 解析的自注入 from: 引用、针对目标 provides 解析的跨 component uses[].inject 引用、FeatureRecipe injectMapping 拦截)都已解析为最终字符串值并合并到此映射中。
字段:
.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>。自定义机制的值来自 component 级自注入、uses[].inject边、Feature 附件的inject:映射,以及 FeatureRecipe 的injectMapping输出。对于 component 级自注入,Component 的spec.inject允许列表必须列出该机制,允许列表未列出的机制会使构建中止。自定义机制的条目也会与核心三种机制一起出现在.context.inject.all中。自定义机制可以使用除all之外的任何名称:该名称就是合并视图本身,因此同名的机制永远无法被单独读取。命名机制all的 inject 块,以及列出它的 Component 或 Feature 允许列表(spec.inject、socket 的inject),会在文档加载时使构建中止,拒绝信息会说明该名称属于这个合并视图。名称区分大小写,因此ALL是一个普通的自定义机制。
该管道是拦截后的状态:在 Recipe 模板读取它时,FeatureRecipe 的 injectMapping 块已在 inject 映射阶段将其覆盖值深度合并到此管道之上。映射可以替换由组件自身的 inject: 块、其某个连接的 inject: 块或其自身附件的 inject: 块所传递的键;而两个附加的 Features 通过各自的 inject: 块或映射都传递的键,会使构建中止,而不会以两个值之一进入此管道。附加到 Release 边界的 Feature 以同样的方式到达该组件,即通过其 FeatureRecipe 的 injectMapping;无论 FeatureRecipe 的 executionScope 如何,它都在该组件自身的上下文中运行——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 是编译器对当前节点每条出站拓扑边的增强视图。每个映射条目以本地 socket 别名为键(例如,当 Aggregate 编写了 uses: { databases: { primary: { target: ... } } } 时,databases.primary 变为 .context.uses.primary),并携带目标已解析状态的 JOIN 投影以及调用方的交付契约:
.target(string) — 目标节点的实例 ID。.socket(string) — 调用方的 socket 名称(即usesSchema键)。.provides(字符串值映射) — 目标已解析的provides:键(目标 Recipe 在 provides 求值时导出的公开输出字符串)。.inject(mechanism → key → value 的映射) — 该边的调用方 inject 指令(uses[].inject声明上的inject:块)。mechanism 键为env/file/arg/自定义;每个 mechanism 的映射条目是本地键 → 目标 provides 键的引用。.labels(字符串值映射) — 目标的标签,绝非消费方组件的标签:即目标自身.context.labels所携带的集合,包括其目录编写的标签以及拓扑构建时label-transform添加的标签。.annotations(三个桶) — 目标的release/catalog/aggregate注解桶。.component(string) — 目标的 Component 类型 URI。.resolved_version(string) — 经 Manifest 解析后目标的 Component 版本。.boundary_path(string) — 目标的 Release 边界路径,无论目标位于调用方的边界还是其他边界中都会设置。.origin_feature(string) — 当该边由 Feature 附件合成时设置(例如,一个 sidecar Feature 向某个凭据 Feature 贡献一条uses边)。.values(map) — 该连接已解析的逐边开发者配置,编写在 Aggregate 的uses条目上。仅当该边携带逐边 values 时存在。.infra(map) — 该连接已解析的逐边运维配置,编写在 Release 的uses条目上。仅当该边携带逐边 infra 时存在。.origin_release(boolean) — 当该连接由 Release 接线而非由 Aggregate 声明时为true;对于 Aggregate 声明的连接则不存在。.features(附件映射) — 编写在该连接上的附件,以 socket 声明的槽位名为键;参见下文。仅当该连接携带附件时存在。.render_facts(列表映射) — 目标的渲染对其输出所报告的内容,以事实名为键,形状与.context.used_by上调用方的.render_facts相同:每个事实都是一个列表,先是目标自身 provider 的调用,然后是其各个 Features 按渲染顺序排列,同一名称从各处得到的列表合并为一个。仅对设置了readsTargetRenderFacts: true的 FeatureRecipe 存在——其附件在所有组件渲染完成后才渲染,因此每个目标的渲染都已完成——此时存在于每个连接上,对 provider 未报告任何内容的目标为空。仅可在该 FeatureRecipe 的valuesMapping:、workload:和artifacts:中读取;在组件自身的 Recipe 模板、injectMapping:、pipeline:步骤的with:和when:中,以及在所有未设置该键的 FeatureRecipe 中均不存在——此类 FeatureRecipe 的模板若读取它,会在任何渲染之前中止构建。
这两个逐边配置映射都限定于消费方:它们只进入消费方节点的渲染上下文,绝不进入目标的渲染上下文。
提供的值在 .provides.<name> 处读取——提供的名称嵌套在 .provides 之下,而不是直接位于边上,因此 .context.uses.<alias>.<name> 不指向任何字段,也不产生任何值。
当连接的两端渲染到不同的输出中时,.provides 持有的是替身而不是值。 当 provider 在两个输出都组装完成后用自己的引用来连接这样的连接时——例如一个 CloudFormation 栈读取另一个栈的值——.context.uses.<alias>.provides 携带的每个值都是 provider 之后会替换的占位符,替换为跨栈引用或值本身,如其专属页面所述。这样的值应当复制,而不是比较——这与此类连接在 inject 管道上交付的值所遵循的规则相同,那也是同类占位符。应将其完整写出、写在更长的字符串中,或通过保持其原样的函数(例如 quote)写出。对从 .provides 读取的值进行比较、据其分支、测量或修改的模板,实际上是在针对占位符做判断,因此构建会改为中止,并指出该模板及其读取的每个值;请改为依据消费组件自身的值进行分支。该中止覆盖读取该连接 .provides 的每个模板,包括附加的 FeatureRecipe 的 injectMapping:,以及在 .boundary 下读取相同连接的边界作用域 FeatureRecipe。两端渲染到同一输出中的连接按原样携带其值。
一个别名对应一个连接,因此该映射为组件建立的每个连接都保存一个条目。 该映射仅以别名为键,无论连接接入哪个 socket;同一组件的任意两个连接都不能共用别名——无论在同一个 socket 上还是两个 socket 上,也无论各自由哪个文档或附件绘制。构建会在任何渲染之前拒绝这样的一对连接,并指出两个连接及各自的编写位置。一个列表两次指向同一目标就构成这样的一对,因为列表条目的别名就是其目标;models socket 上的 local 连接与 databases socket 上的 local 连接同样如此。
Recipe 模板使用此投影查找目标侧状态,而无需遍历 IR 图。FeatureRecipe 的 injectMapping 模板用它读取目标注解,以做出跨边界路由决策(entities/featurerecipe.md 中记录的 K8s DNS 解析器模式是标准的完整示例)。
遍历 .context.uses 的模板按键顺序(按别名排序)看到连接,而不是按 Aggregate 编写的顺序。 模板遍历的每个映射都是如此,包括 .features 和连接的 .features,因此模板无法通过遍历映射恢复编写顺序;在顺序有意义的地方,编写界面将其建模为列表。无论哪种方式,相同输入的多次构建所渲染的输出都逐字节一致。
连接的附件 — .context.uses.<alias>.features
编写在连接上的附件——位于 Aggregate 中组件 uses 条目的 features: 下,或位于 Release 中该连接的条目上——填充 socket 声明的一个槽位。就构建对它所做的一切而言,它是消费方组件的附件: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>指向连接的 socket 所声明的槽位(上例中为credential),因此访问多个目标的消费方会在各目标的别名下读取该目标自己的凭据。不携带附件的连接没有.features,因此读取时需加保护。 - 附件形状。 每个条目所携带的内容与组件自身某个附件的
.features.<name>完全相同——.type、.resolved_version、.labels、.values、.infra,以及绑定到它的 FeatureRecipe 的已解析.provides——参见附件形状。此处读取的 provides 正是该附件自身的 FeatureRecipe 渲染时所依据的值,因此消费方引用的名称与该 FeatureRecipe 输出的资源名称是同一个求值结果。 - 绝不在
.features中。 组件自身的.features只保存编写在其自身块上的附件。因此,一个遍历.features并按类型挑选附件的 Recipe——{{ 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(string) — 发起连接的组件的实例 ID,采用扁平化形式(frontend、data-layer.etl),即subDirectory:路径模板以.component_id读取的值。.socket(string) — 该连接在发起连接的组件上所填充的 socket(其usesSchema键)。.provides(字符串值 map) — 发起连接的组件所发布的内容,收窄到其 Component 声明的键:与该组件的使用方在.context.uses.<alias>.provides读取的值相同。组件的 Recipe 发布但其 Component 未声明的键不在其中。.source_namespace(string) — 发起连接的组件所在的命名空间:适用于它的aggrega.ai/namespace注解,沿其边界逐级向下传递,且以它在 Release 中自身的条目为准。若组件的 Release 条目设置了命名空间,或用null将其清除,则该组件携带自身的设置而非其边界的设置,因此该值指明组件自身资源渲染到的命名空间。当没有命名空间适用于该组件时不存在;应像示例那样通过with或if读取,而不要直接输出。.source_boundary_path(string) — 容纳发起连接的组件的 Release 边界路径,嵌套边界以/连接(edge、edge/inner)。.render_facts(列表的 map) — 发起连接的组件的渲染对其输出所报告的内容,按事实名称作为键,形状与.context.render_facts相同。每个事实都是一个列表,因此模板总是对其进行遍历,即使其中只有一个条目。其条目可能来自发起连接的组件自身的渲染,也可能来自挂载到它的 Features 的渲染:同一名称从各处得到的列表合并为一个,先是组件自身的 provider 调用,然后按渲染顺序依次是其各个 Features。仅对设置了readsCallerRenderFacts: true的 FeatureRecipe 存在——其挂载在所有组件渲染完成后才渲染,因此每个调用方的渲染都已完成——此时每个条目上都有,对于 provider 未报告任何内容的调用方则为空。未设置该键的 FeatureRecipe 在任何条目上都看不到.render_facts,其模板若读取它,构建会在任何渲染之前中止。
这两个放置值,正是边界作用域的 FeatureRecipe 在其 .boundary 边列表中同一连接的条目上以 source_namespace 和 source_boundary_path 读取的值:两种视图以相同方式读取组件的放置位置,因此二者从不冲突。这些列表中的边还携带每个端点的组装路径——source_assembly_path 和 target_assembly_path,即该端点的 provider 将其组装到的、位于构建输出目录下的目录——而 .context.used_by 条目不携带这些。
设置了 readsCallerRenderFacts: true 的 FeatureRecipe 读取每个调用方的事实的方式,与读取宿主的事实相同。对于记录了名为 ports 的事实、且每个条目都带有 port 的 provider:
artifacts: callers.yaml: | callers: {{- range .context.used_by }} - component: {{ .component_id }} ports: {{- range .render_facts.ports }} - {{ .port }} {{- end }} {{- end }}provider 未报告 ports 的调用方会渲染出空的 ports:,而不会失败,因为无人报告的名称读取结果为空。
该列表的行为:
- 按编写顺序。 条目遵循发起连接的组件的编写顺序,再遵循每个组件自身
uses条目的顺序。连接两次的组件出现两次,每个连接一次。由于它是列表而非 map,range按该顺序遇到各调用方——不做任何排序。 - 仅在挂载渲染其自身资源的地方。 FeatureRecipe 的
valuesMapping:、workload:和artifacts:读取它。在组件自身的 Recipe 模板、injectMapping:以及pipeline:步骤的with:和when:中它为空,因为这些产生的内容都可能落入组件自身的渲染输出:injectMapping:写入组件的交付管道,而 pipeline 步骤可能改写组件的文档。正因如此,无论谁使用某组件,其自身的输出都保持不变——为组件多接入一个调用方,改变的是挂载到它上面、读取其调用方的 Feature 的输出,而不会改变组件自身渲染的任何内容。 - 不含连接本身的任何信息。 条目不携带按连接的
values或infra,也不携带连接的任何挂载;这些保留在使用方组件上,位于其.context.uses.<alias>之下。 - 无组件使用时为空。 此时对其执行
range不会渲染任何内容。 - 只传递,从不解释。 身份、socket、已发布的值和放置位置都是编译器原样传递的字符串,渲染事实则是每个调用方的 provider 所报告的内容,按名称作为键。编译器不从名称推断任何东西,不获取任何东西,也不决定资源应允许哪些调用方;由模板决定。
provider 对一次渲染报告的内容 — .context.render_facts
组件的 provider 可以报告其渲染输出的事实——即它所写文档的某些属性,只有凭借它对自身格式的了解才能看出。provider 报告哪些事实、使用哪些名称、每个条目包含什么,是该 provider 自身记录的契约;provider 一侧的说明见 Reporting facts about what a guest emitted。例如 helm provider 会报告其输出的 pod 模板的标签、其控制器和 Service 的选择器,以及其容器的端口——见其 render facts。挂载到该组件的 FeatureRecipe 在 .context.render_facts 读取组件 provider 所报告的内容,按事实名称作为键。对于记录了名为 ports 的事实、且每个条目都带有 name 和 port 的 provider:
artifacts: ports.yaml: | ports: {{- range .context.render_facts.ports }} - name: {{ .name }} port: {{ .port }} {{- end }}- 每个事实都是列表。 provider 将每个事实都作为列表报告,即使其中只有一个条目,因此模板总是对其进行遍历——不存在可单独读取的单个值。
- 每个名称一个列表,在组件的整个渲染中合并。 渲染一个组件可能需要多次调用其 provider——例如一次 chart 渲染和一次 artifacts 放置——每次调用各自报告。同一名称从这些调用得到的列表按调用运行顺序合并为一个。组件所挂载的 Features 渲染的内容不在此列:无论组件的其他 Features 输出了什么,Feature 在
.context.render_facts只读取组件自身的渲染。 - 在所挂载 FeatureRecipe 的每个模板中。 其
valuesMapping:、workload:和artifacts:读取它,其pipeline:步骤的with:和when:也读取它——这些事实来自组件自身的渲染,因此读取它们不会使任何内容依赖于谁连接到该组件。它不存在于组件自身的 Recipe 模板和injectMapping:中,因为它们在组件渲染之前运行。 - 为空而非缺失。 当组件的 provider 未报告任何内容时,
.context.render_facts是一个空 map,无人报告的名称读取结果为空,因此对其执行range不会渲染任何内容,而不会失败。 - 顺序。 列表按 provider 报告的顺序保留其条目。对象条目与上下文中的其他 map 一样是带键的 map,因此遍历它的模板按键的顺序遇到其各个键。
- 只传递,从不解释。 编译器只检查每个事实的值是否为列表。它不读取名称或条目的任何含义;如何处理由模板决定。
断言的 .uses——先按 socket、再按别名作为键
assertions: 模板通过自己的一个更窄的视图读取同样的连接:.uses 位于根上而非 .context 之下,并且不携带连接目标所发布的任何内容,因为两个断言阶段都在渲染之前求值。它与编写形式 uses: <socket>: <alias>: { target: … } 相对应——以 socket 为键,每个 socket 之下再以其上每个连接的别名为键,以列表项形式编写的连接以其目标作为别名。每个连接的条目携带 target、alias,对于由 Feature 附加项引入的连接还携带 origin_feature,以及 .context.uses 所携带事实中的三项,名称相同、值也相同:.labels,即目标的标签;.values,即写在该连接上的值;以及 .features,即写在该连接上的附加项,以插槽为键。这三项在每个条目上都存在,连接没有相应内容时为空。.features 下的附加项只携带其 type、resolved_version 和 values——这是断言读取每个附加项(包括组件自身的附加项)时的形态,因为断言运行时,附加项的 FeatureRecipe 尚未解析其 provides。
持有一个连接的 socket 与持有多个连接的 socket 形态相同,因此断言以同样的方式读取二者。对于一个其 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" 判断该 socket 是否已连接,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(顶层) | 机制映射(可为空) | 渲染附件的 FeatureRecipe 时,且该附件编写了 inject: 块 | 该附件自身的 inject: 条目,按其块所列出的每种机制归类——env、file、arg,或诸如 vault_ref 之类的自定义机制——每个本地名称映射到其 from: 所指定的键。该键要么是 FeatureRecipe 在其 provides: 中发布的键(编译器也会将其交付到该组件的 .context.inject 中),要么是读取 .inject 的 FeatureRecipe 自己消费的键:如果某个条目指定了 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(顶层) | 机制映射(可为空) | 当开发者在父组件上编写了 inject: 块时设置 | 任何 inject-mapping 拦截之前未经修改的开发者意图。该块指明的每种机制——env、file、arg,或诸如 ssm_param 的自定义机制——都位于其自身名称之下,按书写顺序保存完全按原样书写的条目(in,以及 from 或 value):.inject_raw.ssm_param 读取自定义机制的方式与 .inject_raw.env 读取核心机制的方式相同。用于“开发者最初是否请求了这个交付键?”之类的逻辑检查;不受 FeatureRecipe injectMapping 重写的影响。如果开发者省略了 inject: 块,则为 nil。 |
.context.self_inject | 机制映射(始终存在) | 每次渲染;开发者未在组件上编写 inject: 块时为空 | 组件自身 inject: 块中的每个名称,映射到其条目所交付的自身键——provides.<key>、values.<key> 或为空。用于为开发者已交付的自身值跳过默认名称;参见上文。 |
需要拦截后已解析交付的作者应读取 .context.inject。需要不可变原始意图的作者(例如,为了检测拦截,或在开发者省略 inject 块时输出回退行为)应读取 .inject_raw。需要知道开发者已为组件自身的哪些值命名的作者应读取 .context.self_inject。
附件 FeatureRecipe 界面
当渲染器求值附件 FeatureRecipe 的模板时,会额外设置一个顶层字段:
.attachment_name(字符串) — 附件的实例名:即它在所属实体的featuresSchema中填充的槽位,或作者为其指定的自由名称。FeatureRecipe 的locals:、provides:、injectMapping:、valuesMapping:和artifacts:读取该字段,以派生确定性的资源标识符——当宿主的 provider 报告渲染名称时(如helm),使用{{ .context.rendered_name }}-{{ .attachment_name | replace "_" "-" }};当其不报告时,使用{{ .context.instance_id }}-{{ .attachment_name }}——并用于命名正在处理的附件。
基础 Recipe 自身的模板并不解析附件,因此该字段不属于其上下文:引用该字段的 Recipe provides:、locals: 或 source: 模板会中止并指出该引用,而不是渲染出空值。设置了 executionScope: boundary 的 FeatureRecipe 针对边界渲染一次,而不是每个组件渲染一次,因此为边界运行的模板同样无法使用该字段;其 injectMapping: 会针对附件所到达的每个组件运行,并在那里读取该字段。
在生成附件自身资源的模板上——即其 valuesMapping:、workload: 和 artifacts:——附件的上下文还会在 .context.used_by 中列出使用其宿主的组件;并且当其 FeatureRecipe 设置了 readsTargetRenderFacts: true 时,会在 .context.uses.<alias>.render_facts 中携带其宿主所连接的每个组件的渲染结果。这些模板及其 pipeline: 步骤还会在 .context.render_facts 中读取宿主的 provider 对宿主渲染所报告的内容。边界作用域的 FeatureRecipe 在渲染其资源时没有宿主组件,也没有 .context;它改为在 .boundary.internal_uses_edges 和 .boundary.incoming_cross_boundary_uses_edges 下读取进入其边界的每个连接。其 injectMapping: 是它编写的唯一一个在组件上下文中运行的模板——即附件所到达的每个组件的上下文,包括 .context.*——在那里引用 .boundary 会中止构建。
该字段是获取附件实例名的唯一途径。.context.instance_id 是附件所解析的宿主组件——在编译器求值的每个模板界面上,包括 FeatureRecipe 自身的 locals:,它都表示宿主——因此这两个名称不可互换,也不能相互替代。
.source 属于附件自身。FeatureRecipe 的 source: 模板在其 valuesMapping: 之前求值,正如 Recipe 的该模板在它自己的映射之前求值一样;它的求值结果就是 .source 在生成附件资源的模板——其 valuesMapping:、omits:、workload: 和 artifacts:——以及其 pipeline: 步骤上所持有的内容。它绝不是宿主组件的源:未声明 source: 或其模板未生成任何内容的 FeatureRecipe 在那里读不到任何内容,即使宿主的 Recipe 声明了源也是如此。边界作用域的 FeatureRecipe 在相同的模板上读取它自己的源。唯一的例外是 injectMapping:,它在附件的源求值之前运行,并像宿主组件自身的 Recipe 那样读取 .source。
.context.rendered_name 同样属于宿主组件:在按组件附件的每个模板上,它携带宿主自身的 provider 为宿主报告的名称——即宿主自身的 Recipe 读取的值——因此附件可以用 {{ .context.rendered_name }}-{{ .attachment_name }} 以宿主命名资源,即使宿主的标识包含下划线或大写字母,也能得到平台接受的名称。当宿主的 provider 报告名称时它存在,不报告时则不存在;在这样的宿主上,从 FeatureRecipe 内联编写的任何模板(injectMapping: 除外)读取它都会中止构建;参见命名渲染资源。
按位置的可用性
字段的可用性因模板位置而异。Recipe 的 provides: 模板在 provides 求值阶段运行,使用自包含的上下文(没有 .context.inject/.context.uses);Recipe 的 valuesMapping: 在基础渲染阶段运行,使用完整的模板上下文;FeatureRecipe 的 injectMapping: 在 inject 映射阶段运行,使用完整的模板上下文,其中包括被拦截的 inject 管道。完整的逐位置可用性表见 expansion-matrix.md;本页记录该矩阵“可用引用”一列所指向的字段结构。
交叉引用
05-templates.md— 模板概述。expansion-matrix.md— 按模板位置划分的求值矩阵。sprig-functions.md— 接入模板引擎的 Sprig 辅助函数。../entities/recipe.md— Recipe 编写接口。../entities/featurerecipe.md— FeatureRecipe 编写接口(包括用于.context.uses遍历的 K8s DNS 解析器完整示例)。../vocabulary/topology-triad.md— 注入契约规范(涵盖双状态上下文、键冲突规则和完整示例)。../10-status.md#compilation-pipeline-phases— inject 映射、基础渲染和插件流水线接口的当前就绪状态。