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

FeatureRecipe

FeatureRecipe 实体的概念角色(领域 3——由 Wasm 插件驱动的 Feature 接口实现)见 architecture/04-entity-taxonomy.md。本页介绍 FeatureRecipe 目录的编写接口。

目录位置

FeatureRecipes 按 provider 组织在路径的首段(与 Recipes 的模式相同):

aggrega-catalog/
└── feature-recipe/
└── {provider}/ # e.g., `helm`, `compose`
└── {feature-recipe-name}/
└── {version}/
└── recipe.yaml

OCI URI:hub.aggrega.ai/featurerecipe/{provider}/{name}:{version}(例如 hub.aggrega.ai/featurerecipe/helm/k8s-secret-from-parameter:1.0.0)。

编写契约

FeatureRecipes 通过 implements 绑定到一个 Feature 接口,并声明一个具体的 provider。其编写面是基础 Recipe 的全部输入类型,外加两个 FeatureRecipe 专有的块:

  1. 三种输入类型——source + valuesMapping(源引入)、workload(合成)和 artifacts: 形状与基础 Recipe 完全相同(参见 Recipe 输入组合 和 entities/recipe.md)。携带其中任意一种的 FeatureRecipe 是生成资源的——它会在基础 component 旁边渲染资源。这些资源的落点依次带有该 Feature 所附加的 component 以及其附加时使用的名称,采用目标自身布局所允许的两种形式之一:在 provider 为每个贡献者提供独立位置的目标上,作为与其宿主目录并列的 {component}--{instance}/ 目录,位于该目标用来存放贡献者的目录之下;在只读取直接位于某目录中文件的目标上,作为与该 component 自身文件并列的 {component}--{instance}-- 文件名前缀。在将其贡献者组合成单一文档的 provider 上,这些资源则被并入该文档——无论该 Feature 属于哪个系列:作为内联或 $import artifacts: 的 ServiceMonitor 或 ExternalSecret CRD;通过 source: + valuesMapping: 引入的外部 chart 或模块;或通过 workload: 定义的自有计算资源(例如一个 sidecar 代理 Deployment)。valuesMapping: 与基础 Recipe 共享三种编写模式(内联块标量、文件 $import:、指向 MappingLibrary 条目的库 $import:)——参见 entities/recipe.md “The valuesMapping field — three authoring modes”。按照约定,FeatureRecipe 修改基础 component,或在其旁边添加资源,但 schema 并不限制它可以使用哪些输入类型——编译器会渲染 FeatureRecipe 声明的任何内容,仅受所绑定 provider 能力的约束,并且对某种类型是否“适合作为修改器”不预设立场(参见基础不变量)。合成(workload:)需要支持它的 provider;否则构建会在渲染阶段因 provider 能力诊断而中止。
  2. injectMapping(渲染前拦截): 一个原生 Go 模板块,在基础 Recipe 渲染之前执行。它输出一个 JSON 或 YAML 字典,由编译器原生深度合并到调用方的 .context.inject 内存管道上,从而无需 Wasm 即可在调用方侧修改环境变量和连接字符串。
  3. pipeline: 一个由 WebAssembly(Wasm)插件步骤组成的顺序数组,用于渲染后的 Workload 变更(例如通过 JSONPatch 注入 Envoy sidecar,或挂载 secret 卷)。每个步骤的 plugin 字段通过 URI 指定一个 Plugin 实体,并始终以该插件自身的插槽类型限定(<pluginType>/<name>,可选带版本,如 parser/yaml 或 parser/yaml:1.0.0);构建会将该实体解析为其按内容寻址的 .wasm 制品,该制品根据插件的标识和所配置的 registry 定位;此处不接受裸 .wasm 或制品引用。有关编写和引用插件,请参见 Wasm 插件开发者指南;有关双部分插件原则(Fetcher / Injector),请参见 architecture/04-entity-taxonomy.md §“Domain 3: Infrastructure Base”。编译器按声明顺序执行每个步骤:针对渲染输出调用所指定插件的 guest 导出,并应用返回的 JSON Patch 和产生的副作用;各流水线环节的执行状态请参见语言状态。pipeline: 可以独立存在:FeatureRecipe 可以只声明它而不声明任何输入类型,此时它不产生自己的资源,其全部效果就是其步骤对构建已渲染文档所打的补丁,或在这些文档旁边产生的内容。

FeatureRecipe 也可以不携带上述任何块:一个纯连线的 Feature,其效果就是它所携带的 uses 边,不渲染任何内容,其 FeatureRecipe 的存在只是为了满足解析——每个 feature 实例都解析到一个 FeatureRecipe,正如每个 component 都解析到一个 Recipe。在上述块中,injectMapping 是唯一在基础 Recipe 中没有对应项的字段;三种输入类型和 pipeline 与基础 Recipe 共享。

FeatureRecipe 旁边固定的内容与 Recipe 旁边固定的内容相同: 每个 artifacts 条目所导入文件的摘要,以及每个完整写出坐标的远程 source: 的摘要,记录在 FeatureRecipe 自身目录中的 entity.lock 里,该文件由 aggrega pin 写入,你将其与 FeatureRecipe 一同提交。若对某个 FeatureRecipe 执行 pull,而其锁文件未记录这些固定值,则 pull 会中止并指出该步骤,除非要求 pull 执行该步骤。当导入的文件不再与其摘要匹配,或某个源的摘要与 Release 锁文件记录的不一致时(以 git ref: 写出的源按其解析到的提交记录,不进行比较),构建会中止;FeatureRecipe 文件本身永远不会被写入。aggrega pull 介绍了该文件以及如何应对每种中止。

Source 字段模板化

FeatureRecipe 的 source: 是一个模板化表面,条件与 Recipe 的相同:模板在源解析时求值,求值产生的结果就是构建随后解析的内容。两种形态都接受 Go 模板——通用字符串形式,以及结构化对象形式;后者中字符串值的子字段会进行模板求值,非字符串子字段则原样传递。形态清单、scheme 处理和锚定方式与 entities/recipe.md 中“Source field templating”“Source field scheme inventory”和“How a source: path is anchored”所述相同;本节只说明附加项有所不同之处。

locals:
chart_dir: ./charts/exporter
source: "{{ .locals.chart_dir }}"

相对结果相对于什么解析。 相对于声明它的 FeatureRecipe 文档所在的目录——即附加项自己的文件所在目录,而绝不是 component 的——并且结果必须留在该目录之内,与 Recipe 完全相同:跳出该目录的结果或绝对路径,所指向的文件不会随 FeatureRecipe 一起分发,会使构建中止。带有传输 scheme 的结果会被获取,而不是拼接到目录上。从注册表解析的 FeatureRecipe 从其发布归档所携带的文件中读取,这些文件布置在内容缓存中,因此相对结果在已发布内容内部解析,方式与它在目录中的 FeatureRecipe 旁边解析完全相同,并受同样的边界限制。

模板可以读取什么。 引用集合就是 FeatureRecipe 自己的 locals: 条目所检查的那个集合,它与 Recipe 的集合有两处不同,原因在于被解析的是附加项而不是 component:

  • .attachment_name 可用,它指明 Feature 附加时所用的实例名。Recipe 的源模板拒绝它,因为 Recipe 的源是为节点解析的,不涉及任何附加项。
  • .context.instance_id 指明附加项正在为之解析的宿主 component,而不是附加项本身;.context.rendered_name 携带宿主自身的 provider 为宿主报告的名称——仅在该 provider 报告了名称时存在,未报告时会使构建中止。参见为渲染出的资源命名。

