独自のガバナンスプラグインを書く
このページでは、プラグイン開発キットのアダプタースケルトンから始めて、ビルドを拒否するガバナンスプラグインまでを順に説明します。スケルトンをコピーし、ルールを 1 つ書き、.wasm をビルドし、スケルトン付属のペイロードファイルで各エクスポートを手動で呼び出し、ワークスペース自身のカタログで Plugin エンティティとして宣言し、ロールにアタッチして、ルールに違反するビルドが止まるのを確認します。
このページは、4 つのロール、各ロールが運ぶペイロード、ホストが対応する判定を説明するガバナンスソケットと、Plugin エンティティとそのライフサイクルを説明するプラグイン開発者ガイドの実践編です。プロバイダーの作成は、プロバイダーのゲストについての同様のウォークスルーです。
このページのブロックについて。 出力を示すブロックはすべて、以下の手順を記載順に実際に実行した結果からコピーしたもので、出力の慣例に従っています。ブロックは完全なものか、省略した行の位置を示した抜粋のどちらかです。マシンごとに異なる絶対パスを 2 つのプレースホルダーで表します。<guest> はスケルトンのコピーのディレクトリ、<workspace> はプラグインをアタッチするワークスペースのディレクトリです。
必要なもの
- Go ツールチェーン。追加のツールなしで WebAssembly にコンパイルできます。
- スケルトンを含むプラグイン開発キットと、キットが基盤とする ABI パッケージのチェックアウト。コピーの
go.modはその両方を参照します。 aggregaバイナリ。
キットには Rust 用の同じスケルトンが rust/examples/governance-adapter-skeleton に、TypeScript 用が typescript/examples/governance-adapter-skeleton にあります。それぞれ同じ 4 つのペイロードファイルを持ち、未変更のコピーはどれもそれらに同じように応答します。このページの aggrega コマンドは、それぞれのアーティファクト名を使えばどちらにも適用でき、ビルド方法は各 README に記載されています。
完成形の構成
ガバナンスプラグインは、他のプラグインと同様に 2 つのアーティファクトから成ります。.wasm ゲストと、それをカタログに取り込む Plugin エンティティです。アタッチはワークスペース設定の 1 エントリだけです。コンパイラ側は何も変わりません。
このウォークスルーの最後にできる 2 つのディレクトリ(ビルドがワークスペースに書き込むものを除く):
category-guard/ your copy of the skeleton: the Go module that compiles to the .wasm .gitignore README.md the skeleton's own guide go.mod go.sum main.go the describe() self-report and the shared plumbing evaluator.go the seam, where the rule goes annotations.go the annotation-transform role labels.go the label-transform role verdicts.go the ir-verdict and render-verdict roles build.sh annotation-payload.json label-payload.json ir-verdict-payload.json render-verdict-payload.json my-payload.json a copy you edit in section 4 wrong-payload.json a copy you break in section 5 overlay.yaml the identity you supply to the entity generator dist/governance-adapter-skeleton-go.wasm the compiled guestshop/ the workspace the plugin is attached in catalog/component/example/compute/api/1.0.0/component.yaml catalog/component/example/devtool/db-console/1.0.0/component.yaml catalog/recipe/compose/api/1.0.0/recipe.yaml catalog/recipe/compose/db-console/1.0.0/recipe.yaml catalog/plugin/governance/category-guard/0.1.0/plugin.yaml catalog/plugin/governance/category-guard/0.1.0/governance--category-guard.wasm aggregate.yaml manifest.yaml release.yaml .aggrega-config.yamlプラグインが適用するルールはよくあるものです。ワークスペースが出荷しないコンポーネントのカテゴリ(ここでは管理コンソールのカテゴリである devtool)を指定し、そのカテゴリのコンポーネントを含むビルドは、そのコンポーネントを示して停止します。
1. スケルトンをコピーする
cp -r /path/to/aggrega-pdk/go/examples/governance-adapter-skeleton category-guardcd category-guardスケルトンの go.mod は、キット内での配置からの相対パスでキットと ABI パッケージを参照しているため、キットの外にあるコピーではそれらを自分で指定します。モジュールに独自のパスを付け、2 行の replace をチェックアウトに向けてください。
module example.com/category-guard
go 1.26.0
require ( github.com/aggrega-ai/aggrega-abi/go v0.0.0 github.com/aggrega-ai/aggrega-pdk/go v0.0.0 github.com/extism/go-pdk v1.1.3)
replace github.com/aggrega-ai/aggrega-pdk/go => /path/to/aggrega-pdk/go
replace github.com/aggrega-ai/aggrega-abi/go => /path/to/aggrega-abi/goスケルトンの go.sum はそのままにします。
2. ビルドし、各ロールを手動で呼び出す
何も変更する前にコピーをビルドし、最初に実行するのが自分で書いていない配線部分になるようにします。
./build.shWrote <guest>/dist/governance-adapter-skeleton-go.wasmaggrega plugin run-local はパスからゲストを読み込み、指定したエクスポートがゲストの describe() の自己報告で宣言されていること、また --type governance を指定した場合はゲストが自身をガバナンスプラグインとして報告していることを確認したうえで、指定したペイロードで呼び出し、その応答を出力します。スケルトンにはロールごとに 1 つのペイロードファイルが付属し、それぞれがエクスポートに対する小さく有効な入力です。ペイロードは JSON で記述します。どのガバナンスロールのワイヤもバイナリエンコーディングを使うため、コマンドはエクスポートを呼び出す前にペイロードをそれに変換し、エクスポートの応答を JSON で出力します。
aggrega plugin run-local --plugin dist/governance-adapter-skeleton-go.wasm \ --type governance --export transform_annotations --with @annotation-payload.json{ "injections": []}run-local は指定されたパスからゲストとペイロードを読み、ワークスペースを必要としないため、どのディレクトリからでも実行できます。
aggrega plugin run-local --plugin dist/governance-adapter-skeleton-go.wasm \ --type governance --export mutate --with @label-payload.json{ "patches": []}aggrega plugin run-local --plugin dist/governance-adapter-skeleton-go.wasm \ --type governance --export verdict_ir --with @ir-verdict-payload.json{ "results": [ { "severity": "info", "message": "this adapter has no policy engine yet: the seam received rules.policy (43 bytes) and some settings" } ]}aggrega plugin run-local --plugin dist/governance-adapter-skeleton-go.wasm \ --type governance --export verdict_render --with @render-verdict-payload.json{ "results": [ { "severity": "info", "message": "this adapter has no policy engine yet: the seam received rules.policy (43 bytes) and some settings" } ]}各応答は、そのロールが返すことを許された形です。追加する注釈、ラベルの変更、判定です。2 つの変換ロールは何も返さず、各判定ロールは info 判定を 1 つ返します。これは観察を記録し、ビルドの結果を変えない注記です。この注記が、スケルトンの配線が正しいことの証明です。各ペイロードファイルは、ビルドが渡すのと同じ形でアタッチの 2 つの入力を持っています。sources 配下の 1 つのポリシーファイル rules.policy と、settings オブジェクトです。注記は、その両方がシーム、つまりスケルトンの他の部分がロールの受け取った内容で呼び出す 1 つの関数に届いたことを示しています。
以下のルールが読むペイロード ir-verdict-payload.json の全体は次のとおりです。
{ "graph": { "apiVersion": "aggrega.ai/v1beta1", "kind": "IR", "metadata": { "aggregate_name": "shop" }, "spec": { "nodes": { "api": { "component": "example/compute/api", "resolved_version": "1.0.0", "labels": { "component.aggrega.ai/type": "server", "component.aggrega.ai/category": "compute" } } }, "edges": [], "values_mapping": {}, "infra_mapping": {}, "feature_values_mapping": {}, "provenance": { "schema_version": "aggrega.ai/v1beta1", "compiler_version": "0.0.0", "aggregate_version": "1.0.0", "manifest_version": "1.0.0", "release_version": "1.0.0" } } }, "precalculated_paths": [], "sources": [ { "path": "rules.policy", "content": "policy text, handed to the engine verbatim\n" } ], "settings": { "max_nodes": 50 }}これは ir-verdict ロールの入力です。1 つのコンポーネントを含むビルドグラフ、グラフ上で列挙されたルーティングパス、そしてアタッチの sources と settings から成ります。各フィールドはロールのリファレンスページであるポリシーソケットのスキーマで、グラフそのものはビルドグラフのスキーマで説明しています。他の 3 つのファイルは、annotation-transform のスキーマ、mutator のスキーマ、そして verdict_render についてはポリシーソケットのスキーマの RenderPolicyInput に従います。
3. ルールを 1 つ書く
ルールはスケルトンのシームである evaluator.go に置きます。各ロールはペイロードをデコードして JSON ドキュメントとして書き出し、アタッチのポリシーファイル、その設定、そのドキュメント、返してほしい決定の名前を渡して Evaluate を呼び出します。判定ロールは 3 つの決定(deny、warn、audit)を順に求め、それぞれの応答を重大度 halt、warn、info で報告します。2 つの変換ロールは annotations と labels を求めます。したがって、ビルドを止めるルールは deny に応答します。
evaluator.go を次の内容に置き換えます。
package main
import ( "encoding/json" "fmt" "slices" "sort")
// Program is one policy program the attachment carried.type Program struct { Path string Text string}
// categoryLabel is the label a catalog Component states its category in.const categoryLabel = "component.aggrega.ai/category"
// Evaluate refuses every component whose category the attachment's settings// list under forbidden_categories.func Evaluate(programs []Program, settings json.RawMessage, payload json.RawMessage, decision string) ([]json.RawMessage, error) { if decision != denyDecision { return nil, nil }
var config struct { ForbiddenCategories []string `json:"forbidden_categories"` } if len(settings) > 0 { if err := json.Unmarshal(settings, &config); err != nil { return nil, fmt.Errorf("reading the settings: %w", err) } }
var input struct { Graph struct { Spec struct { Nodes map[string]struct { Labels map[string]string `json:"labels"` } `json:"nodes"` } `json:"spec"` } `json:"graph"` } if err := json.Unmarshal(payload, &input); err != nil { return nil, fmt.Errorf("reading the build graph: %w", err) }
// A Go map has no order, so the node ids are sorted: identical input must // yield an identical sequence of decisions. ids := make([]string, 0, len(input.Graph.Spec.Nodes)) for id := range input.Graph.Spec.Nodes { ids = append(ids, id) } sort.Strings(ids)
var decisions []json.RawMessage for _, id := range ids { category := input.Graph.Spec.Nodes[id].Labels[categoryLabel] if !slices.Contains(config.ForbiddenCategories, category) { continue } message, err := json.Marshal(fmt.Sprintf( "component %q is a %s component, and this workspace ships none", id, category)) if err != nil { return nil, err } decisions = append(decisions, message) } return decisions, nil}Program は残します。ロールファイルがそれを使ってプログラムのリストを作るためです。残りがルールで、その中の 4 点は注意して読む価値があります。
- ワイヤが与える名前でペイロードを読みます。 ノードは
graph.spec.nodesにあり、ノード ID をキーとし、それぞれがlabelsを持ちます。これは各ロールのペイロードが公開するものが Rego ポリシーにinput.graph.spec.nodesとして与えるのと同じパスです。このロール用に書いたルールは、他のロールでは何も読みません。render-verdictのペイロードはグラフを持たないため、そこではループがノードを見つけません。 - 何を禁止するかはプラグインではなくオペレーターが決めます。 カテゴリはアタッチの
settingsから来るため、同じ.wasmがdevtoolを禁止するワークスペースにも、何も禁止しないワークスペースにも使えます。 - 応答する前にソートします。 ビルドの出力は同一入力の実行間でバイト単位で同一であり、Go のマップの順序で応答するゲストは内部からそれを壊してしまいます。
- 失敗ははっきり示します。 読めない設定やペイロードは空のリストではなくエラーを返し、ロールはそのエラーを失敗した呼び出しに変えます。空のリストは、ポリシーが述べることを何も見つけなかったという意味です。失敗した呼び出しは、ポリシーが実行されなかったという意味です。ゲストが両者を区別する場合にのみ、ビルドも区別できます。
ルールは programs を読みません。このプラグインのルールはゲストにコンパイルされているため、アタッチは設定を与え、ポリシーファイルは与えません。これはプリコンパイル済みエンジンを中心に作られたゲストと同じ形で、ルールを sources から読み込むゲストとは逆です。
最後に、プラグインが何であるかを記述します。main.go で、descriptor() の説明を変更します。
Description: "Refuse a build that carries a component of a category the attachment forbids.",セクション 6 のエンティティジェネレーターが、これを Plugin エンティティにコピーします。
4. 再度ビルドし、ルールの応答を読む
./build.shWrote <guest>/dist/governance-adapter-skeleton-go.wasm同じファイルで 4 つのエクスポートを再度呼び出します。
aggrega plugin run-local --plugin dist/governance-adapter-skeleton-go.wasm \ --type governance --export transform_annotations --with @annotation-payload.jsonaggrega plugin run-local --plugin dist/governance-adapter-skeleton-go.wasm \ --type governance --export mutate --with @label-payload.jsonaggrega plugin run-local --plugin dist/governance-adapter-skeleton-go.wasm \ --type governance --export verdict_ir --with @ir-verdict-payload.jsonaggrega plugin run-local --plugin dist/governance-adapter-skeleton-go.wasm \ --type governance --export verdict_render --with @render-verdict-payload.json{ "injections": []}{ "patches": []}{ "results": []}{ "results": []}両方の判定ロールからプレースホルダーの注記が消え、どちらも判定を返しません。付属のペイロードの settings はどのカテゴリも禁止していないため、ルールは許可します。空の results リストは、判定ロールがビルドの続行を許すことを示す方法です。
ルールが発動するのを見るには、ペイロードが含むものを禁止する設定を与えます。ir-verdict-payload.json を my-payload.json にコピーし、その settings を次の内容に置き換えます。
"settings": { "forbidden_categories": [ "compute" ] }aggrega plugin run-local --plugin dist/governance-adapter-skeleton-go.wasm \ --type governance --export verdict_ir --with @my-payload.json{ "results": [ { "severity": "halt", "message": "component \"api\" is a compute component, and this workspace ships none" } ]}deny の決定は、ルール自身のメッセージを持つ halt 判定として届きます。ビルドでは、halt はそのメッセージを理由としてビルドを停止します。
5. ペイロードが合わない場合
コマンドは、ペイロードが持つ各フィールドをその形が宣言する型に変換し、変換できないフィールドはゲストの実行前に拒否します。wrong-payload.json という名前のコピーで、ノードの labels をオブジェクトではなくリストとして書いてみます。
"labels": [ "server", "compute" ]aggrega plugin run-local --plugin dist/governance-adapter-skeleton-go.wasm \ --type governance --export verdict_ir --with @wrong-payload.jsonunder key "api": expected JSON object, found [コマンドは 0 以外で終了し、ゲストは呼び出されません。
変換は、ペイロードが持つすべてのフィールドの型を確認しますが、形が必要とするすべてのフィールドをペイロードが持っているかは確認しません。フィールドが欠けたペイロードもそのまま変換されてゲストに渡され、そのフィールドを読むルールを持つゲストはそこで何も見つけません。そのため、手書きしたペイロードはスキーマのリファレンスページと照らし合わせて確認してください。コマンドが何も言わないことは、ペイロードが完全であることを意味しません。
6. ワークスペースのカタログで Plugin エンティティとして宣言する
エンティティの契約フィールドは手書きではなくゲストから読み出されるため、エンティティがバイナリにないエクスポートを主張することはできません。識別情報は小さなオーバーレイ overlay.yaml で与えます。
apiVersion: aggrega.ai/v1beta1kind: Pluginmetadata: name: category-guardaggrega plugin gen-catalog --plugin dist/governance-adapter-skeleton-go.wasm \ --overlay overlay.yaml --output-dir ../shop/catalog/plugingenerated ../shop/catalog/plugin/governance/category-guard/0.1.0/plugin.yaml生成されたエンティティ:
# Generated from the plugin by `aggrega plugin gen-catalog`. You may narrow its capability lists; edit nothing else here.apiVersion: aggrega.ai/v1beta1kind: Pluginmetadata: name: category-guard version: 0.1.0 pluginType: governance description: Refuse a build that carries a component of a category the attachment forbids.spec: abiVersion: v1beta1 exports: - name: transform_annotations - name: mutate - name: verdict_ir - name: verdict_renderversion はスケルトンの build.sh がゲストに埋め込むバージョンで、AGGREGA_PLUGIN_VERSION が別のものを指定しない限り 0.1.0 です。pluginType と 4 つのエクスポートは describe() が報告するものです。ガバナンスプラグインは機能を宣言しません。何を返せるかは、エンティティではなく、アタッチされたロールによって決まります。
プラグインの開発中は取得できる公開物がないため、ビルドはカタログディレクトリからプラグインを読みます。.wasm はエンティティの隣に置きます。エンティティの隣のファイルは、エンティティのドキュメントがあるディレクトリ内で、エンティティのプラグインタイプと名前から名付けられます。governance/category-guard の場合は governance--category-guard.wasm です。
cp dist/governance-adapter-skeleton-go.wasm \ ../shop/catalog/plugin/governance/category-guard/0.1.0/governance--category-guard.wasmファイルはリンクせずにコピーしてください。その位置のリンクは、ワークスペース内のどこか(ワークスペースの外にあるカタログディレクトリの場合は、そのディレクトリ内のどこか)を指す場合にのみたどられます。それより外を指すリンクは、ワークスペース境界で説明するとおり、リンクを示してビルドと pull を停止させます。その名前で .wasm が見つからない pull は、A plugin’s .wasm is not on this machine (プラグインのファイルがこのマシン上にありません) で説明するとおり、期待したファイルを示して停止します。
7. プラグインが守るワークスペース
ワークスペースは小さなショップです。API と、それを Docker Compose でビルドするドキュメントから成ります。カタログには、ルールが拒否する管理コンソール、つまりカテゴリが devtool である Component も含まれています。
catalog/component/example/compute/api/1.0.0/component.yaml:
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: example/compute/api version: 1.0.0 description: The shop's HTTP API. labels: component.aggrega.ai/type: server component.aggrega.ai/category: computespec: schema: infra: port: type: integer default: 8080 description: The port the API listens on.catalog/component/example/devtool/db-console/1.0.0/component.yaml:
apiVersion: aggrega.ai/v1beta1kind: Componentmetadata: name: example/devtool/db-console version: 1.0.0 description: A database administration console in the browser. labels: component.aggrega.ai/type: server component.aggrega.ai/category: devtoolspec: schema: infra: port: type: integer default: 8081 description: The port the console listens on.catalog/recipe/compose/api/1.0.0/recipe.yaml:
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: api version: 1.0.0 description: Runs the API as a Docker Compose service.spec: capability: compose implements: example/compute/api:1.0.0 workload: | apiVersion: aggrega.ai/v1beta1 kind: Workload containers: main: image: "registry.example.com/shop/api:1.0.0" ports: http: {{ .infra.port }}catalog/recipe/compose/db-console/1.0.0/recipe.yaml:
apiVersion: aggrega.ai/v1beta1kind: Recipemetadata: name: db-console version: 1.0.0 description: Runs the database console as a Docker Compose service.spec: capability: compose implements: example/devtool/db-console:1.0.0 workload: | apiVersion: aggrega.ai/v1beta1 kind: Workload containers: main: image: "adminer:4" ports: http: {{ .infra.port }}aggregate.yaml:
apiVersion: aggrega.ai/v1beta1kind: Aggregatemetadata: name: shop version: "1.0.0" description: The shop's API.spec: components: api: type: example/compute/apimanifest.yaml:
apiVersion: aggrega.ai/v1beta1kind: Manifestmetadata: name: shop-manifest version: "1.0.0" description: Binds each component type to its Docker Compose recipe.spec: mappings: components: type: example/compute/api:1.0.0: api:1.0.0 example/devtool/db-console:1.0.0: db-console:1.0.0release.yaml:
apiVersion: aggrega.ai/v1beta1kind: Releasemetadata: name: shop-staging environment: staging version: "1.0.0"spec: aggregate: shop manifest: shop-manifest components: api: {}8. アタッチしてビルドする
オペレーターは、ロールとアタッチの設定を指定して、ワークスペース設定でガバナンスプラグインをアタッチします。.aggrega-config.yaml:
workspace: catalog_dirs: - catalogauto_pull: trueplugins: governance: - uri: governance/category-guard:0.1.0 role: ir-verdict with: settings: forbidden_categories: - devtooluri は、プラグインタイプ、名前、バージョンでエンティティを指定します。ロールは ir-verdict なので、ホストはグラフが構築された後、何かがレンダリングされる前に、ビルドグラフを渡して verdict_ir を呼び出します。auto_pull によりビルドが Release を自分で解決するため、最初のビルドに別の手順は必要ありません。
cd ../shopaggrega build --release release.yaml warning: plugin "governance/category-guard" resolved from local with no recorded digest to check it against, so it runs unverified; it is read from beside its Plugin entity in a catalog directory on every build, and a pull records its digest only for a plugin attached at a transform role; otherwise publish the plugin and reference the published entity to have its digest recordedPull complete: release.lock (entities=7, source_artifacts=0, external_inputs=0)[… omitted: a line reporting total build time, which differs on every run]Build completed: 1 file written to <workspace>/distショップには devtool コンポーネントがないため、ルールはビルドを許可し、Compose の出力は dist/compose/docker-compose.yaml に置かれます。
この警告は想定どおりで、プラグインがローカルである間は出続けます。 これは、照合すべき記録済みのコンテンツダイジェストなしでゲストが実行されたことを示します。1 分前にビルドされ、ビルドのたびにエンティティの隣から読まれるゲストにとっては事実そのものです。判定ロールにアタッチされたプラグインは出力を形作らないため、pull はカタログディレクトリからそのダイジェストを記録しません。ダイジェストを記録するには、プラグインを公開し、公開されたエンティティを参照します。
9. 違反を仕込む
管理コンソールを Aggregate に追加し、Release に配置します。
spec: components: api: type: example/compute/api console: type: example/devtool/db-console components: api: {} console: {}aggrega build --release release.yaml[… omitted: the unverified-plugin warning, and the pull's lines saying the Release could not be rendered to discover its external inputs, which carry the refusal below][POLICY_ERROR E0005] policy plugin "category-guard" rejected the build: component "console" is a devtool component, and this workspace ships none caused by: policy violationビルドは何もレンダリングする前に停止し、dist/ を書き込みません。メッセージはルール自身の文で、先頭にプラグイン名が付くため、読んだ作成者はどのコンポーネントを取り除くべきか、どのポリシーがそれを求めたかがわかります。プラグインはコンソールを削除したり、名前を変えたり、コンソール抜きでビルドをレンダリングしたりはしていません。判定ロールは受け入れるか拒否するかだけで、ホストがその応答を変更として適用することはありません。
次に変更できること
- ルールを増やす、またはポリシー言語を使う。 Go で書いたルールはゲストにコンパイルされます。代わりにファイルからルールを読み込むには、
Evaluateでprograms(アタッチのsources。それぞれがベース名とテキストを持ちます)を読み、エンジンに渡します。ABI は Aggrega 独自のもので、外部のポリシーエンジンをラップするゲストを説明しています。 - 他のロール。 同じ
Evaluateがすべてのロールを担います。annotationsまたはlabelsに応答すると、プラグインは変換ロールでビルドを形作ります。決定の形はスケルトンの README に、各ロールが何を変更できるかは4 つのロールにあります。 - エクスポートを減らす。
ir-verdictだけを担うプラグインは、他のロールファイルとdescriptor()内のそのエントリを削除します。そうすると、ゲストが宣言していないエクスポートにロールを向けるアタッチは、ゲストの実行前に名前を示して拒否されます。 - 型付き設定。 ゲストは
describe()で設定の JSON Schema を宣言でき、その場合ホストはゲストの実行前にアタッチの設定をそれに照らして検証します。型付き設定を参照してください。 - 公開。カタログディレクトリでの構成を、Release が解決・検証するダイジェスト固定のアーティファクトに変えます。そのライフサイクルはプラグイン開発者ガイドで扱います。
関連リファレンス
- ガバナンスソケット — 4 つのロール、そのペイロード、判定の重大度、オペレーターがプラグインをアタッチする方法。
- Plugin コントラクト — 各ソケットの入力と出力の形と、それぞれが運ぶエンコーディング。
- Wasm プラグイン開発者ガイド —
Pluginエンティティ、機能の範囲、公開のライフサイクル。 - プロバイダーの作成 — プロバイダーのゲストについての同様のウォークスルー。
- これらのページの出力の読み方 — 上記の 出力ブロックが従う慣例。