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

治理插槽

本页介绍整个插槽,而不是其中某一个角色:四种角色(两种评判构建,两种塑造构建)、编译器内置的两个策略引擎,以及操作者如何挂接插件。

操作者挂接一个 Wasm 治理插件来检查构建,并根据检查结果采取行动。 编译器宿主始终对内容保持中立、不预设立场:它把构建载荷路由给 guest, 并根据 guest 的返回结果采取行动,从不自行解释策略本身。所有领域策略智能——策略语言、 其引擎以及规则——都位于 guest 内部。

这与每个插槽都遵循的同一个提前编译纯度契约相同: guest 对交给它的载荷求值,并返回一个由宿主原样使用的结果 (参见沙箱契约)。 宿主对 guest 使用的策略语言一无所知,自身也不携带任何 策略引擎代码。

一个治理插件恰好挂接在一个角色上,而由角色(而不是 插件)决定送达哪种载荷,以及该挂接可以对载荷做什么。 其中两种是裁决角色:挂接对构建作出评判,对于它返回的每个裁决,宿主 恰好执行三种操作之一。另外两种是变换角色: 挂接报告对构建的标签或注解的更改,由宿主 应用该更改。服务于多个角色的插件按每个角色各挂接一次, 插件自身不声明任何角色——角色由挂接携带。

本页全面介绍治理插槽:四种角色 及各自携带的载荷、宿主据以行动的裁决严重级别、 操作者提供的与引擎无关的输入通道、如何为编译器内置的两个策略引擎 (一个求值 Rego,一个求值 CEL)中的任一个编写策略、 guest 如何封装外部策略引擎、随附的参考 guest, 以及操作者如何将插件挂接到工作区。关于该插槽在流水线中的位置及其类型化的线路格式,请参见 plugin-contract.md;关于将 插件作为目录实体进行编写和发布,请参见 Wasm 插件开发者指南。

心智模型:宿主负责路由,guest 负责决策

在一次构建中,宿主为该挂载的角色组装载荷,将其传过 ABI 边界,再读回 guest 返回的内容。在 verdict 角色上,返回的是一个 verdict 列表,每个 verdict 带有一个严重级别和一条人类可读的消息: 宿主将每个严重级别映射为一个构建动作,它不会为了理解含义而读取消息,不知道策略检查了什么,也不知道是哪个引擎做出的决定。在 transform 角色上,返回的是要做的更改,其目标是该角色所管辖的 labels 或 annotations,而不涉及其他任何内容。

由于宿主不解释策略内容,整个策略层面都属于 guest:规则用哪种语言编写、由哪个引擎求值,以及规则触发后如何变成一个 verdict 或一项更改。socket 契约是有意设计得很窄的——一个角色、一组输入和一个结果——这样任何可编译为 Wasm 的策略技术都能为其服务。

verdict 角色只负责接受或拒绝,不做其他任何事:宿主只把它的输出当作一个决定来读取,从不将其作为更改来应用,因此策略无法悄悄地把一个不合规的构建变为合规。transform 角色是有意设计的例外,使其成为例外的原因在于它是由操作者挂载的——挂载一个用于调整 labels 的插件,本身就声明了 labels 需要被调整。这样的挂载能更改的内容被限定在其自身角色的范围内,一旦超出该范围,构建就会显式地中止。

四个角色

一个插件只挂接在一个角色上,该角色决定了宿主在流水线中的何处对其求值、它接收什么载荷,以及它可以返回什么。需要承担两个角色的插件要挂接两次——每个角色一次。

裁决角色:ir-verdict 和 render-verdict

  • ir-verdict —— 客体在渲染之前基于中间表示图进行推理。载荷包含完整的、与能力无关的 IR 图(编译器持有的每个节点、边和挂接),以及分析器枚举出的路由路径,因此策略无需重新遍历图即可对拓扑和可达性进行推理。该路径列表按起始节点设有上限——连接稠密或带环的拓扑可能包含比枚举输出更多的不同路由,一旦达到上限,从该起始节点出发的其余路由将不再列出。因此,出现在列表中的路径是真实存在的,而路径的缺失并不能证明不存在路径:如果某个策略的裁决取决于某物不可达,就应当依据载荷中完整提供的节点和边来确定这一点,而不是只依据路径列表。图中有一处并非按原样提供:作者声明为敏感的每个值——无论位于挂接的 values 或 infra 中、边界挂接的 infra 中、节点自身的 values 或 infra 中,还是连接自身的 values 或 infra 中——都会以扣留标记 {"aggrega_withheld": "declared"} 的形式到达,而它的键、它的敏感性标记以及它旁边每个未声明的值都按原样到达。策略判断声明为敏感的内容流向何处,但永远不会收到这些内容本身;参见治理策略读取的挂接事实。ir-verdict 策略在静态分析关口运行,早于任何制品的生成。可将其用于有关架构和连接的策略——拓扑不变量、跨边界认证、凭据流形态——这些策略应在构建渲染任何内容之前将其中止。
  • render-verdict —— 客体在渲染之后基于渲染输出进行推理。载荷包含按路径排序的已生成制品,因此对于相同的输入,各次运行的传输内容逐字节一致。每个制品都带有其输出路径和渲染后的文本;当生成它的 provider 声明了渲染格式时,还会带有该格式;当内容采用在策略之前已被解析的格式时,还会带有其内容的结构化解析视图。render-verdict 策略看到的正是构建所产生的内容,其中没有任何内容被扣留:Recipe 渲染进制品的值按渲染结果到达,因为策略评判的正是制品。可将其用于有关具体输出的策略——例如检查渲染出的 Docker Compose 服务或 Kubernetes 对象的规则。

转换角色:annotation-transform 和 label-transform

  • annotation-transform —— 客体在解析期间、注解展开之前报告要添加的注解。载荷包含该挂接可以注解的每个组件(各自带有已有的注解),以及 Manifest 为其注册了绑定的注解键。注入到已注册键下的注解会继续展开为一个 Feature 挂接,这个角色正是以此方式向构建添加开发者未曾键入的能力。

    它可以注解的组件是边界在 components: 下指定的每个组件,以及边界的 aggregates: 路由条目路由进来的每个组件。路由条目会放置其模块的每个组件,包括嵌套在其中的模块的组件,无论它自己的 components: 指定了全部、部分还是一个也没有(如 documents: {} 一个也没有指定);载荷会携带其中每一个。路由进来的组件通过它在构建图中所带的 id 来寻址——模块名、一个点,以及组件在模块内的名称,如 documents.backend,每多一层嵌套模块就多一个模块名和点——这正是构建图及其诊断信息的写法,因此决策也以这种方式指定它。路由条目放置但未指定的组件在载荷上不带有自己的注解,注入到它上面的注解会被当作在路由条目下写在它上面的注解来应用。

  • label-transform —— 客体在拓扑构建期间报告要应用的标签变更:在图构建完成之后、图被评判之前。载荷包含构建中各节点的投影——每个节点带有它所实例化的 Component、为其解析出的版本、它当前带有的标签,以及其实例声明的值(只读,且其 Component 声明为敏感的每个值都会像图裁决那样被扣留)——外加 Release 的名称和环境。可将其用于开发者不应需要手动键入的派生元数据(合规范围、归属、成本分摊),以及开发者所声明的配置应当获得的能力标签。

各角色携带不同的载荷,因为它们在不同时刻起作用、回答不同的问题。四个角色都携带下文所述的同一个由运维方提供的输入通道。若想直接查看载荷而不只是阅读说明,aggrega build --release <release> --policy-input <dir> 会写出每个角色交给挂接在该处的插件的载荷——包括没有任何挂接的角色——每个角色一个 JSON 文件,或者在某个角色的各挂接收到不同载荷时每个挂接一个文件;与 --dry-run 结合时,它只写出这些文件,不做其他事情。在 annotation-transform、label-transform 和 ir-verdict 处,该文件就是策略读取的 input 文档。在 render-verdict 处,策略引擎会在策略读取之前重塑载荷——每个制品的 documents 都是从中解析出来的——因此,编译器内置引擎上的 render-verdict 策略要在构建中以 warn 或 info 挂接来测试,如在策略把关构建之前对其进行测试所示。对于你自己构建了 .wasm 的插件,aggrega plugin run-local --plugin <plugin.wasm> --export verdict_render --with @<dir>/render-verdict.json 会在该文件上运行它。

判定与严重级别

下面的严重级别是判定角色的词汇。转换角色报告的是变更而不是判定,因此不带严重级别。

guest 返回一个判定列表。每个判定带有一个严重级别,决定构建的处理方式:

  • halt — 停止构建;host 将该判定的消息作为原因呈现。构建不产出任何制品。
  • warn — 标记该判定;构建继续进行。
  • info — 记录该判定;构建结果不受影响。

这三个就是全部,并且与其他所有 socket 的诊断使用的三个相同,因此无论在何处读到严重级别,其含义都一样。

带有任何其他值的判定属于违反契约,而不是第四种处理路径。构建会停止,消息会指出该插件、判定所带的值以及契约声明的三个值——这样,拼写错误的严重级别会作为构建错误被报告,而不会作为一个无人处理的判定被放过。从这三个值中报告的 guest 不受影响。

允许的求值不返回任何内容。guest 只在规则触发时才发出判定,因此空的判定列表表示策略允许了该构建。不存在可发出的“pass”判定——沉默即允许。