.locals 携带该 FeatureRecipe 其他模板所读取的集合:它自己已解析的块,其下是宿主 Recipe 的块,因此附加项声明的键会覆盖宿主中同名的键。引用该集合中不存在的键会中止并指明该键,而不是把该键渲染为空。.provides、.context.inject 和 .context.uses 会被拒绝,理由与 Recipe 的源表面拒绝它们的自包含理由相同。

边界作用域的 FeatureRecipe 改为读取边界。 若某个 Feature 的 FeatureRecipe 声明了 executionScope: boundary,它会针对边界渲染一次,而不是每个 component 渲染一次,因此它的源模板没有可读取的宿主 component。它读取 .boundary.*——与其 locals: 和 provides: 读取的支柱相同——而逐 component 的支柱(.context、.workload、.attachment_name、.inject)对它不可用。

空结果。 不产生任何内容的模板会使附加项没有源,即无源模式——与 Recipe 的源采取的解读相同,并且不同于你自己写 source: ""。

之后 .source 读取的内容。 源在 valuesMapping: 之前求值,正如 Recipe 的源先于其自身的映射求值一样,而它产生的结果就是此后运行的每个模板中的 .source:valuesMapping:、omits:、workload: 和 artifacts: 主体,以及 pipeline: 步骤。因此,读取 .source 的 valuesMapping: 读取的是该 FeatureRecipe 自身的源,而绝不是它所附加到的组件的源;当该 FeatureRecipe 未声明源或其模板不产生任何内容时,它读取不到任何内容。边界作用域的 FeatureRecipe 以同样的方式读取自身的源。injectMapping: 在附加的源求值之前运行,因此那里的 .source 是宿主组件的。

injectMapping 的专属性

injectMapping 字段为 FeatureRecipes 专属——基础 Recipe schema 中有意不包含该字段。这种专属性将变量拦截与 valuesMapping 隔离开来:基础 Recipe 的 valuesMapping 在不知情的情况下消费由 FeatureRecipe 的 injectMapping 块生成的、已改写的 .context.inject 字符串,因此两者保持解耦。该机制的运行方式见下文的 inject-mapping 拦截一节,完整的渲染前拦截语义见 architecture/10-compilation-pipeline.md 中关于 inject mapping 的内容。

注入映射拦截:injectMapping 的工作方式

当调用方需要的目标连接字符串与目标未经修改的 .provides.host 形式不同时——例如为跨边界的 Kubernetes DNS 追加命名空间、为多区域网关添加区域代码前缀,或为 DSN 添加 SSL 模式后缀——injectMapping 会在调用方处理这一变更,且发生在基础 Recipe 的 valuesMapping 看到注入管道之前。

injectMapping 字段是一个 Go text/template,渲染器在注入映射阶段、基础 Recipe 渲染运行之前对其求值。该模板输出一个 JSON 或 YAML 字典,可包含可选的机制键(env、file、arg,或组件的 Recipe 在 .context.inject.<name> 处读取的自定义机制),也可以是默认归入 env 的扁平映射;渲染器将这一覆盖层深度合并到调用方节点的 .context.inject 管道上。通过 injectMapping 进行的调用方路由在注入映射阶段运行,进行简单的字符串处理时无需调用 Wasm 沙箱;Wasm 插件仍保留用于通过 pipeline 数组进行的结构性 AST 变更。

通过 toJson 写出每个值。渲染器以 YAML 读取模板的输出,因此原样插入引号之间的值,一旦包含双引号或反斜杠,要么会破坏该输出,要么读回时已被改变——密码就是常见情形。toJson 将值写成 JSON 字符串,YAML 能将其原样读回,因此该值会连同它所含的每个字符一起送达:

injectMapping: |
env:
{{ .values.key }}: {{ .values.origin | toJson }}

由多个部分拼接而成的值应先拼接好,再通过 toJson 一次性写出,如下面的示例所示。

无法读取的输出会使构建停止。当模板的输出无法读作这两种形式中的任何一种时——通常是因为引号括起的标量被其中的值破坏——它的任何键都无法送达,因此构建会中止并指出该挂接和该 FeatureRecipe,而不是像什么都没有送达那样渲染该组件;参见 fatal-halts.md 中的“An attached Feature’s injectMapping output cannot be read(无法读取已挂接 Feature 的 injectMapping 输出)”。当它给出的原因依赖于声明为敏感的值时,该原因会被隐去。为空的输出,或解析为不送达任何内容的字典的输出,不送达任何内容,也不算失败。

顶层键是一种机制,而 all 不是机制。字典输出的每个顶层键都指明其条目通过哪种机制送达:env、file 和 arg,或任何其他名称,后者会以该名称作为独立的机制送达。.context.inject.all 是在合并之后由这些机制构建出来的,从不从输出中合并,因此写在 all: 下的条目不会到达任何地方;构建会改为中止,指出该挂接、该键和该 FeatureRecipe,并说明输出可以携带哪些键——参见 fatal-halts.md 中的“An attached Feature’s injectMapping output writes deliveries under a key nothing delivers(已挂接 Feature 的 injectMapping 输出将送达内容写在了没有任何机制送达的键下)”。请将此类条目写在组件读取它们所用的机制下。

变更严格限于调用方本地。 FeatureRecipe 只修改其所附加节点的注入管道,绝不修改目标的 .provides 输出。目标的 .provides.host 可能被集群中的多个调用方使用;调用方的 injectMapping 只合并到特定调用方的管道中,因此路由变更始终局限于请求它的那条边。

映射可以重写什么。 在映射渲染时,所有 inject: 块都已完成交付,因此映射的输出总是合并到其他来源已写入的键之上——而由谁写入该键决定了结果。由调用方自身的 inject: 块或其某个连接的 inject: 块交付的键,映射可以重写:这就是拦截,映射的值会替换那一个条目。由映射自身的附加项通过其 inject: 块交付的键,同样可以由它重写。而由另一个已附加的 Feature 交付的键——无论是通过其自身的 inject: 块,还是通过其自身 FeatureRecipe 的 injectMapping——则不可重写:构建会中止并指出这两个附加项,而不是让最后运行的映射决定调用方读取哪个值。因此,两个路由 Features 可以各自限定属于自己的键,但两个 Features 不能同时交付同一个键——包括两个路由 Features 重写同一连接的键的情况,因为第一个属于拦截,而第二个会遇到第一个的交付;参见 fatal-halts.md “Two attached Features deliver one key, the later through its FeatureRecipe’s injectMapping(两个已附加的 Features 交付同一个键,后者通过其 FeatureRecipe 的 injectMapping)”。

零耦合的目标推断

由于编译器会将每个目标层叠后的注解嵌入调用方的 .context.uses 管道,injectMapping 模板无需运维人员将目标身份硬编码到 Feature 的 infra 中,即可提取路由坐标:

  1. 模板在 .context.uses 中搜索,找到注入开发者所请求变量的那条确切拓扑边。
  2. 提取目标层叠后的 release_annotations(例如 aggrega.ai/namespace)。
  3. 格式化完全限定域名(FQDN)或连接字符串。
  4. 输出覆盖字典。

编译器与网络语义无关——无论是 Kubernetes 命名空间、云区域还是桥接代理拓扑——只是用模板生成的任何内容执行深度合并。随后基础 Recipe 的 valuesMapping 运行时,会将 .context.inject.env 中经拦截和重写的字符串当作开发者的原始值来使用。

完整示例:K8s DNS 解析器

标准目录以 core/k8s-dns-resolver 的形式提供此功能,并附带一个 helm FeatureRecipe。由于环境变量名在容器内必须唯一,target_var(例如 API_HOST)可作为调用方内特定注入契约的全局唯一标识符。模板遍历 .context.uses 中的显式边,检查哪条边声明了 target_var,从而定位正确的目标节点并读取其命名空间。唯一的参数是要重写的变量;目标及其命名空间均通过发现获得,绝不硬编码。

