コンテンツにスキップ
AggregaAggrega
言語の選択: 日本語
このページは機械翻訳されています。英語の原文を読む。

組み込みのタグ付けプラグイン

CLI に組み込まれた 2 つのガバナンスプラグインは、ポリシーを記述せずにビルドのノードへラベルを書き込みます。それぞれが何を読み、何を書くか、そしてそれぞれのアタッチ例と書き込まれたラベルを示します。

CLI には、ポリシー言語を書かずに設定だけでラベルを整える 2 つのガバナンスプラグインが含まれています。

Plugin書き込む内容
governance/label-injectorラベルがルールに一致するすべてのノードに、ルールのリストが設定するラベル
governance/selector-tagger1 つのラベル tag。その値は Component 名のマップによって各ノードに与えられます

どちらも他のガバナンスプラグインと同様に、ワークスペース設定の plugins.governance を通じてアタッチします(ポリシーのアタッチを参照)。どちらも組み込みプラグインの一覧に含まれています。このページのアタッチ例では 0.9.0 を指定しています。これは標準ライブラリカタログにある各プラグインの Plugin エンティティのバージョンです。ビルドでは CLI に組み込まれたプラグインが使われます。

2 つに共通すること

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 とは、core/datastore/mariadb のように、Aggregate の type: がノードに与える名前です。どちらのプラグインもノードの値、Release、その環境は読みません。どちらがノードに書き込む内容も、そのノードのラベルと Component だけで決まります。

書き込むのはラベルだけです。 どちらのプラグインが報告する変更も、ビルドの 1 つのノード上の 1 つのラベルを文字列の値とともに指定します。ノードが既に持っているラベルを書き込むと、その値が置き換えられます。Component 自身のラベルも例外ではありません。どちらもラベルを削除せず、値、ノードの Component やバージョン、ノードの集合を変更することもできません。ラベルを整えるロールはそのような変更を提供しないためです(ラベルの整形を参照)。

設定は実行前に検査されません。 どちらも settings のスキーマを宣言していないため、ビルドは設定を書かれたままプラグインに渡します。プラグインが読まないキーは無視されます。綴りを誤った rules は何も設定せず、ビルドは完了します。一方、プラグインが読むキーに別の型の値があると、プラグイン名、続いて decode settings: と理由を示すメッセージでビルドが停止します。

sources 配下のファイルを YAML として、ファイル名順に読みます。 アタッチでファイルをどの順で並べても、プラグインはファイル名順にソートされたファイルを受け取ります。有効な YAML でないファイルは、プラグイン名、続いて parse source "<file>": とパーサーの理由を示すメッセージでビルドを停止させます。内容がプラグインの読む形でないファイルは、decode source "<file>": と理由でビルドを停止させます。

ビルドが適用する入力はロックファイルが保持します。 Release のロックファイルを解決する pull(aggrega pull、または --auto-pull を付けたビルド)は、各アタッチの設定とその各ファイルの内容を記録し、ビルドは記録された内容を適用します。アタッチの設定やファイルを編集した後は、ロックファイルを解決し直してください。そうしないビルドは、記録済みの入力に基づくラベルを書き込み続けます。

with: ブロックなしでアタッチすると、どちらも何も書き込まず、ビルドは完了します。

label-transform に複数のアタッチがある場合は記述順に実行され、それぞれがそれより前のアタッチが書き込んだラベルを読みます。そのため、ルールは前のアタッチが設定したラベルに一致できます。examples/policy-label-transform/ は、Rego ポリシーの後に両方のプラグインをアタッチし、さらに 3 つすべてが書き込んだ内容を読む判定をアタッチしています。

governance/label-injector

ラベルインジェクターは、ラベルがルールに一致するすべてのノードにラベルを追加します。

ラベルインジェクターの設定

設定種類デフォルト効果
rulesルールのリストなしすべてのノードに適用されるルール。ルールがない場合、プラグインは何も書き込みません

各ルールは、ラベルキーから文字列値への 2 つのマップを持ちます。

キーデフォルト効果
matchペアなし列挙されたすべてのペアを、それぞれその値で持つノードが一致します。ペアのないルールはすべてのノードに一致します
setペアなしルールが一致した各ノードにすべてのペアが書き込まれます

ノードが持たないラベルは空文字列として比較されます。そのため、値が "" の match ペアは、そのキーを持たないノードにも一致します。

ルールは記述順に各ノードへ適用され、後のルールが書き込むラベルは、同じキーについて前のルールが書き込んだ値を置き換えます。

ルールの取得元

設定に少なくとも 1 つのルールがある場合、プラグインは設定から rules を読みます。ない場合は、sources 配下のファイルをファイル名順に読み、トップレベルの rules リストに少なくとも 1 つのルールを持つ最初のファイルのルールを、同じ形で採用します。

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 は 2 番目のルールにも一致し、それが値を data-team に置き換えました。その他のラベルはすべて Component 自身のものです。

governance/selector-tagger

セレクタータガーは各ノードに tag ラベルを書き込みます。その値はノードの Component によって検索されます。

セレクタータガーのマップと設定

常にキー tag を書き込みます。キーは設定できません。

マップは sources 配下のファイルから取得されます。各ファイルは、Component 名からそのノードが受け取るタグへの YAML マップです。

core/datastore/mariadb: orders
core/datastore/redis: sessions

すべてのファイルがファイル名順に読まれ、後のファイルのエントリは、前のファイルにある同じ Component のエントリを置き換えます。各タグは文字列です。3 のように YAML が別の型として読む値はビルドを停止させるため、"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 を持たず、他の 2 つは上記のとおりタグ付けされます。

コンパイラが解釈しない箇所

プラグインもコンパイラも、オーナー、バックアップスケジュール、タグが何を意味するかを知りません。ラベルのキーと値はアタッチが与える文字列です。コンパイラは各プラグインにノードを渡し、報告されたラベルを適用して、ビルドグラフの中に保持します。それらを読むポリシーが、その意味を与えます。