guest 可以在一次求值中返回多个判定,并混合不同的严重级别。host 会遍历所有判定:任何 halt 都会停止构建(并呈现每条 halt 消息),而 warn 和 info 判定只会被报告,不会阻断构建。这与区分会停止构建的策略和建议性 lint 检查的“停止与建议”划分相对应。

with 通道:sources 与 settings

策略 guest 通常对其执行的具体规则是通用的——引擎内置于 guest 中,而规则按每次挂载提供。 with 通道承载这种按挂载提供的输入。它有两个与引擎无关的字段:

  • sources——guest 加载的策略定义文件。host 在构建时读取每个指定的文件,并将其字节不透明地传给 guest: 它从不解析 source,传给 guest 的路径是文件的基本名称,而不是 host 上的绝对路径。 这些字节的含义完全由 guest 决定——对一个 guest 是 .rego 文件,对另一个是其他策略格式, 对能读取它的 guest 则是整个策略集的 base64 编码归档。
  • settings——guest 映射到其引擎上的配置映射。guest 从该映射中读取其可调参数 (副本数上限、必需的标签键)。默认情况下,host 原样传递它而不做处理;guest 还可以为它声明一个 schema(见下文), 此时 host 会在运行 guest 之前根据该 schema 校验该映射。

完全内置的 guest——其规则已编译在内,而不是在挂载时提供——会完全省略 with。该通道在每个角色中都是可选的。

类型化 settings

guest 可以为它期望的 settings 声明一个 JSON Schema。声明后, host 会在运行 guest 之前根据该 schema 校验挂载的 settings。不符合的 settings 会使构建停止, 消息中会指出出错的键以及 schema 的期望——缺少必需的键、值类型错误、未知的键或值超出范围,都会被提前捕获, 而不是表现为难以理解的 guest 故障,或者更糟,表现为结果错误却成功的构建。

类型化 settings 是可选的,由 guest 而非 host 声明。未声明 settings schema 的 guest 保持自由形式的行为:host 不经检查地传递其 settings。host 针对 guest 声明的任意 schema 执行普通的 JSON Schema 校验;它不解释这些 settings 的含义。这使检查保持与引擎无关——每个 guest 描述它所读取的 settings 的结构,host 只强制执行这一结构,别无其他。

**未声明 settings 的挂载会被当作 JSON null 校验。**正是这一点让 guest 可以使其 settings 成为必需:只接受对象的 schema 会拒绝未提供 settings 的挂载,构建随之停止。反过来也有相应的后果,而这正是编写时需要刻意考虑的:settings 确实可选的 guest 必须声明一个同时接受 null 和对象的 schema,否则它根本无法在没有 settings 的情况下挂载。编译器内置的两个策略引擎正是出于这个原因声明 "type": ["object", "null"]——挂载时不带 with: 块,它就以默认值运行。仅声明 "type": "object" 的 guest 已使其 settings 成为必需,无论这是否是本意。

ABI 是 Aggrega 自己的

套接字契约是 Aggrega 自己的 ABI,而不是任何策略引擎的 ABI。正因如此,任何编译为 Wasm 的策略技术都可以作为即插即用的 guest:guest 对外使用 Aggrega 的接口——describe(),以及它所服务的角色调用的导出函数——而它使用的引擎只是该接口背后的实现细节。

封装外部策略引擎的 guest 在自身内部吸收该引擎的 ABI。如果该引擎有自己的 Wasm ABI、自己的入口点或自己的宿主回调协议,封装它的 guest 会在内部实例化并驱动它,并将引擎的决策映射回套接字的裁决结构。编译器宿主只看到标准的治理裁决接口;它从不知道涉及的是哪个引擎,也不包含任何特定于引擎的代码。将策略从一个引擎切换到另一个引擎只是更改挂载,而不是更改宿主。

编译器内置两个策略引擎

CLI 二进制文件中编译了两个策略引擎,运维人员可以附加其中任意一个(或两个都附加),方式与附加任何治理插件相同:

坐标策略语言附加的源
governance/regoRego.rego 文件,或整个策略集的 base64 编码归档
governance/cel通用表达式语言(CEL).cel 表达式文件,或 .yaml / .yml 规则文档

语言之外的一切都是共享的。两者都服务全部四种角色,都以相同的字段名读取相同的按角色载荷,都通过同一个 translation 设置将决策映射到相同的三种裁决严重级别,并且在无法求值时都会明确报错,而不是放行构建。每个引擎都以发布它的编译器版本作为自身版本,都不需要外部工具链,也不会在构建时获取任何内容。两种语言各自能表达的内容并不相同:在 Rego 中只需几条辅助规则的规则,在 CEL 中可能需要设置和重复——在编写遍历路由的规则之前,请参阅表达式能表达什么。

区别在于编写规则所用的语言,这也是选择的全部依据。已经维护 Rego 策略库的环境(或在其他地方为准入控制编写 Rego 的团队)附加 Rego 引擎,其策略可以原样运行。将规则表达为针对文档的单个表达式的团队(就像 Kubernetes 验证准入策略那样)附加 CEL 引擎。两者按角色附加,因此一个工作区可以在一个角色上运行 Rego、在另一个角色上运行 CEL,也可以在同一角色上以两个附加同时运行两者。

宿主与决策来自哪个引擎无关:它路由载荷,读回裁决或变更,并据此执行。将策略从一种语言切换到另一种语言,需要更改附加并重写规则——但绝不需要更改宿主。

Rego 策略:两条路径

Rego 是一种常用的策略语言,运行它有两条路径:一个随编译器发布的低门槛引擎,以及一个完全保真的逃生舱口。

编译器中的 Rego 引擎是低门槛的路径。它带有一个 Wasm 原生的 Rego 求值器,因此操作者只需将 .rego 文件放入 sources 并挂接该插件,无需外部工具链,构建时也不会获取任何内容。它服务于全部四种角色:同一个插件根据其挂接的角色,可以评判构建图、评判渲染输出、调整标签或注入注解。它在目录中的标识是 pluginType: governance 下的裸名称 rego,即坐标 governance/rego,其版本就是发布它的编译器版本。为它编写策略是下一节的内容。

该求值器独立地重新实现了 Rego,而不是嵌入参考实现,并且它并未实现所有 Rego 内置函数。当策略调用了求值器未实现的内置函数时,该挂接会显式失败:它返回一个故障,而不是放行。随后构建会以一个指明该插件的故障停止,这有意与 halt 判定区分开来,从而“引擎无法对该策略求值”永远不会被误认为“策略允许该构建”。无法求值的策略会停止构建,绝不会悄然通过。

opa build -t wasm 逃生舱口是完全保真的路径。当策略需要完整的内置函数集或与参考引擎完全一致的语义时,使用 OPA 自己的工具链将其编译为 Wasm 模块,并在一个轻量的适配器 guest 后面运行该模块。适配器将 OPA 的 Wasm ABI 完全吸收在自身内部(参见上文的 ABI 是 Aggrega 自己的):它实例化由 OPA 构建的模块,设置输入,调用求值,并将决策映射回判定的结构。host 只能看到标准的治理判定接口。

一个参考适配器 guest 作为完整示例一同发布。它嵌入了一个用 Rego 编写、并用 opa build -t wasm 预编译为 WebAssembly 模块的策略。该模块是一个固定版本、已签入的产物,因此求值完全在 guest 内运行,不需要 OPA 进程,也不获取任何内容。每次构建时,适配器使用内嵌的 Wasm 解释器在自身内部实例化这个预置模块,满足该模块自身的导入(其线性内存和内置函数回调),将载荷作为 OPA 的 input 文档读取,将挂接的 settings 作为 OPA 的 data 文档读取,对每个已编译的入口点求值,并将每个入口点的 deny / warn / audit 入口点名称分别映射为判定严重级别 halt、warn 和 info。如果预置策略需要一个适配器未实现的、由 host 提供的内置函数,适配器会显式失败,拒绝该模块而不是返回放行,因此无法求值的策略会停止构建,而不是悄然通过。从 Rego 源码重新生成预置模块是使用 OPA CLI 执行的编写步骤,而不是构建时的依赖。../examples/policy-data-class-route/ 围绕它自己的一个模块构建了该适配器,并给出了重新生成两者的命令。

这两条路径共享同一份 host 契约,因此将策略从编译器中的引擎迁移到完整引擎只是一次挂接变更。

为 Rego 引擎编写策略

该引擎完全在 guest 内部求值由运维人员编写的 Rego,无论它挂载在四个角色中的哪一个。以两个角色、两个不同的策略文件挂载两次,就能让一个引擎覆盖同一次构建中的两个时机。

挂载所在角色的载荷是策略的 input 文档,挂载的 settings 对象是策略的 data 文档——因此策略以 data.max_replicas 读取运维人员提供的阈值。挂载在 sources 下声明的每个文件都成为一个策略模块,这些文件声明的每个 package 都会被求值。

策略使用哪种规则语法编写

Rego 有两种规则语法,引擎逐个模块地同时接受这两种语法。 因此,在当前语法出现之前组装的策略集,可以与今天编写的策略在同一个挂载中一起求值。

在当前语法中,规则体由 if 引出,收集到集合中的规则用 contains 表明这一点,模块则通过在 package 声明下方单独一行声明 import rego.v1 来说明自己使用的语法:

package example
import rego.v1
deny contains msg if {
count(input.graph.spec.nodes) > 20
msg := "this build declares more than twenty nodes"
}