路由 Feature 的 schema(core/k8s-dns-resolver):

infra: {
target_var: string # Ops dictates WHICH injected var to rewrite
}

FeatureRecipe 实现:

injectMapping: |
# 1. Grab the atomic base host directly from the flattened pipe, or an
# empty value when nothing was injected under target_var
{{ $base_host := optional .context.inject.env .infra.target_var "" }}
# 2. Dynamically locate the specific edge that injected this variable
{{ $target_edge := dict }}
{{ range $alias, $edge := .context.uses }}
{{ if hasKey $edge.inject.env $.infra.target_var }}
{{ $target_edge = $edge }}
{{ end }}
{{ end }}
# 3. Read the target's namespace from its cascaded release annotation,
# coalescing an absent namespace to "default"
{{ $ns := "default" }}
{{ if $target_edge.annotations }}{{ if $target_edge.annotations.release }}
{{ $raw := optional $target_edge.annotations.release "aggrega.ai/namespace" "" }}
{{ if $raw }}{{ $ns = $raw }}{{ end }}
{{ end }}{{ end }}
# 4. Qualify the host with the namespace — but only when a target connection
# and a base host were actually found, so a target_var that matches no
# connection injects nothing instead of a spurious variable. An unset
# namespace resolves to "default", where the helm provider deploys an
# unannotated workload, so the qualified host always matches the service's
# actual location and is never malformed.
{{ if and $target_edge $base_host }}
{{ $resolved_host := printf "%s.%s" $base_host $ns }}
# 5. Emit the precise override dictionary for the compiler to deep-merge
env:
{{ .infra.target_var | toJson }}: {{ $resolved_host | toJson }}
{{ end }}

路由之外的用例

injectMapping 最常用于跨边界的地址解析(如上文的 K8s DNS 解析器),但这种调用方侧的变更适用于任何需要在基础设施渲染之前拦截并格式化开发者意图的场景。下面另外两种模式展示了它的适用范围。

动态安全格式化(SSL 追加器)。 如果企业要求所有外部数据库连接都使用严格的 TLS 校验,Feature 可以拦截开发者请求的 DB_URL 并追加所需的 SSL 模式,使应用以正确的安全参数启动。

# Inside force-ssl-feature
injectMapping: |
{{ $base_url := index .context.inject.env .infra.target_var }}
env:
{{ .infra.target_var | toJson }}: {{ printf "%s?sslmode=verify-full" $base_url | toJson }}

多区域网关前缀。 如果一个通用 API 组件在全球部署,区域路由 Feature 可以自主查找其自身的环境边界注解,为其调用方注入的连接字符串添加前缀。

# Inside regional-router
injectMapping: |
{{ $base_host := index .context.inject.env .infra.target_var }}
{{ $region_code := index .context.annotations.release "cloud.aggrega.ai/region" }}
env:
{{ .infra.target_var | toJson }}: {{ printf "%s.%s" $region_code $base_host | toJson }}

injectMapping 的边界。 该机制仅限于变更 .context.inject 内存管道(交付契约)。它不能追加新容器、挂载卷,也不能更改基础 Recipe 的 valuesMapping 输出。任何需要对渲染后的 AST(如 JSON 或 YAML 数组)进行结构性更改的变更,都属于 FeatureRecipe 的 pipeline 数组,通过 WebAssembly 插件执行。

pipeline 的补丁目标边界。 pipeline 步骤只修补 provider 渲染为结构化树的输出。YAML 和 JSON 形式的输出是结构化的——包括以 JSON 编写的 Terraform .tf.json 模块——因此步骤的 JSONPatch 会原地编辑所寻址的值,其余每个字节(注释、顺序、格式)保持不变。provider 以不透明主体输出的内容(例如原生 HCL 的 Terraform 配置)不是补丁目标:针对不透明主体的补丁会以诊断信息中止构建,而不是去变更它无法按结构寻址的文本。因此,针对不透明输出编写 pipeline 步骤是一种设计错误,会以明确的中止呈现出来,而不是静默地什么也不做。

引入的 Terraform 模块的输入不是补丁目标,这一点值得说明。 它们是该组件 module 块的参数,由 terraform provider 写入边界的根配置中:这是原生 HCL,按上述规则属于不透明内容,并且是整个边界的产物,而不是该步骤所修补其输出的那个节点的产物。因此,pipeline 步骤无处可以寻址它们,也无法改变引入来源的 Terraform 模块所接收的内容。这些值在编写它们的地方成形——即基础 Recipe 的 valuesMapping: 中。

条件步骤 — when:

pipeline 步骤可以带一个可选的 when: 字段:这是一个内联 Go 模板,编译器在遍历 pipeline 时对其求值,所用的模板上下文和求值器与该步骤的 with: 主体相同。渲染结果决定该步骤是否运行。

  • 结果为假值时,该步骤作为直通被跳过:文档集原样流向下一个步骤,被跳过的步骤不产生任何作用——没有补丁,没有副作用,也没有运行过的记录。
  • 为空或缺失的 when: 始终运行该步骤。

when: 与 optional: 相互独立。when: 决定步骤是否运行;optional: 弱化正在运行的步骤的失败。一个步骤可以同时声明两者——when: 控制是否进入,而如果步骤确实运行,则由 optional: 决定如何处理其中的失败。渲染失败的 when: 模板属于编写缺陷,无论 optional: 如何都会中止构建。

渲染后的 when: 文本按共享的布尔模板规则判定:字符串 true、True 和 TRUE、任何非零数字以及任何其他非空字符串为真;字符串 false、False 和 FALSE、空字符串以及零值数字为假。

凭据 FeatureRecipe 模式

当一个 FeatureRecipe 实现凭据类 Feature(即带有 feature.aggrega.ai/kind: secret 标签的 Feature)时,它可以遵循 Two-Part Plugin Principle(两段式插件原则):一个 pipeline 串联一个 Fetcher 插件(生成特定于 vault 的 CRD)和一个 Injector 插件(将 secret 挂载到目标容器),即 examples/04-secrets 所描述的形态。标准库中的凭据类 FeatureRecipes 不声明 pipeline:,而是自行渲染 secret 资源;参见 examples/05-credential-features。

凭据 FeatureRecipe 与其他任何附件的 FeatureRecipe 一样,通过同一个资源生成阶段进行渲染,并且其 pipeline: 以相同的方式执行:编译器将在该阶段有工作的每个附件作为一个有序序列遍历,并运行每个附件声明的流水线,使用相同的 /own 和 /host 文档集语义。附件因以下两个原因之一加入该序列:其 FeatureRecipe 声明了输入类型,因而生成自己的资源;或者它声明了 pipeline:,因而改写已输出的文档。因此,凭据附件可以像运维附件一样深入宿主组件的渲染文档——挂载密钥卷、添加环境变量引用——两者唯一的区别在于其自身生成的文件落在何处。

在组件上,Feature 上的敏感性声明遵循 FeatureRecipe 的 valuesMapping:,与 Component 的声明遵循其 Recipe 的方式完全相同。 当 FeatureRecipe 从没有 valuesMapping: 的 source: 渲染时,其目标接收的值以 Feature 声明的叶子路径为键,因此声明为 sensitive: true 的叶子会标记其渲染后的键。当 FeatureRecipe 声明了 valuesMapping: 时,这些键由该模板自行生成,没有任何声明为其命名,构建会针对每个这样的叶子打印一条提示,指明附件、叶子和 FeatureRecipe。附加到边界的 Feature 不会产生提示:其 .values 始终为空,因此没有任何已声明的叶子有值可供标记——请参阅 A declared-sensitive value reaches the target through a values mapping(声明为敏感的值通过值映射到达目标)。

provides: 块——向使用方发布

