路径模板变量
Release 边界上的 directory: 和 subDirectory: 字段是在构建时求值的 Go 模板。它们控制渲染出的制品落在磁盘上的位置,并由此决定哪些制品会组装在一起——求值为相同 (path, provider) 元组的两个边界共享一个组装器,并生成一个合并后的输出(一个 Chart.yaml、一个 docker-compose.yaml)。本页是编写参考,介绍这些模板可以引用的变量、严格求值语义,以及让边界从其父级继承的级联规则。
关于空间隔离和按 (path, provider) 分派的概念性说明,请参见 architecture/16-recipe-input-composition.md。关于实体层面的 Release 编写接口,请参见 entities/release.md。provider 端的影响见 providers/architecture.md 以及各 provider 的页面。
严格求值:missingkey=error
路径模板使用 Go 的 missingkey=error 模式求值。引用未声明的字段、未设置的 parameters.X 键,或诸如 {{ .parmaeters.region }} 这样的拼写错误,都会产生明确的错误,而不是悄无声息地把空字符串渲染进路径。
这种严格性与编译器的其余部分并不对称——valuesMapping、injectMapping 以及其他值渲染接口按照 Helm/Sprig 的约定使用 missingkey=zero。路径输出在结构上有所不同:产生空字符串的值渲染模板落入 manifest 字段,其后果是有界的;产生空字符串的路径模板落入目录布局,其后果是无界的(冲突、组装损坏、幽灵路径)。严格的路径模板机制之所以存在,是为了在构建时而非部署时暴露这些故障。
解析时允许列表校验
除运行时的严格性之外,路径模板还会在解析时依据一个封闭的变量名允许列表进行校验。引用不在允许列表中的变量名会在任何渲染工作开始之前中止构建,并给出诊断信息,指明出错的字段及其所在的边界。
该允许列表是有意设计为封闭的:.context.inject、.values 和 .locals 等接口被刻意不向路径模板开放。路径生成是结构层面的问题,而非值渲染层面的问题;将装配路径与每个组件的值绑定,会使路径图依赖于数据,并破坏输出确定性这一不变量。
变量矩阵
| 变量 | directory: | subDirectory: | 描述 |
|---|---|---|---|
{{ .capability }} | 是 | 是 | 参与组件的 Recipe 所声明的渲染能力(helm、helm-chart、compose、terraform、cloudformation),适用于在此路径输出的制品。 |
{{ .boundary_name }} | 是 | 是 | 边界在 Release 中编写的名称(例如 production、eu-prod)。 |
{{ .parameters.X }} | 是 | 是 | 在 Aggregate 上声明并由 Release 赋值的任意类型化参数。严格访问——引用 .parameters.unknown 会中止构建。 |
{{ .manifest.recipe_name }} | 是 | 是 | 通过 Manifest 为参与组件解析出的 Recipe 名称。可用于将各 Recipe 的制品路由到各自的子文件夹。 |
{{ .parent_boundary.* }} | 是 | 是 | 级联访问外层边界已求值的值。参见下文的父边界级联。 |
{{ .component_id }} | — | 是 | 参与贡献的组件的实例 ID。对于挂载在边界上、其 FeatureRecipe 针对该边界只运行一次(executionScope: boundary)的 Feature,它是该挂载的资源在其 aggrega.ai/component-id 标签中携带的组合标识 — 对于边界 app 上的挂载 shared,即 bfr--app--shared,在该挂载的提供程序限制名称长度时会被缩短 — 因此该挂载的输出会落在以该标签命名的目录中。仅在 subDirectory: 中可用,因为 directory: 是按边界设置的属性 — 目录字符串在每个边界只计算一次,早于任何按组件进行的路由。 |
directory: 字段默认为 boundaries/ 后接边界路径(由边界树派生的稳定构建期标识符);只列出组件而未声明边界的 Release 在写出这些组件时完全不带目录段。subDirectory: 字段默认为 {{ .capability }},使每种能力的制品落在边界目录下各自的子文件夹中——无论该字段被省略,还是写成 subDirectory: ""(其含义与省略完全相同)。设置 subDirectory: ".",或编写求值为空字符串的模板,会取消这一分组。
这些模板不决定的内容:artifacts: 的放置
输出路径中有一段不由路径模板设置。Recipe 的 artifacts: 块所指定的文件,会写入以声明它的组件命名的目录下,该目录位于 subDirectory: 的求值结果之内。对于将各参与者的文件并排写出、而非把每个参与者嵌套在各自的 chart 或模块中的目标,这一段是固定的,并且始终存在。
原因在于文件由什么命名。目标渲染或合成的 manifest 由目标根据其所属组件命名,因此它本身已能标识其组件。而制品由其作者编写的键命名——app-config.yaml、netpol.yaml——这个键不包含任何组件信息,因为声明它的 Recipe 并不知道哪些组件会绑定到它。同一边界中绑定到同一 Recipe 的两个组件会写出同一路径,而 Recipe 作者和 Release 作者都没有可用于区分它们的位置。
只添加目录;文件名仍是编写的键,因此作者在输出中读回的文件带有其所写的名称。
subDirectory: 仍能提供什么,以及两者如何组合。 subDirectory: 会移动参与者输出的每一个文件——渲染的 manifest、合成的 manifest 和制品一并移动——因此它适用于为某个组件提供独立目录,以供处理单个组件全部 manifest 集合的下游工具使用,或将多个组件路由到一个共享文件夹。artifacts: 段应用于其求值结果之下。因此,在 Recipe 声明了 artifacts: 的组件上编写 subDirectory: "{{ .capability }}/{{ .component_id }}",会使组件名称出现两次——制品落在 <capability>/<component>/<component>/<key>,而该组件渲染的 manifest 落在 <capability>/<component>/<key>。当你希望汇集组件的全部输出时使用该覆盖;如果只需要分离制品,则不要设置它,默认行为已经做到这一点。
.capability 按组件解析,而边界的 directory: 会出于两个不同目的求值。向子边界发布 .parent_boundary.directory 的按边界求值在任何组件绑定之前运行,因此此时 .capability 为空。确定参与者制品实际落点的按组件求值则带有该组件的能力。因此,编写 directory: "d-{{ .capability }}" 的父边界会沿级联向下发布 d-,而其自身的制品落在 d-compose 下。
父边界级联
嵌套边界会获得一个 .parent_boundary 视图,暴露直接父边界求值后的路径及其自身经级联解析的数据。级联只有一层:一个边界的 .parent_boundary 是它的直接父边界,而不是祖父边界。要访问更上层,父边界自身需在其模板中使用 .parent_boundary,从而显式地将值沿树向下传递。
.parent_boundary 下可用的字段:
| 字段 | 描述 |
|---|---|
.parent_boundary.directory | 父边界求值后的 directory: 值(模板处理之后)。 |
.parent_boundary.boundary_name | 父边界的编写名称。 |
.parent_boundary.parameters | 与父边界所见相同的 .parameters.* 映射(参数值在整个 Release 范围内全局有效,提供此别名是为了对称)。 |
.parent_boundary.annotations | 父边界经级联解析的注解。 |
典型模式:父边界只编写一次 directory:,子边界通过声明 directory: "{{ .parent_boundary.directory }}" 将其产物路由到父边界之下。这会将子边界合并到父边界的组装路径上,生成一个包含所有子边界贡献者的合并输出。core/compose-bridge Feature 正是依赖于此:一个持有 bridge feature 的父边界,两个共享父边界 directory: 的子边界(例如 services-net 和 data-net),以及一个包含所有 component 和 bridge 服务的合并 docker-compose.yaml。
反之亦然:在子边界上省略 .parent_boundary.directory(或求值为不同的路径),每个子边界就会获得各自的组装。两种形式都是一等公民。
布局示例
布局 1 — 默认按 boundary 隔离
spec: boundaries: api-prod: directory: "deploy/api-prod" components: api: {} cache: {} data-prod: directory: "deploy/data-prod" components: db: {}每个 boundary 求值为不同的 directory:,因此各自获得独立的装配:
deploy/api-prod/<capability>/...deploy/data-prod/<capability>/...默认的 subDirectory: "{{ .capability }}" 在每个 boundary 目录内按 capability 隔离产物。两个 boundary,每个 capability 两份装配输出,不进行合并。
布局 2 — 通过共享父目录合并装配
spec: boundaries: cluster: directory: "deploy/cluster" annotations: aggrega.ai/chart-name: "cluster-umbrella" features: bridge: type: core/compose-bridge:1.0.0 boundaries: services-net: directory: "{{ .parent_boundary.directory }}" annotations: { aggrega.ai/namespace: services } components: api: {} data-net: directory: "{{ .parent_boundary.directory }}" annotations: { aggrega.ai/namespace: data } components: db: {}两个子 boundary 都将 directory: 求值为 deploy/cluster(父级的目录),因此所有贡献者在同一装配路径合并。使用默认的 subDirectory: "{{ .capability }}" 时,来自两个子级的 compose 贡献者都落在 deploy/cluster/compose/ 中,并生成一个合并的 docker-compose.yaml。附加在父级上的 compose-bridge Feature 只运行一次(boundary 作用域分派),并将 bridge 服务贡献到同一个合并文件中。
父级的 aggrega.ai/chart-name: "cluster-umbrella" 注解级联到两个子级;如果这些 boundary 还包含 helm-chart 贡献者,两个子级的 helm-chart 子 chart 会组合到一个名为 cluster-umbrella 的 umbrella 下。同一路径上贡献者之间的 chart-name 值不一致会中止构建。
布局 3 — 通过 subDirectory: 加参数按组件路由
spec: parameters: region: "eu-west-1" boundaries: eu-prod: directory: "deploy/{{ .parameters.region }}" components: api: subDirectory: "{{ .capability }}/{{ .component_id }}" db: subDirectory: "{{ .capability }}/{{ .component_id }}" ingress: subDirectory: "shared"该 boundary 的 directory: 求值为 deploy/eu-west-1(参数替换)。按组件设置的 subDirectory: 覆盖将每个贡献者路由到各组件的子文件夹,其中 ingress 组件覆盖为扁平的 shared 子文件夹,用于存放横切产物:
deploy/eu-west-1/<capability>/api/...deploy/eu-west-1/<capability>/db/...deploy/eu-west-1/shared/...这种模式适合需要按组件划分产物目录的企业,以便下游工具针对单个组件的清单进行操作。如果某个组件的 Recipe 还声明了 artifacts:,在选择这种形式之前请先阅读上文的这些模板不决定的内容:这些文件已经带有一个组件路径段,因此此覆盖会再添加一个。
诊断
在以下每种情况下,路径模板机制都会中止构建,errors/fatal-halts.md 以下列名称记录了这些情况。该页面引用了每次中止所输出的消息;请将构建输出与该文本进行比对。
- Path-template references a variable outside the allowlist(路径模板引用了允许列表之外的变量) — 解析时:路径模板引用了不在允许列表中的变量。
- Path collision(路径冲突) — 组装时:两个边界贡献者求值为同一路径,但在某个必须在该路径所有贡献者之间保持一致的属性上存在分歧。
- Instance-ID collision(实例 ID 冲突) — 组装时:两个求值为同一
(path, provider)元组的边界贡献了具有相同实例 ID 的组件。 - Chart-name mismatch(chart 名称不匹配) — 组装时:一个合并的 helm-chart 组装接收到的贡献者带有经级联解析后相互冲突的
aggrega.ai/chart-name注解。 - Missing template key(缺少模板键) — 路径模板引用了某个开放变量下解析不到值的字段(例如,Release 省略了
region时使用{{ .parameters.region }},或在没有父级的顶层边界上使用.parent_boundary键);missingkey=error会生成一条明确的消息,指出边界、模板字段(directory:或subDirectory:)以及缺失的键。.parameters和.parent_boundary是开放的——它们的键是编写的数据——而.manifest声明了自己的键,因此.manifest下拼错的键会在解析时作为未知引用被拒绝,诊断中会列出.manifest定义的键。
交叉引用
entities/release.md— Release 的编写,包括空间隔离以及directory:/subDirectory:字段。providers/architecture.md— provider 分派以及按(path, provider)组装的模型。providers/compose.md— compose 侧按(path, provider)的输出,包括合并路径的场景。providers/helm-chart.md— helm-chart 伞形组合以及合并路径的 chart-name 级联规则。entities/featurerecipe.md— 边界作用域的 FeatureRecipes(core/compose-bridgeFeature 依赖本文所述的合并路径组装模型)。errors/fatal-halts.md— 完整的诊断目录,包括上文列出的路径分派终止。