在旧的方括号规则头语法中,规则收集的值写在规则头的方括号里,规则体直接跟在其后。使用该语法的模块不做任何声明,因为它是通过无法按当前语法解析而被识别的:

package example
deny[msg] {
count(input.graph.spec.nodes) > 20
msg := "this build declares more than twenty nodes"
}

**一个按当前语法可以解析、却未做任何声明的模块会被拒绝,并指明其名称。**正是这一声明确定了解读方式;没有它,同样的规则文本可能得出相反的决策:一个永不成立的规则体,在当前语法下不产生决策,在旧语法下却产生一个决策——于是本应保持沉默的策略会中止构建,而反过来的情况则会放行一个规则本来要阻止的构建。对于这样的模块,引擎不会替你选择一种解读,而是拒绝它,并说明需要添加什么:

policy source "policy.rego" must declare `import rego.v1`. Both Rego rule syntaxes are accepted, and this module parses as either one — so without the import its rules could be read in the older syntax, where the same text can reach the opposite decision. Add `import rego.v1` on its own line below the package declaration.

该拒绝是一个指明插件名称的构建故障,而不是一个 verdict,因此它像无法求值的策略一样中止构建,绝不会被理解为策略放行了构建。

有两个边界情况值得提前了解,以免出乎意料。一个完全没有规则体的模块——只声明数据的模块——会按当前语法解析,因此同样会被要求添加声明,尽管对它而言两种解读不可能产生差异。而用旧语法编写的模块永远不会被拒绝,因为它无法按当前语法解析:正是引擎本身区分这两者,因此一个有意使用方括号规则头的策略,绝不会被误认为忘了声明的当前语法策略。

策略将其决策收集在决策键之下

每个角色都从决策键读取策略的决策——决策键即策略收集结果所用的、具名的规则。读取哪些键,以及某个键下的决策意味着什么,由角色确定。

在 verdict 角色中,决策是一条消息,收集它所用的键决定了该消息上报时的严重级别。默认情况下,这些键是约定俗成的 Rego 收集名称:

收集所用的键上报为对构建的影响
denyhalt中止构建
warnwarn随一次正常完成的构建一同呈现
auditinfo被记录;构建结果不变

请将两套词汇区分开,因为它们确实是两套:deny、warn 和 audit 是你的策略中的名称,而 halt、warn 和 info 是插槽据以上报的严重级别。左列可由你重命名;右列是所有插槽共用的封闭集合。

以不同名称命名决策的策略,需要在挂载的 settings 中声明映射:

with:
settings:
translation:
- key: blocked
severity: halt
- key: advisory
severity: warn

声明的映射会替换默认映射,而不是扩展它:映射中列出的键正是被读取的全部键,因此一旦声明了上面的映射,仍收集到 deny 的策略将得不到任何 verdict。规则的声明顺序即 verdict 的上报顺序。策略未声明的键视为不存在的决策,而不是失败,因此一个策略文件可以服务多个挂载。

三者之外的严重级别,以及声明为空的映射,都会被插件声明的 settings schema 拒绝——host 会在分派之前依据该 schema 校验挂载的 settings。同一个键被映射两次,会在读取映射时被拒绝,这同样发生在任何策略运行之前。无论哪种情况,构建都会在得出决策之前中止,绝不会在映射只应用了一半时进行。

除此之外,settings 就是策略自己的数据:映射从对象中读出,而该对象原样到达策略的 data 文档,因此为默认键编写的策略看到的 data 文档,与完全未配置映射时看到的完全相同。

在 transform 角色中,决策是要做的更改而不是消息,因此没有需要确定的严重级别,转而由键固定:标签塑形角色使用 labels,注解注入角色使用 annotations。translation 设置只在上报 verdict 的地方读取,因此声明了该设置的 transform 挂载,携带的是其角色不会使用的设置。

决策键会从挂载加载的每个 package 中读取,因此策略集可以把规则分散到多个 package 中,每个 package 都贡献自己收集的内容。这一点的另一面值得在踩坑之前了解:在同一个挂载中,决策键在每个 package 中都是保留的规则名,因此一个恰好为自身用途收集到 labels 的辅助 package,其条目会被当作标签决策读取。这会明确报错而不是静默失败——挂载会报告该键下收集的某些内容不是该形态的决策——但理解这类消息最快的方式是把它看作名称冲突,因此请把该键留给决策,并为辅助规则另取名称。

各角色的载荷暴露了什么

载荷就是策略的 input 文档,因此策略按传输格式赋予的名称读取它。

**在携带构建图的两个角色中,构建图位于不同的路径。**针对构建图的裁决接收整个图文档,因此其节点位于 input.graph.spec.nodes;标签塑形角色接收节点的投影,因此其节点位于 input.graph.nodes。所以在这两个角色之间迁移的规则需要修改,而不能直接复制——忘记修改的症状是规则从不触发,而不是报错,因为不存在的路径只是未定义。

角色策略读取的内容
ir-verdictinput.graph——整个构建图文档:节点位于 input.graph.spec.nodes,以节点 id 为键;边位于 input.graph.spec.edges。作者声明为敏感的值读作 {"aggrega_withheld": "declared"}。input.precalculated_paths——枚举出的路由路径,每条都带有其有序的 nodes 列表和 attached_features,即挂接在该路径任意位置上的 Feature 类型(见下文)。该列表始终存在:组件之间没有路由的构建携带一个空列表。
render-verdictinput.artifacts——每个输出文件一个条目,各含 path、content、format 和 documents(即该文件解析后的文档)。format 是渲染该文件的提供程序为其声明的格式——Terraform 提供程序为其输出的每个 .tf 文件声明 hcl,为每个 .tf.json 文件声明 json,vendored 模块的文件也包括在内——若没有任何提供程序声明格式,则为空字符串,例如某个 Recipe 向边界的共享输出贡献的文件。这样的文件仍按其扩展名解析,因此无论哪种情况,其 documents 都存在。无法按结构读取的制品带有 parse_error 且没有文档,因此策略可以针对失败本身拒绝,而不是让无法读取的文件未经检查就通过。
label-transforminput.graph.nodes——构建的节点,以节点 id 为键,各含 component、resolved_version、labels 和 values:节点实例在 Aggregate 中声明的值,其模板已针对其参数求值;若未声明任何值则不存在。节点的 Component 声明为敏感的值读作 {"aggrega_withheld": "declared"},与在 ir-verdict 时相同,而其未声明为敏感的同级值按原样读取。规则读取 input.graph.nodes[id].values 来决定标签;它无法更改值。input.compilation_context——Release 的 release_name 和 environment,因此策略可以按环境作出不同决定。
annotation-transforminput.targets——该挂接可以注解的每个组件,各含 boundary_path、component_name——对于路由条目放置的组件,是它在构建图中的 id,例如 metrics.query——以及 Release 写在该组件自身上的 annotations,每个值都按原样给出:字符串、子键对象,或者在组件选择退出本会继承的某个注解时为 null。组件携带的每个键无论其值为何都会出现,因此规则可以不去改动别人已经写下的键。input.binding_keys——Manifest 为其注册了绑定的注解键。

**Terraform 资源在 Terraform 的两种形式中位于不同的路径。**在原生 .tf 文件的 documents 中,块先嵌套在其类型之下,再依次嵌套在它的每个标签之下,而最后一个标签持有一个块列表,因为类型和标签相同的块会按源码顺序汇集到一个列表中。因此资源属性位于 input.artifacts[_].documents[_].resource.<type>.<name>[_].<attr>——对于任意名称的 RDS 实例,即 input.artifacts[_].documents[_].resource.aws_db_instance[_][_].allocated_storage。.tf.json 文件按 Recipe 编写的样子读取,因此其惯用的对象形式(名称直接持有块本身)位于 resource.<type>.<name>.<attr>,而面向两种形式的策略需要读取两条路径。这对编译器内的两个策略引擎都成立。为另一种形式编写的 Rego 规则会发现其指定的路径未定义:在该处检测某个值的规则从不触发,而用 not 在值缺失时拒绝的规则会对每个资源都触发;对另一种形式进行索引或选择的 CEL 表达式会以一个指明其策略文件的求值故障停止构建。下文 渲染阶段策略适配器 中介绍的参考 Rego 渲染适配器会自行解析原生 .tf 文件,并将单个块读作对象,因此当策略在该适配器与编译器内的引擎之间迁移时,Terraform 路径需要修改,而不能直接复制。

每个角色还额外携带 input.sources——挂接自身的文件,各含其基本名 path 和 content。策略只作为这些文件之一运行,因此无论规则在哪里读取该列表,列表中至少都包含那个文件。

input.settings 是挂接的 settings 对象,与策略的 data 文档是同一个对象,当挂接声明了 settings 时它就存在。当挂接未声明任何 settings 时,规则会得到什么取决于角色:在 ir-verdict、label-transform 和 annotation-transform,该字段不存在,因此 input.settings 与载荷未携带的任何路径一样是未定义的;而在 render-verdict,它是空对象。所以,依赖于某项设置是否已配置的规则应检测它所读取的那项设置,而不是检测整个对象,这样在每个角色上的行为都相同——已配置的 max_nodes 会被读取,而未配置时 input.settings.max_nodes 为未定义,规则保持沉默:

package example
import rego.v1
deny contains msg if {
limit := input.settings.max_nodes
count(input.graph.spec.nodes) > limit
msg := sprintf("this build declares more than %v nodes", [limit])
}

CEL 引擎对未声明的 settings 对象处理方式不同,并在下文其自身的章节中加以说明。

attached_features 和 binding_keys 是列表而不是对象,因此策略用 in 检测成员关系:

package security
import rego.v1
deny contains msg if {
some path in input.precalculated_paths
some gateway in path.nodes
input.graph.spec.nodes[gateway].labels["dataplane.aggrega.ai/content-masking"]
not "core/data-masking" in path.attached_features
msg := sprintf("path %v passes through %v with no masking Feature attached.", [concat(" -> ", path.nodes), gateway])
}

attached_features 是路径上任一节点所持有的每个挂接的 Feature 类型的并集——包括写在该节点某个连接上的挂接,无论写在哪个连接上——因此该规则可由网关本身上的 core/data-masking 挂接满足,而该 Feature 正是挂接在那里:它根据网关声明的内容遮蔽能力进行选择。该挂接遮蔽的是经过该网关的聊天和补全文本;规则检查的是挂接是否存在,而不是它列出了什么。

由于它是整条路径上的并集,该列表只说明某个 Feature 挂接在路由的某处,而从不说明在哪里。需要知道某个 Feature 是否位于路由中两个特定组件之间——持有受限数据的组件和它所到达的组件——的规则,应按顺序读取路由的 nodes 以及每个节点自身的挂接,位于 input.graph.spec.feature_values_mapping[<node>];若用 attached_features 来回答同一问题,Feature 位于第二个组件之后的路由也会通过。../examples/policy-data-class-route/ 就是这样编写的,分别针对 Rego 引擎、CEL 引擎和 OPA。

节点对象本身不带 id:id 是它在 input.graph.spec.nodes 中所处的键,这就是为什么上面的规则把它从 path.nodes 读到的 id 带入消息,而不是读取 id 字段。

策略遇到映射键的顺序

构建图保留作者书写的顺序:节点按组件声明的顺序排列,每个节点的标签按节点携带它们的顺序排列。这一顺序完整地传入 guest——载荷将两者都作为有序条目携带 (见保持顺序的映射)。 策略是否遇到这一顺序,取决于评估该策略的引擎如何保存对象,而不取决于载荷:

  • **Rego 引擎按排序保存对象的键。**遍历 input.graph.spec.nodes、节点的 labels 或任何其他对象(包括策略本身中写的对象)的规则,会按排序顺序遇到键:声明为 web、api、metrics 的组件会以 api、metrics、web 的顺序出现。
  • **CEL 引擎不为映射固定任何顺序。**对 input.graph.spec.nodes 或节点的 labels 的推导式,在输入完全相同的两次构建中可能以不同顺序遇到键,且同一表达式中对同一映射的两次遍历也可能彼此不同。这就是 同一决策键下的消息会排序的原因: 编写规则时,应使其决策不依赖于键所处的位置。
  • **基于插件套件编写的 guest 会遇到作者的顺序。**通过其套件解码后,节点和每个节点的标签按载荷携带的顺序进入套件的保序容器,而每个套件附带的治理适配器骨架会将按同一顺序写出的 JSON 文档交给其引擎。将该文档转换为自身值类型的引擎则会遇到该类型的顺序,如 保持顺序的映射 所述。

塑形标签:策略指定标签,引擎负责寻址

在标签塑形角色中,策略在 labels 下为每个标签收集一个决策,指明节点、标签键以及标签取的值:

package tagging
import rego.v1
labels contains {"node": id, "key": "compliance.example.com/tier", "value": "gold"} if {
some id, node in input.graph.nodes
node.labels["component.aggrega.ai/type"] == "stateful-server"
}

设置一个已存在的键会替换其值。决策也可以改为要求删除某个键:

labels contains {"node": id, "key": "draft.example.com/scratch", "op": "remove"} if {
some id, node in input.graph.nodes
node.labels["draft.example.com/scratch"]
}

策略指定的是标签,而不是编写构建所应用的编辑指令,原因值得了解:指令按路径寻址标签,而 Aggrega 的标签键经常包含 /,它正是路径分隔符——因此手写的路径会寻址到一个嵌套位置,而不是某个标签。引擎对决策指定的标签进行寻址,因此转义只需编写一次,而不必在每个策略中编写,策略也能保持可读,是关于标签而非关于路径的陈述。

决策只能更改标签。引擎发出的每条指令都寻址一个节点上的一个标签,因此策略无法表达对节点的 Component、其解析版本、节点集合或非字符串标签值的更改。指明构建中不存在的节点、或删除节点未携带的标签的决策,会被构建拒绝,并给出指明该指令的消息——绝不会被静默忽略。

../examples/policy-label-transform/ 在两个内置打标插件旁挂接了这样一个策略,以及一个读取它们所写标签的针对构建图的裁决。这些插件各自读取和写入什么,见 内置打标插件。

注入注解

在注解注入角色中,策略在 annotations 下为每个注解收集一个决策,用目标自身携带的坐标指明目标,并给出键及其值:

package tagging
import rego.v1
annotations contains {
"boundary_path": target.boundary_path,
"component_name": target.component_name,
"annotation_key": "backup.example.com/schedule",
"annotation_value": "nightly",
} if {
some target in input.targets
not target.annotations["backup.example.com/schedule"]
}

决策写入的字段名就是它读取目标时所用的字段名,因此仅从载荷就能学会这一约定。读取 input.binding_keys 可以让策略只注入 Manifest 已为其注册含义的键——这些键会展开为 Feature 挂接。

决策的值是你自己也可以写在该注解上的值:字符串,或子键对象。路由单个子键的绑定接受字符串;路由多个子键的绑定接受一个逐一指明这些子键的对象,与运维人员在 Release 中的写法完全相同:

annotations contains {
"boundary_path": target.boundary_path,
"component_name": target.component_name,
"annotation_key": "feature.aggrega.ai/monitoring",
"annotation_value": {"interval": "30s", "port": "metrics", "path": "/metrics"},
} if {
some target in input.targets
not target.annotations["feature.aggrega.ai/monitoring"]
}

构建读取注入值的方式与读取写在 Release 中的相同值完全一样,因此它以相同方式展开,并以相同方式对照所绑定的 Feature 进行检查。引擎以排序方式保存对象的键,因此子键按排序顺序到达构建。任何其他形态的值——null、列表、数字、布尔值,或没有子键的对象——都会被构建拒绝,并指明该注入:该角色用于添加注解,而 null 或空对象读作作者为移除注解而写下的退出声明。指明载荷中不存在的组件的决策也会以同样方式被拒绝,并指明该坐标和注解。

当构建因注入注解的路由方式或其携带的内容而拒绝它时——例如将字符串传给路由多个子键的绑定、所绑定 Feature 的模式不接受的子键值,或经由 values 支柱路由的子键(Release 侧的注解不得使用该支柱)——拒绝信息会指明注入它的插件及该插件挂接的治理角色,从而将该值追溯到作出该决策的策略,而不是追溯到 Release 中一行无人编写的内容。

../examples/policy-annotation-transform/ 挂接了这样一个策略,在一个绑定下注入字符串、在另一个绑定下注入子键对象,并构建出与手工编写这些注解的 Release 相同的文件。

将整个策略集作为一个归档挂载

策略集可以逐个文件挂载,也可以作为单个归档挂载,该归档同时包含其策略文件和数据文档——即 Rego 工具链构建出的形态。挂载文件的内容以文本形式传递给 guest,而压缩归档是任意字节而非文本,因此归档以 base64 编码后挂载,并命名为以 .base64 结尾:

Terminal window
tar czf bundle.tar.gz policy.rego data.json
base64 -w0 bundle.tar.gz > bundle.tar.gz.base64
with:
sources:
- ./policies/bundle.tar.gz.base64

文件名决定了一个文件是归档还是策略文本,这使该选择始终由操作者自己声明:这样,损坏的归档会被报告为损坏的归档,并指明文件和失败的步骤,而不会被当作无法解析的策略文件读取。对归档进行编码是操作者在其工具链构建出归档之后添加的一个步骤。

在归档内部,每个 .rego 成员都是一个策略模块,每个 data.json 或 data.yaml 成员都是嵌套在其所在目录下的数据文档——内容为 {"max": 3} 的 limits/data.json,策略读取为 data.limits.max。其他任何类型的成员由归档为其自身的工具链携带,不属于策略输入。

无法打开的归档是一个指明所挂载文件的失败:无法解码的编码、无法解压的流、被截断的归档、无法读取的数据文件,或根本不包含任何策略的归档。这些情况都不会产生空的策略集,因为空策略集不会得出任何决定——而“归档无法读取”绝不能与“策略允许了该构建”无法区分。

为 CEL 引擎编写策略

该引擎完全在 guest 内部求值由运维人员编写的 CEL,无论它挂接在四种角色中的哪一种。它在目录中的标识是 pluginType: governance 下的裸名称 cel——即坐标 governance/cel——其版本就是发布它的编译器版本。在两个角色上以两个不同的策略文件挂接它两次,就是一个引擎覆盖同一次构建中两个时刻的方式。

plugins:
governance:
- uri: governance/cel:<version>
role: ir-verdict
with:
sources:
- ./policies/topology.cel
settings:
max_nodes: 20

