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

针对渲染输出的策略:一条内部规则,四个目标,两个引擎

一条内部规则挂载在 render-verdict 角色上,评判构建为四个目标写出的文件,并拒绝在每个目标上植入的违规。该规则有两个子句:

每个容器镜像都指明一个固定版本——latest 以外的标签,或一个摘要。每个数据库实例都以加密方式存储其数据。

此工作区为四个目标构建一个 Aggregate——通过 Helm 的 Kubernetes、Docker Compose、Terraform 和 CloudFormation。render-verdict 角色在每个目标都渲染完文件之后评判构建写出的文件,规则读取每个目标自身的输出形态:Kubernetes 对象和 Compose 文件中的镜像,Terraform 文件和 CloudFormation 模板中的 RDS 实例。每个目标都有一个通过的 Release,以及一个植入了违规、被规则拒绝的 Release。

该规则写了两遍,编译在 CLI 中的每个策略引擎各一遍——Rego 和 CEL——两个副本在这里的每次构建上结论一致。Releases 旁边的一个脚本构建全部十六种组合并检查每个结果。

aggrega build

你的策略

接入编译器

通过

文件已写入

可供审阅和部署

未通过

构建已停止

policy plugin "rego" rejected the build: terraform/modules/db/main.tf: the RDS instance db stores its data unencrypted

策略可以停止构建并说明需要修复什么。它从不为了让文件通过而修改你的文件。

它构建了什么

实例目录中的 Component它在此处的角色
dbcore/datastore/postgres订单数据库
reportcore/compute/task一个读取 db 的报表作业,手动启动:它带有 core/manual-trigger,因此 Release 部署时不会启动任何运行

report 通过其 database 连接读取数据库的地址、端口和名称,即 DB_HOST、DB_PORT 和 DB_NAME。每次构建的 Aggregate 都是同一个文件;每个 Release 指明选择目标的 Manifest:

Manifestdbreport
manifest-helm.yamlhelm/postgres,一个 StatefulSethelm/task,一个保持挂起的 CronJob
manifest-compose.yamlcompose/postgres,一个服务compose/task,一个位于 profile 之后的服务
manifest-terraform.yamlterraform/postgres-rds,一个 RDS 实例terraform/task-ecs,一个 Amazon ECS 任务定义
manifest-cloudformation.yamlcloudformation/postgres-rds,一个 RDS 实例cloudformation/task-ecs,一个 Amazon ECS 任务定义

这里的每个 Recipe 都只依靠目录进行渲染:Kubernetes 数据库是合成的,而不是作为 chart 获取的;Terraform 数据库的主体由其 Recipe 写出;Terraform 任务的模块保存在其 Recipe 旁边。因此每次构建都离线运行。

八个 Releases

Release目标规则发现了什么构建结果
release-helm.yamlKubernetesreport 运行 registry.example.com/orders-report:1.4.2完成
release-helm-unpinned.yamlKubernetesreport 以标签 latest 运行同一镜像中止
release-compose.yamlDocker Composereport 运行 registry.example.com/orders-report:1.4.2完成
release-compose-unpinned.yamlDocker Composereport 运行不带标签的镜像中止
release-terraform.yamlTerraform实例使用 Release 指明的密钥加密完成
release-terraform-unencrypted.yamlTerraformRelease 没有指明密钥,因此实例未加密中止
release-cloudformation.yamlCloudFormationRelease 开启了 StorageEncrypted完成
release-cloudformation-unencrypted.yamlCloudFormationRelease 让它保持关闭中止

镜像由 Release 决定:core/compute/task 不打包任何软件,因此 Release 在 infra.image 下指明一次运行所执行的镜像,包括标签。在两个 AWS 目标上,数据库的加密也由 Release 决定。Terraform Recipe 读取 infra.overrides.kms_key_id,并在其已设置时于密钥旁渲染 storage_encrypted = true;CloudFormation Recipe 以资源属性自身的名称读取 infra.overrides.StorageEncrypted 和 KmsKeyId。两者都未设置的 Release 渲染出的实例完全没有加密属性,植入违规的 Releases 正是这样做的。

Kubernetes 和 Compose 数据库运行镜像 postgres:16,这是一个固定标签,因此规则在每个 Release 中评判它们并让它们通过。

