内置的标记插件
编译进 CLI 的两个治理插件,无需编写策略即可在构建的节点上写入标签:各自读取什么、写入什么,以及各自的一个挂接示例及其写入的标签。
CLI 自带两个治理插件,仅凭配置即可塑造标签,无需编写任何策略语言:
| Plugin | 写入内容 |
|---|---|
governance/label-injector | 一组规则在每个标签与规则匹配的节点上设置的标签 |
governance/selector-tagger | 一个标签 tag,其值由一个 Component 名称映射为每个节点给出 |
两者都像任何治理插件一样,通过工作区配置中的 plugins.governance 挂接(参见挂接策略),并且两者都列在嵌入式插件中。本页的挂接示例写的是 0.9.0,即标准库目录中各插件的 Plugin 实体的版本;构建使用的是编译进 CLI 的插件。
两者的共同点
它们只服务 label-transform 角色,不服务其他角色。 每个插件都在标签塑造角色上报告标签变更,时机是构建图构建完成之后、被评判之前(参见转换角色)。挂接在其他任何角色上时,二者都会在运行前被拒绝,因为它们没有为该角色声明导出。在 ir-verdict 上,构建会停止并报告:
[E0085] ir-verdict: plugin "governance/label-injector:0.9.0": call "verdict_ir": wasm: plugin "label-injector" does not declare export "verdict_ir" in describe(): wasm: plugin rejected by the sandbox[E0085] ir-verdict: plugin "governance/selector-tagger:0.9.0": call "verdict_ir": wasm: plugin "selector-tagger" does not declare export "verdict_ir" in describe(): wasm: plugin rejected by the sandbox在 render-verdict 和 annotation-transform 上,拒绝同样是 E0085,只是改为指明 verdict_render 和 transform_annotations。
它们只读取节点的标签及其 Component,其他一概不读。 节点的标签是插件运行时它所携带的标签:其 Component 自身的标签,以及在它之前列出的任何转换所写入的标签。其 Component 是 Aggregate 的 type: 为它给出的名称,例如 core/datastore/mariadb。两个插件都不读取节点的值、Release 或其环境:二者在节点上写入的内容仅由该节点的标签和 Component 决定。
它们写入标签,且只写入标签。 两个插件报告的每项变更都指明构建中某一个节点上的一个标签,并带有字符串值。写入节点已携带的标签会替换其值——包括 Component 自身的标签。两者都不会删除标签,也无法更改值、节点的 Component 或版本,或节点集合:标签塑造角色不提供这类变更(参见塑造标签)。
它们的设置在运行前不受检查。 两者都没有为其 settings 声明 schema,因此构建会将设置原样交给插件。插件不读取的键会被忽略——拼错的 rules 不会设置任何内容,构建照常完成——而插件读取的键若持有其他类型的值,构建就会停止,消息先指明插件,然后是 decode settings: 和原因。
它们按文件名顺序将 sources 下的文件作为 YAML 读取。 无论挂接以何种顺序列出这些文件,插件收到的文件都按文件名排序。不是有效 YAML 的文件会使构建停止,消息先指明插件,然后是 parse source "<file>": 和解析器给出的原因;内容不符合插件所读取形状的文件会以 decode source "<file>": 和原因使构建停止。
lockfile 保存构建所应用的输入。 解析 Release 的 lockfile 的 pull——aggrega pull,或带 --auto-pull 的构建——会记录每个挂接的设置及其每个文件的内容,构建应用的是记录下来的内容。编辑挂接的设置或其某个文件后,请重新解析 lockfile;不这样做的构建会继续写入已记录输入所给出的标签。
在没有 with: 块的情况下挂接时,两者都不写入任何内容,构建照常完成。
label-transform 上的多个挂接按列出顺序运行,每个都读取之前的挂接所写入的标签,因此规则可以匹配较早的挂接设置的标签。examples/policy-label-transform/ 在一个 Rego 策略之后挂接这两个插件,并挂接一个读取三者写入内容的裁决。
governance/label-injector
标签注入器为每个标签与某条规则匹配的节点添加标签。
标签注入器的设置
| 设置 | 类型 | 默认值 | 作用 |
|---|---|---|---|
rules | 规则列表 | 无 | 应用于每个节点的规则;没有规则时,插件不写入任何内容 |
每条规则包含两个从标签键到字符串值的映射:
| 键 | 默认值 | 作用 |
|---|---|---|
match | 无键值对 | 当节点携带列出的每个键值对且各自取该值时即匹配;没有键值对的规则匹配所有节点 |
set | 无键值对 | 每个键值对都会写入规则匹配的每个节点 |
节点未携带的标签按空字符串比较,因此 match 中值为 "" 的键值对也会匹配未携带该键的节点。
规则按列出顺序应用于每个节点,后面的规则为同一个键写入的标签会替换前面规则写入的值。
规则的来源
当设置中至少包含一条规则时,插件从设置中读取 rules。设置中没有规则时,插件按文件名顺序读取 sources 下的文件,并采用第一个顶层 rules 列表至少包含一条规则的文件中的规则,形状相同:
rules: - match: {} set: ops.example.com/owner: shop-team之后任何文件中的规则都不会被读取。在它之前无法解析的文件会使构建停止。
挂接标签注入器及其写入的标签
此挂接为每个节点设置一个所有者,然后为 datastore 类别中的节点设置备份计划和另一个所有者:
plugins: governance: - uri: governance/label-injector:0.9.0 role: label-transform with: settings: rules: - match: {} set: ops.example.com/owner: shop-team - match: component.aggrega.ai/category: datastore set: backup.example.com/schedule: nightly ops.example.com/owner: data-team单独挂接到 examples/policy-label-transform/ 的 Aggregate 上时——db 是 core/datastore/mariadb,cache 是 core/datastore/redis,web 是 core/devtool/adminer——aggrega build --release release-production.yaml --auto-pull --ir-graph 会打印出一个构建图,其节点携带:
"db": { "labels": { "component.aggrega.ai/type": "stateful-server", "component.aggrega.ai/category": "datastore", "component.aggrega.ai/upstream-licensing": "osi-approved", "backup.example.com/schedule": "nightly", "ops.example.com/owner": "data-team" }, [… omitted: the node's Component, its version and the rest of the node]},"cache": { "labels": { "component.aggrega.ai/type": "server", "component.aggrega.ai/category": "datastore", "datastore.aggrega.ai/engine": "kv", "component.aggrega.ai/hosting": "mixed", "component.aggrega.ai/upstream-licensing": "mixed", "backup.example.com/schedule": "nightly", "ops.example.com/owner": "data-team" }, [… omitted: the node's Component, its version and the rest of the node]},"web": { "labels": { "component.aggrega.ai/type": "server", "component.aggrega.ai/category": "devtool", "component.aggrega.ai/upstream-licensing": "osi-approved", "ops.example.com/owner": "shop-team" }, [… omitted: the node's Component, its version and the rest of the node]}每个节点都匹配第一条规则并获得 shop-team;位于 datastore 类别中的 db 和 cache 还匹配了第二条规则,后者将其替换为 data-team。其他所有标签都是 Component 自身的标签。
governance/selector-tagger
选择器标记器在每个节点上写入一个 tag 标签,其值按节点的 Component 查得。
选择器标记器的映射与设置
它总是写入键 tag;该键不可配置。
映射来自 sources 下的文件。每个文件都是一个 YAML 映射,从 Component 名称映射到其节点获得的标记:
core/datastore/mariadb: orderscore/datastore/redis: sessions每个文件都会按文件名顺序读取,后面文件中的条目会替换前面文件中同一 Component 的条目。每个标记都是字符串:YAML 读作其他类型的值(例如 3)会使构建停止,因此请为它加引号——"3"。
| 设置 | 类型 | 默认值 | 作用 |
|---|---|---|---|
default | string | 空 | 映射未列出节点的 Component 时该节点获得的标记;为空时,这样的节点不带 tag |
没有 sources 时,每个节点都获得 default。
挂接选择器标记器及其写入的标签
此挂接根据上面的映射 tags.yaml 标记数据库和缓存,并将其他所有节点标记为 untagged:
plugins: governance: - uri: governance/selector-tagger:0.9.0 role: label-transform with: sources: - tags.yaml settings: default: untagged单独挂接到同一个 Aggregate 上时,aggrega build --release release-production.yaml --auto-pull --ir-graph 会打印出一个构建图,其节点携带:
"db": { "labels": { "component.aggrega.ai/type": "stateful-server", "component.aggrega.ai/category": "datastore", "component.aggrega.ai/upstream-licensing": "osi-approved", "tag": "orders" }, [… omitted: the node's Component, its version and the rest of the node]},"cache": { "labels": { "component.aggrega.ai/type": "server", "component.aggrega.ai/category": "datastore", "datastore.aggrega.ai/engine": "kv", "component.aggrega.ai/hosting": "mixed", "component.aggrega.ai/upstream-licensing": "mixed", "tag": "sessions" }, [… omitted: the node's Component, its version and the rest of the node]},"web": { "labels": { "component.aggrega.ai/type": "server", "component.aggrega.ai/category": "devtool", "component.aggrega.ai/upstream-licensing": "osi-approved", "tag": "untagged" }, [… omitted: the node's Component, its version and the rest of the node]}core/devtool/adminer 不在映射中,因此 web 获得了 default。如果没有 default 设置,web 不带 tag,另外两个节点的标记与上面相同。
编译器不做解释的地方
插件和编译器都不知道所有者、备份计划或标记意味着什么。标签的键和值是挂接提供的字符串;编译器把节点交给每个插件,应用插件报告的标签,并将它们携带在构建图中,由读取它们的策略赋予其含义。