附加无人编写的 Features 的策略:在 `annotation-transform` 注入的注解
一个治理策略为商店的每个组件提供平台的监控和一个 AWS IAM 角色。它通过添加注解来做到这一点。Manifest 将两个注解键绑定到两个 Features,位于已绑定键下的注解会展开为一个 Feature 附件。因此,策略添加的注解为每个组件带来一个 Prometheus ServiceMonitor 和一个 Kubernetes ServiceAccount,而 Aggregate 和 Release 都不编写它们。
该策略附加在 annotation-transform 角色上,为编译进 CLI 的每个策略引擎各附加一次:Rego 和 CEL。核心证明是一个手工编写相同注解的对照 Release。在不使用策略的情况下构建,它渲染出的文件与策略为其添加注解的那个 Release 逐字节相同。
它构建了什么
| 实例 | 目录中的 Component | 它在 release.yaml 中携带的内容 |
|---|---|---|
api | example/compute/service | 不发送 |
worker | example/compute/service | 不发送 |
gateway | example/compute/service | 它自己的监控注解,间隔为 10 秒 |
这三者都通过 Helm 编译到 Kubernetes,输出到 dist/shop/helm/。example/compute/service 是标准库目录中的一个演示 Component。它的每个实例都必须携带一个 core/prometheus-exporter 附件,这是该 Component 声明、由构建检查的要求。
两个注解绑定
manifest.yaml 为两个注解键赋予含义:
features: type: core/prometheus-exporter: helm/prometheus-exporter:1.0.0 core/aws-irsa: helm/aws-irsa:1.0.0 annotations: feature.aggrega.ai/monitoring: feature: core/prometheus-exporter maps: infra: - interval - port - path aws-role: feature: core/aws-irsa maps: infra: - role_arn路由多个子键的绑定以一个逐一命名这些子键的对象作为值,因此 feature.aggrega.ai/monitoring 接受 {interval: …, port: …, path: …}。只路由一个子键的绑定接受一个字符串,因此 aws-role 接受角色的 ARN。注解展开成的挂接以其键命名。core/aws-irsa 以挂接的名称为其 ServiceAccount 命名,这就是该键不含点号或斜杠的原因。
挂接策略
.aggrega-config.yaml 将 hub 指定为其仓库,不指定任何目录文件夹,也不包含任何治理挂接。策略由构建通过 --config 指定的文件挂接:Rego 引擎用 governance-rego.yaml,CEL 引擎用 governance-cel.yaml。Rego 的那个文件内容如下:
plugins: governance: - uri: governance/rego:0.9.0 role: annotation-transform with: sources: - policies/platform-defaults.rego--config 指定本次运行的全局配置文件,取代机器原本会读取的那个文件,而本工作区的 .aggrega-config.yaml 仍然叠加在其之上。
0.9.0 是 hub 发布每个引擎的 Plugin 实体的一个版本,因此挂接可以从工作区读取的仓库中解析,也可以从该版本的 aggrega 二进制文件中解析,该文件本身带有该实体。实际运行的引擎是编译进运行本次构建的 aggrega 二进制文件中的那个,无论挂接指定的是哪个版本。监控注解所接受的对象需要一个能注入子键对象的引擎,而 0.8.7 之前的版本中的引擎做不到这一点。
annotation-transform 策略读取的内容
位于 annotation-transform 的策略读取两样东西:
input.targets列出它可以注解的每个组件。每个目标都有一个boundary_path、一个component_name,以及 Release 写在该组件上的annotations,每个值都保持书写时的原样。input.binding_keys列出 Manifest 绑定的注解键。
aggrega build --release <release> --dry-run --policy-input <dir> 将每个角色接收到的载荷写入 <dir>,除此之外不写入任何内容。在 release.yaml 的一次构建填充其锁文件之后:
aggrega build --release release.yaml --config governance-rego.yaml --dry-run --policy-input payloadsjq -c '.binding_keys' payloads/annotation-transform.json# ["feature.aggrega.ai/monitoring","aws-role"]jq -c '.targets[]' payloads/annotation-transform.json# {"boundary_path":"shop","component_name":"api","annotations":{}}# {"boundary_path":"shop","component_name":"worker","annotations":{}}# {"boundary_path":"shop","component_name":"gateway","annotations":{"feature.aggrega.ai/monitoring":{"interval":"10s","port":"metrics","path":"/metrics"}}}目标的 annotations 保存的是 Release 写在组件本身上的内容。边界的 aggrega.ai/namespace 不在其中。
策略
policies/platform-defaults.rego 在 annotations 下为每个注解收集一个决策。每个决策先用读取目标时所依据的两个字段指明目标,然后给出键和值:
annotations contains { "boundary_path": t.boundary_path, "component_name": t.component_name, "annotation_key": monitoring, "annotation_value": {"interval": "30s", "port": "metrics", "path": "/metrics"},} if { monitoring in input.binding_keys some t in input.targets not monitoring in object.keys(t.annotations)}
annotations contains { "boundary_path": t.boundary_path, "component_name": t.component_name, "annotation_key": role, "annotation_value": sprintf("arn:aws:iam::123456789012:role/shop-%v", [t.component_name]),} if { role in input.binding_keys some t in input.targets not role in object.keys(t.annotations)}每条规则只对 input.binding_keys 中的键触发,因此策略不会添加 Manifest 未赋予含义的任何内容。每条规则还会跳过已经带有该键的目标。针对组件已带有的键的决策会替换 Release 写入的值。没有这项检查,gateway 的 10 秒间隔就会被策略的 30 秒取代。
policies/platform-defaults.cel 将同样的两个决策表述为一个表达式,用 + 连接两个列表。映射键用 in 而不是 object.keys 测试,角色的 ARN 用 + 拼接,因为该表达式语言没有 sprintf。表达式中关于角色的那一半如下:
+ input.targets .filter(t, "aws-role" in input.binding_keys && !("aws-role" in t.annotations)) .map(t, { "boundary_path": t.boundary_path, "component_name": t.component_name, "annotation_key": "aws-role", "annotation_value": "arn:aws:iam::123456789012:role/shop-" + t.component_name, }),构建渲染的内容
aggrega build --release release.yaml --config governance-rego.yaml --auto-pull在 dist/shop/helm/ 下写入十二个文件:每个组件一个 Deployment 和一个 Service,其监控注解展开成的 ServiceMonitor,以及其 aws-role 注解展开成的 ServiceAccount。api 的 ServiceMonitor 的 spec,来自策略注入的注解:
spec: selector: matchLabels: app.kubernetes.io/name: api endpoints: - port: metrics interval: 30s path: /metricsgateway 的 ServiceMonitor 带有 interval: 10s,即其 Release 条目写入的值。api 运行时所用的 ServiceAccount,来自注入的 aws-role:
apiVersion: v1kind: ServiceAccountmetadata: name: api-aws-role namespace: shop annotations: eks.amazonaws.com/role-arn: "arn:aws:iam::123456789012:role/shop-api" aggrega.ai/boundary-path: shop aggrega.ai/recipe-uri: "aws-irsa:1.0.0" [… omitted: the labels, which carry the version of the aggrega binary that built the file]注入还是手写:相同的文件
release-by-hand.yaml 就是 release.yaml 加上在每个组件上手写的、策略会注入的那些注解。在不挂接任何策略的情况下构建,
aggrega build --release release-by-hand.yaml --auto-pull它写出的十二个文件与在任一引擎上挂接了策略的 release.yaml 逐字节相同。比较中没有排除任何内容:注解是否为注入的,不会记录在任何渲染出的文件中。check.sh 每次运行都会比较这两棵目录树。
构建读取注入的值,与读取 Release 中写入的相同值完全一样,因此该值会展开成同一个挂接。
注入记录在哪里
构建图会记录它,--ir-graph 会打印该图。每个接收了注入注解的组件,其 Release 注解中都带有 aggrega.ai/injected-by,指明插件。执行 aggrega build --release release.yaml --config governance-rego.yaml --auto-pull --ir-graph 之后,api 如下:
"release_annotations": { "aggrega.ai/namespace": "shop", "aws-role": "arn:aws:iam::123456789012:role/shop-api", "aggrega.ai/injected-by": "governance/rego"},记录是按组件而非按键进行的:gateway 也带有它,因为其 aws-role。注解展开成的每个挂接在图中都有 "origin": "annotation",与手写的注解一样。
Helm 目标不渲染 aggrega.ai/injected-by 注解,并会说明这一点。在本次构建中,每个接收了注入的组件都会向输出添加三条警告。api 的第一条如下:
warning: node "api" (provider "helm"): target "helm" does not support annotation aggrega.ai/injected-by on synthesized input and ignored it--no-unsupported-field-warnings 会屏蔽这类警告,且不改变构建写出的任何内容。
该角色只添加注解,别无其他
一个决策指明一个组件、一个注解键及其值。决策中没有任何内容能添加组件、更改标签或直接挂接 Feature。策略只能通过 Manifest 绑定的键触及 Feature,而具体是哪个 Feature 由 Manifest 决定。
决策也不能移除注解。它的值是字符串或子键对象,null 会被拒绝并指明该注入,因为 null 是作者让组件退出其本会继承的注解的方式。
绑定路由三个子键之处却是一个字符串
governance-monitoring-as-string.yaml 挂接 policies/monitoring-as-string.rego,后者在监控键下注入字符串 "30s"。该绑定路由三个子键,而字符串一个也没有指明,因此
aggrega build --release release.yaml --config governance-monitoring-as-string.yaml --auto-pull会中止,以 1 退出,且不写入 dist/。该策略在 api 和 worker 上注入了该字符串,每一处都会被拒绝。每条拒绝信息都会指明注入该值的插件及其挂接的角色,因此该值可追溯到做出决定的策略,而不是追溯到 Release 中一行无人写过的内容:
[… omitted: a warning that the attachment is in the global configuration named with --config][OPS_ERROR E0367] .spec.boundaries.shop.components.api.annotations a scalar annotation value does not route to exactly one path of its binding (Release shop-production, at .spec.boundaries.shop.components.api.annotations, "feature.aggrega.ai/monitoring", carrying the bare value "30s", whose binding routes "interval, port, path", whose value plugin "governance/rego" injected at governance role "annotation-transform")---[OPS_ERROR E0367] .spec.boundaries.shop.components.worker.annotations a scalar annotation value does not route to exactly one path of its binding (Release shop-production, at .spec.boundaries.shop.components.worker.annotations, "feature.aggrega.ai/monitoring", carrying the bare value "30s", whose binding routes "interval, port, path", whose value plugin "governance/rego" injected at governance role "annotation-transform")不挂接策略时
在不挂接任何治理的情况下构建 release.yaml,
aggrega build --release release.yaml --auto-pull会中止。其 Component 要求一个 core/prometheus-exporter 挂接,而没有任何东西为 api 或 worker 提供它:
[DEVELOPER_ERROR E0162] aggregate.yaml at .spec.components.api missing required feature: attach a Feature of the required type to the component ("core/prometheus-exporter", required by component type "example/compute/service", under the requirement label "monitoring")---[DEVELOPER_ERROR E0162] aggregate.yaml at .spec.components.worker missing required feature: attach a Feature of the required type to the component ("core/prometheus-exporter", required by component type "example/compute/service", under the requirement label "monitoring")gateway 没有被点名,因为其 Release 条目写有自己的监控。挂接策略后,同一个 Release 可以构建成功:由注入注解展开成的挂接满足该要求,就像手写的一样。
lockfile 记录了什么
annotation-transform 挂接会改变构建渲染的内容,因此锁文件会固定它。Rego 构建之后,release.lock 在 mutators: 下记录该挂接,包括其插件、角色,以及其策略文件的内容和摘要:
mutators: - plugin: governance/rego role: annotation-transform sources: - content: | [… omitted: the policy file, as written] digest: sha256:9779faf366fc131b1a56ea68ccbae811173e3642943909f8d4ca63c00df8781b path: platform-defaults.rego它还在 plugins: 下固定该插件:
plugins: - uri: governance/rego [… omitted: the artifact digest, which depends on the aggrega binary that built it, recorded twice] referenced_from: - governance/rego:0.9.0挂接指定的是 hub 发布的一个版本,因此固定项通过工作区读取的仓库解析,或从该版本的 aggrega 二进制文件中解析。
生成示例
你可以用下面的命令构建这个示例,也可以让你的 AI 助手替你构建。
将示例写入一个以其命名的新文件夹:
aggrega scaffold --example policy-annotation-transform然后它会打印接下来要运行的命令。第一条命令进入新文件夹:
cd policy-annotation-transform构建
aggrega build --release release.yaml --config governance-rego.yaml --auto-pullaggrega build --release release.yaml --config governance-cel.yaml --auto-pullaggrega build --release release-by-hand.yaml --auto-pull标准库目录提供这里的每个 Component、Feature、Recipe 和 FeatureRecipe,以及两个引擎的 Plugin 实体。 它们从 hub.aggrega.ai 解析,即 .aggrega-config.yaml 指定的默认注册表。若用 --catalog 指定目录的检出(获取方式),则不会从注册表拉取任何内容,因此构建可离线运行。--auto-pull 在构建期间填充每个 Release 的锁文件。锁文件和渲染输出是生成的,不随附发布。
借助 AI 助手
已配置 Aggrega 工具的 AI 助手也能完成同样的操作:把下面这条提示粘贴给它。
只使用 Aggrega 工具,不要自己创建任何文件夹。如果 Workspace 文件夹中还没有 `policy-annotation-transform` 文件夹,就调用一次 `scaffold` 工具,将 `example` 设为 `policy-annotation-transform`,不设 `dir`:它会把示例写入新的 `policy-annotation-transform` 文件夹。然后调用 `cli-build` 工具(它运行 `aggrega build` 并接受其 `--config` 标志),将 `workspace_root` 设为 `policy-annotation-transform`,`release` 设为 `release.yaml`,`auto_pull` 设为 true,`config` 设为 `governance-rego.yaml`;然后以同样方式再调用一次,将 `config` 设为 `governance-cel.yaml`。最后调用 `build` 工具,将 `workspace_root` 设为 `policy-annotation-transform`,`release` 设为 `release-by-hand.yaml`,`auto_pull` 设为 true,`write` 设为 true。告诉我每次构建写入了哪些文件;它们位于 `policy-annotation-transform/dist/` 下。检查每一次构建
此自检在文档仓库的检出中运行,该检出包含它所使用的共享构建辅助脚本;由 aggrega scaffold --example 写出的副本不包含该辅助脚本。
./check.shcheck.sh 通过 build-release 辅助脚本进行五次构建,并将每个结果与本页描述的结果进行核对:
- 不挂接策略的
release-by-hand.yaml是参照。它必须渲染出注解展开成的六个文件。 - 不挂接策略的
release.yaml必须因api和worker以E0162中止,且不涉及其他任何组件。 - 挂接策略的
release.yaml在每个引擎上各构建一次。每次构建都必须逐字节写出与参照相同的文件,在其锁文件中固定插件,并将全部三个组件记录为由该插件注入。 - 带有植入字符串的
release.yaml必须以上述拒绝中止。
它每次构建打印一行,然后打印两个绑定渲染出的文件;如果任何结果不符,则以 1 退出,并打印该次构建的输出:
POLICY RELEASE EXIT EXPECTED VERDICT----------------------------------------------------------------------------------------------------none release-by-hand.yaml 0 reference OK: the six attachments' filesnone release.yaml 1 halt OK: E0162 for api and workerrego release.yaml 0 pass OK: byte-identical to the build by hand; pinned; injectedcel release.yaml 0 pass OK: byte-identical to the build by hand; pinned; injectedstring release.yaml 1 halt OK: refused, naming the plugin and its role
files the two annotation bindings rendered, release.yaml with governance-rego.yaml: shop/helm/api--aws-role--api-serviceaccount-shop-api-aws-role.yaml shop/helm/api--feature-zdaggrega-zdai-zsmonitoring--api-servicemonitor-shop-api-scrape.yaml shop/helm/gateway--aws-role--gateway-serviceaccount-shop-gateway-aws-role.yaml shop/helm/gateway--feature-zdaggrega-zdai-zsmonitoring--gateway-servicemonitor-shop-gateway-scrape.yaml shop/helm/worker--aws-role--worker-serviceaccount-shop-worker-aws-role.yaml shop/helm/worker--feature-zdaggrega-zdai-zsmonitoring--worker-servicemonitor-shop-worker-scrape.yaml
check: every build ended as expected.每次构建都在此工作区的独立副本中运行,副本创建在临时目录中,其 .aggrega-config.yaml 中的目录路径改为绝对路径,以便从那里仍能解析。此目录中不写入任何内容。它使用 build-release 辅助脚本解析出的二进制文件,因此由 AGGREGA_BIN 选择,-- 之后的参数会传给每次构建。它的退出状态就是完整的判定结果。
编译器不做解释的地方
编译器将组件和已绑定的键交给策略。它添加策略决定的注解,并像展开任何注解一样,通过 Manifest 的绑定展开它们。它不知道某个服务应当被监控,不知道抓取间隔是什么,也不知道组件应在哪个 IAM 角色下运行:这些含义属于策略和 Manifest。关于角色、载荷和决策键,请参阅治理插槽。关于不使用策略的注解展开,请参阅 annotation-driven-monitoring。
文件
aggregate.yaml— 三个服务,不带注解。manifest.yaml— 将组件类型和两个 Features 绑定到各自的 Helm Recipes,并将两个注解键绑定到这两个 Features。release.yaml— 策略为其添加注解的 Release;只有gateway写有注解。release-by-hand.yaml— 对照组:每个注解都是手写的。.aggrega-config.yaml— 默认注册表;不含治理挂接。governance-rego.yaml、governance-cel.yaml— 通过各个引擎挂接在annotation-transform的策略,各自通过--config指定。governance-monitoring-as-string.yaml— 植入的错误,通过--config指定。policies/platform-defaults.rego、policies/platform-defaults.cel— 策略,每个引擎一份。policies/monitoring-as-string.rego— 植入的错误。build-release.sh— 构建一个 Release,并输出等效的aggrega build命令。check.sh— 进行五次构建并核对每个结果。