跳转到内容
AggregaAggrega
选择语言: 简体中文
本页面由机器翻译。阅读英文原文。

在 CI 中对构建输出执行策略

两个开箱即用的规则脚本,读取 Aggrega 构建的输出目录, 并在其违反规则时拒绝它。它们在流水线中、aggrega build 之后运行, 与该流水线已对配置运行的其他检查并行。

此目录不是 Aggrega 工作区——它不编写任何 Aggregate、 Release 或目录实体。它是一对供你复制到自己仓库中的脚本, 外加调用每个脚本的流水线步骤。

它们所属的途径,以及何时应改用构建内的治理插槽, 见 治理插槽页面。

两条规则

脚本拒绝
require-pinned-image.sh没有标签或标签为 latest 的容器镜像
deny-inline-credential-material.sh以字面值携带凭据材料的已渲染 Secret

每个脚本以输出目录作为唯一参数,并遍历其中的所有内容。 两者都不了解构建在哪里运行、针对哪个目标, 或工作区如何布局:

Terminal window
./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 rule
1 finding — the output breaks it, and every offending artifact is named
2 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 路径, 增加一种工作负载种类就意味着增加一条路径。

生成示例

将示例写入一个以其命名的新文件夹:

Terminal window
aggrega scaffold --example policy-in-ci

然后它会打印接下来要运行的命令。第一条命令进入新文件夹:

Terminal window
cd policy-in-ci

构建

此文件夹不包含工作区,因此这里没有需要构建的内容。./check.sh 会在它自己写出的小型输出目录上运行这两条规则,这些目录采用构建输出的形态,并检查每个判定结果:

Terminal window
./check.sh

要在真实构建上运行规则,请把该构建的输出目录交给它,正如下一节所做的那样。

生成用于运行它们的构建

此目录树中任何已构建的示例都可以。下面的命令就是 产生后文所记录退出码的命令。

Terminal window
cd ../external-secrets-operator
aggrega build --release release.yaml
Terminal window
cd ../ai-agent-and-model-router
aggrega build --release release.yaml

锁文件是生成的而非随附的,因此全新克隆中没有锁文件, 首次构建需要一个;示例概览说明了两种 解决方式。

流水线步骤

下面的片段是 GitHub Actions;这一形式适用于任何 能运行 shell 命令并读取其退出码的流水线。每个 run: 行都是 产生这些退出码的命令。

# every image a rendered workload runs is pinned
jobs:
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 literal
jobs:
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:

Terminal window
$ ./require-pinned-image.sh ../ai-agent-and-model-router/dist
OK: every image pinned across 4 container(s) in 12 document(s)
$ echo $?
0

针对一个 Release,其 Recipe 引用上游 Helm chart 且未 覆盖该 chart 自身的镜像引用:

Terminal window
$ ./require-pinned-image.sh ../advanced-platform/dist
REFUSED: data/helm/db-statefulset-default-db-mariadb.yaml: StatefulSet/db-mariadb container mariadb runs unpinned image registry-1.docker.io/bitnami/mariadb:latest
REFUSED: data/helm/db-statefulset-default-db-mariadb.yaml: StatefulSet/db-mariadb container preserve-logs-symlinks runs unpinned image registry-1.docker.io/bitnami/mariadb:latest
REFUSED: 2 finding(s) across 3 container(s) in 12 document(s)
$ echo $?
1

无内联凭据材料——针对一个 Release,其唯一的 Secret 由运维人员在运行时填充,而不是渲染时带有值:

Terminal window
$ ./deny-inline-credential-material.sh ../external-secrets-operator/dist
OK: no inline credential material across 43 document(s), 1 of them credential-carrying
$ echo $?
0

针对一个按值填充三个凭据槽的 Release:

Terminal window
$ ./deny-inline-credential-material.sh ../ai-agent-and-model-router/dist
REFUSED: helm/agent--router-zumodel-zdcredential--agent-secret-agent-router-model-credential.yaml (document 1): Secret/agent-router-model.credential carries inline material under api-key
REFUSED: helm/router--api-zukey--router-secret-router-api-key.yaml (document 1): Secret/router-api-key carries inline material under master-key
REFUSED: helm/router--provider-zukey--router-secret-router-provider-key.yaml (document 1): Secret/router-provider-key carries inline material under provider-key
REFUSED: 3 finding(s) across 12 document(s), 3 of them credential-carrying
$ echo $?
1

最后这次拒绝是某个环境自行选择的规则,而不是 Release 中的缺陷。按值填充凭据槽是受支持的形式:作者提供材料,目标将其渲染到工作负载可以读取的位置,编译器对此不持任何意见。与此相关但独立的是,当作者声明为敏感的值以字面值传递到交付键时,编译器确实会发出警告——而这一警告只是建议而非中止,因为按值凭据这一类形式是有意设计的。无论哪种情况,禁止这种形式的都是环境本身:在这里,或在治理插槽上。两种途径及其取舍见治理插槽页面。