挂载规则

.aggrega-config.yaml 将 hub 指定为其注册中心,不声明任何目录所在的路径,也不声明任何治理挂载。规则由构建通过 --config 指定的文件挂载:Rego 引擎用 governance-rego.yaml,CEL 引擎用 governance-cel.yaml。Rego 的那个文件内容如下:

plugins:
governance:
- uri: governance/rego:0.9.0
role: render-verdict
with:
sources:
- policies/house-rule.rego

--config 为该次运行指定全局配置文件,取代机器原本会读取的那个文件,此工作区的 .aggrega-config.yaml 仍叠加在其之上。工作区文件中的 plugins.governance 列表会替换指定文件所带的列表,这就是工作区文件不声明该列表的原因。0.9.0 是每个引擎的 Plugin 实体在标准库目录中的版本。两个引擎都编译在 CLI 中——aggrega plugin list 将 governance/rego 和 governance/cel 列在嵌入的内置插件之中——因此这里的构建都不会获取插件。

render-verdict 策略读取什么

位于 render-verdict 的策略在 input.artifacts 处读取构建写出的文件,每个文件一个条目,按路径排序。每个条目带有:

  • path — 文件在 dist/ 下的路径,例如 terraform/modules/db/main.tf;
  • content — 文件的文本,与写出时一致;
  • format — 目标的提供方为该文件声明的格式:Compose 文件为 yaml,CloudFormation 模板为 json,每个 Terraform 文件为 hcl,包括其 Recipe 写出的数据库主体。没有任何声明的地方,它是空字符串,这里的 Kubernetes 文件就是如此;
  • documents — 解析为结构的文件内容,以文档列表的形式:这里每个文件一个文档;
  • parse_error — 仅出现在无法解析的文件上,取代 documents。

除文件之外,input.sources 存放挂载自身的策略文件,input.settings 存放其设置——这里是空对象,因为此挂载未声明任何设置。

aggrega build --release <release> --dry-run --policy-input <dir> 将每个角色接收的负载写入 <dir>,不写其他任何内容。在 render-verdict,该文件是引擎接收的内容,而不是策略读取的内容:其中每个文件带有其 path、content 以及其提供方声明的 format,引擎在接收负载后才从内容中解析出 documents。因此该文件列出规则将看到的文件,但不包括它们的文档。在一次 release-terraform.yaml 构建填充了其锁文件之后:

Terminal window
aggrega build --release release-terraform.yaml --config governance-rego.yaml --dry-run --policy-input payloads
jq -c '[.artifacts[].path]' payloads/render-verdict.json
# ["terraform/aggrega.modules.tf","terraform/modules/db/main.tf","terraform/modules/report/aggrega.provenance.tf","terraform/modules/report/main.tf","terraform/modules/report/variables.tf"]

规则在 documents 中读取的路径要在构建中检查,因为那时引擎已解析了它们。这些 Recipes 写出的文件没有一个解析失败,因此这里没有文件带有 parse_error。此规则的每个子句都读取 documents,因此未能解析的文件会未经检查就通过;不允许这种情况发生的规则会添加一个子句,拒绝带有 parse_error 的文件。

每个子句如何读取其目标的形态

每个子句指明它读取的形态,而其他形态的文件不带有子句所指明的内容:在 Rego 中路径未定义,子句不成立。因此一条规则可在每个目标的输出上运行,而每个子句只找到它自己的那部分。

Compose 写出一个文件,其文档在 services 下按名称为每个服务设键:

deny contains msg if {
some artifact in input.artifacts
some doc in artifact.documents
some name, service in doc.services
unpinned(service.image)
msg := sprintf("%v: service %v runs %v, an image with no tag or the tag latest", [artifact.path, name, service.image])
}

Kubernetes 对象将其容器放在 pod 模板中,CronJob 把模板放在比其他工作负载深一层的位置,即 spec.jobTemplate.spec 下:

pod_template(doc) := doc.spec.jobTemplate.spec.template if doc.kind == "CronJob"
pod_template(doc) := doc.spec.template if doc.kind != "CronJob"

