レンダリングされた出力に対するポリシー: 1 つのハウスルール、4 つのターゲット、2 つのエンジン
render-verdict ロールにアタッチされた 1 つのハウスルールが、ビルドが 4 つのターゲットに対して書き出すファイルを判定し、それぞれに仕込まれた違反を拒否します。このルールには 2 つの節があります。
すべてのコンテナイメージは固定バージョン (
latest以外のタグ、またはダイジェスト) を指定すること。すべてのデータベースインスタンスはデータを暗号化して保存すること。
このワークスペースは 1 つの Aggregate を 4 つのターゲット (Helm を通じた Kubernetes、Docker Compose、Terraform、CloudFormation) 向けにビルドします。render-verdict ロールは、すべてのターゲットがファイルをレンダリングした後に、ビルドが書き出すファイルを判定します。ルールは各ターゲット独自の出力の形を読み取ります。Kubernetes オブジェクトと Compose ファイルではイメージを、Terraform ファイルと CloudFormation テンプレートでは RDS インスタンスを読み取ります。各ターゲットには、通過する Release と、違反が仕込まれルールに拒否される Release があります。
このルールは、CLI に組み込まれてコンパイルされた各ポリシーエンジン (Rego と CEL) に対して 1 回ずつ、計 2 回書かれており、2 つのコピーはここでのすべてのビルドで一致します。Releases の隣にあるスクリプトが 16 通りの組み合わせをすべてビルドし、それぞれの結果を検証します。
aggrega build独自のポリシー
コンパイラに組み込み
合格
ファイルを書き出し
レビューとデプロイの準備完了
不合格
ビルド停止
ポリシーはビルドを停止し、何を修正すべきかを示すことができます。合格させるためにファイルを変更することは決してありません。
構築されるもの
| インスタンス | カタログの Component | ここでの役割 |
|---|---|---|
db | core/datastore/postgres | 注文データベース |
report | core/compute/task | db を読み取るレポートジョブで、手動で開始されます。core/manual-trigger を持つため、Release のデプロイ時に実行は開始されません |
report は、database 接続を通じてデータベースのアドレス、ポート、名前を DB_HOST、DB_PORT、DB_NAME として読み取ります。Aggregate はすべてのビルドで同じファイルです。各 Release は、ターゲットを選ぶ Manifest を指定します。
| Manifest | db | report |
|---|---|---|
manifest-helm.yaml | helm/postgres、StatefulSet | helm/task、サスペンド状態に保たれた CronJob |
manifest-compose.yaml | compose/postgres、サービス | compose/task、プロファイルの背後にあるサービス |
manifest-terraform.yaml | terraform/postgres-rds、RDS インスタンス | terraform/task-ecs、Amazon ECS タスク定義 |
manifest-cloudformation.yaml | cloudformation/postgres-rds、RDS インスタンス | cloudformation/task-ecs、Amazon ECS タスク定義 |
ここでのすべての Recipe はカタログだけからレンダリングします。Kubernetes のデータベースはチャートとして取得されるのではなく合成され、Terraform のデータベースの本体はその Recipe によって書かれ、Terraform のタスクのモジュールはその Recipe の隣に保管されています。そのため、すべてのビルドはオフラインで実行されます。
8 つの Releases
| Release | ターゲット | ルールが見つけるもの | ビルド |
|---|---|---|---|
release-helm.yaml | Kubernetes | report は registry.example.com/orders-report:1.4.2 を実行します | 完了する |
release-helm-unpinned.yaml | Kubernetes | report は同じイメージをタグ latest で実行します | 停止する |
release-compose.yaml | Docker Compose | report は registry.example.com/orders-report:1.4.2 を実行します | 完了する |
release-compose-unpinned.yaml | Docker Compose | report はタグなしのイメージを実行します | 停止する |
release-terraform.yaml | Terraform | インスタンスは Release が指定するキーで暗号化されます | 完了する |
release-terraform-unencrypted.yaml | Terraform | Release がキーを指定しないため、インスタンスは暗号化されません | 停止する |
release-cloudformation.yaml | CloudFormation | Release が StorageEncrypted を有効にします | 完了する |
release-cloudformation-unencrypted.yaml | CloudFormation | Release がそれを無効のままにします | 停止する |
イメージは Release が決めるものです。core/compute/task はソフトウェアをパッケージしないため、Release は実行が使うイメージをタグも含めて infra.image の下で指定します。2 つの AWS ターゲットでは、データベースの暗号化も Release が決めます。Terraform の Recipe は infra.overrides.kms_key_id を読み取り、それが設定されていればキーの隣に storage_encrypted = true をレンダリングします。CloudFormation の Recipe は、リソースプロパティ自身の名前で infra.overrides.StorageEncrypted と KmsKeyId を読み取ります。どちらも設定しない Release は、暗号化の属性をまったく持たないインスタンスをレンダリングします。違反を仕込んだ Releases はまさにそうしています。
Kubernetes と Compose のデータベースは固定タグであるイメージ postgres:16 を実行するため、ルールはすべての Release でそれらを判定し、通過させます。
ルールをアタッチする
.aggrega-config.yaml はハブを自身のレジストリとして指定し、カタログのディレクトリは指定せず、ガバナンスのアタッチメントも宣言しません。ルールは、ビルドが --config で指定するファイルによってアタッチされます。Rego エンジンには governance-rego.yaml、CEL エンジンには governance-cel.yaml です。Rego のものは次のとおりです。
plugins: governance: - uri: governance/rego:0.9.0 role: render-verdict with: sources: - policies/house-rule.rego--config は、マシンが本来読み込むファイルの代わりに、その実行でのグローバル設定ファイルを指定します。このワークスペースの .aggrega-config.yaml は引き続きその上に重ねられます。ワークスペースのファイルにある plugins.governance リストは指定されたファイルが持つリストを置き換えるため、ワークスペースのファイルはこれを宣言していません。0.9.0 は、標準ライブラリのカタログにおける各エンジンの Plugin エンティティのバージョンです。両方のエンジンは CLI に組み込まれてコンパイルされているため (aggrega plugin list は組み込みのビルトインの中に governance/rego と governance/cel を列挙します)、ここでのビルドがプラグインを取得することはありません。
render-verdict ポリシーが読み取るもの
render-verdict のポリシーは、ビルドが書き出すファイルを input.artifacts で読み取ります。ファイルごとに 1 つのエントリがあり、パスでソートされています。各エントリは次を持ちます。
path—dist/の下のファイルのパス。例:terraform/modules/db/main.tf。content— 書き出されたとおりのファイルのテキスト。format— ターゲットのプロバイダーがそのファイルに宣言したフォーマット。Compose ファイルはyaml、CloudFormation テンプレートはjson、Recipe が書くデータベースの本体を含むすべての Terraform ファイルはhclです。何も宣言されていない場合は空文字列で、ここでの Kubernetes のファイルがそうです。documents— 構造にパースされたファイルの内容で、ドキュメントのリストです。ここでは各ファイルに 1 つです。parse_error— パースできなかったファイルにのみ、documentsの代わりに存在します。
ファイルのほかに、input.sources はアタッチメント自身のポリシーファイルを、input.settings はその設定を保持します。このアタッチメントは設定を宣言していないため、ここでは空のオブジェクトです。
aggrega build --release <release> --dry-run --policy-input <dir> は、各ロールが受け取るペイロードを <dir> に書き込み、それ以外は何も書き込みません。render-verdict では、そのファイルはポリシーが読み取るものではなく、エンジンが受け取るものです。その中の各ファイルは path と content、そしてプロバイダーが宣言した format を持ち、エンジンはペイロードを受け取ってから内容を documents にパースします。そのため、このファイルはルールに示されるファイルを列挙しますが、そのドキュメントは含みません。release-terraform.yaml のビルドがロックファイルを埋めた後:
aggrega build --release release-terraform.yaml --config governance-rego.yaml --dry-run --policy-input payloadsjq -c '[.artifacts[].path]' payloads/render-verdict.json# ["terraform/aggrega.modules.tf","terraform/modules/db/main.tf","terraform/modules/report/aggrega.provenance.tf","terraform/modules/report/main.tf","terraform/modules/report/variables.tf"]ルールが documents の中で読み取るパスは、エンジンがそれらをパースしたビルドの中で検証されます。これらの Recipes が書くファイルでパースに失敗するものはないため、ここに parse_error を持つファイルはありません。このルールの各節は documents を読み取るため、パースされなかったファイルは検査されずに通過します。それを許してはならないルールは、parse_error を持つファイルを拒否する節を追加します。
各節がターゲットの形をどう読み取るか
各節は自身が読み取る形を指定し、別の形のファイルは節が指定するものを持ちません。Rego ではそのパスは未定義となり、節は成立しません。そのため 1 つのルールがすべてのターゲットの出力に対して実行され、各節は自分のものだけを見つけます。
Compose は 1 つのファイルを書き出し、そのドキュメントは services の下で各サービスを名前でキーにしています。
deny contains msg if { some artifact in input.artifacts some doc in artifact.documents some name, service in doc.services unpinned(service.image) msg := sprintf("%v: service %v runs %v, an image with no tag or the tag latest", [artifact.path, name, service.image])}Kubernetes のオブジェクトはコンテナを pod テンプレートに持ち、CronJob はそれを他のワークロードより 1 段深い spec.jobTemplate.spec の下に持ちます。
pod_template(doc) := doc.spec.jobTemplate.spec.template if doc.kind == "CronJob"
pod_template(doc) := doc.spec.template if doc.kind != "CronJob"ネイティブ HCL の Terraform は、ブロックをその型の下に、次にそれぞれのラベルの下にネストし、最後のラベルはブロックのリストを保持します。型とラベルを共有するブロックは 1 つのリストにまとめられるためです。そのため、インスタンスの属性はその名前の 1 つ下のインデックスにあり、節はそのリストをたどります。
deny contains msg if { some artifact in input.artifacts native_hcl(artifact) some doc in artifact.documents some name, blocks in doc.resource.aws_db_instance some block in blocks not block.storage_encrypted == true msg := sprintf("%v: the RDS instance %v stores its data unencrypted", [artifact.path, name])}ここでは、値を探すルールの場合よりもリストが重要です。この節は不在を理由に拒否するためです。単一のブロック向けに some name, block in doc.resource.aws_db_instance と書くと、block はリストとなり、block.storage_encrypted はその上で未定義となり、not は未定義のものすべてに対して成立します。その結果、節はインスタンスが暗号化されている release-terraform.yaml も、違反を仕込んだ Release と同じメッセージで拒否してしまいます。
.tf.json ファイルは Recipe が書いたとおりに読み取られ、名前がブロックそのものを保持するため、一方の形式向けに書かれたルールはもう一方を読み取りません。節が最初に format を読み取るのはそのためです。native_hcl は、フォーマットが hcl のファイル、またはフォーマットが空で名前が .tf で終わるファイルを対象とします。どのプロバイダーもフォーマットを宣言しなかったファイルは名前でパースされるため、ルールもそれを読み飛ばすのではなく名前で識別します。ここでビルドされるすべての Terraform ファイルは hcl と宣言されているため、ここで名前によって識別されるファイルはありません。これらの Recipes は .tf.json ファイルを書かないため、ルールはもう一方の形式を読み取りません。各ロールのペイロードが公開するもので両方の形式を説明しています。
CloudFormation は 1 つのテンプレートを書き出し、そのリソースは Resources の下で論理 ID をキーにしており、それぞれが Type と Properties を持ちます。
deny contains msg if { some artifact in input.artifacts some doc in artifact.documents some id, resource in doc.Resources resource.Type == "AWS::RDS::DBInstance" not resource.Properties.StorageEncrypted == true msg := sprintf("%v: the RDS instance %v stores its data unencrypted", [artifact.path, id])}StorageEncrypted プロパティを持たないインスタンス、またはそれが true 以外に設定されているインスタンスは拒否されます。not … == true はその両方で成立します。
CEL のルールが異なる書き方をされている理由
policies/house-rule.cel は同じ 2 つの節を述べ、ここでのすべてのビルドで同じ verdict に至ります。3 か所で書き方が異なり、それぞれにエンジン側の理由があります。
読み取る前にすべてのキーを検査します。 CEL では、値が持たないキーを読み取ることは未定義のパスではなく評価エラーであり、エラーはビルドを停止させます。各ターゲットのファイルには、他のターゲットのファイルが持つキーがありません (Kubernetes オブジェクトには services がなく、Compose ファイルには kind がありません)。そのため、各節は読み取るキーをまず has() で検査します。
// Docker Compose: a service whose image names no fixed version.input.artifacts .filter(a, has(a.documents) && a.documents.exists(d, has(d.services) && d.services.exists(s, has(d.services[s].image) [… omitted: the image test, and the rest of the clause]has(d.services) の検査がないと、aggrega build --release release-helm.yaml --config governance-cel.yaml --auto-pull は、Kubernetes オブジェクトがどのイメージを実行していても停止し、1 で終了して dist/ を書き込みません。エラーを報告する行は、ポリシーファイルとそのキーを示します。
render-verdict: plugin "governance/cel:0.9.0": call "verdict_render": wasm: plugin "cel" call to verdict_render: policy source "house-rule.cel" could not be evaluated: No such key: servicesファイルごとに違反者を 1 つだけ報告します。 決定キーはメッセージを集めますが、CEL の式には、ファイルごとに作るリストを 1 つのリストにまとめる手段がありません。そのため、各 CEL の節は各ファイルで違反者を 1 つ報告します。pod テンプレートの最初のコンテナ、またはファイルが名前でキーにしているサービス、インスタンス、リソースのうち名前のソート順が最初のものです。内包表記はマップを決まった順序でたどらないため、名前で選ぶことで、メッセージがビルドごとに同じに保たれます。Rego のルールはすべての違反者を報告します。1 つの Compose ファイルにバージョンが固定されていないサービスが 2 つある場合、Rego エンジンは 2 つのメッセージで停止し、CEL エンジンは名前のソート順が最初のサービスについて 1 つのメッセージで停止します。ここでのすべての Release のように 1 つだけの場合は、両者は同じメッセージで停止します。
同じことを繰り返します。 CEL には部分式に名前を付ける手段がないため、2 回使う検査は 2 回書かれ、イメージの検査は Rego の unpinned のように呼び出されるのではなく、各節で書き下されています。
この 2 つのファイルは意図的なほぼ重複であり、一方から他方を生成するのではなく、それぞれ上記のルールから独立して書かれています。そのため、エンジン間で結果が食い違うビルドでは、その食い違いが表に出ます。
verdict が出力を変えることはない
render-verdict のポリシーはビルドを受理するか拒否するかです。ビルドが書いたファイルを渡され、verdict を返します。返したものがファイルに適用されることはありません。そのため、対照のビルドはルールをアタッチしてもしなくてもバイト単位で同じファイルをビルドし、check.sh は実行のたびに 2 つのツリーを比較します。拒否されたビルドは dist/ をまったく書き込みません。拒否を解消するには Release を変更し (固定したタグ、暗号化キー)、次のビルドが再び判定されます。
サンプルを生成する
このサンプルは以下のコマンドでビルドできます。または、AI アシスタントにビルドを任せることもできます。
例の名前を付けた新しいフォルダーに例を書き出します。
aggrega scaffold --example policy-render-verdictその後、次に実行するコマンドを表示します。最初のコマンドは新しいフォルダーに移動します。
cd policy-render-verdictビルド
aggrega build --release release-terraform.yaml --config governance-rego.yaml --auto-pullaggrega build --release release-terraform-unencrypted.yaml --config governance-rego.yaml --auto-pull # halts; exits 1同じルールを CEL エンジンで実行するには governance-rego.yaml を governance-cel.yaml に置き換え、Release のファイル名の terraform を helm、compose、cloudformation に置き換えて、それぞれの違反を仕込んだ Releases release-helm-unpinned.yaml、release-compose-unpinned.yaml、release-cloudformation-unencrypted.yaml を使います。
標準ライブラリのカタログが、ここでのすべての Component、Recipe、Feature、FeatureRecipe を提供し、両方のエンジンの Plugin エンティティを持っています。 これらは、.aggrega-config.yaml が指定するデフォルトのレジストリである hub.aggrega.ai から解決されます。--catalog でカタログのチェックアウト(入手方法)を指定すると、レジストリからは何も取得しないため、ビルドはオフラインで実行されます。--auto-pull はビルド中に各 Release のロックファイルを埋めます。ロックファイルとレンダリングされた出力は生成されるものであり、同梱されません。
Terraform の対照は完了します。違反を仕込んだ Release は停止します。
[… omitted: the lines printed while the lockfile is resolved, which carry the refusal below once more and say the render that discovers external inputs could not finish][POLICY_ERROR E0005] policy plugin "rego" rejected the build: terraform/modules/db/main.tf: the RDS instance db stores its data unencrypted caused by: policy violation各メッセージは、ルールが判定したファイルを dist/ の下のパスで示し、その中の違反者を示します。違反を仕込んだ他の Releases も同じように停止します。
policy plugin "rego" rejected the build: helm/report-cronjob.yaml: container main runs registry.example.com/orders-report:latest, an image with no tag or the tag latestpolicy plugin "cel" rejected the build: compose/docker-compose.yaml: service report runs registry.example.com/orders-report, an image with no tag or the tag latestpolicy plugin "cel" rejected the build: cloudformation/cloudformation-stack.json: the RDS instance Db stores its data unencrypted各行は、そのビルドの出力で [POLICY_ERROR E0005] の後にある行で、左端から表示しています。最初の行は Rego エンジンから、他の 2 行は CEL エンジンからのもので、それぞれ報告したエンジンを示しています。もう一方のエンジンは同じメッセージを自身の名前で出力します。
AI アシスタントを使う
Aggrega のツールでセットアップした AI アシスタントでも同じことができます。次のプロンプトを貼り付けてください。
Aggrega のツールのみを使用し、フォルダーは自分で作成しないでください。Workspace フォルダーにまだ `policy-render-verdict` フォルダーがない場合は、`example` を `policy-render-verdict` に設定し、`dir` を指定せずに `scaffold` ツールを 1 回呼び出してください。これにより、新しい `policy-render-verdict` フォルダーに例が書き込まれます。次に、`aggrega build` を実行してその `--config` フラグを受け付ける `cli-build` ツールを、各 Release について 1 回ずつ、`release-terraform.yaml`、`release-terraform-unencrypted.yaml` の順に呼び出してください。毎回、`workspace_root` を `policy-render-verdict`、`release` をそのファイル、`auto_pull` を true、`config` を `governance-rego.yaml` に設定します。2 回目は拒否されることを意図しているので、拒否内容を読み上げてください。最初のビルドが書き込んだファイルを教えてください。それらは `policy-render-verdict/dist/` の下にあります。すべてのビルドの確認
このセルフチェックは、使用する共有ビルドヘルパーを含むドキュメントリポジトリのチェックアウトで実行されます。aggrega scaffold --example が書き出したコピーには、そのヘルパーは含まれません。
./check.shcheck.sh は build-release ヘルパーを通じて、まず各対照をポリシーをアタッチせずに 1 回ビルドして参照とし、次に 8 つの Releases すべてを各エンジンでビルドします。対照は完了し、その参照とバイト単位で同じファイルを書かなければなりません。違反を仕込んだ Release は、E0005 とそれに期待されるメッセージで停止し、ほかの拒否を伴わず、dist/ を書いてはなりません。両方のエンジンに同じメッセージが求められます。ビルドごとに 1 行を出力し、いずれかの結果が異なれば 1 で終了してそのビルドの出力を表示します。
ENGINE RELEASE EXIT EXPECTED VERDICT--------------------------------------------------------------------------------------------------------------none release-helm.yaml 0 reference OKnone release-compose.yaml 0 reference OKnone release-terraform.yaml 0 reference OKnone release-cloudformation.yaml 0 reference OKrego release-helm.yaml 0 pass OK: completed, byte-identical to the build with no policyrego release-helm-unpinned.yaml 1 halt OK: E0005, the expected sentencerego release-compose.yaml 0 pass OK: completed, byte-identical to the build with no policyrego release-compose-unpinned.yaml 1 halt OK: E0005, the expected sentencerego release-terraform.yaml 0 pass OK: completed, byte-identical to the build with no policyrego release-terraform-unencrypted.yaml 1 halt OK: E0005, the expected sentencerego release-cloudformation.yaml 0 pass OK: completed, byte-identical to the build with no policyrego release-cloudformation-unencrypted.yaml 1 halt OK: E0005, the expected sentencecel release-helm.yaml 0 pass OK: completed, byte-identical to the build with no policycel release-helm-unpinned.yaml 1 halt OK: E0005, the expected sentencecel release-compose.yaml 0 pass OK: completed, byte-identical to the build with no policycel release-compose-unpinned.yaml 1 halt OK: E0005, the expected sentencecel release-terraform.yaml 0 pass OK: completed, byte-identical to the build with no policycel release-terraform-unencrypted.yaml 1 halt OK: E0005, the expected sentencecel release-cloudformation.yaml 0 pass OK: completed, byte-identical to the build with no policycel release-cloudformation-unencrypted.yaml 1 halt OK: E0005, the expected sentence
check: every build ended as expected../build-release.sh が解決するバイナリを使うため、AGGREGA_BIN でそれを選択できます。-- 以降の引数はすべてのビルドに渡されます。各ビルドのツリーを比較のために移動するため、このディレクトリに dist/ がある間は開始を拒否し、終了後にも何も残しません。ビルドは、どのビルドとも同じように、このディレクトリのロックファイルを埋めます。終了ステータスが判定のすべてです。
コンパイラが解釈しない箇所
コンパイラは各ターゲットのファイルをレンダリングし、プロバイダーが宣言したフォーマットとともにテキストとしてアタッチされたエンジンに渡し、各 verdict が持つ重大度に従って動作します。イメージタグが何であるか、latest が移動すること、RDS インスタンスを暗号化すべきことは知りません。それらの意味はルールのものです。ロール、ペイロード、決定キーについては、ガバナンスソケットを参照してください。
ファイル
aggregate.yaml— データベースと、それに接続されたレポートジョブ。manifest-helm.yaml、manifest-compose.yaml、manifest-terraform.yaml、manifest-cloudformation.yaml— 1 つのターゲット上で、各コンポーネント型と手動トリガーの Feature をそれぞれの Recipes にバインドします。release-<target>.yaml、release-<target>-unpinned.yaml、release-<target>-unencrypted.yaml— ターゲットごとの対照と、仕込まれた違反。.aggrega-config.yaml— デフォルトのレジストリ。ガバナンスのアタッチメントはありません。governance-rego.yaml、governance-cel.yaml— 各エンジンを通じてrender-verdictにアタッチされるルール。それぞれ--configで指定します。policies/house-rule.rego、policies/house-rule.cel— ルール本体。エンジンごとに 1 つずつです。build-release.sh— 1 つの Release をビルドし、同等のaggrega buildコマンドを表示します。check.sh— 20 回のビルドを実行し、それぞれの結果を確認します。