组织范围的策略:团队的规则、组织的规则和流水线的规则
团队的策略、其所属组织的策略以及其流水线的策略在同一次构建中一起运行,每个都挂载在各自的配置文件中。团队在其工作区中挂载自己的规则;组织在每次构建上添加一条规则,流水线再添加一条,二者都无需编辑团队的文件。构建会读取适用于它的所有文件,并运行这些文件所带的每个挂载。
这些规则以全部三种裁决严重级别报告:info 和 warn 让构建完成,halt 则使其停止。其中一条规则,即组织的规则,被挂载了两次,并通过一个 translation 块每次以不同的严重级别报告。
它构建了什么
| 实例 | 目录中的 Component | 它在此处的角色 |
|---|---|---|
db | core/datastore/mariadb | 商店的数据库 |
web | core/devtool/adminer | 一个数据库管理 UI,连接到 db |
两者都编译为 Docker Compose,输出到 dist/compose/docker-compose.yaml。一个 Aggregate、一个 Manifest 和一个 Release,即 release.yaml;它们都没有指明任何策略。
三个文件
| 谁 | 文件 | 构建如何读取它 | 挂载写在哪里 |
|---|---|---|---|
| 团队 | .aggrega-config.yaml | 它将此目录标记为工作区,因此这里的每次构建都会读取它 | plugins.governance |
| 组织 | org/config.yaml | 作为全局配置文件,通过 --config org/config.yaml 为单次构建指定 | plugins.governance_append |
| 流水线 | pipeline/.aggrega-config-append-ci.yaml | 复制到此目录后,作为流水线的覆盖层 | plugins.governance_append |
三个挂载都是 Rego 引擎 governance/rego:0.9.0,处于 ir-verdict 角色,该角色在渲染任何内容之前评判构建图。0.9.0 是其 Plugin 实体在标准库目录中的版本。引擎本身编译在 CLI 中——aggrega plugin list 将 governance/rego 列在嵌入的内置插件之中——因此这里的构建都不会获取插件。
组织的文件是全局配置文件。 一台机器有一个这样的文件,每次构建都会读取:从其默认位置读取,或读取 AGGREGA_CONFIG 环境变量指定的文件。--config <path> 则为单次运行指定一个文件,工作区自身的文件仍会叠加在其之上读取。在组织中,该文件会位于每位开发者的机器和每条流水线的默认位置;这里它位于 org/ 中,应当读取它的构建会指定它。显式指定全局文件说明了这三种方式的尝试顺序。
流水线的文件是覆盖层。 构建会在其读取 .aggrega-config.yaml 的目录中,读取与之并列的 .aggrega-config-append-ci.yaml。它在这里保存在 pipeline/ 中,在此目录中运行的构建不会读取它,因为读取它的每次构建都会中止;流水线的步骤是把它复制进来:
cp pipeline/.aggrega-config-append-ci.yaml .每个文件都会添加,而流水线的覆盖层只会添加
组织和流水线都把各自的挂载写在 plugins.governance_append 下,它是列表 plugins.governance 的追加配套项。配套项下的条目会在读取每个文件自身的列表之后拼接到解析出的列表上,因此团队的 plugins.governance 和组织的条目都会运行,且两个文件都不提及对方。组织写的是配套项,而不是 plugins.governance 本身,因为工作区文件中的 plugins.governance 列表会替换全局文件中的列表:组织写在那里的规则会被团队的列表丢弃,而构建对此不会输出任何信息。扩展列表而不是替换列表列出了每个列表设置的配套项。
流水线的覆盖层只能添加。它为列表设置写入的内容会添加到其他文件解析出的内容上;它不移除任何内容,也不会覆盖只持有单个值的设置,例如 auto_pull。这个覆盖层带有 auto_pull: true,读取它的构建会忽略该键,并在一条警告中说明。用 <workspace> 表示运行构建的目录的绝对路径,该行内容为:
warning: <workspace>/.aggrega-config-append-ci.yaml: ignoring non-additive key "auto_pull" (the CI-owned overlay is additive-only and cannot override the base config)规则,以及每条规则报告时的严重级别
Rego 策略将每个决定收集在一个决定键下,该键选择决定报告时的严重级别。没有 translation 时,键为 deny、warn 和 audit,分别以 halt、warn 和 info 报告:
| 严重级别 | 构建会做什么 |
|---|---|
halt | 停止,以 1 退出,且不写入 dist/ |
warn | 完成,输出消息,并写入 dist/ |
info | 完成,输出消息,并写入 dist/ |
团队的规则 policies/team.rego 收集在 warn 下,其挂载未声明 translation,因此以 warn 报告:
warn contains msg if { some id, node in input.graph.spec.nodes node.labels["component.aggrega.ai/category"] == "datastore" input.graph.spec.infra_mapping[id].ha.enabled == false msg := sprintf("%v runs with high availability off", [id])}组织的规则 org/policies/estate.rego 拒绝其设置所列类别中的组件,并记录每个组件运行的内容:
deny contains msg if { some id, node in input.graph.spec.nodes category := node.labels["component.aggrega.ai/category"] category in data.refused_categories msg := sprintf("%v runs %v, in the %v category, which the organization does not ship", [id, node.component, category])}
audit contains msg if { some id, node in input.graph.spec.nodes msg := sprintf("%v runs %v %v, upstream licensing %v", [id, node.component, node.resolved_version, node.labels["component.aggrega.ai/upstream-licensing"]])}refused_categories 是每个挂载的一项设置,策略将其挂载的设置作为其 data 文档读取。
转换:一条规则,两种严重级别
挂载设置中的 translation 块声明读取哪些决定键,以及每个键报告时的严重级别。它替换默认映射而不是扩展它:未指明的键不会被读取。
组织的文件以建议的形式推出其规则。其挂载将 deny 以 warn 报告,将 audit 以 info 报告:
settings: refused_categories: [devtool] translation: - key: deny severity: warn - key: audit severity: info流水线挂载同一个文件,并使同一条规则中止构建。它的转换只指明 deny,因此其挂载不会再次报告 audit 记录:
settings: refused_categories: [devtool] translation: - key: deny severity: halt因此,对于同一个 web,同一条规则在开发者的构建上是一条警告,而在流水线的构建上则是构建停止的原因。
生成示例
你可以用下面的命令构建这个示例,也可以让你的 AI 助手替你构建。
将示例写入一个以其命名的新文件夹:
aggrega scaffold --example policy-org-overlay然后它会打印接下来要运行的命令。第一条命令进入新文件夹:
cd policy-org-overlay构建
标准库目录提供 Components、Recipes、Feature 及其 FeatureRecipe。 它们从 hub.aggrega.ai 解析,即 .aggrega-config.yaml 指定的默认注册表。若用 --catalog 指定目录的检出(获取方式),则不会从任何注册表获取任何内容,因此构建可离线运行。--auto-pull 在构建过程中填充锁文件;锁文件和渲染输出是生成的,不随附提供。
仅使用团队的文件:
aggrega build --release release.yaml --auto-pull构建输出团队的警告并完成。同时使用组织的文件:
aggrega build --release release.yaml --auto-pull --config org/config.yaml它以 info 输出组织的记录,以 warn 输出其规则,与团队的警告并列,并且仍然完成:
info: policy plugin "rego": db runs core/datastore/mariadb 1.0.0, upstream licensing osi-approved info: policy plugin "rego": web runs core/devtool/adminer 1.0.0, upstream licensing osi-approved policy plugin "rego" warning: db runs with high availability off policy plugin "rego" warning: web runs core/devtool/adminer, in the devtool category, which the organization does not shipPull complete: release.lock (entities=11, source_artifacts=0, external_inputs=0) notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)[… omitted: the build's time and the line naming the dist/ directory it wrote]每个裁决都指明报告它的插件 rego,而不是挂载它的文件,因此团队的警告和组织的警告看起来一样;像组织的消息那样说明这是谁的规则,就是区分它们的方法。
复制进流水线的覆盖层后,同一命令会中止:
cp pipeline/.aggrega-config-append-ci.yaml .aggrega build --release release.yaml --auto-pull --config org/config.yaml[… omitted: the overlay's warning shown above][… omitted: the lines printed while the lockfile is resolved, which carry the verdicts below once more, the refusal among them] info: policy plugin "rego": db runs core/datastore/mariadb 1.0.0, upstream licensing osi-approved info: policy plugin "rego": web runs core/devtool/adminer 1.0.0, upstream licensing osi-approved policy plugin "rego" warning: db runs with high availability off policy plugin "rego" warning: web runs core/devtool/adminer, in the devtool category, which the organization does not ship notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)[POLICY_ERROR E0005] policy plugin "rego" rejected the build: web runs core/devtool/adminer, in the devtool category, which the organization does not ship caused by: policy violation构建以 1 退出且不写入 dist/。组织的规则被报告两次,每个挂载各一次:组织的挂载以 warn 报告,流水线的挂载以 halt 报告。audit 记录只出现一次,仅来自组织的挂载。从此目录删除 .aggrega-config-append-ci.yaml 即可再次在没有它的情况下构建。
借助 AI 助手
已配置 Aggrega 工具的 AI 助手也能完成同样的操作:把下面这条提示粘贴给它。
只使用 Aggrega 工具,不要自己创建任何文件夹。如果 Workspace 文件夹中还没有 `policy-org-overlay` 文件夹,就调用一次 `scaffold` 工具,将 `example` 设为 `policy-org-overlay`,不设 `dir`:它会把示例写入新的 `policy-org-overlay` 文件夹。然后调用 `build` 工具,将 `workspace_root` 设为 `policy-org-overlay`,`release` 设为 `release.yaml`,`auto_pull` 设为 true,`write` 设为 true,并告诉我策略报告了什么。接着调用 `cli-build` 工具(它运行 `aggrega build` 并接受其 `--config` 标志),将 `workspace_root` 设为 `policy-org-overlay`,`release` 设为 `release.yaml`,`auto_pull` 设为 true,`config` 设为 `org/config.yaml`,并告诉我这次策略报告了什么。告诉我每次构建写入了哪些文件;它们位于 `policy-org-overlay/dist/` 下。检查每一次构建
此自检在文档仓库的检出中运行,该检出包含它所使用的共享构建辅助脚本;由 aggrega scaffold --example 写出的副本不包含该辅助脚本。
./check.shcheck.sh 通过 build-release 辅助脚本构建 release.yaml 五次,每次都在此工作区的一个副本中:仅使用团队的文件;使用由 --config 指定的组织文件;复制进流水线的覆盖层;两者都用;以及使用组织文件的一个副本,该副本把其挂载写在 plugins.governance 下而不是配套项下——此时团队的列表会替换它,只输出团队的裁决。对每次构建,它检查退出状态、是否写入了 dist/,以及构建输出的每个裁决——其严重级别和消息,不缺也不多——并在读取覆盖层时检查指明 auto_pull 的警告。它为每次构建输出一行,然后输出每次构建输出的裁决,如果任何结果不同则以 1 退出,并输出该次构建的输出:
LAYERS EXIT DIST VERDICT----------------------------------------------------------------------------------------------------team 0 yes OKteam + organization 0 yes OKteam + pipeline 1 no OKall three 1 no OKteam + organization, plugins.governance 0 yes OK
team: warn db runs with high availability off
team + organization: info db runs core/datastore/mariadb 1.0.0, upstream licensing osi-approved info web runs core/devtool/adminer 1.0.0, upstream licensing osi-approved warn db runs with high availability off warn web runs core/devtool/adminer, in the devtool category, which the organization does not ship
team + pipeline: ignored auto_pull warn db runs with high availability off halt web runs core/devtool/adminer, in the devtool category, which the organization does not ship
all three: ignored auto_pull info db runs core/datastore/mariadb 1.0.0, upstream licensing osi-approved info web runs core/devtool/adminer 1.0.0, upstream licensing osi-approved warn db runs with high availability off warn web runs core/devtool/adminer, in the devtool category, which the organization does not ship halt web runs core/devtool/adminer, in the devtool category, which the organization does not ship
team + organization, plugins.governance: warn db runs with high availability off
check: every build ended as expected.副本创建在临时目录中,其 .aggrega-config.yaml 中的目录路径被改为绝对路径,以便从那里仍能解析;此目录中的任何文件都不会被编辑或写入。它使用 ./build-release.sh 解析出的二进制文件,因此由 AGGREGA_BIN 选择,-- 之后的参数会传给每次构建。它的退出状态就是完整的判定结果。
编译器不做解释的地方
编译器读取这三个文件,拼接它们所带的挂载,将构建图及其设置交给每个策略,并根据每个决定报告时的严重级别采取行动。它不知道什么是 devtool,组织为什么不会交付它,也不知道高可用性对团队很重要:这些含义是策略的规则和设置。关于角色、负载和决定键,请参阅治理插槽。
文件
aggregate.yaml— 数据库以及连接到它的管理 UI。manifest.yaml— 将每个组件类型和机密 Feature 绑定到其 Docker Compose Recipe。release.yaml— 唯一的 Release。.aggrega-config.yaml— 团队的文件:默认注册表和团队的挂载。policies/team.rego— 团队的规则。org/config.yaml— 组织的全局配置文件及其挂载。org/policies/estate.rego— 组织的规则。pipeline/.aggrega-config-append-ci.yaml— 流水线的覆盖层,复制到此目录后才会被读取。build-release.sh— 构建该 Release,并回显等效的aggrega build命令。check.sh— 进行五次构建并核对每个结果。