在 CI 中对构建输出执行策略
两个开箱即用的规则脚本,读取 Aggrega 构建的输出目录,
并在其违反规则时拒绝它。它们在流水线中、aggrega build 之后运行,
与该流水线已对配置运行的其他检查并行。
此目录不是 Aggrega 工作区——它不编写任何 Aggregate、
Release 或目录实体。它是一对供你复制到自己仓库中的脚本,
外加调用每个脚本的流水线步骤。
它们所属的途径,以及何时应改用构建内的治理插槽, 见 治理插槽页面。
两条规则
| 脚本 | 拒绝 |
|---|---|
require-pinned-image.sh | 没有标签或标签为 latest 的容器镜像 |
deny-inline-credential-material.sh | 以字面值携带凭据材料的已渲染 Secret |
每个脚本以输出目录作为唯一参数,并遍历其中的所有内容。 两者都不了解构建在哪里运行、针对哪个目标, 或工作区如何布局:
./require-pinned-image.sh <output-directory>./deny-inline-credential-material.sh <output-directory>两者只需要 PATH 上有 yq,别无其他。
yq 用读取 YAML 文档的同一表达式读取 JSON 文档,因为
JSON 是 YAML 的子集,所以一个脚本即可覆盖两种输出形态。
除 yq 之外,此目录不需要任何东西:不需要检出目录,不需要 aggrega 二进制文件,也不需要网络。./check.sh 在它自己写出的小型输出目录上运行两条规则,这些目录采用构建产出的形式,并将每个退出码和报告与该目录的预期结果进行比较;任何不匹配都会以 1 退出。要生成一次真实的构建来运行这些规则,需要的就是你所构建的示例所需要的东西。
三个退出码,而非两个
0 no finding — the output satisfies the rule1 finding — the output breaks it, and every offending artifact is named2 cannot evaluate — bad usage, yq absent, or an artifact that does not parse第三个退出码有意与第二个区分开。“无法读取制品” 绝不能与“制品已通过”无法区分,这也正是治理插槽上 无法求值的策略被报告为故障 而非允许的原因。将任何非零退出视为失败的流水线 在两种情况下都能得到正确行为;想区分二者的流水线也可以区分。
未发现任何问题的运行会说明检查了多少内容,因此完全没有匹配到任何内容的规则 是可见的,而不会与匹配到内容并已满足的规则 无法区分:
OK: every image pinned across 3 container(s) in 43 document(s)OK: no inline credential material across 43 document(s), 1 of them credential-carrying调整规则
每个脚本都将 yq 与判定分开,并在二者交汇处用注释
说明:一个 yq 表达式将每个文档读取为
制表符分隔的行,一个 shell 函数对每一行作出判定。要表达
不同的规则,修改这两部分,保持遍历逻辑不变。
这种分离并非装饰。两条看似相似的规则出于 相反的原因需要它:
- 仅凭键是不够的。
ConfigMap与Secret一样携带data:块, 而 ConfigMap 的data:并不是凭据材料。因此 种类也是凭据规则的一部分,而不仅仅是键。 - 递归搜索过度了。
CustomResourceDefinition声明了 自己的 schema,该 schema 可以声明名为image的属性。在 每个文档中搜索image键的规则会把 CRD 的 schema 报告为 未固定的工作负载。因此require-pinned-image.sh显式读取六个 pod-spec 路径, 增加一种工作负载种类就意味着增加一条路径。
生成示例
将示例写入一个以其命名的新文件夹:
aggrega scaffold --example policy-in-ci然后它会打印接下来要运行的命令。第一条命令进入新文件夹:
cd policy-in-ci构建
此文件夹不包含工作区,因此这里没有需要构建的内容。./check.sh 会在它自己写出的小型输出目录上运行这两条规则,这些目录采用构建输出的形态,并检查每个判定结果:
./check.sh要在真实构建上运行规则,请把该构建的输出目录交给它,正如下一节所做的那样。
生成用于运行它们的构建
此目录树中任何已构建的示例都可以。下面的命令就是 产生后文所记录退出码的命令。
cd ../external-secrets-operatoraggrega build --release release.yamlcd ../ai-agent-and-model-routeraggrega build --release release.yaml锁文件是生成的而非随附的,因此全新克隆中没有锁文件, 首次构建需要一个;示例概览说明了两种 解决方式。
流水线步骤
下面的片段是 GitHub Actions;这一形式适用于任何
能运行 shell 命令并读取其退出码的流水线。每个 run: 行都是
产生这些退出码的命令。
# every image a rendered workload runs is pinnedjobs: policy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v5 - name: Compile the Release run: aggrega build --release release.yaml --auto-pull working-directory: ai-agent-and-model-router - name: Images are pinned run: ./require-pinned-image.sh ../ai-agent-and-model-router/dist working-directory: policy-in-ci# no credential material reaches the artifacts as a literaljobs: policy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v5 - name: Compile the Release run: aggrega build --release release.yaml --auto-pull working-directory: external-secrets-operator - name: No inline credential material run: ./deny-inline-credential-material.sh ../external-secrets-operator/dist working-directory: policy-in-ci在你自己的仓库中只有一个工作区,而不是一组示例,因此参数就是构建写入的位置——通常是工作区旁的 dist——脚本则放在你存放流水线工具的位置。只有这两个路径需要改变。
每条规则报告的内容
在此目录中运行,针对三个同级示例的构建。拒绝结果 会列出它所反对的每个制品,因此流水线日志就是问题清单。
镜像已固定——针对其 Recipes 固定了所有镜像的 Release:
$ ./require-pinned-image.sh ../ai-agent-and-model-router/distOK: every image pinned across 4 container(s) in 12 document(s)$ echo $?0针对一个 Release,其 Recipe 引用上游 Helm chart 且未 覆盖该 chart 自身的镜像引用:
$ ./require-pinned-image.sh ../advanced-platform/distREFUSED: data/helm/db-statefulset-default-db-mariadb.yaml: StatefulSet/db-mariadb container mariadb runs unpinned image registry-1.docker.io/bitnami/mariadb:latestREFUSED: data/helm/db-statefulset-default-db-mariadb.yaml: StatefulSet/db-mariadb container preserve-logs-symlinks runs unpinned image registry-1.docker.io/bitnami/mariadb:latestREFUSED: 2 finding(s) across 3 container(s) in 12 document(s)$ echo $?1无内联凭据材料——针对一个 Release,其唯一的 Secret 由运维人员在运行时填充,而不是渲染时带有值:
$ ./deny-inline-credential-material.sh ../external-secrets-operator/distOK: no inline credential material across 43 document(s), 1 of them credential-carrying$ echo $?0针对一个按值填充三个凭据槽的 Release:
$ ./deny-inline-credential-material.sh ../ai-agent-and-model-router/distREFUSED: helm/agent--router-zumodel-zdcredential--agent-secret-agent-router-model-credential.yaml (document 1): Secret/agent-router-model.credential carries inline material under api-keyREFUSED: helm/router--api-zukey--router-secret-router-api-key.yaml (document 1): Secret/router-api-key carries inline material under master-keyREFUSED: helm/router--provider-zukey--router-secret-router-provider-key.yaml (document 1): Secret/router-provider-key carries inline material under provider-keyREFUSED: 3 finding(s) across 12 document(s), 3 of them credential-carrying$ echo $?1最后这次拒绝是某个环境自行选择的规则,而不是 Release 中的缺陷。按值填充凭据槽是受支持的形式:作者提供材料,目标将其渲染到工作负载可以读取的位置,编译器对此不持任何意见。与此相关但独立的是,当作者声明为敏感的值以字面值传递到交付键时,编译器确实会发出警告——而这一警告只是建议而非中止,因为按值凭据这一类形式是有意设计的。无论哪种情况,禁止这种形式的都是环境本身:在这里,或在治理插槽上。两种途径及其取舍见治理插槽页面。