塑造标签的策略:按环境划分的支持级别,以及读取它的裁决
治理插件为此工作区部署的每个组件打上标签:其所有者、其环境应得的支持级别、其备份计划以及一个简短标记,这样任何开发人员都无需手动输入它们。这些标签在构建期间由四个治理挂接推导得出:
- 三个位于
label-transform角色,负责塑造构建节点上的标签:一个读取 Release 环境的 Rego 策略,以及编译进 CLI 的两个标记插件label-injector和selector-tagger; - 一个位于
ir-verdict角色,是针对构建图的 Rego 策略,当生产构建中有节点缺少支持级别时中止该构建。
同一个 Aggregate 的两个 Releases 在环境上不同,分别为 staging 和 production,它们的节点最终带有不同的标签。第三次构建由 check.sh 基于此工作区的一个副本进行,该副本的策略少覆盖一个类别,构建会中止并指出它遗漏的节点。
它构建了什么
| 实例 | 目录中的 Component | 它在此处的角色 |
|---|---|---|
db | core/datastore/mariadb | 商店的数据库 |
cache | core/datastore/redis | 其会话缓存 |
web | core/devtool/adminer | 一个数据库管理 UI,连接到 db |
三者都编译为 Docker Compose,输出到 dist/compose/docker-compose.yaml。Aggregate 和两个 Releases 都没有指定自己的标签:下面的每个标签都由挂接写入。
四个挂接
它们挂接在此工作区 .aggrega-config.yaml 的 plugins.governance 下,因此在这里运行的每次构建都会应用它们:
| 插件 | 角色 | 写入的内容 | |
|---|---|---|---|
| 1 | governance/rego:0.9.0,配合 policies/support-tier.rego | label-transform | 在每个节点上写入 ops.example.com/environment;在其类别列于设置中的每个节点上写入 ops.example.com/support-tier |
| 2 | governance/label-injector:0.9.0 | label-transform | 在每个节点上写入 ops.example.com/owner;在 datastore 类别的每个节点上写入 backup.example.com/schedule |
| 3 | governance/selector-tagger:0.9.0 | label-transform | tag,取自 policies/tags.yaml 中的映射 |
| 4 | governance/rego:0.9.0,配合 policies/production-support.rego | ir-verdict | 不写入任何内容:它中止构建,或让构建完成 |
0.9.0 是标准库目录中三个 Plugin 实体的版本;插件本身编译在 CLI 中,构建从那里提供它们。aggrega build --release release-production.yaml --auto-pull --detail 会针对这三者逐一列出这两项:
[… omitted: the line counting what the pull resolved, and the rows for the Components, the Recipes, the Feature and the FeatureRecipes, each read from the registry] in-binary Plugin governance/label-injector ← governance/label-injector:0.9.0 in-binary Plugin governance/label-injector:0.9.0 ← .aggrega-config.yaml.plugins.governance in-binary Plugin governance/rego ← governance/rego:0.9.0 in-binary Plugin governance/rego:0.9.0 ← .aggrega-config.yaml.plugins.governance in-binary Plugin governance/selector-tagger ← governance/selector-tagger:0.9.0 in-binary Plugin governance/selector-tagger:0.9.0 ← .aggrega-config.yaml.plugins.governance[… omitted: the rows for this workspace's Aggregate and Manifest, the pull's summary, a lint notice about core/secret-value, and the build's summary]同一角色上的挂接按列出的顺序运行,每个挂接都会读取前面挂接写入的标签:标签注入器接收 Rego 策略写入的两个标签,选择器标记器接收这些标签以及标签注入器写入的标签。裁决在这三者之后运行,作用于它们留下的图。
label-transform 策略读取的内容
位于 label-transform 的策略读取 input.graph.nodes 处的节点,以节点 id 为键,每个节点包含:
component— 节点实例化的 Component,例如core/datastore/mariadb;resolved_version— 该 Component 解析到的版本;labels— 策略运行时节点带有的标签:Component 自身的标签,以及之前任何转换写入的标签;values— 节点的实例在 Aggregate 中声明的值,未声明时则不存在。这里只有db声明了一个值,即database: appdb。
它在 input.compilation_context 处读取 Release:release_name 和 environment。正是这一点让同一个策略可以针对不同环境做出不同决定。
而位于 ir-verdict 的策略读取整个构建图,其节点位于更深一层,即 input.graph.spec.nodes。从一个角色移到另一个角色的规则需要修改,而不是照搬:路径错误时它什么也读不到,永远不会触发。ir-verdict 载荷不含 compilation_context,因此裁决无法从 Release 读取环境。这就是为什么这里的第一个策略还会在每个节点上写入 ops.example.com/environment:裁决从该标签读取环境。
要查看载荷而不是阅读相关描述,先构建一次以生成锁文件,然后:
aggrega build --release release-production.yaml --dry-run --policy-input payloads将每个挂接接收到的载荷写入 payloads/:在同一角色上有多个挂接接收不同载荷时,每个挂接一个文件——label-transform.1.rego.json、label-transform.2.label-injector.json、label-transform.3.selector-tagger.json——此外每个其他角色各一个文件,除此之外不写入任何内容。
Rego 策略
policies/support-tier.rego 在 labels 下收集其决策,每个标签一个,指明节点、标签键和值:
env := input.compilation_context.environment
labels contains {"node": id, "key": "ops.example.com/environment", "value": env} if { some id, _ in input.graph.nodes}
labels contains {"node": id, "key": "ops.example.com/support-tier", "value": data.support_tiers[env]} if { some id, node in input.graph.nodes node.labels["component.aggrega.ai/category"] in data.supported_categories}它的设置就是该策略的 data 文档,其中保存着该组织自己的词汇:
settings: # The categories whose components get a support tier. supported_categories: [datastore, devtool] # The tier each environment gives them. support_tiers: production: on-call staging: office-hours每个内置插件写入的内容
label-injector 应用一组规则。如果一个节点的标签包含某条规则 match 下的每一对,它就会获得该规则 set 下的每一对:新增标签,或替换节点已有标签的值。没有任何键值对的 match 匹配所有节点。它从其 rules 设置读取规则(如此处),或者在设置中没有规则时,从 sources 下第一个带有规则的文件读取。这里它的两条规则为每个节点赋予 ops.example.com/owner: shop-team,并为 datastore 类别中的两个节点 db 和 cache 赋予 backup.example.com/schedule: nightly。web 属于 devtool 类别,不会获得备份计划。
selector-tagger 写入一个标签,键始终为 tag。其值来自一个从 Component 名称到标记的映射,从 sources 下的文件读取。如果节点的 Component 不在映射中,则取 default 设置;没有 default 时,该节点不带 tag。policies/tags.yaml 映射了数据库和缓存:
core/datastore/mariadb: orderscore/datastore/redis: sessions而挂接的 default 为 untagged,因此 web 被标记为 untagged。
两者都只根据节点的标签及其 Component 做决定。两者都不读取环境,因此它们在两个 Releases 中写入相同的标签。
两者都只服务于 label-transform。挂接在 ir-verdict 时,任何一个都会在运行前被拒绝;挂接在那里的 selector-tagger 会以如下信息中止构建:
[E0085] ir-verdict: plugin "governance/selector-tagger:0.9.0": call "verdict_ir": wasm: plugin "selector-tagger" does not declare export "verdict_ir" in describe(): wasm: plugin rejected by the sandbox生成示例
你可以用下面的命令构建这个示例,也可以让你的 AI 助手替你构建。
将示例写入一个以其命名的新文件夹:
aggrega scaffold --example policy-label-transform然后它会打印接下来要运行的命令。第一条命令进入新文件夹:
cd policy-label-transform构建
aggrega build --release release-staging.yaml --auto-pullaggrega build --release release-production.yaml --auto-pull标准库目录提供这里的每个 Component、Recipe 和 Feature,以及三个 Plugin 实体。 它们从 hub.aggrega.ai 解析,即 .aggrega-config.yaml 指定的默认注册表。若用 --catalog 指定目录的检出(获取方式),则不会从注册表拉取任何内容,因此构建可离线运行。--auto-pull 在构建期间填充每个 Release 的锁文件;锁文件和渲染输出是生成的,不随附发布。
借助 AI 助手
已配置 Aggrega 工具的 AI 助手也能完成同样的操作:把下面这条提示粘贴给它。
只使用 Aggrega 工具,不要自己创建任何文件夹。如果 Workspace 文件夹中还没有 `policy-label-transform` 文件夹,就调用一次 `scaffold` 工具,将 `example` 设为 `policy-label-transform`,不设 `dir`:它会把示例写入新的 `policy-label-transform` 文件夹。然后按以下顺序为每个 Release 各调用一次 `build` 工具——`release-staging.yaml` 和 `release-production.yaml`——每次都将 `workspace_root` 设为 `policy-label-transform`,`release` 设为该文件,`auto_pull` 设为 true,`write` 设为 true。告诉我每次构建写入了哪些文件;它们位于 `policy-label-transform/dist/` 下。每个节点最终带有的标签
--ir-graph 在标准输出上打印构建图,位于构建摘要之前,图中带有转换处理后每个节点的标签。执行 aggrega build --release release-production.yaml --auto-pull --ir-graph 之后,web 如下:
"web": { "labels": { "component.aggrega.ai/type": "server", "component.aggrega.ai/category": "devtool", "component.aggrega.ai/upstream-licensing": "osi-approved", "ops.example.com/environment": "production", "ops.example.com/support-tier": "on-call", "ops.example.com/owner": "shop-team", "tag": "untagged" }, [… omitted: the node's Component, its version, where it is placed, its catalog metadata, the file it was declared in, and its connection to db]}前三个标签是 Component 自身的;后四个由三个转换写入。check.sh 读取每次构建的图,并列出挂接写入的标签:
labels the attachments wrote, release-staging.yaml: db ops.example.com/environment: staging ops.example.com/support-tier: office-hours ops.example.com/owner: shop-team backup.example.com/schedule: nightly tag: orders cache ops.example.com/environment: staging ops.example.com/support-tier: office-hours ops.example.com/owner: shop-team backup.example.com/schedule: nightly tag: sessions web ops.example.com/environment: staging ops.example.com/support-tier: office-hours ops.example.com/owner: shop-team tag: untagged
labels the attachments wrote, release-production.yaml: db ops.example.com/environment: production ops.example.com/support-tier: on-call ops.example.com/owner: shop-team backup.example.com/schedule: nightly tag: orders cache ops.example.com/environment: production ops.example.com/support-tier: on-call ops.example.com/owner: shop-team backup.example.com/schedule: nightly tag: sessions web ops.example.com/environment: production ops.example.com/support-tier: on-call ops.example.com/owner: shop-team tag: untagged在两个 Releases 之间,只有 Rego 策略的两个标签会变化。
一旦构建填充了锁文件,aggrega inspect release-production.yaml --ir-graph 就会在不构建的情况下打印同一个图,位于其 Release 可读视图之前,因为转换从锁文件中读取它们的文件。没有锁文件时,它打印的图不带由这些文件决定的任何标签:没有 ops.example.com/environment 或 ops.example.com/support-tier,并且每个节点上都是 tag: untagged。
转换只更改标签,别无其他
label-transform 上的一个决策指明一个节点、一个标签键及其值,或者要求删除一个标签。没有任何决策能添加节点、更改节点的 Component 或版本,或改动其值,因此转换无法表达其中任何一种操作。指明构建中不存在的节点的决策不会被忽略:构建会以 E0069 中止,并指出该节点以及它无法设置的标签。
release-production.yaml 的两次构建(带这些挂接和不带挂接)说明了这一点。它们的构建图只在上面列出的标签上不同,别无其他差异。它们的渲染输出则完全没有差异:这里的 Compose Recipes 不渲染这些标签中的任何一个,因此无论有无挂接,dist/compose/docker-compose.yaml 都是逐字节相同的同一个文件,check.sh 每次运行都会比较这两棵目录树。标签存在于构建图中,裁决在那里读取它们。
裁决,以及它中止的构建
policies/production-support.rego 挂接在 ir-verdict,位于转换之后,并读取它们写入的标签:
deny contains msg if { some id, node in input.graph.spec.nodes node.labels["ops.example.com/environment"] == "production" not node.labels["ops.example.com/support-tier"] msg := sprintf("%v is built for production and carries no ops.example.com/support-tier label", [id])}两个 Releases 都能构建:在 staging 中裁决不作任何要求,在 production 中每个节点都带有一个级别。缩小策略的覆盖范围,裁决就会捕获它遗漏的节点。在 .aggrega-config.yaml 中把 supported_categories 写为 [datastore],web 就不会获得支持级别,aggrega build --release release-production.yaml --auto-pull 会中止:
[… omitted: the pull's lines, which carry the refusal below once more, and a lint notice about core/secret-value][POLICY_ERROR E0005] policy plugin "rego" rejected the build: web is built for production and carries no ops.example.com/support-tier label caused by: policy violation构建以 1 退出,且不写入 dist/。使用缩小后的策略,release-staging.yaml 仍然可以构建:其节点标记为 staging,裁决对它们不作任何要求。check.sh 在工作区的副本中进行这次构建,因此无需编辑这里的任何内容即可看到它。
裁决只接受或拒绝,别无其他作用:它无法添加缺失的标签来让构建通过。生产节点必须带有哪个标签是该组织的规则,写在其策略中;编译器将标签作为字符串带入图中,不对其赋予任何含义。
lockfile 记录了什么
锁文件对两类挂接的记录方式不同。生产构建之后,release-production.lock 在 mutators: 下记录每个转换挂接——其插件、角色、设置,以及其每个文件的内容和摘要——并在 plugins: 下固定每个转换插件:
plugins: - uri: governance/label-injector [… omitted: the artifact digest, which depends on the aggrega binary that built it, recorded twice] referenced_from: - governance/label-injector:0.9.0 - uri: governance/rego [… omitted: the artifact digest, recorded twice] referenced_from: - governance/rego:0.9.0 - uri: governance/selector-tagger [… omitted: the artifact digest, recorded twice] referenced_from: - governance/selector-tagger:0.9.0裁决挂接只出现在 verdict_inputs: 下,以其文件的 sha256 表示:
verdict_inputs: - plugin: governance/rego:0.9.0 role: ir-verdict sources: - digest: sha256:5e01fc76f791ef00eba02f02ffb383437c87531f3927ee4a91cec9bf9c6e8cd8 path: production-support.rego裁决挂接不会被固定。只挂接裁决时(从 .aggrega-config.yaml 中移除三个转换),锁文件带有 mutators: [] 和 plugins: [],裁决的文件位于 verdict_inputs: 下。转换会改变流水线其余部分所依据的构建,因此锁文件保存做出该改变的插件;裁决只决定构建是否完成。
检查每一次构建
此自检在文档仓库的检出中运行,该检出包含它所使用的共享构建辅助脚本;由 aggrega scaffold --example 写出的副本不包含该辅助脚本。
./check.shcheck.sh 通过 build-release 辅助脚本进行四次构建,并将每个结果与本页描述的结果进行核对:
- 在此工作区不带任何治理挂接的副本中构建
release-production.yaml,作为参照; - 这里的
release-staging.yaml和release-production.yaml,每个都必须完成,并在每个节点上带有上面列出的标签,生产目录树须与参照逐字节相同; - 在策略只覆盖
datastore类别的副本中构建release-production.yaml,必须以E0005和上面的那句话中止,且旁边没有其他任何拒绝。
它每次构建打印一行,然后打印标签;如果任何结果不符,则以 1 退出,并打印该次构建的输出:
RELEASE GOVERNANCE EXIT EXPECTED VERDICT----------------------------------------------------------------------------------------------------release-production.yaml none 0 reference OKrelease-staging.yaml as attached 0 pass OK: the expected labelsrelease-production.yaml as attached 0 pass OK: the expected labels; byte-identical to the build with nonerelease-production.yaml narrowed 1 halt OK: E0005, the expected sentence[… omitted: the two label listings shown above]check: every build ended as expected.两个副本创建在临时目录中,其 .aggrega-config.yaml 中的目录路径改为绝对路径,以便从那里仍能解析。此目录中的文件不会被编辑;在这里进行的两次构建会像任何构建一样填充其锁文件。它使用 ./build-release.sh 解析出的二进制文件,因此由 AGGREGA_BIN 选择,-- 之后的参数会传给每次构建。只要此目录中存在 dist/,它就拒绝启动,因为它要比较各次构建写出的目录树,而且它不会留下任何目录树。它的退出状态就是完整的判定结果。
编译器不做解释的地方
编译器将节点和 Release 的环境交给每个转换,应用它决定的标签,并将结果交给裁决。它不知道支持级别是什么,不知道 on-call 高于 office-hours,也不知道 devtool 需要一个级别:这些含义属于策略的设置和规则。关于角色、载荷以及策略如何指明标签,请参阅治理插槽;关于策略在产品中的位置,请参阅治理与合规。
文件
aggregate.yaml— 数据库、缓存以及连接到数据库的管理 UI;没有标签。manifest.yaml— 将每个组件类型和机密 Feature 绑定到其 Docker Compose Recipe。由两个 Releases 共享。release-staging.yaml、release-production.yaml— 两个环境。.aggrega-config.yaml— 默认注册表和四个治理挂载。policies/support-tier.rego— 标签转换策略。policies/production-support.rego— 裁决策略。policies/tags.yaml— 选择器标记器的组件到标签映射。build-release.sh— 构建一个 Release,并输出等效的aggrega build命令。check.sh— 执行四次构建并检查每个结果。