知名注解
Providers 读取特定的注解,以配置特定于平台的上下文——这些注解设置在 Release 边界或 Release 组件条目上,或在 Aggregate 中声明于子系统或组件实例上。编译器本身与这些注解的值无关——它将这些值作为不透明字符串原样传递。每个 provider 声明它读取哪些注解、在哪个作用域读取,以及注解缺失时采用什么默认值。该声明位于提供 provider 渲染功能的 Plugin 的 spec.provider.wellKnownAnnotations 上,并且有意保持精简:provider 只列出它确实读取的键。不读取其中任何注解的 provider 则改为声明 spec.provider.readsNoWellKnownAnnotations: true。
本章中的支持矩阵由这些声明生成,其粒度与声明所携带的粒度一致——按 provider 按输入类型划分,因为一个 provider 可能在合成部署单元时能读取某个键,而在渲染内置的制品时却无法读取它。请依据此处的矩阵进行编写:每个单元格说明该 provider 在该路径上读取什么,因为单元格无法表述 provider 未声明的任何内容。如果某个声明指定了该 provider 自身渲染行为契约并不渲染的输入类型,则在读取该 Plugin 实体时会被拒绝,因此这两项声明不会相互矛盾。
保留词汇表是范围更广的集合,它改为存在于两个地方——本章(列出每个保留键,包括没有 provider 读取的键),以及发布 lint 所检查的保留前缀集合。
不变量
- 编译器从不解释或校验 provider 知名注解的值:它将键及其值沿级联传递,并在目标不对该键采取行动时发出警告。
- 每个 provider 都会说明它读取哪些注解以及应用哪些默认值。
- 注解在一个边界内统一生效。如果某个值因 component 而异,它应放在 component 级注解中(覆盖边界注解),或放在 component 的
infra中。 - Provider 知名注解从不与组件标签重复。Component 标签描述组件是什么。边界注解描述组件部署在哪里。
- Recipes 不处理 provider 的知名注解。在 Recipe 生成其内容之后,provider 会自动应用放置上下文(命名空间、镜像仓库前缀、服务账号)。
aggrega.ai/前缀保留给标准库使用。企业自定义注解使用各自的前缀。- Release 中的 Component 级注解会覆盖边界级注解(深度合并,组件优先)。当某个 provider 将多个边界的输出组装为一个制品时,它可能要求某个注解在这些边界之间解析为统一的值:
helm-chartprovider 从aggrega.ai/chart-name获取伞形 chart 的名称;当多个边界向同一个 chart 提供内容,且它们将该注解解析为不同的值时,构建会中止并指出存在分歧的边界,因为一个 chart 不能有两个名称。 - Aggregate 声明的注解作用于相同的键,但优先级低于 Release 的注解。在子系统或组件实例上声明的键——无论是在 Aggregate 本身中,还是在它导入的模块中(此时作用于该模块自身的组件)——只要 Release 没有为该键设置值,就适用于该组件;如果 Release 设置了值,无论设在边界上还是组件的条目上,所应用的都是 Release 的值。目录实体自身的注解从不设置这些键。
aggrega.ai/chart-name是 Aggregate 作用范围的例外:它命名的是一个装配而非组件,并从为该装配做出贡献的 Release 边界中读取。
完整注解矩阵
如何阅读此矩阵
下面六张类别表列出了保留的 aggrega.ai/ 词汇中的每个注解、它控制的内容,以及该注解缺失时 provider 的行为。某个 provider 是否应用某个键是一个更细的问题,因为一个 provider 会渲染不止一种输入类型——供应商提供的制品(sourced)、由 provider 自行合成的 Workload(synthesized),或以 Recipe 的 artifacts: 作为节点全部输出(artifacts-only)——一个键可能在其中一条路径上被读取,而在另一条路径上无法触及。哪个 provider 渲染哪种输入类型见 ../../architecture/16-recipe-input-composition.md;每个 provider 应用哪些键见下文的按 provider 和输入类型的支持情况,它是本页的权威说明。
该表格中的每个单元格属于以下三个层级之一:
- 已应用——provider 在此输入类型上应用该键,渲染输出因此发生确定性的变化。
- 有条件应用——编译器在目标制品旁边生成一个附加的覆盖,而不是编辑该制品,因此该值是否生效取决于该制品自身是否暴露了匹配的键。实践中有效,但从不是保证。没有任何 provider 实现有条件的单元格,声明接口也无法表达这种情况,因此下面生成的表格只包含另外两个层级。之所以命名这一层级,是因为对于供应商提供的制品,这条途径确实存在;若只用两个层级的词汇,矩阵要么声称一个它无法做出的保证,要么否认这条途径的存在。
- 未应用——在这条路径上没有 provider 应用该键:目标在那里没有对应的渲染槽位,因此放置机制对渲染结果没有任何贡献,类别表的默认值列说明你得到的是什么。该值仍作为不透明字符串原封不动地经过构建。这一层级以机制而非值的去向命名,因为这是两个不同的问题,而单元格只能回答前者:provider 应用什么,是该目标渲染槽位的属性,而这正是每个单元格背后的声明所陈述的内容。
有两种作用域,其中只有一种让输入类型成为有意义的维度:
- 节点作用域——
aggrega.ai/namespace、aggrega.ai/image-registry、aggrega.ai/image-pull-secret、aggrega.ai/service-account和aggrega.ai/kubernetes-version决定单个组件自身的渲染输出,该输出由其输入类型所选的路径生成。它们是表格的列。 - 装配作用域和引用作用域——
aggrega.ai/chart-name在装配 umbrella chart 时解析一次,三个aggrega.ai/aws-*键在引用跨越边界时解析。输入类型对两者都不是维度:无论每个参与的节点如何渲染,该值都在装配处或引用处读取。它们有自己的表格,见按装配和按引用解析的键。
类别 1 — 放置
| 注解 | 应用方 | 用途 | 默认值 |
|---|---|---|---|
aggrega.ai/namespace | helm(sourced、synthesized);compose(sourced、synthesized) | Kubernetes 命名空间(helm);Docker 网络名称(compose) | 缺失时不注入(helm);一个以 compose 文件路径命名的网络,由该文件中所有未带该注解的节点共享(compose) |
aggrega.ai/project-name | 保留;没有 provider 读取它 | 保留用于 Docker Compose 项目名称 | — |
aggrega.ai/region | 保留;没有 provider 读取它 | 保留用于放置作用域的云区域 | — |
aggrega.ai/account-id | 保留;没有 provider 读取它 | 保留用于放置作用域的云账号标识符 | — |
aggrega.ai/kubernetes-version | helm(sourced) | 组件所部署到的集群的 Kubernetes 版本,从源码渲染的 chart 将其读取为 .Capabilities.KubeVersion | 同一 helm 版本的原生 helm template 所渲染的版本:即构建该 provider 时所用的 Kubernetes 客户端库的版本 |
aggrega.ai/namespace 在设计上具有双重用途。它以各目标的原生形式表达同一种逻辑隔离意图——“此边界的资源位于其自己的可寻址作用域中”:对 helm 是 Kubernetes metadata.namespace,对 compose 是 Docker 网络名称。Recipe 作者设置一个注解;每个 provider 按目标适当地将其具体化。对于 compose,网络名称按节点从该节点上的注解解析,节点未携带注解时回退到 compose 文件的路径——因此共享同一 compose 文件、未带注解的边界共享同一网络,而将它们分开的正是 aggrega.ai/namespace。无论由两者中的哪一个提供标识,它随后都会被写成 compose 网络名称接受的字符——其他任何字符都会写成转义而不是被替换,因此只要有任何差异的两个标识就会保持在两个网络上,标识的大小写也保持编写时的样子。compose provider 参考完整记录了这一派生过程,包括如何读取编码后的名称以及重命名的代价。
aggrega.ai/kubernetes-version 表述的是组件所部署到的集群的属性,而不是组件在集群中落在何处:chart 模板会根据其渲染所针对的版本选择 API 版本、字段或整个机制,而构建过程没有可以询问的集群。helm provider 读取该值的方式与 helm template --kube-version 读取其标志的方式相同,遇到不是版本的值时会中止构建;未指定时,chart 按同一 helm 版本的 helm template 所渲染的版本进行渲染。helm provider 参考记录了可接受的格式和默认值。
类别 2 — 镜像仓库
| 注解 | 应用方 | 用途 | 默认值 |
|---|---|---|---|
aggrega.ai/image-registry | helm、compose — 仅 synthesized | 容器镜像的仓库前缀,应用于每个合成的容器镜像引用 | 无前缀 |
aggrega.ai/image-pull-secret | helm — 仅 synthesized | Kubernetes imagePullSecrets 名称,与合成 pod 的现有条目合并 | 无 |
类别 3 — 网络
| 注解 | 应用方 | 用途 | 默认值 |
|---|---|---|---|
aggrega.ai/cluster-domain | 保留;没有 provider 读取它 | 保留用于跨命名空间服务发现的 DNS 后缀 | — |
aggrega.ai/ingress-class | 保留;没有 provider 读取它 | 保留用于 Ingress 资源上的 Kubernetes IngressClass | — |
aggrega.ai/service-mesh | 保留;没有 provider 读取它 | 保留用于服务网格 sidecar 注入注解 | — |
类别 4 — 安全
| 注解 | 应用方 | 用途 | 默认值 |
|---|---|---|---|
aggrega.ai/service-account | helm — 仅 synthesized | 合成 Pod 的 Kubernetes ServiceAccount;两者均设置时覆盖 Recipe 的 workload.serviceAccount | Recipe 的 workload.serviceAccount;Recipe 未声明时不设置 |
aggrega.ai/pod-security-standard | 保留;没有 provider 读取它 | 保留用于 Pod Security Standards 级别 | — |
aggrega.ai/iam-role | 保留;没有 provider 读取它 | 保留用于绑定到 workload 的云身份角色 | — |
类别 5 — 打包
| 注解 | 应用方 | 用途 | 默认值 |
|---|---|---|---|
aggrega.ai/chart-name | helm-chart — 按装配 | Umbrella chart 名称 | Aggregate 名称与 umbrella 的组装路径相连接——参见chart 名称解析 |
aggrega.ai/chart-version | 保留;没有 provider 读取它 | 保留用于 Helm chart 版本 | — |
aggrega.ai/stack-name | 保留;没有 provider 读取它 | 保留用于显式命名的栈 | — |
aggrega.ai/tf-backend | 保留;没有 provider 读取它 | 保留用于 Terraform 状态后端标识符 | — |
类别 6 — 云目标
| 注解 | 应用方 | 用途 | 默认值 |
|---|---|---|---|
aggrega.ai/aws-account | cloudformation — 按跨边界引用 | 栈(边界)所部署到的 AWS 账号 | 同账号——跨栈引用通过同账号的栈导出导入解析 |
aggrega.ai/aws-region | cloudformation — 按跨边界引用 | 栈(边界)所部署到的 AWS 区域 | 同区域——跨栈引用通过同区域的栈导出导入解析 |
aggrega.ai/aws-assume-role-arn | cloudformation — 按跨边界引用 | 跨账号栈读取为访问对等栈导出值而承担的 IAM 角色 ARN | 跨账号引用上不提供角色 |
每个 CloudFormation 边界渲染为一个栈。当一条 uses 边从一个边界跨到另一个边界时,cloudformation provider 需要知道对等栈位于何处才能构造该引用:同一账号和区域中的两个栈通过栈导出和导入交换值;位于不同账号或区域的对等栈需要跨账号的栈输出读取,并可选择在所承担的角色下进行。这些注解承载了这一放置上下文。每个注解都在 provider 构造此类引用时读取,并在那一刻通过普通的注解级联解析——组件上设置的值优先于边界上设置的值,而 Release 设置的值优先于 Aggregate 声明的值。因此,边界级的值是表达它们的常见方式,但不是唯一方式。它们是不透明的标量指针字符串——provider 将其传入所构建的引用,从不根据实时 AWS 状态解析它们;账号、区域和角色由 Release 提供或在 Aggregate 中声明,最终的物理读取由运行时环境解析。当所有注解都缺失时,provider 将对等栈视为同账号、同区域,且不提供角色。
按 provider 和输入类型的支持情况
节点作用域的键,按 provider 和输入类型列出。列标题省略了每个键都带有的 aggrega.ai/ 前缀。applied 和 — 表示上文定义的层级,— 即未应用;n/a 表示该 provider 根本不渲染该输入类型,因此那里不存在可以应用或遗漏该键的路径。
| Provider | 输入类型 | namespace | image-registry | image-pull-secret | service-account | kubernetes-version |
|---|---|---|---|---|---|---|
helm | sourced | applied | — | — | — | applied |
helm | synthesized | applied | applied | applied | applied | — |
helm | artifacts-only | — | — | — | — | — |
compose | sourced | applied | — | — | — | — |
compose | synthesized | applied | applied | — | — | — |
compose | artifacts-only | — | — | — | — | — |
helm-chart | sourced | — | — | — | — | — |
helm-chart | synthesized | n/a | n/a | n/a | n/a | n/a |
helm-chart | artifacts-only | n/a | n/a | n/a | n/a | n/a |
terraform | sourced | — | — | — | — | — |
terraform | synthesized | n/a | n/a | n/a | n/a | n/a |
terraform | artifacts-only | — | — | — | — | — |
cloudformation | sourced | — | — | — | — | — |
cloudformation | synthesized | n/a | n/a | n/a | n/a | n/a |
cloudformation | artifacts-only | — | — | — | — | — |
随编译器分发的每个 provider 在此都有对应的行,包括完全不读取任何放置注解的 provider——空的行集将无法与尚未被描述的 provider 区分开来。单独提供的 provider 以相同方式声明其读取的内容,但不在此列出,因为已发布的页面无法枚举它从未见过的 provider。
一个 Recipe 可以同时声明多种输入类型——例如一个 workload: 旁边还带有 artifacts:。请按类型阅读表格:此类节点的合成输出对应 synthesized 行,其制品文件对应 artifacts 的情况。artifacts-only 行是 Recipe 只声明 artifacts: 而不声明其他内容的输入类型。
你不必查阅表格就能知道。 如果设置的键在你某次渲染的目标上、在该渲染的任何输入类型中都不被读取,就会产生一条警告,指出该键、该目标以及该渲染声明的每种输入类型,因此你意外落入的单元格会在构建时自行显现,而不必等你想到来这里查看:
warning: node "frontend" (provider "helm-chart"): target "helm-chart" does not support annotation aggrega.ai/namespace on sourced input and ignored it对于声明多种输入类型的渲染,警告针对的是整个渲染,而不是其中的一半。 由于各类型以相加的方式组合,目标只要在其中任何一种类型上读取该键,就确实会应用它,该渲染的输出也会带有结果——因此不会发出警告。只有当该渲染声明的每种类型都遗漏该键时才会出现警告,并且会列出所有类型:
warning: node "backend" (provider "helm"): target "helm" does not support annotation aggrega.ai/cluster-domain on sourced or synthesized input and ignored it因此,source: 旁边的一个 workload: 就足以让 aggrega.ai/service-account 在该节点上生效,构建也不会对此发出提示——这是如实的报告,因为该值到达了合成的那一半,并出现在生成的清单中。
按渲染而非按组件阅读表格。 附加到节点的 feature 通过其自身 FeatureRecipe 指定的目标、以该 FeatureRecipe 声明的输入类型生成资源——因此它落在表格中自己的那一行,不一定是其宿主组件所在的行。一个合成其 Workload 的组件,若同时有附加的 feature 在旁边提供 artifacts:,则组件自身的清单对应 synthesized 行,附加项的文件对应 artifacts-only 行,在前者上应用的键可能在后者上被遗漏。警告遵循同样的划分,分别告知每一部分,因为它们是不同的文件。附加到边界而非某个具名组件的 feature 也以同样方式阅读表格。
该值仍原封不动地通过——构建不会中止,因为跨越异构目标上组件的边界总会有某些渲染无法处理某个给定的键,这是普通的 Release 而不是错误。边界注解会级联,因此编写的一行会为每个无法处理它的渲染产生一条警告,你由此可以看到输出中哪些部分受到影响。该警告属于 unsupported-field 类别,可用该类别的标志静默;详见警告。有两点限制值得了解:只检查裸 aggrega.ai/ 键,因为带子前缀的键属于你自己的词汇;未声明任何支持声明的 provider 不会产生警告,因为没有可以与你所编写内容进行比较的依据。声明自己不读取其中任何键的 provider 并不会以这种方式保持沉默:其 Plugin 实体上的 readsNoWellKnownAnnotations: true 是一个不涵盖任何键的支持声明,因此到达其某次渲染的每个裸键都会引发该警告。terraform provider 就作了这一声明。
为什么供应商提供的制品应用的键更少。 节点作用域的注解在 provider 拥有对应渲染槽位的地方应用。当 provider 自行合成部署单元时,它拥有结果的每个字段,因此仓库前缀、拉取密钥和服务账号都有落脚之处。而供应商提供的制品——Helm chart、compose 文件、Terraform 模块——带有自己的配置接口,编译器不读取该接口,因此无法知道仓库前缀或服务账号对应该制品自身的哪个键。由外层渲染调用控制的放置仍然适用,这就是 aggrega.ai/namespace 会应用于从源码渲染的 chart 的原因。而需要决定值在他人制品内部归属何处的放置则不适用,作者需通过该制品自身的 values 提供。这就是 sourced 行稀疏而 synthesized 行完整的原因,之后新增的任何键也应预期是这种形态。
按组装和按引用解析的键
随附的键中有四个不是节点作用域的,因此它们位于上方网格之外,而没有并入其中:输入类型对它们不是有意义的维度,为每个键按输入类型各列一行,会把同一个单元格重复三次,并暗示一种并不存在的区别。每个键都声明了边界作用域,下表即由这些声明生成。
| 注解 | 应用方 | 用途 | 默认值 |
|---|---|---|---|
aggrega.ai/chart-name | helm-chart | 组装出的伞形 Helm chart 的名称。 | 使用 Aggregate 名称和伞形 chart 的组装路径(即其在 dist/ 下的输出目录,例如 boundaries/data/helm-chart),二者各自编码后连接。 |
aggrega.ai/aws-account | cloudformation | 该 stack(边界)部署到的 AWS 账户。跨边界引用读取它,以判断对端 stack 是否位于同一账户。 | 对端被视为同账户,跨 stack 引用通过同账户的 stack 导出导入解析,而不是通过跨账户的 stack 输出读取。 |
aggrega.ai/aws-region | cloudformation | 该 stack(边界)部署到的 AWS 区域。跨边界引用读取它,以判断对端 stack 是否位于同一区域。 | 对端被视为同区域,跨 stack 引用通过同区域的 stack 导出导入解析。 |
aggrega.ai/aws-assume-role-arn | cloudformation | 跨账户 stack 读取为访问对端 stack 的导出值而承担的 IAM 角色 ARN。 | 不提供角色,跨账户引用不带 assume-role。 |
各键何时解析,这一点声明本身并不携带。aggrega.ai/chart-name 在每次伞形 chart 组装时解析一次,来源是边界注解级联;同一组装的所有贡献方都必须将其解析为同一个值,不一致时构建会中止并指出相关边界。三个 aggrega.ai/aws-* 键按每个跨边界引用解析,遵循组件优先于边界的优先级,因此组件上的值优先于边界上的值;上文类别 6 描述了每个键所塑造的引用。
没有 provider 读取的保留名称
上方矩阵中有十一个键标记为保留;没有 provider 读取:aggrega.ai/project-name、aggrega.ai/region、aggrega.ai/account-id、aggrega.ai/cluster-domain、aggrega.ai/ingress-class、aggrega.ai/service-mesh、aggrega.ai/pod-security-standard、aggrega.ai/iam-role、aggrega.ai/chart-version、aggrega.ai/stack-name 和 aggrega.ai/tf-backend。
在 Release 上或 Aggregate 中设置其中任何一个键,对渲染输出都没有影响。没有 provider 读取它们,也不会代为应用任何默认值——特别是,不会为 aggrega.ai/cluster-domain 应用任何 DNS 后缀,因此需要集群域名的 Recipe 必须将其作为普通值提供,而不能依赖该注解。需要这些行为之一的 Recipe 作者,应将其表达为 Recipe 值或组件的 infra 字段。
没有 provider 声明这十一个键。 provider 的 wellKnownAnnotations 只列出
它读取的键,因此这十一个键都不会出现在其中——读者打开
helm、helm-chart、compose 或 cloudformation Plugin 时,看到的只有有效的键,
别无其他。这正是窄声明的意义:已声明的键就是
有效的键,其旁边的作用域说明它在哪条路径上生效。
其中两个保留名称与有效键相近,但不能与之互换。aggrega.ai/region 和 aggrega.ai/account-id 在放置作用域上命名区域和账户,不会到达任何 provider;cloudformation provider 读取的键是类别 6 中带云命名空间的 aggrega.ai/aws-region 和 aggrega.ai/aws-account。当你指的是 CloudFormation 跨 stack 放置上下文时,请编写 aws- 形式——不带前缀的这对键仅为防止冲突而保留,并未连接到任何功能。另有两个保留名称由其他机制而非注解覆盖:aggrega.ai/stack-name 是保留的,而 cloudformation 边界渲染到的 stack 名称由 release 和边界标识确定性地派生;workload 的云身份角色则作为发出该绑定的 Feature 上一个由运维人员设置的普通字段提供,而不是通过 aggrega.ai/iam-role。
这些名称仍然保留,并且仍然列在此处,因为 aggrega.ai/ 前缀是保留的:企业目录不得将这些键之一用于自己的含义,因为平台为其自身的含义保留了该键。本矩阵与发布 lint 检查的保留前缀集合共同构成保留登记册,二者由一项检查保持为同一组名称,该检查读取两者并在它们不一致时失败。因此,编写这十一个键之一既不会导致验证失败,也不会触发“不要使用裸 aggrega.ai/ 前缀”规则——它只是没有效果。
helm-chart 边界发出的伞形 chart 版本始终为 0.1.0;它是一个固定值,而不是 aggrega.ai/chart-version 的默认值。
注意:使用
aggrega.ai/前缀的 Manifestfeatures.annotations绑定会在加载时被拒绝;该前缀专门保留 给本章记录的 provider 公认注解。 编写注解驱动的 Feature 绑定的作者,标准库快捷方式使用feature.aggrega.ai/, 企业快捷方式使用自定义域名。注意:Release 注解上显式的
null会从覆盖它的边界或组件中移除继承的 绑定(注解驱动的 Feature 退出)。同一边界中未退出的同级组件 保留继承的绑定;缺失的键继续照常 从父级级联继承。
编译器读取的由目录编写的注解
上文所述均为提供方注解:在 Release 上编写或在 Aggregate 中声明,由编译器作为不透明字符串透传,由提供方读取。另有一套小得多的词汇方向相反——由架构师在目录实体自身的 metadata.annotations 上编写,由编译器读取,提供方永远不会看到。上文的不变式 1 针对的是提供方词汇,不适用于这些注解;编译器只读取此处列出的键,不读取其他键。
这些键位于 <scope>.aggrega.ai/ 子前缀之下,而不是裸的 aggrega.ai/ 前缀之下,因此不属于上文矩阵所承载的保留登记表,也不受发布 lint 对裸前缀键所应用的保留前缀规则约束。
| 注解 | 编写位置 | 读取方 | 用途 |
|---|---|---|---|
features.aggrega.ai/requiredType.<label> | Component metadata.annotations | 编译器,基于最终确定的图 | 声明一个存在性强制要求:该 Component 的每个实例必须至少带有一个类型等于该注解值的附件。<label> 是作者自选的后缀,用于在诊断信息中命名该要求;它不是槽名,也不会被任何东西解引用。用不同的标签重复该键即可声明多个强制要求。 |
任何作用域上的附件都能满足该强制要求——组件级或子系统级的 features: 块、Release 边界级或组件级的块,或由注解驱动的展开——因为它检查的是实例最终的附件集合,而不是每个附件的来源。未满足的强制要求会中止构建,并给出标签和所需类型;值不是 Feature 类型 URI,或前缀之后没有标签的键,会以另一个声明格式错误的诊断中止。完整的编写说明,以及强制要求与 featuresSchema 槽的区别,见 entities/component.md 的“Presence mandates”。
由 provider 发出的来源标签
上述注解流入构建——由 Release 或 Aggregate 编写,由 provider 使用。Providers 还会生成一组与之平行、流出构建的标签,并将它们附加到渲染输出上,以便下游工具能够将运行时资源追溯到生成它们的目录内容。这些来源标签不在 Release 上编写;它们派生自构建自身的状态(Recipe 标识、边界路径、aggregate 名称、环境、同步波次、编译器版本),并由 provider 在渲染时生成。
各 provider 发出的集合,会附加到 helm provider 渲染的每个 Kubernetes manifest、helm-chart provider 添加到子 chart 的每个通过 $import: 加载的 artifact,以及 compose 发出的每个服务上——helm-chart 子 chart 自身的模板按其作者编写的原样复制,因此它们带有该作者所写的任何内容:
| 标签 | 来源 | 发出情况 |
|---|---|---|
app.kubernetes.io/name | 节点 ID(对于 FeatureRecipe 发出的资源,则为该附件派生的标识符——见下文) | 仅 helm 和 helm-chart——Kubernetes 标准标签,不在 compose 服务上发出 |
aggrega.ai/component-id | 节点 ID(对于 FeatureRecipe 发出的资源,则为该附件派生的标识符——见下文) | 全部三个 provider |
aggrega.ai/recipe-uri | 生成方 Recipe 的 <recipe-name>:<recipe-version>(对于 FR 发出的资源,则为生成方 FeatureRecipe 的) | 全部三个 provider,当生成方实体同时设置了名称和版本时;在 helm 和 helm-chart 上为注解 |
aggrega.ai/boundary-path | 该组件被路由到的边界路径 | 全部三个 provider,当边界路径非空时;在 helm 和 helm-chart 上为注解 |
aggrega.ai/aggregate-name | Aggregate metadata.name | 全部三个 provider,当已设置时 |
aggrega.ai/compiler-version | 构建时写入的编译器版本 | 全部三个 provider,当已设置时 |
aggrega.ai/provider | 渲染该资源的 provider | 全部三个 provider |
aggrega.ai/provider-version | 该 provider 的版本 | 全部三个 provider |
aggrega.ai/environment | Release metadata.environment | 全部三个 provider——每个 Release 都会声明它 |
aggrega.ai/sync-wave | 每个边界的 syncWave 整数 | 全部三个 provider,当非零时;在 helm 和 helm-chart 上为注解 |
aggrega.ai/aggregate-name、aggrega.ai/environment、aggrega.ai/compiler-version、aggrega.ai/provider 和 aggrega.ai/provider-version 的值来自构建不要求其符合 Kubernetes 标签值规则的字符串——名为 imported/flow 的 Aggregate、名为 eu/prod 的环境、开发构建的 (devel) 版本。在 helm 和 helm-chart 上,若值已是有效的标签值,这些标签各自按原样携带其值;有效的标签值为:字母、数字、-、_ 和 .,两端为字母或数字,最多 63 个字符。否则,标签携带被改写为该形式的值——其他每个字符都变为 -,连续的 - 合并为一个,两端修剪到字母或数字,结果截断为最多 63 个字符——同时原样的值作为注解添加在同一键下。因此,名为 imported/flow 的 Aggregate 会被打上标签 aggrega.ai/aggregate-name: imported-flow,并带有注解 aggrega.ai/aggregate-name: imported/flow;不含任何标签可保留字符的值仅由注解携带。选择器按渲染输出中出现的标签值进行匹配,需要确切名称的工具在存在注解时读取注解。Compose 的标签值不受约束,它将原样的值作为标签携带。
各 provider 的发出说明
helm——标签落在每个渲染出的 Kubernetes 资源(Deployment、Service、PVC 等)的metadata.labels中,而标签值无法承载的键——aggrega.ai/recipe-uri、aggrega.ai/boundary-path、aggrega.ai/sync-wave,以及按上文所述被改写的任何标签的原样值——则落在metadata.annotations中。sourced 模式(Helm SDK 渲染并在渲染后注入标签)、synthesized 模式(workload 合成)和artifacts:路径产生相同的集合。helm-chart——相同的标签和注解会落在该 provider 添加到子 chart 的templates/中的每个通过$import:加载的 artifact 上。源 chart 自身的模板,以及放在子 chart 根目录的内联内容 artifact,都不带有这些标签和注解——参见 helm-chart.md。compose——标签落在每个发出的 compose 服务的services.<name>.labels中。sourced 模式(在合并后的 base + valuesMapping 文档上进行合并后标签注入)和 synthesized 模式(workload 合成直接设置服务的 labels 块)都产生相同的集合。Kubernetes 专用的app.kubernetes.io/name在 compose 输出中省略。
对于 FeatureRecipe 发出的资源,aggrega.ai/component-id 的值由附件构建,而非由宿主组件的名称构建——FeatureRecipe 交付这些资源的每种方式都是如此,因此附件的资源在标签上永远不会与宿主组件自身的资源无法区分。该标识是否也是这些资源命名的依据,取决于交付方式:Aggrega 合成的 workload 以该标识命名,而由附件作者提供的 chart 或片段则保留宿主组件的 Helm release 名称和输出文件前缀,因为作者自己的模板是针对该名称渲染的。该值如何组成——两种开头、各组成部分及其 -- 连接、标签无法承载的字符如何写出、对目标而言过长的值如何缩短,以及它是哪些名称的依据、不是哪些名称的依据——与 provider 无关,因此只在 vocabulary/labels-and-annotations.md “Provenance labels emitted on rendered output”中说明一次,此处不再重复。本页负责另一半:标签落在每个 provider 渲染输出的什么位置。
aggrega.ai/recipe-uri 解析为 FeatureRecipe 自身的 name:version,而非使用方 Recipe 的标识——读取该标签以识别生成方实体的下游工具,对组件发出的输出和 FR 发出的输出都能获得正确的来源。
Sync-wave 注解
上文的 aggrega.ai/sync-wave 键与一个 sync-wave 注解配对,下游工具读取该注解来确定其应用内容的顺序。在 compose 上,该键是一个标签,公开 wave 值以供选择器查询;在 helm 和 helm-chart 上,它是一个注解,而配对的注解则将该值放在各工具按约定读取的位置。
| 注解 | 发出情况 | 使用方 |
|---|---|---|
argocd.argoproj.io/sync-wave | helm,在其渲染的每个 Kubernetes 资源上;以及 helm-chart,在每个通过 $import: 加载的 artifact 上——前提是所属边界的 syncWave 非零 | ArgoCD 的 sync-wave 排序 |
helm.sh/hook-weight | 仅 helm,在 syncWave 非零时,用于已带有 helm.sh/hook 注解的图表模板化清单 | Helm 在 hook 阶段内的 hook-weight 排序 |
helm.sh/hook-weight 的生成取决于路径
有一个细节值得 chart 作者注意:helm.sh/hook-weight 只会出现在通过 chart 模板化路径渲染的 manifest 上,即通过 Helm SDK 渲染的 chart 的 templates/ 目录。通过 artifacts 路径生成的 Manifests(在 helm provider 上是 Recipe 的 artifacts: 块中的每个条目,无论是内联内容还是通过 $import: 加载;在 helm-chart 上是通过 $import: 加载的条目)会带有 argocd.argoproj.io/sync-wave 注解和完整的来源标签集,但它们不会获得 helm.sh/hook-weight,即使该 artifact 带有 helm.sh/hook 注解也是如此。
这一区别是结构性的:helm.sh/hook 和 helm.sh/hook-weight 是 Helm 运行时的排序原语,作用于图表模板化的 hook 资源。Recipe 作者的 artifacts 是在 Recipe 层声明的额外资源;默认情况下它们不参与 Helm 的 hook 生命周期。
如果需要对 hook 资源进行 Helm hook-weight 排序,请将该资源编写为由 helm provider 渲染的 Recipe 的 source: 目录下的图表模板,而不是 artifacts: 条目;helm-chart 子 chart 的模板按原样复制,不会获得这两个注解中的任何一个。该图表模板将同时获得 argocd.argoproj.io/sync-wave 和 helm.sh/hook-weight,其值与所属边界的 syncWave 值一致。
编写示例
边界级别的放置与注册表配置:
spec: boundaries: production: annotations: aggrega.ai/namespace: prod-east aggrega.ai/image-registry: registry.corp.com aggrega.ai/image-pull-secret: corp-registry-creds components: api: {} worker: {}按组件覆盖(对于同一注解键,组件优先于边界):
spec: boundaries: production: annotations: aggrega.ai/namespace: prod-east components: api: {} legacy-thing: annotations: aggrega.ai/namespace: legacy-east # override — this component deploys elsewhereAggregate 侧注解级联
注解也存在于 Aggregate 编写面上:位于子系统作用域(spec.subsystems.<name>.annotations)和组件实例作用域(spec.subsystems.<name>.components.<name>.annotations,顶层组件则为 spec.components.<name>.annotations)。Aggregate 侧级联将开发者编写的注解沿子系统树向下传递给所包含的组件。
级联规则
子系统级注解会传播到该子系统子树中的每个嵌套子系统和每个所包含的组件。更近层级的注解以键为粒度覆盖更外层级的注解:组件级注解会覆盖同一键上继承来的任何子系统级注解,而不影响同级键或同级组件。
某个作用域上的注解键处于以下三种状态之一:
- 缺省键:该作用域不为此注解声明值。嵌套子系统和所包含的组件会继承祖先作用域中的任何绑定。
- 字符串值:该作用域声明了一个值。嵌套子系统和所包含的组件会继承此值,除非它们声明了自己的值或选择退出。
- 显式 YAML
null:该作用域从其子树中移除此键上继承来的任何绑定。同级组件和同级子系统保留各自独立的继承;只有选择退出的作用域的子树失去该绑定。
spec: subsystems: data: annotations: feature.myco/db-pool: "shared-pool" # propagates to api and worker components: api: # inherits feature.myco/db-pool: "shared-pool" worker: annotations: feature.myco/db-pool: null # opts out for this component only special: annotations: feature.myco/db-pool: "vip-pool" # closer-level override在 Aggregate 中声明的 Provider 注解
上方矩阵中的键同样会在 Aggregate 中级联,提供程序会应用级联最终留在每个组件上的值。子系统的 aggrega.ai/namespace 决定其下每个组件的放置位置;组件实例自身的值则改为决定该组件的放置位置。Aggregate 导入的模块携带自己的级联:其子系统和组件实例作用于该模块自己的组件,而导入方 Aggregate 声明的任何内容都不会深入到模块内部。
在每个键上,Release 都位于 Aggregate 之上。如果 Release 为某个组件设置了某个键——在其边界上或在该组件自身的条目上——则应用 Release 的值;如果未设置,则应用 Aggregate 的值。两侧逐键分层叠加,因此只设置了 aggrega.ai/namespace 的 Release 会让 Aggregate 声明的 aggrega.ai/image-registry 继续生效。
Release 中显式的 null 只撤回 Release 自身的值。写有 aggrega.ai/namespace: null 的组件条目会移除其 Release 边界本应交给它的命名空间,随后该组件采用其 Aggregate 声明的值——如果 Aggregate 也未声明,则没有值。Release 无法移除 Aggregate 声明的值;它只能在其上设置自己的值。
# Aggregatespec: subsystems: billing: annotations: aggrega.ai/namespace: billing # api and worker render into billing components: api: type: core/server:1.0.0 worker: type: core/server:1.0.0 annotations: aggrega.ai/namespace: billing-batch # worker renders into billing-batch# Releasespec: boundaries: production: components: api: annotations: aggrega.ai/namespace: prod-billing # the Release's value wins: api renders into prod-billing worker: {}aggrega.ai/chart-name 是唯一不在此范围内的键:它命名由多个组件组装而成的伞形 chart,因此它从为该 chart 提供内容的 Release 边界中读取,而从不从组件的注解中读取。
Recipe 或 FeatureRecipe 模板按名称读取注解分组——.context.annotations.aggregate、.context.annotations.release 和 .context.annotations.catalog 各自保存该侧所写的内容——因此从某一个分组读取放置键的模板只能看到该侧的值。
侧与支柱的划分
“Aggregate 即编写面”不变式将 Aggregate 侧注解限制在 values 支柱。Manifest 注解绑定在 maps.infra(Release 侧路由)或 maps.values(Aggregate 侧路由)下声明路由路径;若某个 Aggregate 侧注解的绑定只声明了 maps.infra 路径,构建会中止,并给出明确的诊断,指出注解键、路由到的支柱和编写侧。对称的规则适用于 Release 侧:Release 侧注解只能通过 maps.infra 路由;针对仅含 values 的绑定的 Release 侧注解会触发相应的错误。每条诊断都归入注解值所在文档的领域:来自 Aggregate 的为 [DEVELOPER_ERROR],来自 Release 的为 [OPS_ERROR],因此诊断开头即指明应打开的编写面。
在两个支柱中都声明了路径的绑定,在每一轮中只路由与该侧兼容的子集:Aggregate 侧注解只触发 values 支柱的路径,Release 侧注解只触发 infra 支柱的路径。跨侧组合(values 来自 Aggregate,infra 来自 Release)会为每个 (Component, Feature) 对生成一个 Feature 附件,两个支柱均被填充,并以逐叶来源记录每个叶子由哪一侧提供。
编写示例:子系统注解路由到 values
# Manifest bindingspec: mappings: features: type: core/db-pool: db-pool-helm:1.0.0 annotations: feature.myco/db-pool: feature: core/db-pool:1.0.0 maps: values: - pool # routes to values.pool# Aggregatespec: subsystems: data: annotations: feature.myco/db-pool: "shared-pool" components: api: type: core/server:1.0.0 worker: type: core/server:1.0.0注解展开后,api 和 worker 都带有一个合成的 feature.myco/db-pool Feature 附件,其 values.pool 字段的值为 "shared-pool"。构建图(aggrega validate --release <release> --ir-graph)以 origin: annotation、side: aggregate 和 annotation_source: aggregate.yaml:subsystems.data.annotations.feature.myco/db-pool 记录每个叶子。
结构化注解值
具有多个可配置字段的 Feature 适合用单个注解键一次为其中若干字段提供值。结构化注解形式允许一个键在一次声明中路由到多个绑定路径:
# Aggregate Subsystem — Developer's intent for db-pool (values-pillar subkeys)subsystems: data: annotations: feature.myco/db-pool: db_name: "prod-db" read_replicas: 5# Release Boundary — Operator's sizing for db-pool (infra-pillar subkeys)boundaries: prod: annotations: feature.myco/db-pool: pool_size: 20 max_connections: 100Manifest 绑定在按支柱分组的 maps: 列表中声明全部四个子键的路由:
# Manifestspec: mappings: features: annotations: feature.myco/db-pool: feature: core/db-pool:1.0.0 maps: values: - db_name - read_replicas infra: - pool_size - max_connections注解值的形状为以下三种形式之一:
- 标量字符串:单个值。绑定必须总共恰好声明一个路径;该标量路由到此路径。
- 结构化对象:子键到子值的映射。每个子键的路径必须出现在绑定的
maps.infra或maps.values列表中;子值路由到所声明支柱上指定的 Feature schema 字段。 - 显式 YAML
null:在此级联作用域中整体退出所继承的绑定。
结构化值中的每个子键都独立地对照绑定的 maps 列表进行解析。若某个子键既不在 maps.infra 中也不在 maps.values 中,构建会中止,并给出明确的错误,指出出错的子键和已声明的路径。
结构化值的级联合并
结构化注解按子键进行深度合并级联。子级联作用域的注解与父级注解按子键合并;较近层级在子键粒度上覆盖父级:
subsystems: data: annotations: feature.myco/db-pool: db_name: "data-default" read_replicas: 3 components: api: annotations: feature.myco/db-pool: db_name: "api-override" # overrides parent at this subkey only # read_replicas not listed → inherits 3 from parent analytics: annotations: feature.myco/db-pool: read_replicas: null # per-subkey opt-out: removes inherited subkey # db_name not listed → inherits "data-default" from parent级联后的有效注解:
- Component
api:{ db_name: "api-override", read_replicas: 3 } - Component
analytics:{ db_name: "data-default" },read_replicas在此作用域已退出
若子级联层级的值是标量(而父级是结构化值),则整体替换而不合并。级联层级之间的形状不匹配以较近层级的值为准;编译器不会对形状不匹配发出警告。
整值 null 与逐子键 null
级联提供两种不同粒度的退出机制:
# Whole-value null — opts out wholesale at this scopecomponents: api: annotations: feature.myco/db-pool: null整个注解绑定在此组件上被抑制;在此作用域中,不会从该注解键合成任何 Feature 附件。同级组件保留其继承的绑定。
# Per-subkey null — opts out just one subkeycomponents: api: annotations: feature.myco/db-pool: db_name: "api-db" read_replicas: null注解在此作用域中继续生效,但 read_replicas 子键被抑制。其他子键(在此作用域声明或从父级级联层级继承的)保持不变。
编写指导:使用整值 null 在某个作用域禁用由注解驱动的 Feature 附件。若想保留注解的大部分贡献、只抑制一个或多个特定字段,使用逐子键 null。
逐子键的侧与支柱划分
当注解值为结构化值时,Aggregate-as-Authoring-Surface 不变量按子键适用。每个子键的支柱(依据绑定的 maps 声明)必须与编写侧兼容:
- Aggregate 侧注解只能携带路由到
maps.values的子键。 - Release 侧注解只能携带路由到
maps.infra的子键。
路由到不兼容支柱的子键会中止构建,并给出明确的错误,指出具体的子键和支柱。错误链会在中止前收集每个注解的所有不兼容子键,因此运维人员在一个构建周期内就能看到所有问题,而不必反复修复、重建。
逐子键类型校验
每个子键的运行时值都会对照目标 Feature 的 spec.schema 在所路由支柱上声明的类型进行校验。支持的声明类型为 string、integer、number、boolean、object、array、null。若子值的 YAML 类型与 schema 声明的类型不匹配,构建会中止,并给出明确的错误,指出子键、实际类型和声明类型。
类型匹配是严格的,不做强制转换。字符串 "20" 对应整数类型的 schema 字段时会中止;作者应在 Feature schema 上正确声明类型,或使用以字符串形式透传的标量注解。
严格校验的编写手段。 在 Feature 的 spec.schema 中未声明 type 的属性接受任何运行时值形状,包括嵌套映射。当 schema 未声明约束时,构建不会自行虚构约束。需要严格逐子键类型校验的作者应在 spec.schema 的每个属性上声明 type。下游的 FeatureRecipe 渲染层会处理注解贡献所携带的任何形状。
跨侧组合
当 Aggregate 侧注解(values 子键)和 Release 侧注解(infra 子键)针对同一 Component 上的同一 Feature 附件时,构建会将这些贡献合并为一个两个支柱均已填充的 Feature 附件。逐叶来源记录每个子键的来源:合成的附件中,values.db_name 归属于 Aggregate 编写位置,infra.pool_size 归属于 Release 编写位置。
跨侧组合模式是同时包含开发者意图字段和运维规格字段的 Features 的规范编写形式:Aggregate 声明认知层面的选择(使用哪个数据库、应用层面有多少副本);Release 声明物理规格(连接池多大、基础设施层面有多少连接)。一个 Manifest 绑定通过一组 maps 声明将二者联系在一起。
相关参考
- Provider 架构 — provider 插件架构,以及负责 provider 渲染的 Plugin 的作用。
- ../entities/release.md — Release 编写界面,边界注解和组件注解位于其中。
- ../entities/aggregate.md — Aggregate 编写界面,子系统注解和组件级注解位于其中。
- ../entities/manifest.md — Manifest 的
mappings.features.annotations映射,注解绑定在其中声明各自的maps:路由。 - ../../architecture/11-governance-and-compliance.md — 编译期来源标记机制,与由作者控制的注解相互补充。