組み込みのタグ付けプラグイン
CLI に組み込まれた 2 つのガバナンスプラグインは、ポリシーを記述せずにビルドのノードへラベルを書き込みます。それぞれが何を読み、何を書くか、そしてそれぞれのアタッチ例と書き込まれたラベルを示します。
CLI には、ポリシー言語を書かずに設定だけでラベルを整える 2 つのガバナンスプラグインが含まれています。
| Plugin | 書き込む内容 |
|---|---|
governance/label-injector | ラベルがルールに一致するすべてのノードに、ルールのリストが設定するラベル |
governance/selector-tagger | 1 つのラベル 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 sandboxrender-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-teamexamples/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: orderscore/datastore/redis: sessionsすべてのファイルがファイル名順に読まれ、後のファイルのエントリは、前のファイルにある同じ Component のエントリを置き換えます。各タグは文字列です。3 のように YAML が別の型として読む値はビルドを停止させるため、"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 を持たず、他の 2 つは上記のとおりタグ付けされます。
コンパイラが解釈しない箇所
プラグインもコンパイラも、オーナー、バックアップスケジュール、タグが何を意味するかを知りません。ラベルのキーと値はアタッチが与える文字列です。コンパイラは各プラグインにノードを渡し、報告されたラベルを適用して、ビルドグラフの中に保持します。それらを読むポリシーが、その意味を与えます。