策略通过一个名称 input 访问整个负载,因此它读取的名称就是线上格式赋予它们的名称:构建图位于 input.graph,枚举出的路由路径位于 input.precalculated_paths,渲染出的文件位于 input.artifacts,注解目标位于 input.targets。这些按角色划分的路径就是上文每种角色的负载暴露什么中列出的路径,并且对两个引擎完全相同——同一种线上格式,在同一个根名称下读取。

挂接自身的文件位于 input.sources,其设置位于 input.settings,因此运维人员提供的阈值读作 input.settings.max_nodes。无需学习第二个文档:设置和其他一切一样都是 input 的一部分。两者总是以一个值的形式存在——挂接未声明任何设置时,设置在每个角色上都是空对象——因此访问它们的表达式无需防范它们缺失,而某项设置是否已配置则通过检测其键来判断:has(input.settings.max_nodes)。

两种编写形式,以及在二者间做出选择的文件名

策略以两种形式之一挂接,由文件名决定是哪一种:

文件名结尾读作
.cel一个表达式,按原样求值
.yaml 或 .yml一个规则文档——一个规则列表
其他任何结尾一个表达式

文件名就是全部规则。没有任何设置用于选择形式,也不会检查文件文本来猜测形式——文本本来也无法回答这个问题,因为表达式自身的最外层值是一个映射,规则文档的最外层值也是,因此两种形式无法按结构区分。

因此这条规则双向生效,两种错误都会被拒绝,而不是被误读。 名为 policy.cel 的规则文档会被拒绝,因为 YAML 规则列表不是表达式;名为 policy.yaml 的表达式会被拒绝,因为表达式不是规则列表。每次拒绝都会指明该文件。两个方向的修复方法都是重命名文件。

一个策略集可以包含所需数量的文件,两种形式可以在同一个挂接中自由混用。

表达式,位于名为 .cel 的文件中

表达式语言没有可用来归集决策的规则名称,因此决策就是表达式产生的值:一个从决策键到该键所归集内容的映射。 在裁决角色上,一个键归集在其下得出的消息;在塑造构建的角色上,它归集要应用的决策。

{
"deny": input.graph.spec.nodes
.filter(n, input.graph.spec.nodes[n].resolved_version == "latest")
.map(n, "component " + n + " tracks the latest version; pin it"),
"warn": size(input.graph.spec.nodes) > input.settings.max_nodes ? ["this build declares a lot of components"] : [],
}

文件省略的键在该文件中没有得出决策,因此文件无需列出每个键——而且每个角色只读取与其相关的键,因此一个策略集可以用同一组文件同时服务裁决角色和塑造构建的角色。一个键携带其所归集内容的列表、单个内容,或表示无内容的 null 值。

求值结果不是映射的表达式会被拒绝,并指明应写的结构。裸写的 size(input.graph.spec.nodes) <= 5 是一个值得预料的错误:它是一个布尔值,而把 false 当作中止,就意味着编造一条作者从未写过的消息。

规则文档,位于名为 .yaml 或 .yml 的文件中

规则文档是一个规则列表,每条规则指明它得出的决策键、决定是否得出该决策的表达式,以及得出时报告的内容:

- key: deny
expression: size(input.graph.spec.nodes) > 20
message: this build declares a lot of components
- key: warn
expression: has(input.settings.max_nodes)
message: a component ceiling is configured for this environment

规则报告的内容取决于它得出的决策键,与在表达式中完全一样。文本是裁决携带的消息。映射是塑造构建的角色所读取的那一个决策的字段:

- key: labels
expression: input.compilation_context.environment == "production"
message:
node: app
key: compliance.example.com/tier
value: gold

规则写哪一种只由规则本身决定——没有用于选择的设置——而为其键写错类型的规则会被拒绝,并指明其名称。

一个值得在踩坑前了解的 YAML 细节:以双引号开头的表达式必须为文档读取器加上引号,因为以 " 开头的值会被读作带引号的标量,而不是以引号开头的文本。

- key: annotations
expression: '"backup.example.com/schedule" in input.binding_keys'
message:
boundary_path: main
component_name: app
annotation_key: backup.example.com/schedule
annotation_value: nightly

在任何求值之前,规则文档会被读作它所代表的表达式。 每条规则变成其决策键:表达式成立时携带其报告,不成立时不携带任何内容,共享同一键的规则会被合并。因此同一个求值器运行两种形式,规则文档的决策与它所代表的表达式完全一致——在每个角色上,无论是裁决还是塑造构建的决策。由此产生两个结果。文档与它所代表的手写表达式得出相同的决策,因为它们是同一次求值。并且下文的排序规则属于求值后的形式而非文档——文档中的规则不会按编写顺序报告。

哪种形式适用——它们不可互换

两种形式都经由同一个求值器运行,因此二者在速度和可信度上没有差别。不同的是各自能表达什么;而由于两种形式意味着要学两样东西,这种分工值得明确说明,而不是留给个人喜好。 按规则报告的内容来选择。

  • 报告固定时,使用规则文档。 消息或决策只写一次,紧挨着得出它的表达式,文件读起来像一串守卫条件。对于“如果这成立,就确切地说这句话”,这是更简短的形式。
  • 报告要指明发现了什么时,使用表达式。 一个表达式筛选构建中的组件,并为每个组件产生一条消息——或一个决策——因此读者会针对每个违规者看到 component payments tracks the latest version; pin it,而不是一句关于数量的话。

第二项工作正是规则文档做不到的:它的每条规则携带一个预先写好的报告,因此无法说明是哪个组件触发了它。先选用文档形式、随后又想在消息中写出违规者的名称,最终只能把规则改写为表达式,所以值得一开始就按这个问题做出选择。

表达式能表达什么

该引擎求值的表达式可使用 filter、map 和 exists 推导式,字符串和列表上的 +,size、in、startsWith、string(),条件运算符,以及用计算得出的整数索引列表。它们不提供某些 CEL 环境添加的扩展函数:join、split、substring、indexOf、flatten、cel.bind 和 lists.range 都会作为未声明的引用被拒绝;推导式只接受一个变量,因此 exists(i, v, …) 这类双变量形式也会以同样方式被拒绝。拒绝是一个构建错误,会指明文件和该引用:

policy source "routes.cel" could not be evaluated: Undeclared reference to 'join'

有三个结果会影响遍历路由的规则的写法:

  • 无法为中间值命名。 使用两次的子表达式要写两次,或通过对单元素列表做映射来绑定:[value].map(name, …)[0] 会在 name 绑定到 value 的情况下对其主体求值一次。
  • 无法遍历列表的位置。 按位置比较路由中组件的规则,从其设置中获取位置——例如一个 positions 列表 [0, 1, 2, …]——并在每个位置上索引路由,因此它必须防范比该列表更长的路由,方法是遇到这样的路由时中止,而不是只读取其中一部分。
  • 决策键归集的是消息,而不是消息列表。 为每条路由产生一个消息列表的表达式在决策键下会被拒绝——错误会说明它归集了一个列表类型的值而不是消息——因此规则应为每条路由产生一条记录,并由其构造消息。此外,表达式产生两次的消息会被报告两次:下文描述的排序只对键所归集的内容排序,不会去除重复项。

../examples/policy-data-class-route/ 包含一条在这三点约束下编写的 CEL 规则,旁边是为 Rego 引擎编写的相同规则。

决策键与严重级别

决策键、到严重级别的默认映射,以及用于重命名它们的 translation 设置,都与 Rego 引擎相同——参见上文的策略在决策键下收集其决策。默认情况下,deny 以 halt 报告,warn 以 warn 报告,audit 以 info 报告;声明的 translation 会替换该默认映射而不是扩展它,并且它声明的顺序就是判定的报告顺序。

两个引擎为它声明了相同的设置 schema,因此无论用哪种语言表达决策,translation 块的含义都相同,格式错误的块会在任何策略运行之前被拒绝。

在塑造构建的角色上,键是固定的而不是映射的:标签塑造角色上为 labels,注解注入角色上为 annotations。

排序:键内排序,以及决策上的全序

**同一决策键下的消息按排序后的顺序报告。**这是契约的一部分,而不是展示上的选择,其原因值得记住:对映射的推导——对 input.graph.spec.nodes 使用 .filter(...) 和 .map(...),这是编写按组件规则最自然的方式——遍历该映射的顺序并不由求值器固定。如果不加处理,相同的输入在每次构建中都会以不同的顺序报告相同的消息。排序消除了这一点。

由此产生两件容易被误读为缺陷、但其实并非缺陷的事情:

  • 规则文档的规则同样按排序报告,而不是按编写顺序——因为文档是作为它所代表的表达式来求值的,而排序作用于键所收集的内容。
  • **手写的列表同样会被排序。**携带 ["second", "first"] 的键会先报告 first,再报告 second。求值结果中没有任何东西能区分作者手写的列表和推导生成的列表,因此不存在需要保留的编写顺序。

跨键的顺序是 translation 声明的顺序。跨文件的顺序是文件名的顺序,因为附加项的源文件按名称排序后到达,而不是按附加项列出它们的顺序。

在塑造构建的角色上,同样的道理适用于决策本身,并且顺序更强:决策按其所指定的全部内容升序报告,这是决策可表达内容上的全序——先是节点,然后是标签键,然后是添加还是删除该标签,最后是值;对于注入,先是边界,然后是组件,然后是注解键,最后是其值。对标签或注解的更改会影响渲染输出,因此任意顺序将意味着相同的输入在每次构建之间渲染出不同的结果。