FeatureRecipe 的 provides: 块是它发布的输出:一个以字符串为值的 Go 模板映射,在该附件自身的作用域(.values、.infra、该 FeatureRecipe 完全解析后的 .locals,以及宿主节点的 .context.instance_id 和 .context.rendered_name)中求值。locals 先解析,因此 provides: 条目读取它们时得到的是已解析的值;引用 locals: 块未声明的键会导致中止。附件正是通过它告诉使用方自己产出了什么——所生成资源的名称、生成的数据键、云身份——而使用方无需从相同的输入重新推导该标识。

使用方在 .features.<instance-name>.provides.<key>(对于凭据附件则为 .features.<slot>.provides.<key>)读取它,这与 uses 边的 .context.uses.<alias>.provides 相对应。如果附件写在使用方的某个连接上,使用方在该连接下的 .context.uses.<alias>.features.<slot>.provides.<key> 读取同一映射,且该附件不在其 .features 中(参见连接的附件)。附件自身的 inject: 块会针对同一映射解析其 from: 引用,因此作者可以任选一种通道:provides 用于模板读取,inject 用于投递到环境变量、文件或参数。

# FeatureRecipe: emits a ServiceAccount and publishes its name.
provides:
name: "{{ .infra.service_account_name }}"
# Consuming Recipe: binds the pod to what the attachment published.
workload: |
serviceAccount: "{{ .features.identity.provides.name }}"

当该 FeatureRecipe 所 implements 的 Feature 声明了 schema.provides 契约时,该契约会针对 FeatureRecipe 强制执行:Feature 声明的每个键都必须出现在 FeatureRecipe 的 provides: 中,否则构建中止并指出缺失的键。允许发布额外的键——契约是下限,而非上限。值从不被检查;它们是由运行时解析的不透明确定性指针。

解析在每个附件上只发生一次,且在使用方渲染之前;同一个已解析的映射同时供给使用方的读取、契约检查以及附件自身的 Resource Generation——因此使用方读到的内容与附件生成的内容不可能不一致。

Provider 与 implements

spec.capability 是必填项,指定其 Wasm 渲染插件负责渲染该 FeatureRecipe 输出的 provider(helm、helm-chart、compose 等),其规则与 Recipe 的 spec.capability 相同(参见 entities/recipe.md):版本固定用于选择由该插件的哪个版本进行渲染,它不属于 FeatureRecipe 的名称——Manifest 将声明了 capability: "compose:1.2.3" 的 FeatureRecipe 映射为 compose/<name>:<version>,而在名称中写入版本固定的映射值会在任何查找之前被作为格式错误的 recipe 引用(E0095)拒绝。implements 字段将该 FeatureRecipe 绑定到其 Feature 接口,支持精确匹配、主版本兼容范围匹配或无版本匹配——关于 implements 版本匹配语义,参见 vocabulary/inheritance-and-interface。

执行范围 — spec.executionScope

可选的 spec.executionScope 枚举用于选择资源生成(Resource Generation)的分派模型。它接受两个值;省略该字段时默认为 component。

  • component(默认)。 FeatureRecipe 的资源生成对每个挂接的组件实例运行一次。每次调用都会收到一个以 .context.* 为根的按组件的模板上下文:.context.instance_id、.context.inject、.context.uses、.context.annotations 等。它的 valuesMapping:、workload: 和 artifacts: 还会读取 .context.used_by,即其 uses 条目指向宿主的那些组件,每个都带有其身份、其 socket、其发布的内容,以及它所在的命名空间和边界;宿主自身渲染的任何模板都看不到这些信息。
  • boundary。 资源生成对每个挂接的边界运行一次,无论该边界子树中有多少组件使用该 feature。每次调用收到的是以 .boundary.* 而非 .context.* 为根的边界范围模板上下文。

上文所述的 injectMapping 拦截始终按使用方进行,与 executionScope 无关。每个使用该 feature 的组件仍会得到自己的调用方侧 .context.inject 重写。只有资源生成步骤(source/valuesMapping 和 pipeline 数组)会在边界范围内去重。

因此,边界作用域 FeatureRecipe 的模板在两种作用域中运行。 它的 injectMapping 针对挂接所到达的每个组件各运行一次,基于该组件的上下文——也就是组件作用域 FeatureRecipe 的 injectMapping 所读取的上下文:.context.*、.attachment_name、.features,以及挂接自身的 .values、.infra 和 .locals。其中 .infra 是边界挂接的 infra: 块,.locals 是针对边界求值一次的块。它编写的其他所有模板——包括其 locals:、provides:、source:、valuesMapping: 和 artifacts:,以及其流水线步骤的 with: 和 when:——都针对边界运行一次,基于下文所述的边界作用域上下文。每个模板都按其运行的作用域进行检查:读取 .context.instance_id 的 valuesMapping: 会使构建停止,而读取它的 injectMapping 会渲染出该组件的标识。任何组件的上下文中都不设置 .boundary,因此无论 FeatureRecipe 的 executionScope 是什么,读取它的 injectMapping 都会使构建停止并指出该引用。

边界范围的模板上下文

当 executionScope: boundary 时,FeatureRecipe 中除 injectMapping 以外的模板针对该 feature 所挂接边界的 .boundary.* 视图求值。该视图提供:

  • .boundary.path — 该 feature 所挂接的 Release 边界的路径:从最外层向内的各边界名称,以 / 连接(bridge、bridge/frontend)。它指代边界本身,而不是其输出写入的目录,后者由 directory: 设置(取代 .context.instance_id)。
  • .boundary.assembly_path — 挂接自身输出被组装到的目录,相对于构建的输出目录:即边界求值后的 directory: 和 subDirectory:,也就是构建将该输出路由到的目录(bridge/compose)。当且仅当某个连接端点渲染到同一个组装文件中时,它才等于该端点的 source_assembly_path 或 target_assembly_path,因此 FeatureRecipe 通过比较它们来区分位于自身文件内的连接和位于其他文件中的连接。
  • .boundary.boundary_name — 该边界在 Release 中编写的名称。
  • .boundary.components — 以实例 ID 为键的映射,包含该边界子树中的每个组件(instance_id、component、resolved_version、boundary_path)。
  • .boundary.internal_uses_edges — 两个端点都位于该边界子树内的 uses: 边(compose-bridge 模式会枚举这些边,保留两个端点都组装到其自身 compose 文件中、且位于该文件不同网络上的边,以推导其按边的代理配置)。每条边都带有其端点解析后的 provides、注入的环境变量,以及每个端点的放置信息:source_namespace 和 target_namespace,即适用于该端点的 aggrega.ai/namespace 注解(端点自身的 Release 条目有设置时取该设置,否则取其边界的设置);source_boundary_path 和 target_boundary_path,即容纳该端点的 Release 边界的路径;以及 source_assembly_path 和 target_assembly_path,即其 provider 将其组装到的、位于构建输出目录下的目录,由其边界求值后的 directory: 和 subDirectory: 组成(bridge/compose)。组装路径相同的两个端点渲染到同一个组装文件中;在没有适用的命名空间时,compose provider 将组装路径视为该端点的网络。
  • .boundary.outgoing_cross_boundary_uses_edges — 源在子树内、目标在子树外的边。
  • .boundary.incoming_cross_boundary_uses_edges — 目标在子树内、源在子树外的边(供 ingress 类聚合器使用)。
  • .boundary.cross_boundary_uses_edges — 传入和传出跨边界边的并集,供需要完整跨边界视图的 FeatureRecipe 使用。
  • .boundary.labels — 子树标签的并集,保留编写顺序。
  • .boundary.annotations — 该边界自身的注解加上级联注解。
  • .boundary.feature_attachments — 挂接在该边界上的每个 feature(以便边界范围的 FR 在需要时检查同级 feature)。

