数据支柱
五个 DSL 结构关键字(parameters、values、uses、infra、inject)的概念框架见 architecture/06-data-taxonomy-and-composition.md。本页介绍规范的数据支柱列表、各支柱的编写语义、跨支柱机制,以及作者在各支柱中会遇到的默认值术语。与之互补的拓扑三元组(provides、inject、uses,即连接图边的关键字)见 topology-triad.md;有别于数据支柱的元数据术语(标签、注解、发布面字段)见 labels-and-annotations.md 和 publishing-surface.md。
规范支柱列表
Aggrega 实体带有七个具名数据支柱。其中五个作为贯穿渲染的活动状态参与 IR 数据流;另外两个是暂时的或私有的,仅存在于特定的编译阶段。
| 支柱 | 所在位置 | 生命周期 | 角色 |
|---|---|---|---|
values | Aggregate 组件 / 附件实例 | 贯穿渲染始终存活 | 由 Developer 编写的认知负载 |
infra | Release 组件、附件和连接条目 | 贯穿渲染始终存活 | 由 Operator 编写的物理规格 |
provides | Recipe provides: 块 | 贯穿渲染始终存活(派生支柱——见下文) | 由 Recipe 计算、供拓扑管道消费的公共输出字符串 |
uses | Aggregate 组件 / 特性实例 | 贯穿渲染始终存活 | 指向其他组件 / 特性的拓扑边 |
features | Aggregate + Release 组件实例;槽位在目录实体的 featuresSchema 中声明——见下文“Features 支柱” | 贯穿渲染始终存活 | 附件支柱——所有附件族共用一种形态 |
parameters | Aggregate + Release 根 | 在整个管道结束前均可读取,直到所有渲染阶段完成;渲染期间路径模板可通过非对称授权访问;值模板的上下文消费插值后的字面量,而不是直接读取 .parameters | 由 Release 填充的按环境槽位 |
locals | Recipe locals: 块 | Recipe 私有——仅在该 Recipe 自身的模板内可见 | Recipes 在 locals 前导部分派生的计算字符串状态 |
values / infra / provides / uses / features 是五个活动支柱,运行时模板上下文分别通过 .values、.infra、.provides、.context.uses 和 .features 暴露它们。parameters 和 locals 不在活动支柱列表中——parameters 是因为它在解析后不再保留;locals 是因为它是 Recipe 私有的,从不跨越实体边界。
支柱是路标,而不是墙:模板引擎在每个位置都允许跨支柱读取,除非自包含规则明确禁止(Recipe provides: 和 Recipe source: 块读取 .context.inject / .context.uses;见 templates/expansion-matrix.md)。支柱边界是编写纪律,而非语言强制。
支柱边界与编写规范
在允许完整模板上下文的每个位置,Recipe 模板的跨支柱读取都不受限制。编写规范期望作者:
- 读取
.values获取认知载荷(由 Developer 编写的意图)。 - 读取
.infra获取物理规格(由 Operator 编写的规格)。 - 读取
.context.uses[].provides.<key>获取跨组件的指针字符串(拓扑三元组的数据流)。 - 读取
.context.inject获取水合后的交付管道(由component.inject、uses[].inject以及 FeatureRecipeinjectMapping拦截中的 inject 来源汇集而成)。
该规范是路标,而非围墙。读取 .infra.replicas 来驱动某个 values: 字段的 Recipe 模板可以正常工作;模板引擎不会拦截该读取。架构的定位是:支柱边界描述的是编写意图(数据归谁所有),而非运行时限制。约定与四域划分相对应:由 Developer 编写的值来自 .values;由 Operator 编写的规格来自 .infra;跨组件坐标来自拓扑管道。
当需要有意的跨支柱桥接时(例如,按照 vocabulary/inheritance-and-interface.md,某个 Component 的 schema: 暴露一个面向开发者的调节项,由 Recipe 的 valuesMapping: 模板将其导入运维侧 infra: 形状的输出),架构将该桥接视为有路标标示的例外。参见下文“跨支柱机制”。
Values
values: 支柱承载由开发者编写的认知载荷——开发者为每个组件实例指定的应用形态参数。Component 的 schema: 声明 values 的结构;开发者的 Aggregate 为每个实例填充具体的值。这是开发者的领域。
编写位置:
- Aggregate
components.<id>.values:——每个组件实例的认知载荷。 - Aggregate
subsystems.<name>.components.<id>.values:——同上,用于按子系统分组的组件。 - Aggregate
components.<id>.features.<name>.values:以及子系统的features.<name>.values:——挂载的 values 载荷,无论所挂载的 Feature 属于哪个系列(凭据挂载的 vault 查询参数与其他挂载一样在此编写)。
禁止出现在:
- Release 实体(Release 的 schema 在任何嵌套层级都禁止
values:块——参数提升(Parameter Hoisting)是受支持的按环境变化的途径;参见下文的 Parameters)。
**验证方:**Component schema 的 values: 块(对于 Feature 挂载,则为 Feature schema 的 values: 块),按照 vocabulary/validation-surface.md 第 2 层,在加载 Component / Feature 时解析为 JSON Schema 2020-12。
**使用方:**Recipe 的 valuesMapping: 模板,通过 .values 读取。完整的模板上下文在每个基础渲染模板位置都暴露解析后的 values 字典。
Infra
infra: 支柱承载由 Operator 编写的物理规格——副本数、资源请求、IOPS 限制、区域固定、机器类型。它表达的是在哪里、有多大,与 values 的是什么、如何运行互为补充。这是 Operator 的领域。
四个编写界面
作者会在四个不同的界面上遇到 infra:,每个界面的范围和级联行为各不相同:
| # | 界面 | 范围 | 合并优先级 |
|---|---|---|---|
| 1 | Release 边界 components.<id>.infra:(在没有边界的 Release 中为 spec.components.<id>.infra:) | 一个组件实例 | 该组件自身的规格;没有其他界面写入它 |
| 2 | Release 边界 features.<name>.infra: | 边界范围的挂载,作用于边界内的每个组件 | 对该挂载而言优先级最低——界面 3 会逐字段覆盖它 |
| 3 | Release 边界 components.<id>.features.<name>.infra: | 一个组件上的一个挂载 | 对该挂载逐字段覆盖界面 2 |
| 4 | Release components.<id>.uses.<socket>.<alias>.infra: | 一条连接 | 依据插槽的 infraSchema 进行校验;只作用于使用方组件的渲染 |
界面 1 是最常编写的:Operator 为 Release 放置的每个组件确定规格。边界本身不携带 infra:——Release schema 会拒绝它——因此多个组件共用的规格要在每个组件上分别编写,或通过 extends: 从父 Release 继承(见下文)。界面 2 和 3 涵盖 Feature 挂载的规格——Features 携带自己的 infra 负载,FeatureRecipe 在合成 sidecar 或按 Feature 的资源时会使用它:边界范围的挂载只需确定一次规格,某个组件可以调整其中的单个字段。
“Infra 主要本地化”——带例外的规则
infra: 的架构目标是组件本地化:一个组件的规格只作用于该组件实例,不会渗透到其他组件。正是这一机制让运维可以提高数据库 IOPS,而不影响 API 服务器的 CPU 请求。
规则:infra: 主要本地化于编写它的界面。按设计存在以下级联例外:
- **边界注解级联。**边界
annotations:会穿过嵌套边界级联到内部组件(见 labels-and-annotations.md 中注解矩阵的界面 5)。被 Recipes 用作路由输入的注解会成为间接的infra影响——边界级注解经由.context.annotations.release流入每个节点的 Recipe 的渲染输出。 - **通过
extends:的 Release 继承。**一个extends:父 Release 的 Release,会在每个携带infra声明的界面上继承父级的这些声明,除非子级按键覆盖。子级的值逐键胜出,直到第一个不可再分的值——标量、列表、模板——该值整体替换;子级写为null的键会被移除,而不是被设为空。该继承有意跨越单个 Release 的边界;完整的合并规则以及随之传递的其他内容,请参见entities/release.md。 - **Schema 桥接的跨支柱传递。**Component 的
schema:可以暴露一个面向开发者的values:调节项,由 Recipe 的valuesMapping:模板将其传入 provider 的infra:形状的输出(参见下文“跨支柱机制——Schema 桥接的跨支柱传递”)。严格来说,该值源自values:并流入渲染输出;这种级联发生在实例内部,但跨越了支柱。
本地化是设计意图,而不是引擎强制执行的墙:上述级联是有意的例外,每一个都在携带它的界面处有文档说明。
注解驱动的 Feature 展开中的侧别与支柱划分。“Aggregate 作为编写界面”这一不变式同样贯穿注解驱动的 Feature 展开路径:Aggregate 侧注解(子系统和组件实例范围)只能触发 maps.values 子键;Release 侧注解(边界和组件实例范围)只能触发 maps.infra 子键。一个 Manifest 绑定可以在两个支柱中声明路径;每一侧只触发其兼容的子集,跨侧组合在 IR 构建时按字段合并各方贡献。该划分在注解界面上保留了 values 归开发者、infra 归运维的编写分离——与 values: 和 infra: 在显式挂载界面上强制执行的分离相同。关于按子键的说明以及跨侧组合模式,请参见 providers/well-known-annotations.md §“Side-vs-pillar partition per subkey”。
Provides
provides: 支柱是派生的——由 Recipe 声明,但与 values / infra 不同,开发者不直接编写它。Recipes 计算拓扑管道将要消费的公共输出字符串。
Recipe 的 provides: 块是由 <key>: <template> 键值对组成的映射。在 provides 求值期间,每个模板都针对该 Recipe 自身自包含的界面(.values、.infra、.context.instance_id、节点的 provider 报告了名称时的 .context.rendered_name,以及节点已解析的 .locals)进行求值。生成的字符串通过 .provides 暴露,并由调用方的 uses[].inject 块通过 from: "<key>" 引用来消费。.locals 之所以可用,是因为节点的 locals 在该阶段的前导部分、先于其 provides 解析(参见下文的 Locals);引用 locals 块未声明的键会导致停止。
自包含不变式。 Recipe 的 provides: 模板不得引用 .context.inject 或 .context.uses。provides 求值以任意顺序运行这些模板——它们只闭包节点自身的数据,因此顺序无关紧要。跨节点引用会使该求值与拓扑迭代顺序耦合,而设计有意避免这一点。有关该规则及其理由,参见 templates/expansion-matrix.md 第 6 行。
为什么 provides: 是一个支柱。 这些输出字符串是每个 Recipe 的规范公共界面;下游消费者(调用方的 uses[].inject,以及通过 .context.uses 读取目标已解析 provides 的 FeatureRecipe injectMapping 块)将该字典视为类型化契约。将 provides: 称为支柱,承认了它与 values / infra / uses / features 并列的一等地位。把它当作“只是 Recipe 的内部细节”会低估它作为拓扑管道主要数据源的作用。
Uses
uses: 支柱是拓扑边声明。一个组件实例的 uses: 块列出该组件参与的边,即它借以消费目标的套接字。完整语法记录在 topology-triad.md 中;本节为完整起见将 uses: 列为一个支柱。
uses: 位于 Aggregate 组件实例和 feature 附件上;运行时模板上下文为每个出站连接公开一个条目,以其别名为键,即 .context.uses。该投影携带每条边已解析的目标元数据(目标的 provides、标签、注解),使调用方的 Recipes 能在基础渲染模板求值时读取跨组件的指针字符串,并在 .context.uses.<alias>.features.<slot> 处读取写在该连接上的附件。
Features 支柱
features: 是附件支柱:一个关键字、一种形态、涵盖所有附件。运行类 Feature、凭据类 Feature 和身份类 Feature 都在这里以作者选定的实例名声明。运行时模板上下文将节点的附件暴露为 .features.<name>,每个附件携带 type、values、infra 以及该附件解析后的 provides。写在组件某个连接上的附件则以相同形态暴露在该连接下,即 .context.uses.<alias>.features.<slot>,而绝不会出现在 .features 下——因此遍历 .features 的 Recipe 只会遇到组件自身的附件(参见模板上下文契约)。
实例名与实体在 featuresSchema 中声明的某个槽位相匹配的附件会填充该槽位;其他实例名的附件则为自由附件。填充槽位正是将基于槽位的凭据所经过的四个界面连接起来的方式:
| 界面 | 编写位置 | 角色 |
|---|---|---|
Component / Feature featuresSchema: | 目录实体 | 声明实体期望的槽位;按槽位限定交付方式允许列表(env / file / blackbox),并可选地指定填充必须满足的标签选择器 |
Aggregate components.<id>.features.<slot>: | Aggregate 组件实例 | 用附件填充槽位;提供附件自身的 values:,对于透明槽位还提供其 inject: 映射 |
Workload containers.<name>.attachments.<KEY>.from/as: | Recipe 的 Workload 主体 | 引用已声明的槽位——或者在 connection: <alias> 旁引用该连接的 socket 所声明的槽位——并规定按容器交付填充内容的方式 |
FeatureRecipe(source / workload / artifacts / valuesMapping、injectMapping、pipeline:) | 绑定的 FeatureRecipe | 生成附件的输出——一个发出的资源、一次交付改写,或两者兼有 |
槽位名是贯穿这四者的关键标识符:界面 1 声明它,界面 2–4 引用它,数据流是单向的(声明 → 填充 → 引用 → 生成)。
编写检查清单参见 examples/04-secrets.md 中的“The secret-delivery checklist”(密钥交付检查清单)。
Locals
locals: 支柱是 Recipe 私有的状态。整个块在 locals 前置阶段解析,早于该节点的 provides:;解析得到的字符串对该 Recipe 自身之后的每个模板可见——provides:、source:、valuesMapping:、workload:、artifacts:、assertions:、pipeline[].with。provides: 模板若引用该块未声明的键,则会中止。
编写位置: Recipe 的 spec.locals: 块——由 <key>: <template> 键值对组成的映射,在一个自包含的节点本地界面上求值:.context.instance_id、.values、.infra,以及同一块中已解析的条目。界面上没有其他内容:.provides、.metadata 和 .context.* 的其余部分都不在其中,引用其中任何一个都会中止。
顺序至关重要。 条目按书写顺序解析,一个条目可以读取定义在其上方的同级条目,并得到其解析后的值。链式引用只能向下进行——当一个条目读取另一个条目时,把被读取的定义移到读取者下方会被拒绝,编译器也绝不会为使引用得以解析而重新排列该块。引用后面的条目会中止并指出顺序错误;引用未声明的键会中止并指出该键。对于 source: 为结构化块的 Recipe,在固定其所指制品时也会拒绝这两种错误,因此 aggrega pull 会在任何构建渲染输出之前报告它们。该检查读取的是引用解析到的路径,而不是字面写法,因此直接形式、with .locals 块、绑定到 .locals 的变量,以及带括号的块,即 (.locals).<key> 或 ($.locals).<key>,都能覆盖到。它不覆盖一种写法:通过函数访问的键,例如 index .locals 或 (default dict .locals).<key>。以这种方式访问不存在的键不会中止,并会渲染出字面文本 <no value>,而不是空内容——但通过 index 本身访问时例外:当其读取的映射中不含该键时,它会在每个模板界面上中止并指出该键。
可见性: Recipe 私有。不存在 .context.uses[].locals 字段——调用方无法通过连接边读取其目标的 locals。调用方可以读取的是目标的 provides:。
使用场景:
- 计算 Recipe 内部的指针字符串(例如
secret_target_admin_password: "redis-auth",即某个 Secret 名称的后缀),供该 Recipe 的valuesMapping:和provides:共同使用,并供挂接到同一 component 的凭据 FeatureRecipe 以.locals.secret_target_admin_password读取——挂接项的模板看到的是宿主 Recipe 解析后的 locals 与挂接项自身 locals 合并后的结果。在helm目标上,它们各自都将完整名称写为{{ .context.rendered_name }}-{{ .locals.secret_target_admin_password }}:渲染名称是以 Kubernetes 名称所允许的字符拼写的 component 名称,而 local 无法读取它,因此由 local 携带后缀,由每个读取者将两者拼接。 - 在单个 Recipe 内消除重复的计算值(主机名只计算一次,由多个
valuesMapping:字段引用)。 - 为复杂模板逻辑提供中间值,否则内联写法将难以阅读。
provides: 与 locals:——公开面与私有面
Recipe 侧的这两个支柱有意划分了可见性,编写者应牢记这一点:
provides:是公开面。 每个键都是规范的拓扑管道界面——下游调用方的uses[].inject块通过from: "<key>"引用来使用它们。provides:字典是调用方所依赖的类型化契约;重命名或删除一个键,对每个在uses[].inject声明中引用它的 Recipe 都是破坏性变更。locals:是私有面。 每个键都是 Recipe 内部状态,仅在该 Recipe 自身的后续模板中可见。任何调用方都无法读取 Recipe 的 locals;locals:中的名称不属于任何已发布的接口,重命名它们只是 Recipe 内部的重构,对下游没有影响。
两者也有先后顺序:locals: 先解析,因此 provides: 可以读取 .locals,但 locals: 不能读取 .provides。因此,要通过 provides: 发布某个 local 的值,就是添加一个读取该 local 的 provides 条目——表达式仍只保留在一处。
这种划分是有意为之,遵循将 Recipe 内部(私有)与 Recipe 接口(公开)分离的架构原则。把 provides: 和 locals: 当作同一命名空间的编写者会失去可见性区分,并有通过拓扑管道暴露内部状态的风险——在 provides: 中声明的每个键都会成为 Recipe 契约界面的一部分,无论编写者是否有此意图。应遵循的做法是:先在 locals: 中声明键;只有当下游调用方确实需要时,才将其提升到 provides:。
可见性由键所声明的支柱决定:没有按键设置的可见性标记,因此一个既私有又发布的值,就是一个 locals: 条目加上一个读取它的 provides: 条目。
Parameters
Aggregate 和 Release 的 schema 都在根部带有一个 parameters 字典。开发人员声明该 Aggregate 期望的键;运维人员通过特定于环境的 Release 文件填入值。这种解耦是 GitOps 推进的机制:单个不可变的 Aggregate.yaml 依次经过 Dev、Staging 和 Production 环境,由每个环境的 Release 提供各自的参数值。
spec: parameters: corp_db_name: type: string required: true env_workers: type: integer required: true region: type: string required: true enable_debug: type: boolean required: true components: my-backend: type: core/python-worker:1.0.0 values: workers: {{ .parameters.env_workers }} region: "{{ .parameters.region }}"# release-prod.yaml — inline parameter valuesspec: aggregate: my-app manifest: prod-manifest parameters: corp_db_name: "enterprise_data" env_workers: 10 region: "eu-west-1" enable_debug: false对于将参数值保存在单独文件中的 CI/CD 流程(例如与 Release 一同签入的按环境划分的 .yaml),Release 使用 $import: 形式:parameters: { $import: ./prod-values.yaml }。该文件的内容会在 Release 层面替换内联映射。无论从何处运行命令,该路径都从包含该 Release 的目录解析,并且必须指向工作区内的文件——对于在工作区之外指定的 Release,则必须指向包含它的目录内的文件。多文件分层(将基础文件与特定于环境的覆盖层组合)通过 Release 的 extends: 链表达——父 Release 提供基础参数;子 Release 继承并按键覆盖。
参数生命周期。 编译器分三个阶段解析参数。(1) 默认值填充——定义了 default: 且没有 Release 值的槽位获得其默认值。(2) 参数契约校验——带类型的 parameters: 契约依据声明的 type / enum / min / max / pattern 约束校验每个值,包括已填充的默认值,因此违反自身契约的默认值会使构建中止。(3) 插值——编译器将该 Aggregate 的全部文本作为模板求值,并将每个 {{ .parameters.<slot> }} 引用替换为解析后的值。合并后的映射随后在整个渲染过程中保持可读,这样路径模板(Release 边界的 directory: / subDirectory:)就能依据 ../path-template-variables.md 中记录的封闭允许列表直接读取 .parameters.<slot>。值模板界面(Recipe valuesMapping、FeatureRecipe injectMapping / provides / pipeline.with、Workload 主体)的模板上下文中不会收到 .parameters——它们使用的是第 3 阶段插值写入周围 values: 字符串中的解析后的值。
参数提升检查清单
每个跨环境的值都依次经过四个编写触点。作者应记住的心智模型:对于任何在 Dev / Staging / Production 之间变化的值,预计需要修改 Aggregate(声明)、values 模板(引用)、Release(填充)和 Recipe 模板(使用)。
| 步骤 | 界面 | 操作 |
|---|---|---|
| 1 | Aggregate spec.parameters.<name> | 声明参数,作为该 Aggregate 带类型的编写契约的一部分。每个参数槽位带有声明的 type(string、integer、number、boolean、array、object)、可选的 description、可选的 default、可选的值空间约束(enum、min、max、pattern、minLength、maxLength),以及对象类型槽位的可选嵌套结构。该契约在插值之前校验 Release 提供的每个值。 |
| 2 | 同一 Aggregate 内的 Component values: 模板 | 在使用该参数的任何 component(或 feature、或子 aggregate)的 values: 块内,通过 {{ .parameters.<name> }} 引用该参数。该引用是一个 Go 模板表达式——编译器在解析的插值阶段对其求值。 |
| 3 | Release spec.parameters.<name>(内联或 parameters: { $import: ./path.yaml }) | 在 Release 层面用特定于环境的值填充该参数。按环境划分的 Release 文件为同一参数键提供不同的值,而无需修改 Aggregate。 |
| 4 | Recipe valuesMapping: 模板 | 通过 {{ .values.<key> }} 使用解析后的值——Recipe 是值模板界面;其模板上下文不直接携带 .parameters。按环境的差异通过上述插值阶段写入的插值后 values: 字典传达到 Recipe。(Release 边界上的路径模板是例外:根据非对称授权,它们在渲染期间直接读取 .parameters.<slot>。) |
这四个触点是顺序进行且缺一不可的:跳过 Aggregate 声明,Release 就没有可填充的槽位;跳过 values 引用,Recipe 就没有可使用的值;跳过 Release 填充,参数就为空。编译器在解析期间校验这条链(先依据带类型的 parameters: 声明进行参数契约校验,再插值到周围的 values: 字符串中,然后依据 Component 或 Feature 的 schema: 对生成的 values: 字典进行 JSON Schema 校验);不匹配会表现为参数契约违规(依据带类型的 parameters: 声明捕获)、未填充模板错误(在插值时捕获),或针对 values: schema 的 JSON Schema 约束违规(在 schema 校验时捕获)。
该模式是 GitOps 推进的标准机制:单个不可变的 Aggregate 在各环境间推进,由每个环境的 Release 提供各自的参数值。作者希望按环境变化的每个值都应放在参数链中,而不是直接嵌入 Aggregate。
按支柱划分的 extends: 合并语义
当目录实体声明 extends: 且编译器遍历继承链时,每个支柱的内容按该支柱特定的规则合并。各支柱的语义不同;下表是按支柱划分的标准参考。
| 支柱 | 在 extends: 链上的合并行为 |
|---|---|
values(JSON Schema 2020-12) | 在 Feature 链上,schema 通过 JSON Schema 2020-12 组合方式进行组合。进行继承的 Component 不编写任何支柱内容,在链的任意深度上都原样接收其基础实体所编写的块。 |
infra(JSON Schema 2020-12 片段) | 与 values 相同——在 Feature 链上组合,由进行继承的 Component 整体继承。 |
provides(Recipe 模板映射) | 顶层浅替换:同名时子键完全替换父键;同级键保留父级的内容。模板不会组合;子级的模板完全拥有其槽位。 |
uses (usesSchema) | 按 socket 名称进行逐 socket 的整条目覆盖。子级可添加其基础实体未声明的 socket,而以现有名称重新声明的 socket 会直接替换该条目——连同其值 schema、infra schema 和 selector 一起。socket 条目不会组合,也不会将重新声明的 selector 与基础实体的进行比较。 |
features(featuresSchema 按槽位的 schema) | 按槽位名称进行逐槽位的整条目覆盖,规则与 usesSchema 相同。子级可自由添加槽位;重新声明的槽位会直接替换基础实体的条目,而不是与之组合。 |
locals(Recipe 模板映射) | 顶层浅替换——与 provides 相同。 |
parameters(Aggregate 根映射) | Aggregate 没有 extends: 字段,因此不存在合并参数的 Aggregate 链。在 Release 的 extends: 链上,映射值参数进行深度合并且子键优先,标量值参数由子级替换,子级写为 null 的键会被移除。 |
总体模式取决于实体种类和界面。Feature 经 schema 校验的支柱会组合,遵循 JSON Schema 2020-12。进行继承的 Component 的支柱被整体继承——它不编写任何支柱,因此其契约与基础实体完全相同,基础实体的约束从构造上就无法放宽。固定形状的界面——usesSchema 和 featuresSchema——按名称覆盖,对两种实体都是如此:子级添加条目,重新声明的条目直接替换基础实体的条目。以模板编写的支柱使用按键浅替换,使子级完全拥有其声明的任何模板槽位。
进行继承的 Component 通过 assertions: 而不是通过支柱来收紧约束——它添加的谓词与继承的谓词一起求值。该机制参见 inheritance-and-interface.md。
关于继承机制本身,参见 inheritance-and-interface.md 中的“Inheritance via extends”,其中涵盖了目录实体种类。Release 不是目录实体,按其自身规则合并;该规则见 entities/release.md 中的“Composite Release and extends: inheritance”。
跨支柱机制
路标式框架允许在除已记录的自包含面之外的任何位置进行跨支柱读取。下列模式将常见的跨支柱机制规范化;另记录了一种编写上的不良迹象,以便作者认清其中的权衡。
Schema 桥接的跨支柱传递——设路标,不设墙
支柱边界是一种编写纪律:架构以路标标明什么内容放在哪里(values: 用于开发者的认知意图,infra: 用于运维的物理规格,provides: 用于 Recipe 输出的字符串,等等),由目录评审者执行该约定。模板引擎本身允许跨支柱读取,除非已记录的自包含规则禁止(Recipe 的 provides: 看不到 .context.inject;FeatureRecipe 边界作用域的 provides: 看不到按消费者区分的字段)。支柱之墙是路标,而非强制。
一个典型的有路标的例外:Component 的 schema: 可以声明一个面向开发者的 values: 调节项,由 Recipe 的 valuesMapping: 模板将其传入渲染后的 infra: 形态输出。开发者通过一个有类型的 values: 字段表达意图;Recipe 模板将得到的值传入 provider 的基础设施层,开发者无需编写基础设施代码。示例如下:
# Component schema declares a developer-facing dial in valuesspec: schema: values: required_iops: { type: integer, min: 100 }# Recipe valuesMapping pipes the developer's intent into the provider's infra-side knobvaluesMapping: iops_limit: "{{ .values.required_iops }}"该桥接在 inheritance-and-interface.md 中有记录,并附有示例。其架构意图(一个已声明的、由 Recipe 传递的跨支柱调节项)只有一个方向——开发者侧的 values: 流入运维侧的渲染输出——并落在 Recipe 的映射模板中,而不在 Component schema 本身中。支柱边界仍保持路标式:开发者看到 values:,Recipe 同时看到 values: 和 infra:,渲染输出将二者合并。
跨支柱 inject 累加器
.context.inject 管道是三个跨支柱来源的汇合点:
- Component 级自注入(
component.inject)——从组件自身的values和自身的provides获取字符串。 - Uses 注入(
uses[].inject)——从目标的provides获取字符串。 - FeatureRecipe
injectMapping:拦截——从上述任一来源以及 FeatureRecipe 自身的infra:载荷获取字符串。
到基础渲染运行时,.context.inject.<mechanism>.<key> 已累积了来自全部三个来源的条目。该累加器在构造上就是跨支柱的——源自 values、provides 和 infra 的条目都流入同一个 .context.inject 映射。消费 .context.inject 的 Recipes 看到的是合并后的状态,无需知道哪个支柱贡献了哪个条目。
关于 inject 语法和冲突规则,参见 topology-triad.md。
跨支柱约束重复
位于两个支柱、具有不同验证层的字段可能带有重复的约束。典型示例:在 Component 的 usesSchema 中声明的端口号(经 JSON Schema 验证,范围 min: 1, max: 65535),同一端口号又在 Workload 的 services.<name>.ports.<port> 字段中被使用,而 provider 渲染插件的 spec.provider.workloadSchema 可能为非特权端口添加 min: 1024 规则。provider 渲染 Plugin 的 spec.provider.workloadSchema 记录了该 provider 如何转换 Workload,并将该 provider 标记为能够合成 Workload;它不校验任何内容。无论 provider 是什么,每个 Workload 主体都依据平台的 Workload schema 进行校验,因此只写在 workloadSchema 中的约束——例如 min: 1024 端口规则——不会被强制执行;若要拒绝这样的值,请把约束放在 Component 的 schema 中或断言中。
Feature 挂载 / Component 支柱隔离
Feature 挂载不会写入父 Component 的支柱。每个挂载的 Feature 带有自己的支柱载荷(自己的 values: 块和自己的 infra: 块)。合成该 Feature 资源的 FeatureRecipe 独立于 Component 读取自己的支柱载荷。隔离针对的是输入:挂载读取的是它自己的内容,无论其写出的内容最终如何。当目标的 provider 写出离散文档时,挂载的渲染输出位于 Component 输出旁边、自己的目录下;当 provider 将一个边界的各贡献者折叠为一个文档时,挂载与 Component 一样向该文档贡献内容,且每个资源仍带有挂载自身的标识,使来源保持可读。
对作者的两个影响:
- Feature 挂载上的
values:设置不会出现在 Component 的valuesMapping:模板的.values中。Component 只看到自己的 values。 - Feature 的
infra:载荷不会流入 Component 的infra:。每个挂载的 Feature 都有自己的物理规格,作用域限于该 Feature 的资源。
这种隔离明确遵循架构的关注点分离:Features 是通过五层洋葱模型叠加到 Components 上的独立贡献者。关于挂载面及其顺序,参见 labels-and-annotations.md “Feature 挂载——五个面”。
两个支柱中的同名属性
Component 或 Feature 的 spec.schema.values: 和 spec.schema.infra: 声明同名属性——在根级、任意嵌套深度或两者皆有——是一种常见的编写坏味道。两个支柱按设计是独立的命名空间(编译器接受这种重叠),因此 schema 能通过验证,渲染输出也格式良好。这种坏味道是认知层面的:读者和模板作者每次浏览 schema 或针对它编写模板时,都会遇到“我读的这个 foo 属于哪个支柱?”的困扰。
# Smell — both pillars declare `mode`. A reader of the schema or a# template against the Feature has to disambiguate every reference.spec: schema: values: mode: { type: string } infra: mode: { type: string }有意重叠的作者确有保留两者的理由——例如,一个 mode 在 values 下表示“应用运行模式”("debug" / "production"),在 infra 下表示“部署拓扑模式”("standalone" / "clustered"),二者语义不同,只是名称恰好相同。无意重叠的作者(更常见的情况)应重命名其中一个条目。
第二种有意的形态是任一方作者都可提供的同一数据。标准库中携带调用方定位符的凭据 Features——core/referenced-secret、core/referenced-secret-set、core/secret-value 和 core/secret-provided——在两个支柱中以同一名称和同一形态声明它,因此开发者可在 values 中写入,或运维人员在 infra 中写入,而每个 Feature 自身的断言会拒绝两处都写或两处都不写的挂载。下述提示在每次加载到这四个 Feature 时都会点名它们;对它们而言,提示报告的是契约,而非失误。
对于每个重叠在至少一侧解析为终端叶子的同名属性,目录加载会发出 notice: LINT: <kind> "<name>" at <path> declares property "<property>" in both values: and infra: pillars (path: <dotted-path>) 提示。作为共享组织命名空间存在的同名属性(两个支柱都带有名为 ingress 的对象,其子属性互不相交)不会告警;只报告叶子重叠。该警告仅为提示——构建继续进行。
支柱校验层级
各支柱的校验分布在三个层级中。每个层级关注不同的问题;同一字段可以被多个层级校验(参见上文“跨支柱约束重复”)。
| 层级 | 校验内容 | 运行位置 |
|---|---|---|
| 1 — JSON Schema 外壳 | 结构形态(存在哪些键,类型是否与字段声明匹配) | 解析阶段,每次加载文件时 |
2 — 按支柱的 schema(schema / featuresSchema / usesSchema) | 按支柱的类型化内容,按 JSON Schema 2020-12 校验 | 解析阶段,外壳校验通过之后 |
| 3 — provider 能力门控 | Workload 内容由所绑定 provider 的合成模式能力进行门控,并由 provider 渲染插件的 spec.provider.workloadSchema 记录 | 基础渲染阶段,valuesMapping 解析之后 |
关于四层错误形态表以及各层的错误前缀,参见 validation-surface.md。
默认值机制
默认值通过几种不同的机制出现在整个语料中。作者会在五个以上的上下文中遇到“default”一词;下表是权威参考,说明当作者将字段留空时由哪种机制产生值。
| # | 机制 | 编写位置 | 触发条件 |
|---|---|---|---|
| 1 | JSON Schema default:(紧凑形式 { default: <value> }) | Component / Feature schema:、Aggregate parameters: | 当开发者省略该键时,字段以默认值通过校验。对于 Aggregate 参数,参数合并会在契约校验运行之前填入声明的默认值(参见 templates/parameters-context.md)。 |
| 2 | Go 模板 optional .X `Y` <fallback> | Recipe valuesMapping:、Workload 主体、FeatureRecipe 模板、断言求值器 | 感知存在性的回退——仅当映射中不存在该键时才返回 <fallback>;若该键处编写了零 / 空 / false,则返回所编写的值。这是 Aggrega 侧缺失字段回退的权威形式。参见 templates/sprig-functions.md。 |
| 3 | Go 模板 | default <expr> | Recipe valuesMapping:、Workload 主体、FeatureRecipe 模板 | 在“空”时触发的内联管道(Sprig 的空值检查——零、空字符串、false、nil)。它将映射中缺失与存在但为零/空/false 混为一谈。适用于可以接受这种混淆的按调用点覆盖语义(绑定的回退值不同于字段在 schema 层的默认值)。不适用于编写的零 / 空 / false 属于合理意图的缺失字段回退——这种情况请使用 optional(机制 2)。 |
| 4 | Sprig default 函数({{ default <expr> .field }}) | 同 3 | 机制 3 的函数形式,具有相同的空值混淆。 |
| 5 | Recipe locals: 回退 | Recipe locals: 模板 | 某个 locals 条目计算出一个带默认值的字符串,供 Recipe 的其余部分使用 |
推荐的放置指南。 当默认值确实属于类型契约的一部分时(例如“该端口默认为 5432,除非开发者覆盖”),JSON Schema default:(机制 1)是权威方式——IDE 自动补全会显示默认值;校验工具会遵循它;契约随 Component / Feature 目录实体或随 Aggregate 参数声明一起携带。当 Recipe 模板需要为可选映射键提供回退时,optional 辅助函数(机制 2)是权威的缺失字段回退形式——它能区分编写的零 / 空 / false 与缺失。Go 模板 | default(机制 3)保留用于可以接受缺失值与假值混淆的按调用点覆盖场景;仅当覆盖语义是明确意图时才使用它。
交叉引用
inheritance-and-interface.md—extends:机制、implements:接口绑定(Interface Binding)、schema-bridge 跨支柱管道传递。topology-triad.md—provides、inject、uses的拓扑机制。labels-and-annotations.md— 区别于数据支柱的内容侧元数据词汇(上文的规范支柱列表不包含 labels / annotations / 发布字段,它们属于元数据词汇)。publishing-surface.md— 区别于数据支柱的发布侧元数据词汇。validation-surface.md— 四个 schema 校验层,包括上文的三个支柱校验层级。templates/expansion-matrix.md— 各模板位置上跨支柱读取的可用性,以及 Recipeprovides:和source:处的自包含规则。examples/04-secrets.md— 六触点的密钥交付检查清单。architecture/06-data-taxonomy-and-composition.md— 五个 DSL 结构关键字的规范概念框架。