塑造标签

在标签塑形角色中,策略在 labels 下为每个标签收集一个决策,指明节点、标签键以及标签取的值:

{
"labels": input.graph.nodes
.filter(n, input.graph.nodes[n].labels["component.aggrega.ai/type"] == "stateful-server")
.map(n, {
"node": n,
"key": "compliance.example.com/tier",
"value": input.compilation_context.environment == "production" ? "gold" : "bronze",
}),
}

设置一个已存在的键会替换其值。决策也可以改为请求删除某个键,方法是将 op 指定为 remove:

{
"labels": input.graph.nodes
.filter(n, "draft.example.com/scratch" in input.graph.nodes[n].labels)
.map(n, {"node": n, "key": "draft.example.com/scratch", "op": "remove"}),
}

单个决策不需要用列表包裹,未指定 labels 键的文件不决定任何标签。

策略指定的是标签,而不是编写构建所应用的编辑指令,原因见 Rego 引擎的标签塑造一节:Aggrega 的标签键通常包含 /,手写的路径会定位到一个嵌套位置,而不是一个标签。引擎会定位决策所指定的标签。

读取节点可能没有的标签会导致失败,而不是得到空值,这就是第二个示例在读取键之前先检查它是否存在的原因。这是表达式语言自身关于读取缺失键的规则,而且它会明确报错:试图读取任何节点都没有的标签的策略,会报告它无法被求值,而不是悄悄地什么也不决定。

决策只能更改标签。指定构建中不存在的节点、或删除节点没有的标签的决策,会被构建拒绝,并给出指明该指令的消息——绝不会被静默忽略。

**每个节点和标签键只产生一个决策。**可能为同一节点上的同一标签产生两个不同值的规则是欠规定的:应在表达式内部确定该值——使用条件运算符,或使用只允许一个分支的过滤器——而不是同时发出两个决策。

../examples/policy-label-transform/ 完整展示了标签塑形角色,其策略是为 Rego 引擎编写的。

在已注册的键下注入注解

在注解注入角色上,策略在 annotations 下为每个注解收集一个决策,通过目标自身携带的坐标指定目标,并给出键及其值:

{
"annotations": input.targets
.filter(t, "backup.example.com/schedule" in input.binding_keys)
.map(t, {
"boundary_path": t.boundary_path,
"component_name": t.component_name,
"annotation_key": "backup.example.com/schedule",
"annotation_value": "nightly",
}),
}

决策写入的字段名就是它读取目标时所用的字段名,因此仅凭载荷就能学会这一约定。读取 input.binding_keys 可以让策略只注入 Manifest 已为其注册含义的键——正是这些键会展开为 Feature 附加项。每个字段都是必需的:键为空或组件名为空的注解不是策略有意请求的内容。组件所在的边界可以合理地用空字符串表示,因此该字段必须存在,但可以为空。

该值是你自己也可以写在该注解上的值:字符串,或子键映射,后者用于为一次路由多个子键的绑定提供值——"annotation_value": {"interval": "30s", "port": "metrics", "path": "/metrics"}。由于表达式语言不为映射规定任何顺序,引擎会按排序顺序写出映射的子键,并按表达式产生的样子传递该值;JSON 模型无法容纳的值——字节、时间戳、时长——会被拒绝,而不是被转换为文本。随后,构建读取该值的方式与读取写在 Release 中的相同值完全一样,并拒绝 null、列表、数字、布尔值或空映射,同时指明该注入。针对同一组件和键、值不同的两个决策按值的 JSON 排序。目标的 annotations 按原样携带每个现有值——字符串、映射,或表示退出的 null——因此检测 "feature.aggrega.ai/monitoring" in t.annotations 无论该键的值为何都能找到它。

指定载荷中不存在的组件的决策会被构建拒绝,并指明该坐标和注解。当构建因注入注解的路由、其子键值或其支柱而拒绝它时,拒绝信息会指明注入它的插件及其挂接的角色。与标签一样,每个组件和注解键只产生一个决策,在表达式内部确定值,而不是为一个键发出两个决策。

../examples/policy-annotation-transform/ 完整展示了注解注入角色,其策略为两个引擎分别编写。

当策略或决策无法读取时

引擎无法读取、无法求值,或产生的内容不是文档所述形状的决策的策略,会使构建失败,而不是返回判定或更改。该失败作为构建故障报告,指明文件,并在故障属于文件某一部分时指明其中的位置——这有意区别于 halt 判定,以免“此策略无法求值”被误认为“此策略允许构建”。

对于表达式,这涵盖无法解析的源——报告时附带解析器自身给出的行号和列号,并在出错位置下方标出脱字符——以及求值结果不是从决策键到该键所收集内容的映射的源。

对于规则文档,这涵盖不是规则列表的文本、不含任何规则的列表、缺少字段或字段为空的规则、该形式未定义的字段、既不是文本也不是文本到文本映射的报告,以及无法读取的表达式。属于某条规则的故障会指明该规则的位置——从一开始计数,与作者计数自己文件的方式一致——及其决策键。表达式无法解析的规则会在求值之前被拒绝,因此脱字符落在作者编写的表达式内部,而不是作者从未见过的转换后文本中的某个位置。

对于塑造构建的角色上的决策,这涵盖在应为决策的位置出现消息、缺少坐标,以及本引擎决策形式未定义的字段。最后一种值得单独说明:拼写错误的 annotation_valu 会被拒绝,而不是被忽略,因此错误会被报告,而不是悄悄注入一个空值,留下一个完成了却没有该更改的构建。每一次这样的拒绝都会指明文件,并在最后指明该类决策必须指定的内容。

渲染阶段的策略适配器

渲染阶段适配器基于构建的渲染输出进行推理,而不是基于其 IR 图。渲染载荷携带所生成的制品——每个制品都带有其输出路径和渲染内容,并在适用时带有渲染所用的格式及其解析后的结构化视图——以及该挂载自身的 sources 和 settings(各自在挂载声明时提供)。适配器按其目标输出形态读取这些内容,对结构化结果评估策略,并将结果映射为 halt / warn / info 裁决。由于载荷本身不指定任何输出形态,同一种适配器模式可服务于任意渲染目标;新的输出形态意味着新的适配器,而不是对宿主的修改。

每个渲染阶段适配器都是上文意义上的适配器:它对外使用 Aggrega ABI,对内吸收特定目标的格式或外部策略引擎的契约,从而使编译器不包含任何输出格式或策略逻辑。编译器内置的 Rego 和 CEL 引擎直接服务于 render-verdict 角色;除此之外,还有两个参考渲染阶段适配器作为完整示例,随插件开发工具包的 Rust 示例一同提供,每种常见输出形态各一个。

../examples/policy-render-verdict/ 在 render-verdict 挂接一条规则,作用于四个目标的输出——Kubernetes 对象、Docker Compose 文件、Terraform 根配置和 CloudFormation 模板——该规则为编译器内的每个引擎各编写一次,并检查每个目标中预置的违规会使构建停止,而其对照项会通过。

要编写你自己的适配器,无论是在这个角色还是其他角色,请从每个插件开发工具包随附的治理适配器骨架开始:编写你自己的治理插件 会带你从该骨架一路走到一个它会拒绝的构建。

YAML、JSON 和 Terraform HCL 输出——参考 Rego 渲染适配器

参考 Rego 渲染适配器针对任意 YAML 或 JSON 渲染输出以及 Terraform 的原生 HCL 输出,运行由运维人员提供的 Rego。它是渲染阶段形态的一个完整示例:使用与编译器内置引擎相同的 Wasm 原生 Rego 求值器,以及相同的 deny / warn / audit 收集约定,映射到相同的三种裁决严重级别,只是基于渲染后的文件而非构建图进行推理。

在各 YAML/JSON 目标之间,它与输出形态无关。适配器将每个制品的内容解析为一个或多个 YAML 或 JSON 文档——YAML 是 JSON 的超集,因此 CloudFormation 栈之类的 JSON 模板也通过同一个解析器解析——并将解析后的文档与原始内容一起提供给策略。策略使用普通 Rego 即可对任何此类目标的结构化渲染输出进行推理:input.artifacts[_].documents[_] 给出解析后的文档(Docker Compose 文件的 services、CloudFormation 模板的 Resources),input.artifacts[_].content 给出原始文本,而挂载的 settings 对象即 Rego 的 data 文档。例如,一个针对 Docker Compose 输出的“要求使用批准的镜像仓库”策略,会拒绝任何镜像不带仓库前缀的服务。

该适配器还能基于 Terraform 的原生 HCL 渲染输出进行推理。原生 .tf 文件既不是 YAML 也不是 JSON,因此适配器将其投影为与 Terraform-JSON(.tf.json)文件解析结果相同的规范对象:策略在 input.artifacts[_].documents[_].resource.<type>.<name>.<attr> 读取资源属性——对于 RDS 实例,即 input.artifacts[_].documents[_].resource.aws_db_instance[_].allocated_storage——无论编译器生成的是哪种 Terraform 形式,读取方式都相同。属性类型会被保留(数字仍是数字,布尔值仍是布尔值),未解析的 Terraform 表达式则以其 ${ ... } 形式保留为字符串。Terraform-JSON 内容(.tf.json、.auto.tfvars.json)不加改变地通过 YAML/JSON 路径解析;而 Terraform 模板文件(.tftpl)是模板文本而非独立配置,不会被投影,并像任何非结构化内容一样给出 parse_error。