边界范围 FR 上的 .infra 支柱解析为挂接到边界的 feature 的 infra: 块(在 Release 侧为该边界挂接编写的物理规格)。对于边界范围的 FR,.values 始终为空:Release schema 的支柱拆分规则禁止在 Release 级别的 Feature 挂接上使用 values:,因此挂接到边界的 feature 没有可投射的值。需要参数形态数据的边界范围 FR 应通过 .infra(运维人员编写边界 feature 配置的入口)或通过 .boundary.annotations(在该边界或任一祖先上编写、可级联解析的字符串值)来获取;.parameters 不属于该视图,读取它的模板会停止并指出该视图定义的根。.locals 仍是 FR 自身的 locals 块。.steps 和 .metadata 保持不变。

边界范围模板字段允许列表

除 injectMapping 外,边界范围 FR 的每个模板都只能引用边界范围视图中可用的字段。当 executionScope: boundary 时,如果此类模板引用了仅限按组件的字段(例如 .context.instance_id、.context.inject、.context.uses),该 FeatureRecipe 会在解析时验证失败,错误信息会指出该 FR、违规字段以及边界范围视图定义的字段。反方向同样适用对应规则:引用 .boundary.* 字段的组件范围 FR 也会在同一验证器中失败。injectMapping 在两种作用域下都按其运行所在的组件上下文进行检查,因此它可以读取 .context.*,而其中对 .boundary 的引用会停止并指出该引用以及该上下文定义的根。

该验证器执行与路径模板变量允许列表相同的模板 AST 遍历,只是每种范围使用不同的引用集合。

去重与资源生成输出

对于 executionScope: boundary,编译器按元组 (boundary_path, FR-instance) 对资源生成去重。同一边界子树中的两个组件使用同一个挂接到边界的 feature 时,只触发一次 FR 调用,而不是两次。同一 feature 的跨边界挂接在每个边界中独立运行。

边界范围的 FR 对每个 (boundary_path, FR-instance) 元组输出一组非中间文件,文件所在位置取决于 provider 如何组合其边界的输出。此处仅以实例名作为坐标,而组件范围的挂接还会带上其组件:边界范围的 feature 挂接在边界上而非任何组件上,因此外层的边界目录已经表达了组件段所能表达的全部信息,也没有组件可供命名。

将每个文档直接写入边界目录的 provider 会声明其目标只读取直接位于某个目录中的文件。因此不存在可供挂接放置的外层目录,实例名改为用作文件名前缀:<boundary_directory>/<fr-provider>/<feature-instance>--<file>,与边界自身的文件并列。实例名会被编码,因为文件名没有可依赖的分隔符;它与文件自身名称之间以一个任何编码坐标都不可能包含的双字符边界相接,因此两个输出同一文件名的挂接仍会生成两个文件。

将其边界输出组合进外层结构的 provider(一个 chart 为每个贡献者包含一个 chart,一个根配置为每个贡献者包含一个模块)会把每个贡献者放在各自的子目录中,而边界挂接和其他贡献者一样也是贡献者。其输出位于 <boundary_directory>/<fr-provider>/<contributors-directory>/<feature-instance>/,其中 <contributors-directory> 是该目标对其子单元所在位置的称呼。该子目录带有挂接的实例名,即你在边界的 features: 块中为其编写的名称,因此构建生成的目录可以在你编写的内容中找到。

中间输出会在 FR 求值后的路径上、以 FR 自身的 spec.capability 流向该边界的按(路径,provider)组装器;core/compose-bridge Feature 正是借助这一机制,在同一组装路径上将一个 bridge 服务与按组件的 compose 贡献者合并。此类输出只会作为在该处由边界的组件组装而成的文件的一部分写出,因此如果没有任何组件落在该路径上——例如每个组件都被其 subDirectory: 发往别处——构建会停止并指出该边界、该 Feature、其输出被路由到的路径以及 provider,而不是将输出写到无处(参见 fatal-halts.md 中的“A boundary-level Feature’s output reaches no assembled file(边界级 Feature 的输出未到达任何组装文件)”)。

感知级联的 provides: 解析

边界作用域的 FR 为每个 (boundary_path, FR-instance) 元组生成一组 provides:,并只求值一次。FR 的 provides: 模板使用边界作用域的模板上下文求值(因此可以引用 .boundary.components、.boundary.path、.infra,但不能引用按使用方划分的字段,也不能引用 .values)。provides 的值相对于使用方是常量——边界子树中的每个使用方看到的都是相同的提供值。

使用方对边界作用域 FR provides 的解析在所有地方读取的都是那一次求值的结果。挂接所到达的每个组件都在 .features.<instance-name>.provides.<key> 读取它——无论是在其自身 Recipe 的模板中,还是在 FeatureRecipe 自身的 injectMapping 中(后者在该组件的上下文中运行)。通过挂接所带的 uses 边在 .context.uses.<feature-alias>.provides.<provided-name> 读取的使用方 Component 会得到相同的值:编译器将其解析为该使用方所在边界的边界作用域 FeatureRecipe 的 provides:,从使用方的 uses 边(携带每个挂接的特性实例标识)走到边界作用域 FR 的 provides:。一个预处理阶段会在使用方组装之前对这些 provides 求值,因此在构建使用方的管道时这些值已经存在。

按使用方的效果是一张写在 provides: 中、由 injectMapping 读取的表。 需要为每个使用方改变某些内容的边界作用域 FeatureRecipe,会在其 provides: 中根据边界的连接一次性计算出一张以使用方为键的表,而其 injectMapping 读取当前组件的行——(index .features .attachment_name).provides,以 .context.instance_id 为键——并按照每个映射都遵循的规则,通过使用方自身的管道交付这些行(参见映射可以改写什么)。编译器只负责传递 FeatureRecipe 写出的表,不读取其中的任何内容。

compose-bridge 模式

compose-bridge FeatureRecipe 是边界作用域 FR 的典范模式,它是用上述机制编写的 catalog 内容:编译器和 compose provider 都不包含任何 bridge 逻辑,因此 catalog 可以用不同方式实现 core/compose-bridge Feature。一个 core/compose-bridge feature 挂接在一个父边界上,该父边界包含两个共享 directory: 的子边界(例如 services-net 和 data-net),每个子边界都带有自己的 aggrega.ai/namespace 注解(aggrega.ai/namespace: services-net、aggrega.ai/namespace: data-net),从而各自落在独立的网络上;如果没有这些注解,两者会共享以其 compose 文件路径命名的同一个网络,无需 bridge 即可互相访问。其 executionScope: boundary 使 FR 对每个父边界挂接运行一次。

它的 provides: 一次性计算出 bridge 表。 它从 .boundary.internal_uses_edges 中保留两个端点都组装到其自身 compose 文件中的边——source_assembly_path 和 target_assembly_path 都等于 .boundary.assembly_path——且两个端点位于该文件的不同网络上;端点的网络是其 aggrega.ai/namespace,若没有则为其组装路径。位于两个 compose 文件之间的边不会被桥接,其使用方保留目标自身的名称。每条被桥接的边都会获得一个监听端口——即目标自身的端口;若某条更早的边已在该端口上监听,则为不低于挂接的 portBase(默认 10000)的第一个空闲端口——以及一个上游,即目标发布的主机(由挂接的 providesField 指定的 provides 字段,默认 host)及其 port;上游由边推导得出,从不手工编写。它还从同一张表计算每个使用方的改写:边从主机字段交付的变量变为 aggrega-gw:<listen port>;如果同一条边还从 port 交付了一个变量,则主机变量变为 aggrega-gw,而该端口变量变为监听端口。