原生 HCL 中的 Terraform 将一个块嵌套在其类型之下,然后嵌套在其每个标签之下,最后一个标签持有一个块列表,因为共享类型和标签的块会汇集到一个列表中。因此实例的属性位于其名称下一个索引处,子句会遍历该列表:

deny contains msg if {
some artifact in input.artifacts
native_hcl(artifact)
some doc in artifact.documents
some name, blocks in doc.resource.aws_db_instance
some block in blocks
not block.storage_encrypted == true
msg := sprintf("%v: the RDS instance %v stores its data unencrypted", [artifact.path, name])
}

这里列表比对于查找某个值的规则更重要,因为此子句以缺失为由拒绝。若按单个块来写——some name, block in doc.resource.aws_db_instance——block 就是列表,block.storage_encrypted 在其上未定义,而 not 对任何未定义的内容都成立:该子句也会拒绝 release-terraform.yaml,尽管其实例已加密,消息与植入违规的 Release 相同。

.tf.json 文件按其 Recipe 写出的样子读取,名称直接持有块本身,因此为一种形式编写的规则读不了另一种形式。这就是子句先读取 format 的原因:native_hcl 接受格式为 hcl 的文件,或格式为空且名称以 .tf 结尾的文件——没有提供方为其声明格式的文件按其名称解析,因此规则也按名称识别它,而不是跳过它。这里构建的每个 Terraform 文件都声明为 hcl,因此这里没有文件是按名称识别的。这些 Recipes 不写出 .tf.json 文件,因此规则不读取其他形式。每个角色的负载暴露什么说明了这两种形式。

CloudFormation 写出一个模板,其资源在 Resources 下按逻辑 ID 设键,每个资源带有其 Type 和 Properties:

deny contains msg if {
some artifact in input.artifacts
some doc in artifact.documents
some id, resource in doc.Resources
resource.Type == "AWS::RDS::DBInstance"
not resource.Properties.StorageEncrypted == true
msg := sprintf("%v: the RDS instance %v stores its data unencrypted", [artifact.path, id])
}

没有 StorageEncrypted 属性、或该属性设置为 true 以外任何值的实例会被拒绝:not … == true 对两者都成立。

为什么 CEL 规则的写法不同

policies/house-rule.cel 陈述相同的两个子句,并在这里的每次构建上得出相同的裁决。它在三处写法不同,每处都出于引擎方面的原因。

它在读取每个键之前先测试它。 在 CEL 中,读取值不带有的键是一个求值错误,而不是未定义的路径,而错误会使构建停止。每个目标的文件都缺少其他目标文件带有的键——Kubernetes 对象没有 services,Compose 文件没有 kind——因此每个子句都先用 has() 测试它读取的键:

// Docker Compose: a service whose image names no fixed version.
input.artifacts
.filter(a, has(a.documents) && a.documents.exists(d,
has(d.services) && d.services.exists(s,
has(d.services[s].image)
[… omitted: the image test, and the rest of the clause]

若没有 has(d.services) 测试,aggrega build --release release-helm.yaml --config governance-cel.yaml --auto-pull 会停止,无论 Kubernetes 对象运行什么镜像,都以 1 退出且不写入 dist/,报告该错误的那一行会指明策略文件和该键:

render-verdict: plugin "governance/cel:0.9.0": call "verdict_render": wasm: plugin "cel" call to verdict_render: policy source "house-rule.cel" could not be evaluated: No such key: services

它在每个文件中只报告一个违规者。 决定键收集消息,而 CEL 表达式无法把它按文件构建的各个列表合并成一个列表。因此每个 CEL 子句在每个文件中报告一个违规者:pod 模板的第一个容器,或者在文件按名称设键的服务、实例和资源中,名称排序最靠前的那个。推导式遍历映射时没有固定顺序,因此按名称选择才能让消息在各次构建之间保持不变。Rego 规则报告每个违规者。当一个 Compose 文件中有两个未固定版本的服务时,Rego 引擎会带着两条消息中止,CEL 引擎则带着一条消息中止,针对名称排序最靠前的服务;只有一个时,就像这里的每个 Release 那样,两者以相同的消息中止。

它会重复自身。 CEL 无法为子表达式命名,因此用到两次的测试要写两次,镜像测试在每个子句中完整写出,而不是像 Rego 的 unpinned 那样被调用。

这两个文件是刻意的近似副本,各自根据上面的规则独立编写,而不是由一个生成另一个,这样引擎之间出现分歧的构建就会显示出这种分歧。

裁决从不改变输出

位于 render-verdict 的策略接受或拒绝构建。它接收构建写出的文件并返回裁决;它返回的任何内容都不会应用到这些文件上。因此,无论是否挂载规则,对照构建都会写出逐字节相同的文件,check.sh 在每次运行时都会比较这两棵树。被拒绝的构建根本不写入 dist/。要解决拒绝,需要修改 Release——固定的标签、加密密钥——然后下一次构建会再次被评判。

生成示例

你可以用下面的命令构建这个示例,也可以让你的 AI 助手替你构建。

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

Terminal window
aggrega scaffold --example policy-render-verdict

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

Terminal window
cd policy-render-verdict

构建

Terminal window
aggrega build --release release-terraform.yaml --config governance-rego.yaml --auto-pull
aggrega build --release release-terraform-unencrypted.yaml --config governance-rego.yaml --auto-pull # halts; exits 1

将 governance-rego.yaml 换成 governance-cel.yaml 即可在 CEL 引擎上运行同一规则,将 Release 文件名中的 terraform 换成 helm、compose 或 cloudformation,并使用它们植入违规的 Releases release-helm-unpinned.yaml、release-compose-unpinned.yaml 和 release-cloudformation-unencrypted.yaml。

标准库目录提供这里的每个 Component、Recipe、Feature 和 FeatureRecipe,并带有两个引擎的 Plugin 实体。 它们从 hub.aggrega.ai 解析,即 .aggrega-config.yaml 指定的默认注册表。若用 --catalog 指定目录的检出(获取方式),则不会从任何注册表获取任何内容,因此构建可离线运行。--auto-pull 在构建过程中填充每个 Release 的锁文件;锁文件和渲染输出是生成的,不随附提供。

Terraform 对照构建完成。植入违规的 Release 中止:

[… omitted: the lines printed while the lockfile is resolved, which carry the refusal below once more and say the render that discovers external inputs could not finish]
[POLICY_ERROR E0005]
policy plugin "rego" rejected the build: terraform/modules/db/main.tf: the RDS instance db stores its data unencrypted
caused by: policy violation

每条消息都以 dist/ 下的路径指明规则所评判的文件,以及其中的违规者。其他植入违规的 Releases 以同样方式中止:

policy plugin "rego" rejected the build: helm/report-cronjob.yaml: container main runs registry.example.com/orders-report:latest, an image with no tag or the tag latest
policy plugin "cel" rejected the build: compose/docker-compose.yaml: service report runs registry.example.com/orders-report, an image with no tag or the tag latest
policy plugin "cel" rejected the build: cloudformation/cloudformation-stack.json: the RDS instance Db stores its data unencrypted

每一行是其构建输出中 [POLICY_ERROR E0005] 之后的那一行,从左边距开始显示。第一行来自 Rego 引擎,另外两行来自 CEL 引擎,每行都指明报告它的引擎;另一个引擎以自己的名称输出相同的消息。

借助 AI 助手

已配置 Aggrega 工具的 AI 助手也能完成同样的操作:把下面这条提示粘贴给它。

只使用 Aggrega 工具,不要自己创建任何文件夹。如果 Workspace 文件夹中还没有 `policy-render-verdict` 文件夹,就调用一次 `scaffold` 工具,将 `example` 设为 `policy-render-verdict`,不设 `dir`:它会把示例写入新的 `policy-render-verdict` 文件夹。然后按以下顺序为每个 Release 各调用一次 `cli-build` 工具(它运行 `aggrega build` 并接受其 `--config` 标志)——`release-terraform.yaml` 和 `release-terraform-unencrypted.yaml`——每次都将 `workspace_root` 设为 `policy-render-verdict`,`release` 设为该文件,`auto_pull` 设为 true,`config` 设为 `governance-rego.yaml`。第二次构建预期会被拒绝,所以请把拒绝信息读给我听。告诉我第一次构建写入了哪些文件;它们位于 `policy-render-verdict/dist/` 下。

检查每一次构建

此自检在文档仓库的检出中运行,该检出包含它所使用的共享构建辅助脚本;由 aggrega scaffold --example 写出的副本不包含该辅助脚本。

Terminal window
./check.sh

check.sh 通过 build-release 辅助脚本,先在不挂载任何策略的情况下将每个对照构建一次作为参照,然后在每个引擎下构建全部八个 Releases。对照构建必须完成,并写出与其参照逐字节相同的文件;植入违规的 Release 必须以 E0005 和为其预期的消息中止,旁边没有其他拒绝,并且不写入 dist/。两个引擎都要求同样的消息。它为每次构建输出一行,如果任何结果不同则以 1 退出,并输出该次构建的输出:

ENGINE RELEASE EXIT EXPECTED VERDICT
--------------------------------------------------------------------------------------------------------------
none release-helm.yaml 0 reference OK
none release-compose.yaml 0 reference OK
none release-terraform.yaml 0 reference OK
none release-cloudformation.yaml 0 reference OK
rego release-helm.yaml 0 pass OK: completed, byte-identical to the build with no policy
rego release-helm-unpinned.yaml 1 halt OK: E0005, the expected sentence
rego release-compose.yaml 0 pass OK: completed, byte-identical to the build with no policy
rego release-compose-unpinned.yaml 1 halt OK: E0005, the expected sentence
rego release-terraform.yaml 0 pass OK: completed, byte-identical to the build with no policy
rego release-terraform-unencrypted.yaml 1 halt OK: E0005, the expected sentence
rego release-cloudformation.yaml 0 pass OK: completed, byte-identical to the build with no policy
rego release-cloudformation-unencrypted.yaml 1 halt OK: E0005, the expected sentence
cel release-helm.yaml 0 pass OK: completed, byte-identical to the build with no policy
cel release-helm-unpinned.yaml 1 halt OK: E0005, the expected sentence
cel release-compose.yaml 0 pass OK: completed, byte-identical to the build with no policy
cel release-compose-unpinned.yaml 1 halt OK: E0005, the expected sentence
cel release-terraform.yaml 0 pass OK: completed, byte-identical to the build with no policy
cel release-terraform-unencrypted.yaml 1 halt OK: E0005, the expected sentence
cel release-cloudformation.yaml 0 pass OK: completed, byte-identical to the build with no policy
cel release-cloudformation-unencrypted.yaml 1 halt OK: E0005, the expected sentence
check: every build ended as expected.

它使用 ./build-release.sh 解析出的二进制文件,因此由 AGGREGA_BIN 选择;-- 之后的参数会传给每次构建。只要本目录中存在 dist/,它就拒绝启动,因为它会把每次构建的目录树移走以进行比较,而且它不会留下任何目录树;各次构建会像任何构建一样填充本目录的锁文件。它的退出状态就是完整的判定结果。

编译器不做解释的地方

编译器渲染每个目标的文件,将它们连同其提供方声明的格式作为文本交给挂载的引擎,并根据每个裁决所带的严重级别采取行动。它不知道什么是镜像标签、latest 会变动,也不知道 RDS 实例应当加密:这些含义属于规则。关于角色、负载和决定键,请参阅治理插槽。

文件

  • aggregate.yaml — 数据库以及与之连接的报表作业。
  • manifest-helm.yaml、manifest-compose.yaml、manifest-terraform.yaml、manifest-cloudformation.yaml — 在一个目标上将每种组件类型和手动触发 Feature 绑定到各自的 Recipes。
  • release-<target>.yaml、release-<target>-unpinned.yaml、release-<target>-unencrypted.yaml — 每个目标一个对照和一个预置的违规。
  • .aggrega-config.yaml — 默认注册表;不含治理挂接。
  • governance-rego.yaml、governance-cel.yaml — 通过各个引擎挂接在 render-verdict 的规则,每个都用 --config 指定。
  • policies/house-rule.rego、policies/house-rule.cel — 该规则,每个引擎一份。
  • build-release.sh — 构建一个 Release,并输出等效的 aggrega build 命令。
  • check.sh — 执行二十次构建并检查每次的结果。