**该列表说明的是适配器的解析器接受什么,而不是编译器生成什么。**两者并非同一集合,自动加载的变量文件正是两者不同的情形:编译器在任何路径上都不生成此类覆盖文件——源模块的输入是边界根配置中该组件模块块的参数——因此只有当某个 vendored 模块自带此类文件、并由 sourced 路径原样复制到输出中时,这种形态才会出现在策略的视图中。如果策略期望编译器生成这类文件,它将永远不会触发。

当制品内容无法解析时,适配器不会静默放行:它保留原始内容,不为该制品提供任何解析后的文档,并将解析器的消息记录在 input.artifacts[_].parse_error 下,从而让策略能够明确地因格式错误的制品而中止构建。与编译器内的 Rego 引擎一样,调用嵌入式求值器未实现的内置函数的策略会显式失败——报告一个指明该插件的故障,绝不静默放行。

Kubernetes 输出——Kubewarden 渲染适配器

Kubewarden 渲染适配器针对渲染后的 Kubernetes 清单运行 Kubewarden 风格的准入策略。它对内吸收 Kubernetes 准入审查契约:Kubewarden 策略接收一个包装单个对象的请求,并返回接受或拒绝的响应。在渲染阶段,构建的输出本身就是一组 Kubernetes 资源,这使该阶段成为运行准入形态策略的自然位置。对每个渲染对象,适配器从解析后的对象本身推导出准入字段,在 guest 内将对象包装为准入审查形态的请求,运行策略,并将响应映射为裁决:拒绝成为一条裁决;接受则不产生任何输出。随附的参考策略是一条“要求标签”规则——每个对象都必须带有由 settings 指定的标签键——这是常见的 Kubewarden 模式。

渲染阶段适配器的共同范围

  • **渲染阶段,每个适配器对应一种输出形态。**渲染阶段适配器基于渲染后的制品而非 IR 图进行推理,并以其所解析的输出形态为目标——参考 Rego 渲染适配器对应 YAML/JSON 和 Terraform 原生 HCL,Kubewarden 适配器对应 Kubernetes 对象。图阶段的策略,或针对随附适配器均不解析的输出形态的策略,属于另一种 guest。
  • **仅做验证。**渲染阶段适配器只接受或拒绝;它从不返回修改后的对象。变更型策略返回的修改后对象会被忽略——编译器从不依据策略裁决改写渲染输出。策略只做决定,不做编辑。

挂接策略

运维人员通过工作区配置(.aggrega-config.yaml)中的 plugins.governance 列表挂接治理插件。每个条目指定一个插件、它所挂接的 role,以及可选的、提供其规则和可调参数的 with 通道:

plugins:
governance:
- uri: <resolvable-plugin-reference>
role: ir-verdict
with:
sources:
- ./policies/replicas.rego
settings:
max_replicas: 3

uri 解析到该插件。宿主在构建时读取每个 sources 文件并将其字节交给 guest,并原样传递 settings。未挂接任何治理插件的构建会将该插槽作为空操作运行,因此挂接对工作区而言纯粹是增量的。

服务多个角色的同一插件按每个角色各挂接一次,每次挂接都有自己的规则和自己的设置:

plugins:
governance:
- uri: governance/rego:<version>
role: label-transform
with:
sources:
- ./policies/tagging.rego
- uri: governance/rego:<version>
role: ir-verdict
with:
sources:
- ./policies/topology.rego
settings:
translation:
- key: blocked
severity: halt

挂接指定哪个版本。uri 指定一个 Plugin 实体——即 <pluginType>/<name> 坐标,以及冒号后的版本——而版本参与解析。对于编译进 CLI 的两个引擎,该实体来自两个位置之一。每个编译器发行版都会以其自身版本发布 governance/rego 和 governance/cel 的 Plugin 实体,标准库目录收录它们,每个都处于发布它的那个发行版的版本;工作区从其列出的目录文件夹中读取它们。aggrega 二进制文件各携带一个实体,版本为其自身发行版的版本,不含其他版本。如果挂接指定的版本两者都不携带,且没有任何 pull 将其拉取到内容缓存中,构建会以 E0137 停止,并指明该引用。

因此,挂接应指定工作区所读取的目录中携带的版本。该版本在 aggrega 的其他发行版下也能从目录中解析,而只有二进制文件携带的版本——即其自身发行版的版本——只能在该发行版下解析,在裁决角色和转换角色上都是如此。在转换角色上,pull 会将其解析出的版本固定在锁文件中,并以 E0103 拒绝工作区所读取的目录和二进制文件都不携带的版本。版本选择的是 Plugin 实体(它记录插件的导出项和运行时限制),而不是引擎:一旦引用解析完成,运行的引擎就是编译进执行该构建的二进制文件中的那个引擎,因为二进制文件内置的插件是读取插件模块的第一个位置。工作区自行声明的治理插件——位于其自身目录文件夹中的 Plugin 实体,旁边放着它的 .wasm——按该实体所记录的版本来指定。

每个角色选择一个默认入口函数——判定图的角色为 verdict_ir,判定渲染产物的角色为 verdict_render,塑造标签的角色为 mutate,注入注解的角色为 transform_annotations——挂接可以通过 function: 将某个角色指向另一个导出。宿主会拒绝分派到 guest 未在其 describe() 自我报告中声明的导出,因此,若挂接指定了其 guest 不服务的角色,会在 guest 运行之前按名称报告,而不是悄无声息地什么也不做。

function: 指明由 uri 所指插件上的一个导出。处于裁定角色(ir-verdict 或 render-verdict)的挂接项若指明了 function: 却没有 uri:,所指的就是不属于任何插件的函数,因此配置在读取时即被拒绝,归入 E0224,并指出该文件以及该条目在其列表中的位置:请添加导出该函数的插件的 uri。

plugins.governance 列表有一个增量配套项 plugins.governance_append:在每个配置层,配套项中的条目会拼接到已解析的 governance 列表之后,因此工作区配置或全局配置是组合策略挂接,而不是遮蔽基础列表。

CI 拥有的叠加层

除手写的 .aggrega-config.yaml 之外,自动化流水线可以拥有一个单独的叠加文件 .aggrega-config-append-ci.yaml。它的存在是为了让流水线能够挂接它所控制的策略(或其他列表值配置),而无需编辑开发者手写的基础配置——流水线可以整体覆盖自己的叠加文件。

叠加层严格是增量的。它按照与基础文件相同的配置 schema 进行校验,对于每个列表值字段,其条目会拼接到已解析的列表之后。它只能添加:不能移除基础条目,也不能以标量覆盖基础值——它携带的标量或映射键没有增量含义,会被忽略(并在解析警告中指明),而不会被应用。而且它从不锚定工作区根目录:只有带有 workspace: 块的 .aggrega-config.yaml 才会这样做,因此将叠加层放入某个目录只会添加挂接,而不会改变工作区的起始位置。

这为流水线提供了一个实施全组织范围策略的清晰接缝:流水线放入一个列出强制策略插件的 .aggrega-config-append-ci.yaml,这些挂接会合并到开发者所编写内容之上,而绝不会取而代之。

# .aggrega-config-append-ci.yaml — owned by the pipeline, additive only
plugins:
governance_append:
- uri: <organization-policy-plugin-reference>
role: render-verdict
with:
settings:
required_label: app.kubernetes.io/name

examples/policy-org-overlay/ 构建一个工作区,其中有一个团队的挂接、一个通过全局配置文件的 governance_append 添加的组织挂接,以及一个通过此覆盖层添加的流水线挂接,并检查每种组合打印什么以及是否完成。

在策略把关构建之前对其进行测试

如果 Rego 规则指定了其角色的载荷中不存在的路径,这并不是错误:该路径未定义,规则永远不成立,构建会像策略允许了它一样完成。因此,新策略需要经过三步才能获得 halt:以只报告而不停止的严重级别挂接它,对照其角色接收的载荷检查它指定的每条路径,并阅读它在将要评判的构建上报告的内容。

以下命令在 examples/policy-org-overlay/ 的一个副本中运行,该副本的 .aggrega-config.yaml 挂接了一个新策略来代替团队的策略。该策略旨在拒绝关闭了高可用性的数据存储,而它的规则是从一个标签塑形策略复制过来的:

package datastores
import rego.v1
deny contains msg if {
some id, node in input.graph.nodes
node.labels["component.aggrega.ai/category"] == "datastore"
input.graph.spec.infra_mapping[id].ha.enabled == false
msg := sprintf("%v is a datastore running with high availability off", [id])
}

**挂接它,使其只报告。**该策略收集在 deny 下,默认会停止构建。只指定 deny 且级别为 warn 的 translation 会把它的每个决策报告为警告,并让构建完成;info 则改为记录它们。策略本身保持将来强制执行时的样子:

plugins:
governance:
- uri: governance/rego:0.9.0
role: ir-verdict
with:
sources:
- policies/datastore-ha.rego
settings:
translation:
- key: deny
severity: warn

**写出载荷,并在其中查找路径。**一旦某次构建填充了 Release 的锁文件,

Terminal window
aggrega build --release release.yaml --dry-run --policy-input payloads

会将每个角色交给其挂接的载荷写入 payloads/,不写其他任何内容,并报告如下,其中 <workspace> 代表构建运行时所在的目录:

policy input: 4 file(s) written to <workspace>/payloads
[… omitted: a lint notice about core/secret-value, the rendered files the run prints in place of writing them, the build's time, and the line saying only the policy inputs were written]

这四个文件是 annotation-transform.json、ir-verdict.json、label-transform.json 和 render-verdict.json;没有任何挂接的角色也会写出文件,因此可以在策略挂接到任何地方之前,就对照其角色检查它。在 ir-verdict、label-transform 和 annotation-transform,该文件就是策略读取的 input 文档,因此在信任规则之前,可以用任意 JSON 工具从中读出规则指定的每条路径:

Terminal window
jq '.graph.nodes' payloads/ir-verdict.json
# null
jq -c '.graph.spec.nodes | keys' payloads/ir-verdict.json
# ["db","web"]
jq -c '.graph.spec.infra_mapping.db.ha' payloads/ir-verdict.json
# {"enabled":false,"read_replicas":0}

规则要找的节点不在那里:input.graph.nodes 是标签塑形角色存放节点的位置,而在 ir-verdict,节点位于 input.graph.spec.nodes(参见 每个角色的载荷暴露什么)。该文件还说明了修正后的规则必须作出的决定:db 是一个数据存储,其高可用性已关闭,应当报告它。

在安装了 OPA 的环境中,Rego 策略可以直接针对同一文件求值:opa eval -i payloads/ir-verdict.json -d policies/datastore-ha.rego 'data.datastores.deny'。编译器内的 Rego 引擎是一个独立实现,因此作出决定的仍然是构建中的求值:它未实现的内置函数会停止构建,而不是被求值。

在 render-verdict,该文件不是策略的 input。其中每个制品都携带其 path、content 和 format;规则读取的 documents 是策略引擎收到载荷后从内容中解析出来的,因此针对 documents 的规则在该文件中什么也找不到。该角色上的策略要在引擎解析它们的地方测试:在构建中,如下一步所示。

**构建,并将它报告的内容与载荷所说的进行比较。**使用复制来的路径时,

Terminal window
aggrega build --release release.yaml --auto-pull

会完成且不报告任何内容:

Pull 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]

载荷中有一个关闭了高可用性的数据存储,而策略对此只字未提:这种沉默就是错误所在,而构建中没有其他任何东西指向它。当规则读取 input.graph.spec.nodes 时,同一命令会报告 db 并完成:

policy plugin "rego" warning: db is a datastore running with high availability off
Pull 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]

添加 --dry-run 会报告相同的裁决且不写入 dist/,因此这一循环可以在工作区上运行而不扰动其输出。

为 CEL 引擎编写的同一规则不会静默失败。在那里,读取载荷中不存在的键是一个求值故障,因此复制来的路径放在以相同 translation 挂接的 policies/datastore-ha.cel 中时,

{
"deny": input.graph.nodes
.filter(n, input.graph.nodes[n].labels["component.aggrega.ai/category"] == "datastore"
&& input.graph.spec.infra_mapping[n].ha.enabled == false)
.map(n, n + " is a datastore running with high availability off"),
}

即使在 warn 级别也会停止构建。它以 1 退出,最后一行指明策略文件和该键:

ir-verdict: plugin "governance/cel:0.9.0": call "verdict_ir": wasm: plugin "cel" call to verdict_ir: policy source "datastore-ha.cel" could not be evaluated: No such key: nodes

render-verdict 策略也以同样方式测试。在同一工作区中以相同的 translation 挂接在 render-verdict、拒绝在主机上发布端口的 Compose 服务的规则,

package published
import rego.v1
deny contains msg if {
some artifact in input.artifacts
some doc in artifact.documents
some name, service in doc.services
count(service.ports) > 0
msg := sprintf("%v publishes a port on the host", [name])
}

会报告唯一一个这样做的服务:

policy plugin "rego" warning: web publishes a port on the host
[… omitted: the pull's line, a lint notice about core/secret-value, the build's time and the line naming the dist/ directory it wrote]

**然后强制执行。**移除 translation 会让 deny 恢复为 halt,之前报告了 db 的构建现在会因它而停止,以 1 退出,且不写入 dist/:

[… omitted: the lines printed while the lockfile is resolved, which carry the refusal below once more, and a lint notice about core/secret-value]
[POLICY_ERROR E0005]
policy plugin "rego" rejected the build: db is a datastore running with high availability off
caused by: policy violation

不必一次在所有地方移除只报告的挂接。一个配置文件可以将其挂接的 translation 保持在 warn,同时流水线的覆盖层以 deny 在 halt 挂接同一策略,examples/policy-org-overlay/ 正是这样推行组织规则的:在开发者的构建上是一条警告,而在流水线的构建上则是构建停止的原因。

在 CI 中针对构建输出运行策略

上文所述都是在构建内部附加策略。还有第二种途径, 它完全不需要插座:在流水线中针对构建写出的文件 运行你自己的工具。

这之所以可行,是由构建的输出决定的。Kubernetes 和 Compose 目标写出 YAML;Terraform 目标写出原生 HCL,或 .tf.json 形式的 JSON。 这些正是生态中的配置工具已经能读取的格式——而且 aggrega build 将普通文件写入一个目录,没有包装格式、没有 索引,也无需解包。因此,读取 YAML、JSON 或 HCL 的工具针对 构建输出运行的方式,与针对人工手写的配置运行的方式相同, Aggrega 也无需为此增加插座、插件类型或配置键。

因此,现有的规则集无需移植。如果你已经在 Conftest、 Kyverno CLI、kubeconform、Checkov 或 OPA 中维护规则,这些规则可以原样针对 Aggrega 构建的输出运行,而评估它们的工具就是你的 流水线已经安装的那个。

两个开箱即用的规则脚本位于 examples/policy-in-ci/,每个都附有调用它的流水线步骤,以及它们在真实构建上产生的两次拒绝。它们只使用 yq,因此无需安装任何策略工具链即可运行;它们展示的模式——读取输出目录、作出判定、以非零状态退出并指出违规的制品——也是处于这一位置的任何工具所采用的模式。

规则应归属哪条途径

两条途径都是一等的,一个工作区通常两者兼用。起决定作用的是 规则需要看到什么,以及它需要在何时起作用。

在以下情况下将其附加到插座:

  • 构建根本不能产生该制品。 ir-verdict 策略 在静态分析关口运行,早于任何渲染,因此在此处中止 不会写出任何内容——没有需要审查、隔离或被意外 应用的输出文件。流水线检查必然在文件生成之后运行。
  • 规则需要只有构建才掌握的事实。 ir-verdict 角色读取 组装好的图:节点、边及其插座,每个附件及其填充的插槽, 作者声明为敏感的值,以及路由路径。这些信息 都不会保留到渲染输出中——Kubernetes 清单不会记录 值由哪个插座传递,也不会记录资源由哪个 Feature 贡献——因此 关于拓扑或来源的规则只有一个归宿,那就是插座。
  • 无论构建在哪里运行,规则都必须成立。 治理附件位于 工作区配置中,因此它既适用于流水线的构建,也同样适用于 开发者的本地构建。流水线检查只在流水线运行的地方适用。
  • 规则应当塑造构建,而不是评判构建。 只有变换角色 能做到这一点,而且只是因为运维人员附加了它。

在以下情况下在 CI 中运行:

  • 规则已经存在,存在于你的团队运行和审查的工具中,针对的是 该工具已经能解析的格式。将其重新表述为插座策略内容 只是额外的工作,最终不会带来新的覆盖范围。
  • 规则针对的是目标将会接收到的制品——最终的 文件集合,经过所有变换之后、以被应用的形式呈现。这也是 render-verdict 角色的对象,因此仅就这一点而言,两条途径看到的 是同样的内容,选择取决于其他几点。
  • 发现结果是给审查者看的,而不是给构建用的。 将制品和 发现结果一并发布的流水线能让审查者同时看到两者; 而中止的构建只给他们一条消息。
  • 检查超出了单次构建的范围——将本次构建的输出与 上一次构建、与集群的实时状态,或与任何构建 载荷都不包含的清单进行比较。处于任一判定角色的策略只能看到它所附加的 那次构建,仅此而已。

两条途径是互相组合而非互相竞争的:拓扑不变量通过 ir-verdict 中止构建,然后同一条流水线再针对该构建写出的内容 运行整个环境现有的制品规则。

交叉引用

  • plugin-contract.md — 该插槽在流水线中的位置、 它承载的类型化传输结构,以及每个插件运行所在的沙箱。
  • plugin-developer-guide.md — 编写插件、 describe() 自述,以及发布 → 拉取 → 构建的生命周期。
  • ../entities/plugin.md — 将插件带入目录的 Plugin 实体。
  • ../cli/aggrega-build.md — 调度该插槽的 构建命令。
  • ../schema/other/aggrega-config.md — 工作区配置 schema,包括 plugins.governance 挂载 入口。
  • ../examples/policy-in-ci/ — 两个针对构建输出的可运行规则脚本,各附有对应的流水线步骤。
  • ../examples/policy-data-class-route/ — 一条针对路由的 ir-verdict 规则,分别为 Rego 引擎、CEL 引擎以及参考适配器 guest 背后的 OPA 编写,每个引擎通过一个 --config 文件按构建挂载,并附有一个脚本,检查三者在每个 Release 上得出相同的结果。