它的 injectMapping 交付每个使用方的行。 它在每个使用方的上下文中运行,从 .features.<attachment>.provides 读取该使用方在表中的行,并将其交付到使用方自身连接所交付的值之上(例如 DB_HOST),这属于拦截;没有对应行的使用方不会收到任何内容。如果该键由挂接到使用方的另一个 Feature 交付——通过其 inject: 块或其 injectMapping——构建将停止并指出这两个 Features,而不是替换该交付(参见 fatal-halts.md 中的“Two attached Features deliver one key, the later through its FeatureRecipe’s injectMapping(两个已挂接的 Features 交付了同一个键,后者通过其 FeatureRecipe 的 injectMapping)”)。网关的 listen 与使用方的改写读取自同一张表,因此在构造上按边一致,包括经 portBase 重新分配的冲突。

它的 valuesMapping 编写网关。 FeatureRecipe 自身的 compose 片段声明了 aggrega-gw 服务。只要有任何内容被桥接,其 valuesMapping 就会为每条被桥接的边添加一个 nginx stream server 块(listen <port>; set $uN <target-host>:<target-port>; proxy_pass $uN;,位于 resolver 指令之下,使每个上游在连接时解析,而不是在启动时解析一次;这些变量中的 $ 写作 $$,以便 Docker Compose 的 $ 插值为 nginx 留下字面量 $),并作为挂载的 compose 配置交付——一个带内联 content: 的顶层 configs: 条目,由 aggrega-gw 引用并挂载到 /etc/nginx/nginx.conf(因此 nginx 无需编写 command: 即可加载它)。内联 configs.content 需要 Docker Compose ≥ 2.23.1。它还在网关的 x-aggrega-networks-of 下列出每个被桥接的端点,compose provider 会将其解析为这些端点所在的网络,因此网关会加入其桥接边所跨越的每个网络(使用方的网络和目标的网络)——在运行时,使用方可以访问 aggrega-gw:<port>,网关也可以 proxy_pass 到目标。如果没有任何内容被桥接,片段声明的网关仍会被渲染,但处于空闲状态:没有配置、没有额外网络,也没有改写。

按(路径,provider)划分的 compose 组装器将网关与按组件的贡献者合并到同一求值路径:一个包含所有组件及桥接网关的 docker-compose.yaml。如果边界的组件都没有被组装到网关所在的文件中,构建会停止,而不是将网关写到无处。上游是一个确定性的编译期 compose 服务指针;由 compose 的运行时 DNS 解析(不进行编译期的运行时解析)。

在调用方之后渲染 — spec.readsCallerRenderFacts

可选的 spec.readsCallerRenderFacts(布尔值,默认 false)声明此 FeatureRecipe 的模板会读取连接到其宿主的组件所渲染的内容:即这些调用方各自的 provider 就其输出所报告的渲染事实。provider 报告什么、以何种名称报告,由该 provider 自己的契约决定;报告关于 guest 输出内容的事实描述了 provider 可以报告的事实。

此类挂载何时渲染。 构建按固定顺序逐个渲染其组件,挂载通常紧跟在其所挂载的组件之后渲染。连接到宿主且在该顺序中靠后的组件,此时尚未渲染,因此它输出的内容还不存在,无从读取。FeatureRecipe 设置了 readsCallerRenderFacts: true 的挂载,会改为在构建中的每个组件都渲染完成后再渲染,并与所有既未设置此键也未设置 readsTargetRenderFacts 的挂载一起渲染——因此在求值该挂载之前,每个调用方的渲染都已完成。其输出落在原本会落到的位置,名称也相同;此键改变的是挂载何时渲染,而不是渲染什么。较晚的渲染会带来一个顺序上的结果:当 FeatureRecipe 带有改写其宿主组件文档的 pipeline,且宿主的 provider 输出离散文档时,这些步骤会在宿主其他挂载的 pipeline 之后运行,而不是按它们的挂载顺序运行。

它读取什么。 设置此键后,.context.used_by 的每个条目都带有 .render_facts:即该调用方的渲染事实,以事实名称为键。每个渲染事实都是一个列表,因此模板始终需要对其进行 range 遍历——即使它只有一个条目。 其条目可以来自调用方自身的渲染,也可以来自挂载到该调用方的各个 Features 的渲染:同一名称从各处得到的列表会合并为一个,调用方自身的 provider 调用在前,然后是其各个 Features,按它们的渲染顺序排列。调用方的某个 Feature 如果自身也设置了此键,同样会在所有组件之后渲染,因此它报告的内容不在其中。如果调用方的 provider 什么都没有报告,它带有的 .render_facts 为空,因此无人报告的名称读出来为空:

artifacts:
callers.yaml: |
callers:
{{- range .context.used_by }}
- component: {{ .component_id }}
ports:
{{- range .render_facts.ports }}
- {{ .port }}
{{- end }}
{{- end }}

存在哪些事实名称、每个条目包含什么,由调用方的 provider 的文档化契约决定——例如 helm provider 的契约就是它的渲染事实,其中给出了它所渲染的 pod 的标签。调用方的事实位于 FeatureRecipe 的 valuesMapping:、workload: 和 artifacts: 所读取的连接上;pipeline: 步骤的 with: 和 when: 完全看不到连接到宿主的组件,因此步骤只读取宿主自身的事实。每个挂载到组件的 FeatureRecipe——无论是否设置此键——都在 .context.render_facts 处以相同的结构读取该组件自身的事实;模板上下文对这两者都有描述。

只要模板读取这些事实,就要声明该键。 在未设置该键的 FeatureRecipe 中内联编写的模板(其 valuesMapping:、其 workload: 或某个 artifacts: 条目)若读取 .context.used_by 下的 render_facts,会在任何内容渲染之前中止构建,并指出该引用及其所在的字段(参见 fatal-halts.md 中的“A template reads its callers’ render facts without declaring it(模板读取其调用方的渲染事实但未声明)”)。该检查读取的是模板的书面内容,因此看不到模板运行时构建的引用,也看不到写在从文件或库导入的内容中的引用;而模板若从与 .context.used_by 并列的其他列表上读取名为 render_facts 的字段,或在与其并列的 {{ with .context }} 中以 .render_facts 读取宿主自身的事实,都会被视为读取调用方的事实;宿主自身的事实请完整写为 .context.render_facts。决定挂载何时渲染的是该键而不是该检查,因此凡是模板读取其调用方渲染事实的 FeatureRecipe,无论以何种方式读取,都应设置该键;设置它的唯一代价是渲染推迟。

pipeline 步骤只读取其宿主自身的事实。 步骤可以改写宿主组件自身的文档,而组件自身的输出不会因谁连接到它而改变,因此步骤的 with: 和 when: 永远看不到连接到宿主的组件——无论 FeatureRecipe 是否设置此键,此键决定的是挂载何时渲染,与步骤能看到什么无关。因此,内联编写的步骤 with: 或 when: 如果在 .context.used_by 之下读取 render_facts,构建会在任何渲染之前停止,短代码为 E0326,并指出该引用及步骤的字段——而不是渲染出一个空值。在步骤中请通过完整写出的 .context.render_facts 读取宿主自身的事实,并在 FeatureRecipe 的 valuesMapping:、workload: 或 artifacts: 中读取调用方的事实。此检查读取的是模板的书面内容,限制与上文的检查相同。

作用范围。 此键适用于每个组件渲染一次的 FeatureRecipe——即 executionScope: component,这是默认值。声明了 executionScope: boundary 的 FeatureRecipe 无论是否设置此键,都在其一贯的位置渲染,并且生成其资源的模板读取 .boundary 而不是 .context。

在目标之后渲染 — spec.readsTargetRenderFacts

