输出组合
一次 Aggrega 构建通过六种不同的机制,将输出文件生成到 dist/ 下按边界划分的目录中:源渲染、workload 合成、FeatureRecipe 资源生成、FeatureRecipe 插件流水线补丁、Release 级组合,以及直接制品输出。这些机制按既定顺序运行;当两种机制在同一边界目录中生成同名文件时,输出会以确定的方式发生冲突;检测到冲突时,构建会在输出之前中止,并列出每一个贡献者,所用类别由相应冲突规则指明。
本页集中说明这六种机制,并给出它们之间的渲染顺序。各章节和各实体的参考文档分别涵盖各自的内容;涵盖全部六种机制的冲突检测规则则在本页说明。
六种产生输出的机制
每种机制位于特定的 Recipe / FeatureRecipe 编写界面,并按特定的命名约定生成文件。这些机制按节点累积——单个组件实例可以同时驱动多种机制(一个 sourced 基础 Recipe + 一个由 Workload 合成的配套文件 + 一个由 FeatureRecipe 生成的 ExternalSecret CRD + 一个应用于合成 Deployment 的插件流水线补丁)。
1 — Recipe sourced 渲染(source: + valuesMapping:)
编写界面。 Recipe 声明 source: <path> 以及 valuesMapping:(该字段接受内联 Go 模板、文件 $import:,或指向 MappingLibrary 条目的库 $import:——参见 entities/recipe.md “The valuesMapping field — three authoring modes”)。source 指向磁盘上的 Helm chart、docker-compose YAML 文件或其他 provider 原生制品。
流水线位置。 基础渲染,在 Recipe 的 locals 和 provides 解析之后。
输出形态。 因 Provider 而异:
- helm provider —— 扁平的 Kubernetes YAML 文件,先以组件标识命名,再以资源本身命名:
<component-id>-<kind>[-<namespace>]-<name>.yaml;不带 kind 或不带 name 的文档则改以其模板路径命名。名称来自资源而非模板,因此位于不同子目录、文件名相同的两个模板仍是两个文件。Helm SDK 使用合并后的 values 渲染 chart;Aggrega 在渲染后注入来源标签和注解。 - helm-chart provider — 子 chart 文件复制到
charts/<instance_id>/下,除 chart 自身的name外均原样保留;umbrella 会将该名称设为实例的编码标识,使两个各自引入声明了同一名称的 chart 的组件仍可区分(参见providers/helm-chart.md);同时为每个边界一并输出 umbrella 的Chart.yaml+values.yaml。 - compose provider —— 中间文件
<nodeID>.compose-fragment.yaml,流入 Release 级组合(机制 5)。
2 — Recipe Workload 合成(workload:)
编写界面。 Recipe 声明携带一个 Workload 文档的 workload:。该字段接受内联内容(块标量)或 $import:(文件路径)。
流水线位置。 基础渲染,在 Recipe 的 valuesMapping 解析之后(Workload 主体本身是一个使用完整模板上下文求值的 Go 模板字符串)。
输出形态。 因 Provider 而异:
- helm provider —— 一个由 Workload 的
form选定的控制器对象(stateless 对应 Deployment,stateful 对应 StatefulSet,daemon 对应 DaemonSet,task 对应 Job,scheduled 对应 CronJob)+ 每个服务一个 Service + 每个persistent卷一个 PVC。两种命名形态,且二者并不相同: 控制器对象以节点的 release 名称及其 kind 命名——<release name>-deployment.yaml、<release name>-statefulset.yaml、<release name>-daemonset.yaml、<release name>-job.yaml、<release name>-cronjob.yaml——而按资源生成的文件以其所承载的资源命名,kind 放在最后:<release name>-<svcName>-service.yaml和<release name>-<volName>-pvc.yaml,因为每个文件都以该资源自身的metadata.name命名。release 名称是以 Kubernetes 名称所允许的字母表写出的节点标识,因此只要节点 ID 不含下划线和大写字母,二者就相等:节点my_api写出my-zuapi-deployment.yaml(参见entities/workload.md“Synthesized-name convention”)。唯一暴露方式为外部名称的 Workload 则生成<release name>-service.yaml,因为没有可承载的服务键。 - compose provider —— 中间文件
<nodeID>.compose-fragment.yaml,流入 Release 级组合。 - helm-chart provider —— 不支持;helm-chart 的角色仅限于 sourced 模式的 chart 组合。以 helm-chart 为目标且带有
workload:的 Recipe 会在渲染时被拒绝(helm-chart provider 报告不具备合成能力)。
3 — FeatureRecipe 资源生成(FeatureRecipes 的 sourced 模式)
编写界面。 FeatureRecipe 声明 source: 以及 valuesMapping:(或等效项),模式与 Recipe sourced 渲染相同,但用于 Feature 附件而非主 Components。
流水线位置。 基础渲染,与父 Component 的基础 Recipe 渲染并行。每个 Feature 附件各自运行一次 FeatureRecipe 渲染。
输出形态。 由父 Component 的 provider 决定,因为附件的输出加入该 Component 的组装组,而非自成一组——并且取决于该 provider 如何合并该组,因为正是这一点决定了是否存在放置附件的位置。共三种形态,每种合并方式一种:
- 为每个贡献者提供独立位置的 provider——一个 chart 为每个贡献者容纳一个 chart,一个根配置为每个贡献者容纳一个模块——也为附件提供独立位置,位于其所附加组件的旁边而非内部。两个坐标组成该位置的单个目录段
<component-id>--<feature-instance-id>,因此带有附件aux的组件api位于api旁边的api--aux,处在该 provider 为其贡献者指定的目录下。之所以放在旁边而非内部,是因为此类 provider 的目标在它分配的位置上发现贡献者:这些位置之下一级的目录是属于该贡献者的内容,而不是独立的贡献者,因此不会被任何东西寻址或读取。声明在边界上的附件没有可命名的宿主组件,因此其目录段仅为其实例名称。每个坐标在连接之前都会被编码,因此本身包含连接序列的坐标不会被误认为连接处。 - 将每个文档直接写入边界目录的 provider 没有这样的位置,因为这正是它对其目标的声明:只读取直接位于目录中的文件。因此,同样的两个坐标从目录段移入文件名,附件的文件以
<component-id>--<feature-instance-id>--<file>的形式落在组件自身文件旁边。两个坐标会被编码,因为文件名没有可依赖的分隔符;它们在一个任何编码坐标都不可能包含的双字符边界处与文件自身名称连接——正是这一点使两个生成同一文件名的附件仍产出两个不同的文件。 - 将其组内贡献者折叠为一个文档的 provider 也会将附件的输出折叠进该文档,其中每个资源都携带附件自身的标识,使各内容的来源保持可读。当此类 provider 承载一个为不同目标渲染的附件时,该内容无法折叠进不属于它的文档,因此会写在组装文档旁边——出于同样原因,采用上述文件名前缀形态。
常见形态:
- 由凭据 FeatureRecipe 的 Fetcher 生成的
ExternalSecret/VaultSecretCRD。 - 由可观测性 Feature 生成的
ServiceMonitor/PrometheusRuleCRD。 - 由路由 Feature 生成的
HTTPRoute/GatewayCRD。
4 — FeatureRecipe 插件流水线(RFC 6902 补丁 + 资源发出)
编写位置。 FeatureRecipe 声明 pipeline:——一个由 Wasm 插件步骤组成的数组(Two-Part Plugin Principle(两段式 Plugin 原则):凭据类 Features 使用 Fetcher + Injector;非凭据类 Features 可使用任意插件流水线)。
流水线位置。 插件流水线阶段,在基础渲染和 FeatureRecipe 源模式渲染完成之后。
输出形态。 因 Plugin 而异。一个步骤返回两类输出:
- RFC 6902 补丁,由应用引擎应用到渲染集合中被寻址的文档上(例如,在合成的 Deployment 上追加一个 sidecar 容器、挂载一个密钥卷、改写一个环境变量)。
- 副作用——通过步骤的
side_effects随补丁一同发出的完整新资源(通常是 Fetcher 的 vault-fetch CRD,随后由 Injector 引用)。
当前状态: 可用,见语言状态 → 编译流水线阶段。每个声明的步骤都在 aggrega build 期间运行:宿主针对渲染集合调度该步骤的 Wasm 插件,应用返回的补丁,并发出该步骤的副作用。插件契约的接口见 plugins/plugin-contract.md。
5 — Release 级组合(按 provider 的边界装配)
编写位置。 由 Release 的结构驱动——无需在各 Recipe 中编写。装配边界的能力会在该边界内每个节点都渲染完成之后执行一次装配:compose 能力将所有按节点生成的片段汇集为每个边界一个 docker-compose.yaml,helm-chart 能力将按节点生成的子 chart 副本汇集为每个边界一个伞形 chart。
流水线位置。 在基础渲染之后,当该边界内每个节点的按 Recipe 输出都已累积完成时。
输出形态。 因 provider 而异:
- compose provider——在边界根目录下生成一个
docker-compose.yaml,汇总每个参与节点的服务、卷和网络。中间的<nodeID>.compose-fragment.yaml文件(机制 1 + 2)被合并到这一个输出中;这些片段不会出现在最终的边界目录中。 - helm-chart provider——在边界根目录下生成一个伞形
Chart.yaml+values.yaml,以及位于charts/<instance_id>/下的按节点子 chart 目录。
6 — Recipe 直接制品发出(artifacts:)
编写位置。 Recipe 将 artifacts: 声明为由具名条目组成的映射;每个条目要么是内联内容(承载文件正文的模板字符串),要么是指向模板文件路径的 $import: 引用——不经过 provider 直接发出文件。
流水线位置。 制品求值阶段,位于基础渲染之内。
输出形态。 每个制品条目一个文件,按该条目在 artifacts: 映射中的键命名。Recipe 作者直接决定文件名和内容。
当前状态: 可用,见语言状态 → Recipe 输入种类。每个条目在工作负载合成和源解析之后,使用完整的模板上下文求值,所得文件以该条目的键发出。目标如何处理发出的制品取决于能力:接受独立制品的 provider 将其作为单独文件发出,而只接受与其他输入种类搭配的制品的 provider 会将该条目折叠进其装配的内容中——因此,正文若不符合该装配器预期的形态,会以 TRANSLATION_ERROR 类别中止,而不会被原样发出。为某个能力编写制品之前,请查看 architecture/16-recipe-input-composition.md 中的按能力对照表。
渲染顺序
这六种机制按既定顺序运行,使下游机制能够读取上游的输出。顺序如下:
- Provides 求值——对每个节点,首先按作者编写的顺序解析 Recipe 的
locals:块,每个条目可读取其上方的条目;随后对该节点的provides:模板求值,各模板之间的顺序任意(自包含:.context.instance_id、节点的 provider 报告了.context.rendered_name时的该值、.values、.infra、已解析的.locals、静态文本)。正是“先 locals 后 provides”的顺序,使provides:条目能够读取一个 local 并得到已解析的值。 - Locals 发布与 source 解析——这些 locals 被发布到
.locals上,Recipe 的source:URI 模板基于它们求值(若 source 指针使用了模板,则在此解析)。source 层共享 locals 上下文,因此它读取的是.locals而不是.provides。 - Inject 映射——对 FeatureRecipe 的
injectMapping:块求值(inject 管道在 Recipe 渲染之前被拦截)。 - Values 映射——对 Recipe 的
valuesMapping:求值(sourced 模式和 sourceless 模式都会产生 values 字典)。 - Workload 合成——Recipe 的 Workload 合成(机制 2 为合成模式输出 manifests)。
- Artifact 求值——对 Recipe 的
artifacts:求值(机制 6)。 - Provider 渲染——由 provider 进行渲染(机制 1——sourced 模式产生扁平的 manifests;sourceless 模式产生生成式 manifests)。
- Feature 渲染——为节点上的每个 Feature 挂载执行 FeatureRecipe 渲染(机制 3 + 4——Resource Generation 在此运行;插件流水线稍后在第 9 步运行)。
- 插件流水线——渲染后变更:FeatureRecipe 的
pipeline:插件步骤应用 RFC 6902 补丁并输出额外的资源(机制 4)。 - Release 级组合——该能力的边界组装将各节点的片段汇集为各边界的输出(机制 5)。
顺序之所以重要,是因为下游机制可以读取上游的输出——例如,插件流水线中的某一步可以给 provider 渲染出的 Deployment 打补丁,而 Release 级组合器可以合并由 provider 渲染、feature 渲染以及插件流水线输出的片段。
冲突检测规则集
当两个机制在同一边界目录中生成同名文件时,构建会中止并列出每个贡献者,所用类别由下面各条规则分别指明。规则集如下:
Recipe 形状规则:artifacts: 条目键冲突
一个 Recipe 在 artifacts: 下声明了两个键相同的条目(该键决定输出的文件名,无论条目主体是内联编写还是通过 $import: 加载)。在 Recipe 加载时检测,参见 errors/fatal-halts.md “artifacts: entry keys must be unique(条目键必须唯一)”。
Recipe 形状规则:跨输入类型的输出时冲突
Recipe 的三种输入类型——sourced、synthesized 和 artifacts——都会向同一边界目录输出文件。如果源渲染、workload 合成或 artifact 输出的结果生成了一个文件,而另一种输入类型也生成了同名文件,构建会在输出时中止。在输出时检测,见 errors/fatal-halts.md “Emission-time filename collision across input kinds(跨输入类型的输出时文件名冲突)”。
Compose 服务名冲突(Release 级)
当两个不同节点(位于任意边界组合中)向合并后的 compose 输出贡献同名服务时,compose provider 会在组合该边界时于 TRANSLATION_ERROR 类别下中止,并列出每个贡献的 (boundary, node, serviceName) 元组。在 Release 级组合时检测,见 providers/compose.md 的 Release 级输出一节。
服务仅凭名称即被拒绝,不比较两个节点声明的内容。一个 compose 服务就是一个运行中的容器,因此两个各自需要一个服务的节点只能共用一个,无论两个定义多么相同,总有一个贡献者的意图会丢失。
Compose 卷名和配置名冲突(Release 级)
当两个不同节点向合并后的 compose 输出贡献同名的顶层 volumes: 或 configs: 条目,且两个声明不同时,compose provider 会在 TRANSLATION_ERROR 类别下中止,并列出该条目和每个贡献的 (boundary, node) 元组。在 Release 级组合时检测,见 providers/compose.md 的 Release 级输出一节。
与上面的服务规则不同,此规则会比较声明内容,贡献者意见一致时共用名称是合法的。一个命名卷或配置是一个对象,因此两个节点以相同方式声明它时,都恰好得到了合并文档最终包含的条目,没有任何丢失。两个节点以不同方式声明它,就是对同一个对象存在分歧,保留任一声明都会让本可成功的构建丢弃另一个声明。当两个声明在组装后的文件中描述同一条目时,即视为一致,因此写成空映射的主体与完全省略的主体是一致的。
Helm-chart 子 chart 别名与目录
helm-chart 子 chart 位于 charts/<instance_id>/,其 values 限定在其别名之下,别名是针对别名位置编码后的实例 ID。除非两个实例的实例 ID 是相同的字符串,否则它们不可能得到同一个别名,因为编码会把别名不接受的字符显式写出,而不是替换它们——因此一个别名只标识一个子 chart,写在其下的 values 只会到达该子 chart。而根据 Aggregate 展平规则,实例 ID 在每个边界内唯一,因此目录也不会冲突。两者都是结构性的:都不依赖检查。
Helm 渲染资源名冲突
在一个边界内,渲染出相同 Kubernetes 资源名的两个节点会生成两个 metadata.name 字段重叠的 YAML 文件。文件名不同,因为每个文件都以其自身的命名基础为前缀,但其中的 metadata.name 仍可能相同——因此构建会检查渲染出的资源所携带的名称,若两个贡献者在同一命名空间中为同一 kind 推导出同一名称,构建会在写出任何内容之前以 TRANSLATION_ERROR 类别中止,并指出该名称以及推导出它的每个组件和每个挂接(参见 errors/fatal-halts.md)。
最主要的情况通过构造而非检查来排除。 以 release 名称命名其资源的 sourced chart 不再可能在两个组件之间产生此冲突,因为只要两个命名基础有任何不同,就会得到两个不同的 release 名称——见 providers/helm.md “How the release name is derived”。还剩两种情况,上述检查报告的正是它们。一种是在模板中以字面量写入资源名的 chart,任何推导都无法将这样的名称与其他字面量区分开。另一种是同一个组件上的两个 Feature 挂接,各自交付其作者编写的 chart:按设计,两者都基于该组件的 release 名称渲染,因此两个以 .Release.Name 命名资源的 chart 会在此相遇——请为两个 chart 的资源指定不同的名称,或将它们挂接到不同的组件上。
每个合成名称都以节点自身的标识开头——控制器对象的名称如此,每个按资源的名称也通过合成 Service 名称约定 <release name>-<svcName>(见 entities/workload.md “Synthesized-name convention”)如此——这通过构造在结构上排除了跨节点冲突。构建因 Deployment / Service 名称而中止的作者,应首先检查是否有两个不同的 Recipes 通过不同的渲染路径输出了同名资源(例如,sourced chart 的 templates/deployment.yaml 与 workload 合成的 Deployment 的 metadata.name 冲突)。
跨机制交互模式
Workload 合成 + 插件管道补丁
典型模式:机制 2(workload 合成)输出一个基础 Deployment;机制 4(Injector 插件)应用一个 RFC 6902 补丁,将一个 secret 卷挂载到该 Deployment 中。两种机制相互组合——Deployment 是同一个 K8s 资源,补丁将 ConfigMap / Secret 引用叠加到合成的基础之上。
这是在合成的 workload 上注入凭据的主要模式。Fetcher(机制 3,资源生成)输出一个 ExternalSecret CRD,由集群在运行时获取;Injector(机制 4,插件管道补丁)修改 Deployment,以挂载由此产生的 K8s Secret。
不同边界上的 Sourced + Workload 合成
单个 Aggregate 可以在边界 A 上将一个组件绑定到 sourced helm Recipe(机制 1),同时在边界 B 上将一个同级组件绑定到合成 Workload 的 helm Recipe(机制 2)。每个边界的目录承载相应的输出形态;跨边界的文件命名不会冲突,因为每个边界的 dist/ 目录彼此同级隔离。
按输出目录进行的 Compose Release 级合并
compose 能力的组装会把目录求值为同一路径的所有边界的每节点片段,汇集到该路径下的一个 docker-compose.yaml 中;同一 Release 中两个以 compose 为目标的边界,目录不同时写出两个文件,共享一个目录时写出一个合并后的文件。
因此,服务名冲突按文件、在其 Release 级合并时依上述规则检测。位于不同目录、各自声明了名为 api 的服务的两个以 compose 为目标的边界不会冲突:每个边界的文件各自携带自己的服务。共享一个目录的两个边界写出一个文件,构建会中止并列出两个贡献者。
交叉引用
entities/recipe.md— Recipe 编写接口(机制 1 + 2 + 6 从 Recipe 内容产出)。entities/featurerecipe.md— FeatureRecipe 编写接口(机制 3 + 4 从 FeatureRecipe 内容产出)。providers/helm.md— helm provider 按机制划分的输出形态和命名约定。providers/helm-chart.md— helm-chart provider 的伞形 chart + 子 chart 组合(机制 5)。providers/compose.md— compose provider 的按节点分片 + Release 级组合(机制 5)。errors/fatal-halts.md— 关于artifacts:条目键唯一性以及跨输入类型文件名冲突的 Recipe 形态规则。templates/expansion-matrix.md— 渲染顺序中各模板位置的求值时机。plugins/plugin-contract.md— 插件管道契约接口(机制 4)。10-status.md— 机制 6(artifacts:)以及机制 4 插件管道运行时的当前就绪状态。architecture/10-compilation-pipeline.md— 完整的编译管道,包括各渲染阶段的顺序。architecture/16-recipe-input-composition.md— 三种 Recipe 输入类型(机制 1 + 2 + 6 的上游框架)。