ラベルを形作るポリシー: 環境ごとのサポートティアと、それを読み取る判定
ガバナンスプラグインは、このワークスペースがデプロイするすべてのコンポーネントに、所有者、その環境が得るサポートティア、バックアップスケジュール、短いタグのラベルを付けるため、開発者がそれらを入力する必要はありません。ラベルはビルド中に、4 つのガバナンスアタッチメントによって導出されます。
- 3 つは
label-transformロールにあり、ビルドのノード上のラベルを形作ります。Release の環境を読み取る Rego ポリシーと、CLI に組み込まれた 2 つのタグ付けプラグインlabel-injectorとselector-taggerです。 - 1 つは
ir-verdictロールにあり、ビルドグラフに対する Rego ポリシーで、サポートティアのないノードが残った本番ビルドを停止させます。
1 つの Aggregate の 2 つの Releases は環境が staging と production で異なり、それぞれのノードは異なるラベルを持つことになります。3 つ目のビルドは、ポリシーの対象カテゴリーが 1 つ少ないこのワークスペースのコピーから check.sh が行うもので、停止して取りこぼしたノードを名指しします。
構築されるもの
| インスタンス | カタログの Component | ここでの役割 |
|---|---|---|
db | core/datastore/mariadb | ショップのデータベース |
cache | core/datastore/redis | そのセッションキャッシュ |
web | core/devtool/adminer | db に接続されたデータベース管理 UI |
3 つともすべて Docker Compose にコンパイルされ、dist/compose/docker-compose.yaml に出力されます。Aggregate も両方の Releases も独自のラベルを指定していません。以下のラベルはすべてアタッチメントが書いたものです。
4 つのアタッチメント
これらはこのワークスペースの .aggrega-config.yaml の plugins.governance の下でアタッチされるため、ここで実行するすべてのビルドに適用されます。
| プラグイン | ロール | 書き込む内容 | |
|---|---|---|---|
| 1 | governance/rego:0.9.0、policies/support-tier.rego を使用 | label-transform | すべてのノードに ops.example.com/environment。設定にカテゴリーが列挙されているすべてのノードに ops.example.com/support-tier |
| 2 | governance/label-injector:0.9.0 | label-transform | すべてのノードに ops.example.com/owner。datastore カテゴリーのすべてのノードに backup.example.com/schedule |
| 3 | governance/selector-tagger:0.9.0 | label-transform | tag。policies/tags.yaml のマップから |
| 4 | governance/rego:0.9.0、policies/production-support.rego を使用 | ir-verdict | なし。ビルドを停止させるか、完了させます |
0.9.0 は標準ライブラリのカタログにある 3 つの Plugin エンティティのバージョンです。プラグイン自体は CLI に組み込まれており、ビルドはそこからそれらを提供します。aggrega build --release release-production.yaml --auto-pull --detail は、3 つそれぞれについてその両方を一覧表示します。
[… omitted: the line counting what the pull resolved, and the rows for the Components, the Recipes, the Feature and the FeatureRecipes, each read from the registry] in-binary Plugin governance/label-injector ← governance/label-injector:0.9.0 in-binary Plugin governance/label-injector:0.9.0 ← .aggrega-config.yaml.plugins.governance in-binary Plugin governance/rego ← governance/rego:0.9.0 in-binary Plugin governance/rego:0.9.0 ← .aggrega-config.yaml.plugins.governance in-binary Plugin governance/selector-tagger ← governance/selector-tagger:0.9.0 in-binary Plugin governance/selector-tagger:0.9.0 ← .aggrega-config.yaml.plugins.governance[… omitted: the rows for this workspace's Aggregate and Manifest, the pull's summary, a lint notice about core/secret-value, and the build's summary]1 つのロールのアタッチメントは列挙された順に実行され、それぞれが前のアタッチメントが書いたラベルを読み取ります。ラベルインジェクターは Rego ポリシーが書いた 2 つのラベルを受け取り、セレクタータガーはそれらとラベルインジェクターが書いたラベルを受け取ります。判定は 3 つすべての後に、それらが残したグラフに対して実行されます。
label-transform ポリシーが読み取るもの
label-transform のポリシーは、input.graph.nodes にあるノードを読み取ります。ノードはノード ID をキーとし、それぞれ次のものを持ちます。
component— ノードがインスタンス化する Component(例:core/datastore/mariadb)。resolved_version— その Component が解決されたバージョン。labels— ポリシーの実行時にノードが持つラベル。Component 自身のラベルと、それ以前のトランスフォームが書いたラベルです。values— ノードのインスタンスが Aggregate で宣言する値。宣言がなければ存在しません。ここではdbだけがdatabase: appdbという値を 1 つ宣言しています。
Release は input.compilation_context で読み取ります。release_name と environment です。これにより、1 つのポリシーが環境ごとに異なる決定を下せます。
一方、ir-verdict のポリシーはビルドグラフ全体を読み取り、そのノードは 1 階層深い input.graph.spec.nodes にあります。あるロールから別のロールに移したルールは、コピーするのではなく編集します。パスが間違っていると何も読み取れず、決して発火しません。ir-verdict のペイロードには compilation_context がないため、判定は Release から環境を読み取れません。そのため、ここでの最初のポリシーはすべてのノードに ops.example.com/environment も書き込みます。判定はそのラベルから環境を読み取ります。
ペイロードについて読むのではなく実際に見るには、ロックファイルができるよう一度ビルドしてから、次を実行します。
aggrega build --release release-production.yaml --dry-run --policy-input payloadsこれは各アタッチメントが受け取るペイロードを payloads/ に書き出します。1 つのロールで複数のアタッチメントが異なるペイロードを受け取る場合はアタッチメントごとに 1 ファイル(label-transform.1.rego.json、label-transform.2.label-injector.json、label-transform.3.selector-tagger.json)、それ以外のロールはそれぞれ 1 ファイルとし、それ以外は何も書き出しません。
Rego ポリシー
policies/support-tier.rego は、ラベルごとに 1 つの決定を labels の下に集め、ノード、ラベルキー、値を示します。
env := input.compilation_context.environment
labels contains {"node": id, "key": "ops.example.com/environment", "value": env} if { some id, _ in input.graph.nodes}
labels contains {"node": id, "key": "ops.example.com/support-tier", "value": data.support_tiers[env]} if { some id, node in input.graph.nodes node.labels["component.aggrega.ai/category"] in data.supported_categories}その設定はポリシーの data ドキュメントであり、組織の語彙を保持します。
settings: # The categories whose components get a support tier. supported_categories: [datastore, devtool] # The tier each environment gives them. support_tiers: production: on-call staging: office-hours各組み込みプラグインが書き込むもの
label-injector はルールのリストを適用します。ラベルにルールの match の下のすべてのペアを含むノードは、その set の下のすべてのペアを受け取ります。ペアは追加されるか、ノードがすでに持つラベルの値を置き換えます。ペアのない match はすべてのノードに一致します。ルールは、ここでのように rules 設定から読み取るか、設定にルールがない場合は sources の下でルールを持つ最初のファイルから読み取ります。ここでの 2 つのルールは、すべてのノードに ops.example.com/owner: shop-team を与え、datastore カテゴリーの 2 つのノードである db と cache に backup.example.com/schedule: nightly を与えます。web は devtool カテゴリーにあり、バックアップスケジュールは付きません。
selector-tagger は常に tag というキーで 1 つのラベルを書きます。その値は、sources の下のファイルから読み取る、Component 名からタグへのマップから得られます。Component がマップに列挙されていないノードは default 設定を取り、default がなければ tag なしのままになります。policies/tags.yaml はデータベースとキャッシュをマップしています。
core/datastore/mariadb: orderscore/datastore/redis: sessionsそしてアタッチメントの default は untagged なので、web には untagged のタグが付きます。
どちらもノードのラベルとその Component だけから判断します。どちらも環境を読み取らないため、両方の Releases で同じラベルを書きます。
どちらも label-transform にのみ対応します。ir-verdict にアタッチすると、どちらも実行前に拒否されます。そこにアタッチした selector-tagger は、次のメッセージでビルドを停止させます。
[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サンプルを生成する
このサンプルは以下のコマンドでビルドできます。または、AI アシスタントにビルドを任せることもできます。
例の名前を付けた新しいフォルダーに例を書き出します。
aggrega scaffold --example policy-label-transformその後、次に実行するコマンドを表示します。最初のコマンドは新しいフォルダーに移動します。
cd policy-label-transformビルド
aggrega build --release release-staging.yaml --auto-pullaggrega build --release release-production.yaml --auto-pull標準ライブラリのカタログが、ここにあるすべての Component、Recipe、Feature と、3 つの Plugin エンティティを提供します。 これらは、.aggrega-config.yaml が指定するデフォルトのレジストリである hub.aggrega.ai から解決されます。--catalog でカタログのチェックアウト(入手方法)を指定すると、レジストリからは何も取得しないため、ビルドはオフラインで動作します。--auto-pull はビルド中に各 Release のロックファイルを埋めます。ロックファイルとレンダリング結果は生成されるものであり、同梱はされません。
AI アシスタントを使う
Aggrega のツールでセットアップした AI アシスタントでも同じことができます。次のプロンプトを貼り付けてください。
Aggrega のツールのみを使用し、フォルダーは自分で作成しないでください。Workspace フォルダーにまだ `policy-label-transform` フォルダーがない場合は、`example` を `policy-label-transform` に設定し、`dir` を指定せずに `scaffold` ツールを 1 回呼び出してください。これにより、新しい `policy-label-transform` フォルダーに例が書き込まれます。次に、各 Release について 1 回ずつ、`release-staging.yaml`、`release-production.yaml` の順に `build` ツールを呼び出してください。毎回、`workspace_root` を `policy-label-transform`、`release` をそのファイル、`auto_pull` を true、`write` を true に設定します。各ビルドが書き込んだファイルを教えてください。それらは `policy-label-transform/dist/` の下にあります。各ノードが最終的に持つラベル
--ir-graph はビルドグラフを標準出力に、ビルドのサマリーより前に出力します。グラフには、トランスフォームが残したとおりの各ノードのラベルが含まれます。aggrega build --release release-production.yaml --auto-pull --ir-graph の後、web は次のようになります。
"web": { "labels": { "component.aggrega.ai/type": "server", "component.aggrega.ai/category": "devtool", "component.aggrega.ai/upstream-licensing": "osi-approved", "ops.example.com/environment": "production", "ops.example.com/support-tier": "on-call", "ops.example.com/owner": "shop-team", "tag": "untagged" }, [… omitted: the node's Component, its version, where it is placed, its catalog metadata, the file it was declared in, and its connection to db]}最初の 3 つのラベルは Component 自身のもので、最後の 4 つは 3 つのトランスフォームが書いたものです。check.sh は各ビルドのグラフを読み取り、アタッチメントが書いたラベルを一覧表示します。
labels the attachments wrote, release-staging.yaml: db ops.example.com/environment: staging ops.example.com/support-tier: office-hours ops.example.com/owner: shop-team backup.example.com/schedule: nightly tag: orders cache ops.example.com/environment: staging ops.example.com/support-tier: office-hours ops.example.com/owner: shop-team backup.example.com/schedule: nightly tag: sessions web ops.example.com/environment: staging ops.example.com/support-tier: office-hours ops.example.com/owner: shop-team tag: untagged
labels the attachments wrote, release-production.yaml: db ops.example.com/environment: production ops.example.com/support-tier: on-call ops.example.com/owner: shop-team backup.example.com/schedule: nightly tag: orders cache ops.example.com/environment: production ops.example.com/support-tier: on-call ops.example.com/owner: shop-team backup.example.com/schedule: nightly tag: sessions web ops.example.com/environment: production ops.example.com/support-tier: on-call ops.example.com/owner: shop-team tag: untaggedReleases の間で変わるのは、Rego ポリシーの 2 つのラベルだけです。
ビルドでロックファイルが埋まれば、aggrega inspect release-production.yaml --ir-graph はビルドせずに同じグラフを、Release の読みやすい表示より前に出力します。トランスフォームはそのファイルをロックファイルから読み取るためです。ロックファイルがなければ、出力されるグラフにはそれらのファイルが決めるラベルが一切含まれません。ops.example.com/environment も ops.example.com/support-tier もなく、すべてのノードが tag: untagged になります。
トランスフォームはラベルを変えるだけで、それ以外は何も変えない
label-transform での決定は、1 つのノード、1 つのラベルキー、その値を指定するか、1 つのラベルの削除を求めます。ノードを追加したり、ノードの Component やバージョンを変えたり、その値に触れたりする決定は存在しないため、トランスフォームはそのいずれも表現できません。ビルドに存在しないノードを指定した決定は無視されません。ビルドは E0069 で停止し、そのノードと設定できなかったラベルを示します。
release-production.yaml を、これらのアタッチメントありとなしでビルドした 2 つのビルドがそれを示します。両者のビルドグラフは上に挙げたラベルだけが異なり、それ以外は何も違いません。レンダリング結果はまったく異なりません。ここでの Compose Recipes はこれらのラベルをどれもレンダリングしないため、dist/compose/docker-compose.yaml はアタッチメントの有無にかかわらずバイト単位で同じファイルであり、check.sh は実行のたびに 2 つのツリーを比較します。ラベルはビルドグラフの中にあり、判定はそこでそれらを読み取ります。
判定と、それが停止させるビルド
policies/production-support.rego はトランスフォームの後、ir-verdict にアタッチされ、それらが書いたラベルを読み取ります。
deny contains msg if { some id, node in input.graph.spec.nodes node.labels["ops.example.com/environment"] == "production" not node.labels["ops.example.com/support-tier"] msg := sprintf("%v is built for production and carries no ops.example.com/support-tier label", [id])}両方の Releases がビルドできます。staging では判定は何も求めず、production ではすべてのノードがティアを持ちます。ポリシーの対象範囲を狭めると、判定は取りこぼされたノードを捕捉します。.aggrega-config.yaml で supported_categories を [datastore] と書くと、web にはサポートティアが付かず、aggrega build --release release-production.yaml --auto-pull は停止します。
[… omitted: the pull's lines, which carry the refusal below once more, and a lint notice about core/secret-value][POLICY_ERROR E0005] policy plugin "rego" rejected the build: web is built for production and carries no ops.example.com/support-tier label caused by: policy violationビルドは 1 で終了し、dist/ を書き出しません。狭めたポリシーでも release-staging.yaml はビルドできます。そのノードには staging のラベルが付き、判定はそれらに何も求めません。check.sh はこのビルドをワークスペースのコピーの中で行うため、これを確認するためにここで何かを編集する必要はありません。
判定は受け入れるか拒否するかだけで、それ以外は何もしません。ビルドを通すために欠けているラベルを追加することはできません。本番ノードがどのラベルを持たなければならないかは組織のルールであり、そのポリシーに書かれます。コンパイラはラベルを文字列としてグラフに運ぶだけで、そこに意味を読み取りません。
ロックファイルに記録される内容
ロックファイルは 2 種類のアタッチメントを異なる方法で記録します。本番ビルドの後、release-production.lock は各トランスフォームのアタッチメントを mutators: の下に持ち(プラグイン、ロール、設定、各ファイルの内容とダイジェスト)、各トランスフォームプラグインを plugins: の下に固定します。
plugins: - uri: governance/label-injector [… omitted: the artifact digest, which depends on the aggrega binary that built it, recorded twice] referenced_from: - governance/label-injector:0.9.0 - uri: governance/rego [… omitted: the artifact digest, recorded twice] referenced_from: - governance/rego:0.9.0 - uri: governance/selector-tagger [… omitted: the artifact digest, recorded twice] referenced_from: - governance/selector-tagger:0.9.0判定のアタッチメントは verdict_inputs: の下にだけ、ファイルの sha256 で現れます。
verdict_inputs: - plugin: governance/rego:0.9.0 role: ir-verdict sources: - digest: sha256:5e01fc76f791ef00eba02f02ffb383437c87531f3927ee4a91cec9bf9c6e8cd8 path: production-support.rego判定のアタッチメントは固定されません。判定だけをアタッチした場合(3 つのトランスフォームを .aggrega-config.yaml から削除した場合)、ロックファイルは mutators: [] と plugins: [] を持ち、判定のファイルは verdict_inputs: の下にあります。トランスフォームはパイプラインの残りが基にするビルドを変えるため、ロックファイルは変更を加えたプラグインを保持します。判定はビルドが完了するかどうかを決めるだけです。
すべてのビルドの確認
このセルフチェックは、使用する共有ビルドヘルパーを含むドキュメントリポジトリのチェックアウトで実行されます。aggrega scaffold --example が書き出したコピーには、そのヘルパーは含まれません。
./check.shcheck.sh は build-release ヘルパーを通じて 4 つのビルドを行い、各結果をこのページが説明するものと照合します。
- 基準として、ガバナンスのアタッチメントのないこのワークスペースのコピーで
release-production.yamlをビルドします。 - ここでの
release-staging.yamlとrelease-production.yaml。それぞれが、各ノードに上記のラベルを持って完了しなければならず、本番のツリーは基準とバイト単位で同じでなければなりません。 - ポリシーが
datastoreカテゴリーのみを対象とするコピーでのrelease-production.yaml。E0005と上記の文で停止しなければならず、それ以外の拒否が並んではなりません。
ビルドごとに 1 行を出力し、続いてラベルを出力します。いずれかの結果が異なれば、そのビルドの出力を表示して 1 で終了します。
RELEASE GOVERNANCE EXIT EXPECTED VERDICT----------------------------------------------------------------------------------------------------release-production.yaml none 0 reference OKrelease-staging.yaml as attached 0 pass OK: the expected labelsrelease-production.yaml as attached 0 pass OK: the expected labels; byte-identical to the build with nonerelease-production.yaml narrowed 1 halt OK: E0005, the expected sentence[… omitted: the two label listings shown above]check: every build ended as expected.2 つのコピーは一時ディレクトリに作成され、その .aggrega-config.yaml にあるカタログのパスは、そこからでも解決できるよう絶対パスに書き換えられます。このディレクトリのファイルは編集されません。ここで行う 2 つのビルドは、他のビルドと同じようにロックファイルを埋めます。./build-release.sh が解決するバイナリを使うため、AGGREGA_BIN でそれを選択でき、-- 以降の引数はすべてのビルドに渡されます。ビルドが書き出すツリーを比較するため、このディレクトリに dist/ がある間は開始を拒否し、終了後にも何も残しません。終了ステータスが判定のすべてです。
コンパイラが解釈しない箇所
コンパイラは各トランスフォームにノードと Release の環境を渡し、それが決めたラベルを適用し、その結果を判定に渡します。サポートティアとは何か、on-call が office-hours より上位であること、devtool にティアが必要であることは、コンパイラは知りません。それらの意味はポリシーの設定とルールです。ロール、ペイロード、ポリシーがラベルを指定する方法についてはガバナンスソケットを、製品におけるポリシーの位置付けについてはガバナンスとコンプライアンスを参照してください。
ファイル
aggregate.yaml— データベース、キャッシュ、およびデータベースに接続された管理 UI。ラベルはありません。manifest.yaml— 各コンポーネント型とシークレットの Feature を、それぞれの Docker Compose Recipe にバインドします。両方の Releases で共有されます。release-staging.yaml、release-production.yaml— 2 つの環境。.aggrega-config.yaml— デフォルトのレジストリと 4 つのガバナンスのアタッチメント。policies/support-tier.rego— ラベル変換ポリシー。policies/production-support.rego— verdict。policies/tags.yaml— セレクタタガーのコンポーネントからタグへのマップ。build-release.sh— 1 つの Release をビルドし、同等のaggrega buildコマンドを表示します。check.sh— 4 つのビルドを行い、それぞれの結果を検証します。