可选的 spec.readsTargetRenderFacts(布尔值,默认 false)声明此 FeatureRecipe 的模板读取其宿主所连接的组件渲染的内容:这些目标各自的 provider 对其输出所报告的渲染事实。它读取的是连接的另一端,与 readsCallerRenderFacts 相反——即宿主的 uses 条目所指向的组件,而不是 uses 条目指向宿主的组件——关于事实本身的一切,读取方式都相同。

任一键都会使附加在所有组件之后渲染。 若某个附加的 FeatureRecipe 设置了 readsCallerRenderFacts: true、readsTargetRenderFacts: true 或两者,该附加会在构建中的每个组件都渲染完成后再渲染,如上一节所述——这种延后渲染只有一次,它对附加输出的落点以及对其 pipeline 步骤顺序的影响,无论是哪个键使附加延后,都完全相同。两个键唯一的区别在于附加的上下文中哪些连接携带事实:在构建顺序中位于宿主之后的目标,此时已经渲染完毕,因此它输出的内容可供读取。

读取的内容。 设置该键后,.context.uses 的每个条目都携带 .render_facts:目标的渲染事实,按事实名称作为键,形状与调用方条目所携带的相同。每个渲染事实都是一个列表,因此模板总是对其进行 range 遍历。其条目可以来自目标自身的渲染,也可以来自附加到该目标的 Features 的渲染:目标自身的 provider 调用在前,然后是其各个 Features,按其渲染顺序排列;目标的某个 Feature 若自身也在所有组件之后渲染,则不在其中。若目标的 provider 未报告任何内容,则携带空的 .render_facts。模板可以通过别名读取某一个连接的事实,即 .context.uses.<alias>.render_facts.<name>,也可以依次读取每个连接的事实:

artifacts:
targets.yaml: |
targets:
{{- range .context.uses }}
- component: {{ .target }}
ports:
{{- range .render_facts.ports }}
- {{ .port }}
{{- end }}
{{- end }}

未设置该键的 FeatureRecipe,无论设置了其他什么,在任何连接上都看不到 .render_facts。存在哪些事实名称,由各目标的 provider 的文档化契约决定——helm provider 的事实即其 render facts,列出了它所渲染的 pod 的标签、控制器选择器和容器端口,因此正是出口策略为精确选中其宿主可访问的 pod 所需的内容。

只要模板读取事实,就声明该键。 在未设置该键的 FeatureRecipe 中内联编写的模板——其 valuesMapping:、其 workload: 或某个 artifacts: 条目——若读取 .context.uses 下的 render_facts,会在任何渲染开始前中止构建,给出短代码 E0347,并指出该引用及其所在的字段(参见 fatal-halts.md 中的“A template reads its targets’ render facts without declaring it(模板未声明即读取其目标的渲染事实)”)。设置 readsCallerRenderFacts 并不能消除此错误。该检查按模板的书写形式读取,限制与调用方的检查相同:它看不到模板运行时构造的引用,也看不到从文件或库导入的内容中写下的引用——而只要模板读取了 .context.uses,同时又从其他某个值上读取名为 render_facts 的字段(包括 {{ range .context.used_by }} 内调用方的条目),就会被视为读取其目标的事实。读取两端事实的模板需同时设置两个键。

pipeline 步骤只读取其宿主自身的事实。 步骤的 with: 和 when: 读取宿主建立的连接,方式与宿主自身的 Recipe 读取它们相同,但从不读取其目标的渲染事实——无论 FeatureRecipe 是否设置了该键。步骤可以重写宿主组件自身的文档,而宿主自身的渲染读取的是其目标所发布的内容,而非它们输出的内容。因此,内联编写的步骤 with: 或 when: 若读取 .context.uses 下的 render_facts,会在任何渲染开始前中止构建,给出短代码 E0348,并指出该引用及步骤的字段——而不是渲染出空值。请在 FeatureRecipe 的 valuesMapping:、workload: 或 artifacts: 中读取目标的事实。

作用范围。 与调用方的键相同:它适用于每个组件渲染一次的 FeatureRecipe。声明 executionScope: boundary 的 FeatureRecipe 无论是否设置该键,都在原本的位置渲染,并且它在 .boundary 下读取的连接不携带任何渲染事实。

locals: 块

FeatureRecipe.spec.locals: 是一个可选的具名 Go 模板字符串映射,其渲染输出会向同一 FeatureRecipe 内的其他所有模板暴露一个 .locals.* 映射。它相当于 FeatureRecipe 私有的 Recipe locals::在这里一次性计算派生字符串,然后在 injectMapping、valuesMapping、pipeline[].with 和 provides 中引用,无需重复计算。FeatureRecipe 的 assertions: 不读取它们:断言的 .locals 来自宿主组件的 Recipe,如 assertions-block.md 所述。每个条目的渲染输出在存储时会去除首尾空白。该块是一个映射,而不是单个模板主体;在此位置写标量会被 schema 拒绝。

apiVersion: aggrega.ai/v1beta1
kind: FeatureRecipe
metadata:
name: regional-router
spec:
implements: core/regional-router:^1.0.0
capability: helm
locals:
region_prefix: "{{ .infra.region | lower }}"
fqdn_suffix: "{{ printf \"%s.svc.cluster.local\" .infra.namespace }}"
injectMapping: |
env:
"{{ .infra.target_var }}": "{{ .locals.region_prefix }}.{{ .infra.target_var | lower }}.{{ .locals.fqdn_suffix }}"

.locals.* 按调用划分:每次 FR 调用都解析自己的 locals: 块,结果只对该调用的下游模板可见。该块在 FR 的其他编写面模板求值之前解析,因此这些模板看到的都是已解析的值。

每个条目针对一个自包含的上下文求值:.context.instance_id、.context.rendered_name、.attachment_name、.values、.infra,以及本块中已解析的条目。这有意比 FR 其他模板读取的上下文更窄:locals: 条目无法访问 .context.annotations、.context.inject、.context.uses 或 .provides,引用其中任何一个都会中止构建并指出该引用。需要这些支柱的派生值应放在读取它们的模板中,而不是放在 locals: 中。

该上下文中的各个名称回答不同的问题,locals: 条目读取它们的方式与 FeatureRecipe 的其他模板完全相同:

  • .context.instance_id 是该附加项正在为之解析的宿主 component。在编译器求值的每个模板面上,它都表示宿主 component,因此无论你在编写哪个实体的块,同一引用的含义都相同。
  • .context.rendered_name 是宿主 component 自身 provider 报告的名称:在 helm 下是 release 名称,即用 Kubernetes 名称所允许的字母表书写的宿主标识。只有宿主的 provider 报告了名称时它才存在;在 provider 未报告名称的宿主上读取它会中止构建。
  • .attachment_name 是正在解析的附加项实例:即它在所属实体的 featuresSchema 中填充的槽位,或你为它指定的自由名称。

因此,为输出资源派生名称的 locals: 条目会组合宿主和附加项,与 artifacts: 模板的做法完全一样:

spec:
locals:
scrape_name: "{{ .context.instance_id }}-{{ .attachment_name }}" # api-scrape_target

当名称必须是平台接受的名称,且宿主的 provider 报告了名称时,应改用 .context.rendered_name 组合:对于 helm 下名为 my_api 的宿主和附加项 scrape,{{ .context.rendered_name }}-{{ .attachment_name }} 得到 my-zuapi-scrape,而使用标识会得到 my_api-scrape,这是 Kubernetes 名称所拒绝的。参见为渲染资源命名。

locals: 条目中的 .values 和 .infra 是附加项自身的支柱,在附加项声明上编写,而不是宿主 component 的。

编写顺序至关重要

条目按编写顺序解析,条目可以读取在其上方定义的同级条目,并获得该同级条目的已解析值:

spec:
locals:
region_prefix: "{{ .infra.region | lower }}" # defined first
bucket: "{{ .locals.region_prefix }}-artifacts" # reads the entry above

