組織全体のポリシー: チームのルール、組織のルール、パイプラインのルール
チームのポリシー、その組織のポリシー、そのパイプラインのポリシーが 1 つのビルドで一緒に実行され、それぞれが独自の設定ファイルでアタッチされます。チームはワークスペースで自身のルールをアタッチし、組織はすべてのビルドに 1 つ追加し、パイプラインはさらに 1 つ追加します。どちらもチームのファイルを編集しません。ビルドは自身に適用されるすべてのファイルを読み込み、それらが持つすべてのアタッチメントを実行します。
これらのルールは 3 つの verdict の重大度すべてで報告されます。info と warn ではビルドが完了し、halt ではビルドが停止します。そのうちの 1 つである組織のルールは 2 回アタッチされ、translation ブロックによって、それぞれ異なる重大度で報告されます。
構築されるもの
| インスタンス | カタログの Component | ここでの役割 |
|---|---|---|
db | core/datastore/mariadb | ショップのデータベース |
web | core/devtool/adminer | db に接続されたデータベース管理 UI |
どちらも Docker Compose にコンパイルされ、dist/compose/docker-compose.yaml に出力されます。Aggregate が 1 つ、Manifest が 1 つ、Release が 1 つ (release.yaml) で、いずれもポリシーを指定していません。
3 つのファイル
| 誰 | ファイル | ビルドがどのように読み込むか | アタッチメントが書かれる場所 |
|---|---|---|---|
| チーム | .aggrega-config.yaml | このディレクトリをワークスペースとしてマークするため、ここでのすべてのビルドが読み込みます | plugins.governance |
| 組織 | org/config.yaml | グローバル設定ファイルとして、--config org/config.yaml で 1 回のビルドに指定されます | plugins.governance_append |
| パイプライン | pipeline/.aggrega-config-append-ci.yaml | このディレクトリにコピーされると、パイプラインのオーバーレイとして読み込まれます | plugins.governance_append |
3 つのアタッチメントはいずれも Rego エンジン governance/rego:0.9.0 で、ir-verdict ロールにあります。このロールは、何かがレンダリングされる前にビルドグラフを判定します。0.9.0 は、標準ライブラリのカタログにおけるその Plugin エンティティのバージョンです。エンジン自体は CLI に組み込まれてコンパイルされているため (aggrega plugin list は組み込みのビルトインの中に governance/rego を列挙します)、ここでのビルドがプラグインを取得することはありません。
組織のファイルはグローバル設定ファイルです。 マシンには 1 つあり、すべてのビルドで読み込まれます。デフォルトの場所から、または AGGREGA_CONFIG 環境変数が指定するファイルから読み込まれます。--config <path> は代わりに 1 回の実行に対してファイルを指定し、その上にワークスペース自身のファイルが引き続き読み込まれます。組織では、このファイルはすべての開発者のマシンとすべてのパイプラインのデフォルトの場所に置かれますが、ここでは org/ に置かれ、それを読み込むべきビルドが指定します。グローバルファイルを明示的に指定するでは、3 つの方法が試される順序を説明しています。
パイプラインのファイルはオーバーレイです。 ビルドは、.aggrega-config.yaml を読み込むディレクトリで、その隣にある .aggrega-config-append-ci.yaml を読み込みます。ここでは pipeline/ に保管されており、このディレクトリで実行されるビルドはこれを読み込みません。これを読み込むビルドはすべて停止するためです。パイプラインのステップは、これをコピーすることです。
cp pipeline/.aggrega-config-append-ci.yaml .各ファイルは追加し、パイプラインのオーバーレイは追加のみを行う
組織とパイプラインはどちらも、自身のアタッチメントを plugins.governance_append の下に書きます。これは plugins.governance リストの追加用コンパニオンです。コンパニオンの下のエントリは、各ファイル自身のリストが読み込まれた後に、解決済みのリストに連結されます。そのため、チームの plugins.governance と組織のエントリの両方が実行され、どちらのファイルも相手を指定しません。組織が plugins.governance 自体ではなくコンパニオンに書くのは、ワークスペースのファイルにある plugins.governance リストがグローバルファイルのリストを置き換えるためです。そこに書かれた組織のルールはチームのリストによって削除され、ビルドはそれについて何も出力しません。リストを置き換えずに拡張するでは、各リスト設定のコンパニオンを一覧にしています。
パイプラインのオーバーレイは追加しかできません。リスト設定に対して書いた内容は、他のファイルが解決した内容に追加されます。何も削除せず、auto_pull のような単一の値を持つ設定を上書きすることもありません。このオーバーレイは auto_pull: true を持っており、これを読み込むビルドはそのキーを無視し、警告でその旨を伝えます。<workspace> をビルドが実行されたディレクトリの絶対パスとすると、その行は次のとおりです。
warning: <workspace>/.aggrega-config-append-ci.yaml: ignoring non-additive key "auto_pull" (the CI-owned overlay is additive-only and cannot override the base config)ルールと、それぞれが報告される重大度
Rego ポリシーは各決定を決定キーの下に集め、そのキーが決定の報告される重大度を選びます。translation がない場合、キーは deny、warn、audit で、それぞれ halt、warn、info で報告されます。
| 重大度 | ビルドが行うこと |
|---|---|
halt | 停止し、1 で終了し、dist/ を書き込みません |
warn | 完了し、メッセージを出力し、dist/ を書き込みます |
info | 完了し、メッセージを出力し、dist/ を書き込みます |
チームのルール policies/team.rego は warn の下に集め、そのアタッチメントは translation を宣言しないため、warn で報告されます。
warn contains msg if { some id, node in input.graph.spec.nodes node.labels["component.aggrega.ai/category"] == "datastore" input.graph.spec.infra_mapping[id].ha.enabled == false msg := sprintf("%v runs with high availability off", [id])}組織のルール org/policies/estate.rego は、設定に列挙されたカテゴリのコンポーネントを拒否し、各コンポーネントが何を実行するかを記録します。
deny contains msg if { some id, node in input.graph.spec.nodes category := node.labels["component.aggrega.ai/category"] category in data.refused_categories msg := sprintf("%v runs %v, in the %v category, which the organization does not ship", [id, node.component, category])}
audit contains msg if { some id, node in input.graph.spec.nodes msg := sprintf("%v runs %v %v, upstream licensing %v", [id, node.component, node.resolved_version, node.labels["component.aggrega.ai/upstream-licensing"]])}refused_categories は各アタッチメントの設定であり、ポリシーは自身のアタッチメントの設定を data ドキュメントとして読み込みます。
変換: 1 つのルール、2 つの重大度
アタッチメントの設定にある translation ブロックは、どの決定キーを読み込み、それぞれをどの重大度で報告するかを宣言します。これはデフォルトのマッピングを拡張するのではなく置き換えます。指定されていないキーは読み込まれません。
組織のファイルは、そのルールを助言として展開します。そのアタッチメントは deny を warn で、audit を info で報告します。
settings: refused_categories: [devtool] translation: - key: deny severity: warn - key: audit severity: infoパイプラインは同じファイルをアタッチし、同じルールでビルドを停止させます。その変換は deny だけを指定しているため、そのアタッチメントが audit の記録を 2 度報告することはありません。
settings: refused_categories: [devtool] translation: - key: deny severity: haltつまり、同じ web に対する 1 つのルールが、開発者のビルドでは警告となり、パイプラインのビルドでは停止の理由となります。
サンプルを生成する
このサンプルは以下のコマンドでビルドできます。または、AI アシスタントにビルドを任せることもできます。
例の名前を付けた新しいフォルダーに例を書き出します。
aggrega scaffold --example policy-org-overlayその後、次に実行するコマンドを表示します。最初のコマンドは新しいフォルダーに移動します。
cd policy-org-overlayビルド
標準ライブラリのカタログが、Components、Recipes、Feature とその FeatureRecipe を提供します。 これらは、.aggrega-config.yaml が指定するデフォルトのレジストリである hub.aggrega.ai から解決されます。--catalog でカタログのチェックアウト(入手方法)を指定すると、レジストリからは何も取得しないため、ビルドはオフラインで実行されます。--auto-pull はビルド中にロックファイルを埋めます。ロックファイルとレンダリングされた出力は生成されるものであり、同梱されません。
チームのファイルだけの場合:
aggrega build --release release.yaml --auto-pullビルドはチームの警告を出力して完了します。組織のファイルも加えた場合:
aggrega build --release release.yaml --auto-pull --config org/config.yamlチームの警告と並んで、組織の記録を info で、そのルールを warn で出力し、それでも完了します。
info: policy plugin "rego": db runs core/datastore/mariadb 1.0.0, upstream licensing osi-approved info: policy plugin "rego": web runs core/devtool/adminer 1.0.0, upstream licensing osi-approved policy plugin "rego" warning: db runs with high availability off policy plugin "rego" warning: web runs core/devtool/adminer, in the devtool category, which the organization does not shipPull complete: release.lock (entities=11, source_artifacts=0, external_inputs=0) notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)[… omitted: the build's time and the line naming the dist/ directory it wrote]各 verdict は、それをアタッチしたファイルではなく、それを報告したプラグイン rego を示します。そのため、チームの警告と組織の警告は同じように見えます。組織のメッセージのように、誰のルールかを述べるメッセージが、両者を区別する方法です。
パイプラインのオーバーレイをコピーすると、同じコマンドが停止します。
cp pipeline/.aggrega-config-append-ci.yaml .aggrega build --release release.yaml --auto-pull --config org/config.yaml[… omitted: the overlay's warning shown above][… omitted: the lines printed while the lockfile is resolved, which carry the verdicts below once more, the refusal among them] info: policy plugin "rego": db runs core/datastore/mariadb 1.0.0, upstream licensing osi-approved info: policy plugin "rego": web runs core/devtool/adminer 1.0.0, upstream licensing osi-approved policy plugin "rego" warning: db runs with high availability off policy plugin "rego" warning: web runs core/devtool/adminer, in the devtool category, which the organization does not ship notice: LINT: Feature "core/secret-value" at core/secret-value:1.0.0 declares property "origin" in both values: and infra: pillars (path: origin)[POLICY_ERROR E0005] policy plugin "rego" rejected the build: web runs core/devtool/adminer, in the devtool category, which the organization does not ship caused by: policy violationビルドは 1 で終了し、dist/ を書き込みません。組織のルールは各アタッチメントから 1 回ずつ、計 2 回報告されます。組織のアタッチメントからは warn で、パイプラインのアタッチメントからは halt で報告されます。audit の記録は組織のアタッチメントからのみ、1 回だけ現れます。再びこれなしでビルドするには、このディレクトリから .aggrega-config-append-ci.yaml を削除します。
AI アシスタントを使う
Aggrega のツールでセットアップした AI アシスタントでも同じことができます。次のプロンプトを貼り付けてください。
Aggrega のツールのみを使用し、フォルダーは自分で作成しないでください。Workspace フォルダーにまだ `policy-org-overlay` フォルダーがない場合は、`example` を `policy-org-overlay` に設定し、`dir` を指定せずに `scaffold` ツールを 1 回呼び出してください。これにより、新しい `policy-org-overlay` フォルダーに例が書き込まれます。次に、`workspace_root` を `policy-org-overlay`、`release` を `release.yaml`、`auto_pull` を true、`write` を true に設定して `build` ツールを呼び出し、ポリシーが何を報告したかを教えてください。続いて、`aggrega build` を実行してその `--config` フラグを受け付ける `cli-build` ツールを、`workspace_root` を `policy-org-overlay`、`release` を `release.yaml`、`auto_pull` を true、`config` を `org/config.yaml` に設定して呼び出し、今回ポリシーが何を報告したかを教えてください。各ビルドが書き込んだファイルを教えてください。それらは `policy-org-overlay/dist/` の下にあります。すべてのビルドの確認
このセルフチェックは、使用する共有ビルドヘルパーを含むドキュメントリポジトリのチェックアウトで実行されます。aggrega scaffold --example が書き出したコピーには、そのヘルパーは含まれません。
./check.shcheck.sh は build-release ヘルパーを通じて release.yaml を 5 回ビルドし、それぞれをこのワークスペースのコピーで行います。チームのファイルだけ、--config で指定した組織のファイルあり、パイプラインのオーバーレイをコピーしたもの、その両方、そしてアタッチメントをコンパニオンではなく plugins.governance の下に書いた組織のファイルのコピーありの 5 つです。最後のものではチームのリストがそれを置き換え、チームの verdict だけが出力されます。それぞれについて、終了ステータス、dist/ が書き込まれたかどうか、ビルドが出力したすべての verdict (重大度とメッセージで、欠けるものも余分なものもないこと) を検証し、オーバーレイが読み込まれる場合は auto_pull を指摘する警告も検証します。ビルドごとに 1 行を出力し、続いてそれぞれが出力した verdict を出力し、いずれかの結果が異なれば 1 で終了してそのビルドの出力を表示します。
LAYERS EXIT DIST VERDICT----------------------------------------------------------------------------------------------------team 0 yes OKteam + organization 0 yes OKteam + pipeline 1 no OKall three 1 no OKteam + organization, plugins.governance 0 yes OK
team: warn db runs with high availability off
team + organization: info db runs core/datastore/mariadb 1.0.0, upstream licensing osi-approved info web runs core/devtool/adminer 1.0.0, upstream licensing osi-approved warn db runs with high availability off warn web runs core/devtool/adminer, in the devtool category, which the organization does not ship
team + pipeline: ignored auto_pull warn db runs with high availability off halt web runs core/devtool/adminer, in the devtool category, which the organization does not ship
all three: ignored auto_pull info db runs core/datastore/mariadb 1.0.0, upstream licensing osi-approved info web runs core/devtool/adminer 1.0.0, upstream licensing osi-approved warn db runs with high availability off warn web runs core/devtool/adminer, in the devtool category, which the organization does not ship halt web runs core/devtool/adminer, in the devtool category, which the organization does not ship
team + organization, plugins.governance: warn db runs with high availability off
check: every build ended as expected.コピーは一時ディレクトリに作成され、その .aggrega-config.yaml にあるカタログのパスはそこからでも解決されるよう絶対パスにされます。このディレクトリのファイルは編集も書き込みもされません。./build-release.sh が解決するバイナリを使うため、AGGREGA_BIN でそれを選択でき、-- 以降の引数はすべてのビルドに渡されます。終了ステータスが判定のすべてです。
コンパイラが解釈しない箇所
コンパイラは 3 つのファイルを読み込み、それらが持つアタッチメントを連結し、各ポリシーにビルドグラフとその設定を渡し、各決定が報告される重大度に従って動作します。devtool が何であるか、組織がなぜそれを出荷しないのか、高可用性がチームにとって重要であることは知りません。それらの意味はポリシーのルールと設定です。ロール、ペイロード、決定キーについては、ガバナンスソケットを参照してください。
ファイル
aggregate.yaml— データベースと、それに接続された管理 UI。manifest.yaml— 各コンポーネント型とシークレットの Feature を、それぞれの Docker Compose Recipe にバインドします。release.yaml— 唯一の Release。.aggrega-config.yaml— チームのファイル。デフォルトのレジストリとチームのアタッチメント。policies/team.rego— チームのルール。org/config.yaml— 組織のグローバル設定ファイルとそのアタッチメント。org/policies/estate.rego— 組織のルール。pipeline/.aggrega-config-append-ci.yaml— パイプラインのオーバーレイ。このディレクトリにコピーされると読み込まれます。build-release.sh— Release をビルドし、同等のaggrega buildコマンドを表示します。check.sh— 5 つのビルドを行い、各結果を確認します。