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

内置的标记插件

编译进 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: orders
core/datastore/redis: sessions

每个文件都会按文件名顺序读取,后面文件中的条目会替换前面文件中同一 Component 的条目。每个标记都是字符串:YAML 读作其他类型的值(例如 3)会使构建停止,因此请为它加引号——"3"。

设置类型默认值作用
defaultstring空映射未列出节点的 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,另外两个节点的标记与上面相同。

编译器不做解释的地方

插件和编译器都不知道所有者、备份计划或标记意味着什么。标签的键和值是挂接提供的字符串;编译器把节点交给每个插件,应用插件报告的标签,并将它们携带在构建图中,由读取它们的策略赋予其含义。