链式引用只能向下。当一个条目读取另一个条目时,条目的顺序决定构建是否成功:把 region_prefix 移到 bucket 下方,构建就会中止。编译器从不为了让引用得以解析而重排该块,因此重排 locals: 块是行为上的变更,而不是表面上的变更。

引用块中稍后定义的条目会中止构建并指出顺序错误(把定义移到读取者上方);引用块中根本未声明的键会中止构建并指出该键(修正拼写)。该检查会跟踪块的别名:通过 with .locals 主体重新绑定的点访问的键,或通过绑定到 .locals 的变量访问的键,会以与直接写法完全相同的方式中止,从带括号的块上读取的键也是如此,如 {{ (.locals).nope }} 或 {{ ($.locals).nope }}。只有一种写法可以绕过检查:通过模板文本无法确定其结果的调用访问的键,如 {{ index .locals "nope" }} 或 {{ (default dict .locals).nope }}。从这类调用的结果上读取的字段不会中止,而是渲染字面文本 <no value>;index 读取会中止并指出该键,因为在每个模板面上,当 index 读取的映射不含该键时都会中止,参见 errors/fatal-halts.md 中的“A template indexes a map with a key the map does not hold(模板使用映射中不存在的键索引映射)”。provides: 读取完全解析后的块,因为该 FeatureRecipe 的 locals 在其 provides 之前解析;引用未声明键的 provides: 模板会中止构建。这些规则与 Recipe 的 locals: 块所遵循的规则相同,参见 entities/recipe.md 中的“locals: 块”。

**作用域行为。**对于 executionScope: component(默认),locals: 针对每个附加的 component 实例,基于上述自包含上下文求值。对于 executionScope: boundary,locals: 针对每个 boundary 附加项,基于以 .boundary.* 为根的 boundary 作用域视图求值;按 component 划分的字段(.context.instance_id、.context.inject、.context.uses)和 .attachment_name 不可用,因为该 FeatureRecipe 对 boundary 只运行一次,而不是每个 component 运行一次。boundary 作用域的模板字段允许列表对 locals: 的适用方式与对其他 FR 编写面模板相同。针对附加项所到达的每个 component 运行的 injectMapping,会将那一次 boundary 求值的结果作为其 .locals 读取。求值契约(编写顺序、只能向下的同级读取、两种中止)在两种作用域下完全一致;只有外围上下文的结构不同。

与 injectMapping 覆盖和 pipeline[].with 映射的区别。locals: 为下游模板生成一个上下文可见的映射;它不产生输出。injectMapping 写入消费者的 .context.inject 管道(调用方侧变更)。pipeline[].with 提供 Wasm 插件的 args 载荷。这三个面相互正交:一个 FeatureRecipe 通常会同时使用这三者,由 locals: 承载另外两者引用的共享派生字符串。

assertions: 块

FeatureRecipe.spec.assertions: 是一个可选的映射,由具名规则组成,用于表达 FeatureRecipe 的实现不变量——即在该 FeatureRecipe 所基于的特定 Wasm 插件流水线、chart 或机制下成立的跨字段规则。每个键是一个规则标识符,会出现在失败消息中;每个值是一个 Go 模板体。与 Recipe 断言一样,FeatureRecipe 断言是特定实现的属性;Feature 级别的契约规则在更早的流水线阶段独立生效。

spec:
implements: core/referenced-secret:^1.0.0
pipeline:
- id: fetch_secret
plugin: pipeline-step/aws-secrets-manager:1.2.0
function: step
assertions:
# aws-secrets-manager plugin 1.x requires an explicit region when none is
# implied through the Aggregate's infra block.
region-supplied-for-secrets-manager: |
{{- if not .values.region -}}
{{- if not .infra.aws.region -}}
{{- fail "aws-secrets-manager plugin 1.x requires either values.region or infra.aws.region to be set" -}}
{{- end -}}
{{- end -}}

上面的规则特定于 aws-secrets-manager 插件 1.x;如果绑定的是另一个 core/referenced-secret FeatureRecipe,则该规则不适用。Feature 定义中的 Feature 级别契约规则仍会同时生效。

FeatureRecipe 断言在 FeatureRecipe 绑定之后、资源生成(Resource Generation)之前求值。组件作用域 FR 的模板上下文与 Recipe 断言的上下文一致(实体实例字段,加上 .provides、.locals、.recipe.metadata、.recipe.source);对于边界作用域 FR(executionScope: boundary),断言针对边界作用域视图求值(可使用 .boundary.* 字段,不可使用逐组件字段)。完整的编写语法和实际示例,请参阅 templates/assertions-block.md。

omits: 字段——将渲染出的文档排除在源之外

大多数 FeatureRecipes 从不需要它。它适用于这样的 FeatureRecipe:其 source: 是一个你按原样使用的 chart(最常见的是从 registry 拉取的 chart),而该 chart 会渲染出一个本次挂载不得输出的文档,例如该 chart 每次渲染都会重新生成的 Secret,或宿主 component 或 operator 已经提供的对象。omits: 会将这类文档排除在该 FeatureRecipe 生成的内容之外;对于该 FeatureRecipe 作为源的 compose 文件,则排除本次挂载不得提供的 service、volume 或 config;对于它作为源的 CloudFormation 模板,则排除 resource。

spec:
capability: helm
implements: core/observability/collector:1.0.0
source:
kind: helm-oci-chart
url: oci://registry.example.com/charts/collector
version: "0.9.1"
omits:
# The collector chart ships its own ServiceAccount; the host supplies one.
- kind: ServiceAccount
name: collector
- when: "{{ .infra.without_dashboards }}"
kind: ConfigMap
name: collector-dashboards

该键在 Recipe 上的编写方式完全相同,其完整参考见 Recipe → omits: 字段:每个条目字段选择什么;when: 会最先求值,值为 false 时该条目被丢弃;每个生效的条目都必须排除某些内容,否则构建会停止并指出该条目;源仍会完整渲染,只是其输出被过滤;以及哪些 provider 支持该键。在 FeatureRecipe 上唯一不同的是模板的求值位置:

  • 每个条目的模板都针对该 FeatureRecipe 的 valuesMapping: 所用的上下文求值,作用域由其 executionScope 选定。component 作用域的 FeatureRecipe,其条目对每个挂载求值一次,针对该挂载的 .values 和 .infra;boundary 作用域的 FeatureRecipe,其条目对每个 boundary 求值一次,针对 boundary 作用域视图和 boundary 挂载的 .infra。关于挂载的模板可以读取哪些内容的规则,对这些条目的适用方式与对其 valuesMapping: 相同。
  • **只有该 FeatureRecipe 自身的 source: 渲染出的内容会被过滤。**其 workload: 和 artifacts: 不会被过滤,宿主 component 的输出也不会:一个挂载的条目只作用于它自己的 chart、它自己的 compose 文件或它自己的 CloudFormation 模板,不涉及其他任何内容。宿主在两者共同组装进的 docker-compose.yaml 中以相同键声明的 compose service 不受影响,宿主在两者共同组装进的 stack 中以相同逻辑 ID 声明的 resource 同样不受影响。要修改宿主渲染的文档,应由宿主的 Recipe 声明该条目,或由一个 pipeline: 步骤对其打补丁。

条目引发的停止会指出节点、provider、该 FeatureRecipe 以及该条目在其 omits: 列表中的位置;对于 boundary 作用域的 FeatureRecipe,消息上方的一行会指出该挂载及其 boundary。

关于在 Recipe 上编写该键的完整示例(排除拉取的 chart 生成的 Secret,以及缺少该条目时和条目未匹配任何内容时的停止),参见 ai-gateway-own-webhook-certificate。