Feature
Feature 实体的概念角色(Domain 2 中的模块化运维特性)见 architecture/04-entity-taxonomy.md。运维 Features 与凭据 Features(即带有 feature.aggrega.ai/kind: secret 标签的 Features)之间的区别见 architecture/08-credential-model.md。Feature 选择器所使用的语义标签词汇见 entities/component。本页介绍 Feature 目录的编写接口。
目录位置
与 Components(使用带类别子目录的三段式 URI)不同,Features 采用扁平组织:每个 Feature 在其发布者下占一个目录,其中每个版本各占一个目录。
aggrega-catalog/└── feature/ └── {publisher}/ # e.g., `core`, `acme` ├── secret-value/ │ └── 1.0.0/ │ └── feature.yaml # feature.aggrega.ai/kind: secret (credential Feature) ├── data-masking/ │ └── 1.0.0/ │ └── feature.yaml └── ...OCI URI:hub.aggrega.ai/feature/{publisher}/{feature-name}:{version}(例如 hub.aggrega.ai/feature/core/data-masking:1.0.0)。
编写契约
Features 声明:
metadata.labels:使用feature.aggrega.ai/kind: secret将一个 Feature 标记为凭据 Feature。该标签是供作者、目录站点和标签选择器使用的描述性元数据;没有任何编译器分支读取它,一次挂载产生什么,由 Manifest 将其类型映射到的 FeatureRecipe 决定,而不是由该标签决定。凭据 Feature 与普通 Feature 的挂载方式相同,位于同一挂载面上,可在任意作用域挂载。标准库的凭据系列按结果划分:core/secret-value将一个值送入注入管道;core/referenced-secret指名一个可引用的 secret 资源(Kubernetes Secret、AWS Secrets Manager secret、Vault 条目),该资源可以由其 FeatureRecipe 的输出创建,也可以是已存在的资源,并声明一个schema.provides输出契约——name(资源的与 provider 无关的定位符)和key(资源内的数据字段)——消费方以.features.<slot>.provides.<key>读取它来引用该资源,而无需重新推导其名称;core/referenced-secret-set实体化一个携带调用方提供的一组数据键的资源,并只发布定位符,供目标已知道其所读键名的消费方使用;core/secret-provided暴露一个已存在 secret 的值;core/generated-secret不产生任何内容,因为目标引擎自行生成并管理凭据,所以它既不声明values也不声明provides,其 FeatureRecipes 是纯粹的连接,不渲染任何字节。成员之间由两个维度区分:谁提供材料——作者写入它或指明从何处获取它,或者由目标引擎完全拥有它,如core/generated-secret——以及挂载产生什么:注入的值、可引用的资源,或根本不渲染任何内容。每个成员在同一挂载面上与其他成员对等,因此凭据槽位总是被绑定的,Releases 之间变化的是绑定它的内容。声明了schema.provides契约的凭据 Feature 要求实现它的每个 FeatureRecipe 发布这些键——否则构建中止——而featuresSchema槽位的selector指向它所需的系列成员。usesSchema(可选):声明该 Feature 可以消费的拓扑插槽(例如,凭据 Feature 指向 vault 的path/key插槽)。Split Schema 机制参见 architecture/13-catalog-and-registry.md §2。schema:校验 Feature 挂载的values和infra块——即 Developer 在 Aggregate 中对每次挂载配置的认知意图(values属于 Developer 的领域,Release schema 禁止在 Feature 挂载上使用values:),以及 Operator 在 Release 中按环境决定的容量(infra)。声明了default:的字段既会据此校验,也会在无人编写该字段时填入渲染后的支柱;参见 Feature 作用域与编写形态。接受以紧凑形式 YAML 简写(默认方式;参见vocabulary/compact-form-authoring.md)或完整 JSON Schema YAML 表达的 JSON Schema 2020-12,并可通过跨文档$ref:引用 SchemaLibrary 条目以共享形态(参见vocabulary/cross-document-ref.md)。携带 secret 材料的叶节点声明sensitive: true——标准库中的凭据 Features 标记持有材料的叶节点,并有意不标记其发布的定位符,因为资源名称和数据键都是公开的。该关键字及声明它所能达到效果的上限,见vocabulary/compact-form-authoring.md“Declaring a leaf sensitive”。featuresSchema(可选):声明该 Feature 自身运行所需的挂载槽位——Feature 声明槽位的方式与 Component 完全相同,因此本身需要凭据的 Feature(例如 Datadog sidecar Feature 的 API 密钥)会指明绑定点,而不是去借用宿主 Component 的槽位。关于 Feature 声明自身槽位、FeatureRecipe 读取填充内容的示例,参见 Feature 自身的凭据。每个槽位接受与 Component 的featuresSchema槽位相同的字段,语义相同——包括可选的selector(一个 Kubernetes 风格的标签选择器,约束哪个 Feature 可以填充该槽位,是usesSchema插槽选择器在槽位上的对应物;标签不满足它的填充会中止,且该选择器仅针对所挂载 Feature 的标签求值)、可选的sensitive(声明绑定该槽位的任何内容都处理 secret 材料——这是关于绑定点的陈述,而不是关于某个具体填充的陈述),以及同样的开放性:声明槽位从不禁止以未被任何槽位声明的名称进行挂载。完整字段表、槽位级敏感性声明及其与 schema 叶节点声明的区别,以及一个声明槽位的实体进行部署时的两种形态,均见 entities/component.md “Attachment Slots”。appliesTo/appliesToAnyOf:控制该 Feature 可挂载到哪些 Components 的标签选择器。在静态分析阶段由编译器原生的标签匹配引擎求值。选择器语法参考见下文 基于标签的挂载 和 architecture/13-catalog-and-registry.md §2 “Kubernetes-Style Selectors”。interoperability(可选):一个携带conflictsWith的嵌套块——即不能与本 Feature 同时到达同一组件的 Features。当一个组件最终同时携带二者时,无论各自挂载在哪个作用域,构建都会在渲染前中止。完整说明见下文interoperability块。
Feature 的结构化渲染绑定到其对应的 FeatureRecipe,后者将 Feature 接口映射到具体的基础设施实现。
基于标签的附加
Feature schema 上的两个 applies 选择器控制该 Feature 附加到哪些 Components,由编译器的原生标签匹配引擎在静态分析阶段求值:
appliesTo— 一个 Kubernetes 风格的标签选择器字符串,即 AND 组合接口。以逗号分隔的各项要求必须全部成立,支持完整的运算符集合:key=value、key!=value、key in (v1, v2)、key notin (v1, v2)、单独的key(标签存在)、!key(标签不存在)。声明appliesTo: "datastore.aggrega.ai/engine=vector"的 Feature 只附加到带有该确切键值对标签的 Components;appliesTo: "component.aggrega.ai/type in (server, worker), compliance.aggrega.ai/data-class notin (restricted)"在单个选择器字符串中表达“任何不持有受限数据的 server 或 worker”。appliesToAnyOf— OR 组合接口。一个选择器项列表,任意一项匹配即可。每一项要么是字符串形式的选择器(语法与appliesTo相同;字符串内的各项要求以 AND 组合),要么是仅用于相等匹配的扁平键值映射。当一个 Feature 适用于多种互不相关的组件形态时使用——例如,一个可观测性 Feature 适用于{ component.aggrega.ai/type: worker }或{ component.aggrega.ai/type: task },而无需把两者强行合并为单个选择器字符串。
如果没有 any-of 形式,架构师就需要为该 Feature 适用的每一种不相关组件形态重复编写同一份 Feature YAML。两种形式可以组合:一个 Feature 可以同时声明两者,其结果在两种形式之间以 AND 组合——appliesTo 字符串必须成立,且至少一个 appliesToAnyOf 项必须匹配。省略或为空的选择器不声明任何约束,匹配所有标签集合。
每次对该 Feature 的一个附加求值时,选择器字符串都会按这六种形式解析,超出这些形式的要求会终止构建,而不会被解读为其他某种选择器:空要求(开头、结尾或重复的逗号,或仅由分隔符组成的字符串)、含有空白或含有 =、!、(、) 及逗号中任一字符的键,以及未闭合的 in ( 或 notin ( 集合。这样可以捕获那些否则会悄悄选中与本意相反对象的错误:为让 Feature 不附加到前端而写的 appliesTo: "!tier=frontend" 会被拒绝,因为 ! 只命名标签键——排除某个值应写作 tier!=frontend;tier in frontend 也会被拒绝,应改写为 tier in (frontend)。值是其运算符之后的文本,无论包含什么字符,因此 tier==frontend 要求的是值为 =frontend 的标签。终止信息会指出该 Feature、其选择器以及无法解析的要求。没有任何附加的 Feature 永远不会被求值,因此其上格式错误的选择器要等到有附加指向它时才会被报告。
选择器语法参考见 architecture/13-catalog-and-registry.md §2“Kubernetes 风格选择器”——Feature 选择器接受的语法与 usesSchema 插槽选择器接受的语法相同,即 Kubernetes 用户在 kubectl get -l 中熟悉的字符串形式。
interoperability 块
Feature schema 声明一个可选的 spec.interoperability 块,其中只有一项控制:该 Feature 可以与哪些其他 Features 在同一个组件上共存。
interoperability.conflictsWith:与所定义的 Feature 互斥的 Features 列表,每一项的写法与挂载的 type 命名 Feature 的写法相同。它可防止生成不兼容的配置,例如在同一组件上同时挂载仅支持 TCP 的网格和感知 HTTP 的代理。
当某个组件最终同时带有此 Feature 和其列表所列的某个 Feature 时,构建会在渲染任何内容之前终止。判断依据是作用范围:挂载作用于它所写在的组件,以及它所写在的子系统或边界内的每个组件,包括嵌套的边界;写在 Release 组件条目上的挂载,或由注解驱动展开产生的挂载,也以同样方式作用于其组件。因此,以下情况下声明的冲突会导致终止:两个 Features 挂载在同一组件上;一个在边界上,另一个在该边界内的组件上;一个在外层边界上,另一个在嵌套于其中且包含组件的边界上;一个在子系统上,另一个在该子系统中的组件上。挂载在不共享任何组件的兄弟边界上的两个 Features 永远不会相遇,不包含任何组件的边界也不作用于任何内容,这两种情况都不会终止。
- 声明一次即可。 只要任一 Feature 的列表列出了另一个,构建就会终止;第二个 Feature 无需反过来列出第一个。
- 只比较名称,不论版本。 每个条目和每个挂载的 type 都会去掉版本后再比较,因此条目
core/fixed-replica-controller与挂载core/fixed-replica-controller:2.0.0匹配,而带版本的条目会匹配它所指 Feature 的所有版本。 - 只读取名称。 编译器将 Feature 作者声明的名称与组件所带的 Features 进行比较,这与
appliesTo属于同类求值,处理的是作者编写的数据。两个 Features 是否不兼容由作者判断,而该列表就是记录这一判断的地方。
终止信息会指出其列表列出另一方的那个 Feature、两者各自被挂载的每个位置(Aggregate 中的组件上、子系统上、带路径的 Release 边界上、Release 组件条目上,或由某个具名注解的注解驱动展开挂载),以及两者相遇的组件。在多个组件上相遇的一对会针对每个组件各报告一次。消息内容参见 errors/fatal-halts.md。
示例:
apiVersion: aggrega.ai/v1beta1kind: Featuremetadata: name: core/autoscaler version: 1.0.0spec: appliesTo: "component.aggrega.ai/type=server" schema: values: metric_target: { type: string, enum: [cpu, memory, custom], required: true } infra: min_replicas: { type: integer, min: 1, required: true } max_replicas: { type: integer, min: 1, required: true } interoperability: conflictsWith: - core/fixed-replica-controller此 Feature 只挂载到类型为 server 的 Components,并声明与另一个控制副本数的 Feature 不兼容:任何组件最终同时带有两者的构建都会在渲染之前终止。需要所挂载组件名称的 FeatureRecipe(例如为了让自动扩缩器指向其目标)会从其模板上下文中读取该名称,并写到其输出中需要的位置:.context.instance_id 是组件的标识,.context.rendered_name 是组件自身的 provider 为其渲染的资源所取的名称,按资源定位时应使用这个名称。在 helm 下,它是合成的工作负载所生成 Deployment 的名称,也是 chart 构建自身名称所依据的 release 名称。
通过 extends 继承
Feature 可以声明 spec.extends: <feature-name>,指向一个基础 Feature,并继承其编写接口。该引用通过基础 Feature 的 metadata.name 来命名它,而不是通过该 Feature 发布时使用的注册表坐标;它接受与所有目录引用相同的三种版本形式:裸名称(core/queue)表示可用的最高版本,精确版本(core/queue:1.0.0),或脱字符范围(core/queue:^1.0.0)。编译器在加载目录时遍历父链,校验该链无环,然后将父级 spec 合并到子级中,生成单个解析后的 Feature。键冲突时以子级编写的字段为准;父级的 metadata.labels 和 metadata.annotations、appliesTo / appliesToAnyOf 选择器、interoperability 块、usesSchema、featuresSchema,以及 schema 上的 JSON Schema 2020-12 声明会自动向下合并。其他所有 metadata 字段都原样取自子级,因此标识和来源信息永远不会被继承。
Feature 的 metadata: 继承哪些内容。 labels 和 annotations 沿继承链按键合并,基础 Feature 在先,共享键上以扩展方 Feature 的值为准——与 Components 遵循的规则相同。metadata: 的其余部分不会传递:name、version、description、maintainers、license、repository、home 和 keywords 均属于扩展方 Feature 自身,完全按编写内容保留。
# Base Feature — generic message queue intentapiVersion: aggrega.ai/v1beta1kind: Featuremetadata: name: core/queue version: 1.0.0spec: appliesTo: "component.aggrega.ai/type=worker" schema: values: qos: { type: string, enum: [at-most-once, at-least-once, exactly-once], required: true } infra: partition_count: { type: integer, min: 1 }
---# Child Feature — Kafka-specialized variantapiVersion: aggrega.ai/v1beta1kind: Featuremetadata: name: core/kafka-queue version: 1.0.0spec: extends: core/queue:1.0.0 schema: values: compression_codec: { type: string, enum: [none, gzip, snappy, lz4], default: none }合并后的 core/kafka-queue 从父级继承 appliesTo,继承 values.qos 和 infra.partition_count 属性,并在此基础上添加 values.compression_codec。显式声明 appliesTo 的子级会整体覆盖父级的选择器(标签选择器的合并不是深度合并——子级的选择器替换父级的选择器)。子级的 schema.values.qos 会覆盖父级对该属性的声明。
挂载接口的各部分如何继承。 两种选择器形式彼此独立地继承,因为它们是组合关系而非替换关系:每种存在的形式都必须满足——appliesTo 字符串必须匹配,并且至少一个 appliesToAnyOf 项必须匹配——而缺省的形式不施加任何约束。因此,一个 Feature 可以沿用其基础 Feature 的 AND 选择器,同时声明自己的 OR 集合。interoperability 块按字段继承——声明了该块但没有 conflictsWith 列表的子级仍带有其基础 Feature 声明的列表,而声明了自己的 conflictsWith 的子级会替换基础 Feature 的列表,而不是追加到其中。三者都不声明的 Feature 的挂载位置与其基础 Feature 完全相同。
继承是 schema 合并,而不是接口绑定。 Feature 的 extends: 链生成一个解析后的 Feature,而不是一个多态家族。Manifest 绑定的 feature: 字段引用的不是链中基础 Feature 的 URI——Manifests 按叶子 Feature 的 URI 绑定,解析后的 schema 包含继承来的属性。FeatureRecipe 通过 implements: 实现的 Feature 契约同样是叶子 URI;FeatureRecipes 不会遍历继承链。
aggrega pull 会获取基础实体。 基础 Feature 是每个挂接了扩展它的 Feature 的 Release 的依赖,无论是否有其他地方提及它。aggrega pull 会沿每个 extends: 追溯到链的末端,从 registry 获取任何 catalog 目录中都没有的基础实体,并把每个基础实体记录到该 Release 的锁文件中,由提及它的 Feature 的 spec.extends 引用;构建会从那里读取基础实体。
错误模式。 循环的 extends: 链,以及没有任何目录实体提供的父级,都会中止构建,并指出解析开始时的 Feature、需要打开其 extends: 行的 Feature,以及它声明的引用。消息见 Cyclic extends on Components or Features (Component 或 Feature 上的循环 extends) 和 An extends: chain cannot be assembled (无法组装该链)。
关于涵盖 Components、Features 和凭据 Features 的更广泛的继承 / 接口词汇,见 vocabulary/inheritance-and-interface.md。
可组合性:纯粹性社会契约
标准库的约定是一个 Feature,一个内部功能——可观测性边车就是一个可观测性 Feature;网络代理边车就是一个网络代理 Feature;二者不会合并为一个承载两个不相关关注点的复合体。该约定使各个 Features 保持可组合、可独立版本化、可独立挂载。
核心 Go 编译器不强制执行这一约定。混合多个关注点的 Feature 定义在语法上合法,并且可以正常编译。强制执行需要主动选择启用:
- 编写内部目录的企业可以编写自定义的 linter 插件,在 CI/CD 中检查 Feature 定义,并在单个 Feature 的
appliesTo标签跨越不相关的能力领域时发出警告。 - Feature 作者若在
interoperability.conflictsWith中记录两个 Features 会相互重叠,即选择启用一项构建时检查:只要二者作用到同一个组件,编译器就会停止。它只比较声明的名称,因此它强制执行的是作者写下的声明,而不是纯粹性约定本身。
开源标准库的 Features 通过编写规范遵循纯粹性约定;当紧密耦合的复合体确实契合部署模型时,企业目录可以自由偏离这一约定。
什么值得成为 Feature,以及产品自身的调节项应归于何处
Feature 是一种附加项:它带来开发者或运维人员有意附加的东西——资源、一个流水线步骤、连接配置——而标准库的约定是,它应能被至少两个独立产品所支持。后半句是编写 Feature 之前要应用的检验,因为可移植性正是 附加项 一词所承诺的。附加项意味着该能力可以迁移:把它附加到一个组件,再附加到另一个组件,每个产品的实现都以自己的方式支持它。
业界只有一个产品具备的能力,是该产品自身的调节项,而不是 Feature。 它应作为编写的值放在该产品自身的配置面上,由决定它的作者在其支柱中设置,并与配置同一产品的其他所有内容放在一起阅读。若将其发布为 Feature,就等于提供了其他任何产品都无法兑现的可移植性:该附加项在构造上只指向一个产品,因此作者把它附加到下一个想用的产品时,会遇到构建中止并报出该类型,而这个 Feature 就传授了一种它从未具备的能力。
该检验统计的是业界的产品,而不是本目录中的组件,每个产品都依据其自身当前的配置参考来判断。只要有两个独立产品实现了某项能力,无论这里提供了其中多少个,该能力都是可移植的;因此可以在目录中尚无任何实现之前就声明一个 Feature——此时附加它会使构建中止并报出该类型——而每个已提供的实现都是针对一个产品的 FeatureRecipe,以该产品的配置方式来支持该附加项。
上游证书固定就是一个实例。 固定(pin)是对上游可以出示哪个密钥的控制:只接受公钥与 Release 所提供的公钥相匹配的证书。这与要求上游证书链接到 Release 提供的信任锚是不同的断言,与断言证书主题内容也不同——后两者规定证书必须声明什么,而固定规定它必须是哪个密钥。这里有多个网关能够基于信任锚进行验证,因此 dataplane.aggrega.ai/upstream-tls: trust-anchor 是选择器可以匹配的值。固定是一项单独的能力,并且至少有两个独立产品为其向上游发起的连接实现了它:Tyk 接受 PEM 格式的上游公钥,Envoy 接受其哈希值。因此它是一个 Feature,即 core/upstream-key-pinning,其选择器指定 dataplane.aggrega.ai/upstream-pinning: public-key;而本目录实现了什么则逐个产品给出答案:core/gateway/tyk 带有该值,并为其每个目标提供一个 FeatureRecipe,而这里嵌入 Envoy 的网关只对客户端出示的证书暴露其固定设置,或根本不暴露,因此它们不带该值,附加到它们时会在选择器处中止。固定缩小了上游可以出示的范围;它是一种控制,并不保证连接在其他方面是可靠的。
该检验有两条边界,其中第二条最容易被忽略:
- 它是编写规范,而不是编译器检查。 一个声明了没有任何产品实现的选项的 Feature,同样能通过 schema 校验、发布 linter 和渲染——编译器不解释 Feature 承诺了什么。判断由目录作者负责。
- 某个产品无法支持某个选项,并不构成删除该选项的理由。 只要两个或更多产品以可归为一类的名称提供某项能力,该能力就是可移植的,Feature 应保留它;无法支持它的产品拒绝它即可。一个缩减到所有产品都支持的 Feature 几乎就没什么可说的了。
Feature 的作用域与编写形态
Feature 的 spec.schema 定义 Feature 自身的 values: 和 infra: 形态:values 是 Developer 在 Aggregate 中按每个 Feature 挂载配置的认知意图,区别于 Operator 按环境决定的容量数值(infra)。Feature 的支柱位于各自的命名空间中,独立于宿主 Component 的支柱进行验证。当 Developer 在 Aggregate 中将一个 autoscaler Feature 挂载到一个 web-server Component 上时,Aggregate 携带 Component 的 values:(宿主形态)以及 Feature 的 values:(扩缩意图形态,即由哪个指标驱动扩缩);面向 operator 的容量数值(min_replicas / max_replicas)则通过 Release 中该 Feature 挂载上的 infra: 块传入。
# Aggregate fragment — Feature attachment with its own values:components: web-server: type: core/web-server values: log_level: "info" # the Component's own values tls_enabled: true features: autoscaler: type: core/autoscaler values: metric_target: "cpu" # the Feature's own values (dev intent: scale on CPU)# Release fragment — Feature attachment's infra block (operator-side capacity):boundaries: prod: components: web-server: features: autoscaler: infra: min_replicas: 2 max_replicas: 10Feature 的 schema: 验证 Feature 挂载自身的 values: 和 infra: 块。Component 的 schema: 验证 Component 自身的块。两者在静态分析阶段独立求值;与 Feature 的 schema: 不匹配的挂载支柱会使构建中止,错误的作用范围是 Feature 挂载位置,而不是宿主 Component。被验证的是挂载的有效配置,即组合所有配置过它的作用域后的结果,因此一个在某个作用域中合规、随后在更窄作用域中被覆盖为非法内容的值会被捕获。
**声明的默认值会物化到挂载的渲染支柱中。**除验证之外,在 Feature 的 values 或 infra 字段上声明的 default: 会在构建时填入该挂载的渲染支柱中,用于所有未被编写的键,因此读取 {{ .infra.tier }} 的 FeatureRecipe 模板得到的是 schema 声明的值,而不是空值。作者提供的值始终优先,默认值只填充其省略的键:一个只编写了 Feature schema 中某个键的挂载,仍会获得该 schema 其他键的声明默认值;部分编写的嵌套对象会保留已写的内容,并补上未写的同级键。
编写时值得了解填充的三个特性:
- **默认值从不取代任何作用域提供的值。**当一个 Feature 在多个作用域上挂载时(例如一个 Release 边界及其某个 component),以更窄作用域的值为准,默认值只填充所有作用域都未写入的内容。
- **默认值填充挂载,但从不创建挂载。**在未被任何对象挂载的 Feature 上声明默认值不会对输出产生任何影响,因此 Feature 的 schema 无法添加没有作者要求的配置。
- 在 Release 边界而非单个 component 上声明的挂载只填充
infra,因为该表面没有可填充的values:块。
由于物化使用与验证相同的 schema 解析,在父 Feature 上声明的默认值会传递到 extends: 子项的挂载中,通过跨文档 $ref: 引用到 SchemaLibrary 中的默认值也会被物化。仅在本地文档内 #/$defs/ 引用中声明的默认值,或在 allOf / oneOf / anyOf 分支下声明的默认值,不会被物化。
有一个后果值得明确说明,因为仅靠验证无法发现它:同时带有 default: 的 required: 字段会由该默认值满足,因此省略它是合法的,而检查所接受的值就是渲染输出所携带的值。
编译器的模板上下文通过 .features.<alias> 字段(每个挂载包含 .type、.resolved_version、.labels、.values、.infra 和 .provides)向绑定的 FeatureRecipe 暴露 Feature 的实例状态。FeatureRecipe 中的模板在 FeatureRecipe 自身的模板作用域内通过 .values.<field> 读取 Feature 自身的 values:;除非 Feature 显式声明了指向宿主 Component 的 uses: 插槽,否则宿主 Component 的 values: 对 FeatureRecipe 的模板不直接可见。
这种作用域分离使 Features 可组合:autoscaler Feature 不依赖于它挂载到哪个 Component;无论宿主是什么,其 schema: 都描述自动扩缩意图。宿主 Component 的 values: 归宿主负责;Feature 的 values: 归 Feature 负责;两个支柱相互组合,字段名不会跨越边界泄漏。
注解绑定目标
Feature 本身不声明注解绑定;这些绑定由 Manifest 的 mappings.features.annotations 映射承载。Feature 作为路由目标间接参与绑定关系:每个绑定通过其 feature: 字段指定一个 Feature 类型,绑定的 maps.infra 和 maps.values 列表声明指向所指定 Feature 的 spec.schema.infra.<path> 和 spec.schema.values.<path> 属性的点分路径。
在加载 catalog 时,编译器会验证绑定的 maps 列表中的每个点分路径,都对应目标 Feature 的 spec.schema 在所指定支柱上实际声明的属性。如果绑定路由到 Feature schema 未声明的路径,catalog 加载会以明确的 OPS_ERROR 中止,并指出该绑定、目标 Feature 以及它所路由经过的支柱和路径——绑定写在 Manifest 中,而 Manifest 是运维人员的文档。因此,schema 作者可以确知,他们在 spec.schema.values.<path> 或 spec.schema.infra.<path> 下声明的任何属性都可以作为绑定目标;反之,Manifest 绑定所路由经过的任何属性都必须存在于目标 Feature 的 schema 中。
当 Aggregate 侧或 Release 侧的注解与某个绑定匹配时,编译器会合成一个 Feature 附加,其支柱载荷将注解值路由到所指定的路径中。合成的附加在结构上与同一位置由作者显式声明的 Feature 附加无法区分;下游的渲染、验证以及 FeatureRecipe 模板上下文都以统一方式处理这两种形态。关于绑定形态、侧与支柱的划分以及显式附加优先的原则,请参阅 entities/manifest.md §“Annotation-Driven Feature Bindings”。关于 Aggregate 侧的级联规则和编写示例,请参阅 providers/well-known-annotations.md §“Aggregate-side annotation cascade”。
assertions: 块
Feature.spec.assertions: 是一个可选的映射,由具名规则组成,用于表达 Feature 契约的架构不变量——即针对该 Feature 的 values: 以及所附着 Component 的解析后状态的跨字段规则。每个键是一个规则标识符,会出现在失败消息中;每个值是一个 Go 模板主体。编译器在 schema 校验之后、绑定的 FeatureRecipe 渲染之前,按书写顺序对它们求值,第一个失败的规则会以该规则自身的错误消息中止构建。
spec: appliesTo: "component.aggrega.ai/type=server" assertions: active-active-needs-two-replicas: | {{- if and (eq .values.mode "active-active") (lt .values.replicas 2) -}} {{- fail "mode=active-active requires replicas >= 2" -}} {{- end -}}与 Component 断言一样,Feature 断言表达的是契约层面的不变量——即无论由哪个 FeatureRecipe 实现渲染,该 Feature 附着都必须满足的属性。对于依赖具体实现的跨字段规则(例如某个 Wasm 插件的要求、某个 chart 的特殊行为),请改用 FeatureRecipe 的 assertions: 字段。关于完整的编写语法、模板上下文,以及 Feature 断言与 FeatureRecipe 断言之间的职责划分,请参阅 templates/assertions-block.md。