コンテンツにスキップ
AggregaAggrega
言語の選択: 日本語
このページは機械翻訳されています。英語の原文を読む。

ガバナンスソケット

ソケットの 1 つのロールではなくソケット全体を扱います。4 つのロール(ビルドを判定する 2 つと、ビルドを整形する 2 つ)、コンパイラに同梱される両方のポリシーエンジン、そしてオペレーターがプラグインをアタッチする方法です。

オペレーターは Wasm ガバナンスプラグインをアタッチして、ビルドを検査し、その結果に基づいて処理を行います。コンパイラのホストは内容に対して中立で、主張を持たないままです。ホストはビルドの ペイロードをゲストに渡し、ゲストが返したものに基づいて処理を行い、ポリシー自体を解釈することは 決してありません。ドメインのポリシーに関する知見のすべて(ポリシー言語、その エンジン、そしてルール)はゲストの内部にあります。

これは、すべてのソケットが従うのと同じ事前(ahead-of-time)純粋性の契約です。 ゲストは渡されたペイロードを評価し、ホストがそのまま消費する結果を返します (サンドボックスの契約を参照)。 ホストはゲストが話すポリシー言語について何も知らず、独自の ポリシーエンジンのコードを一切持ちません。

ガバナンスプラグインはちょうど 1 つのロールにアタッチされ、プラグインではなくロールが、 どのペイロードが届くかと、そのアタッチメントがそれに対して何をしてよいかの両方を決めます。 2 つは判定ロールです。アタッチメントはビルドを判定し、ホストは返された判定ごとに 3 つの処理のうちちょうど 1 つを実行します。2 つは変換ロールです。 アタッチメントはビルドのラベルまたはアノテーションへの変更を報告し、ホストは それを適用します。複数のロールを担うプラグインはロールごとに 1 回ずつアタッチされ、 プラグイン自身はロールを宣言しません。ロールはアタッチメントが保持します。

このページはガバナンスソケットを包括的に扱います。4 つのロール とそれぞれが運ぶペイロード、ホストが処理の基準とする判定の重大度、 オペレーターが与えるエンジンに依存しない入力チャネル、コンパイラに同梱される 2 つのポリシーエンジン (Rego を評価するものと CEL を評価するもの)のいずれかに向けたポリシーの書き方、 ゲストが外部のポリシーエンジンをラップする方法、同梱される参照用ゲスト、 そしてオペレーターがプラグインをワークスペースにアタッチする方法です。パイプラインにおけるソケットの位置と型付きのワイヤ形式については plugin-contract.md を、 プラグインをカタログエンティティとして作成・公開する方法については Wasm プラグイン開発者ガイドを参照してください。

メンタルモデル: ホストがルーティングし、ゲストが判断する

ビルド時、ホストはアタッチメントのロールに応じたペイロードを組み立て、ABI 境界を越えてそれを渡し、ゲストが返したものを読み取ります。verdict ロールでは、それは verdict のリストであり、各 verdict は重大度と人間が読めるメッセージを持ちます。 ホストは各重大度をビルドアクションに対応付けますが、メッセージの意味を読み取ることはなく、ポリシーが何を検査したかも、どのエンジンが判断を下したかも知りません。transform ロールでは、それは行うべき変更であり、そのロールが管理するラベルまたはアノテーションのみを対象とし、それ以外は対象にしません。

ホストはポリシーの内容を解釈しないため、ポリシーに関わる領域はすべてゲストのものです。ルールをどの言語で記述するか、どのエンジンで評価するか、ルールの発火をどのように verdict や変更に変えるかは、すべてゲストが決めます。ソケットの契約は設計上意図的に狭く、ロール、入力の集合、結果のみで構成されています。これにより、Wasm にコンパイルできるあらゆるポリシー技術がこのソケットを担えます。

verdict ロールは受理または拒否のみを行い、それ以外は何もしません。ホストはその出力を判断としてのみ読み取り、変更として適用することはないため、ポリシーが非準拠のビルドをひそかに準拠させることはできません。transform ロールは意図的な例外であり、それを例外たらしめているのは、オペレーターがそれをアタッチしたという事実です。ラベルを整形するプラグインをアタッチすることは、ラベルを整形するという宣言にほかなりません。そのようなアタッチメントが変更できる範囲は自身のロールの領域に限られ、その範囲外のものに対してはビルドが明示的に停止します。

4 つのロール

プラグインはちょうど 1 つのロールにアタッチされ、そのロールによって、ホストがパイプラインのどこでそれを評価するか、どのペイロードを受け取るか、何を返してよいかが決まります。2 つのロールを担うべきプラグインは、ロールごとに 1 回ずつ、計 2 回アタッチします。

判定ロール: ir-verdict と render-verdict

  • ir-verdict — ゲストはレンダリング前に、中間表現グラフを対象に推論します。ペイロードには、ケイパビリティに依存しない完全な IR グラフ (コンパイラが保持するすべてのノード、エッジ、アタッチメント) に加えて、アナライザが列挙するルーティングパスが含まれるため、ポリシーはグラフを再走査せずにトポロジーと到達可能性を推論できます。このパスリストは開始ノードごとに上限があります。密に接続されたトポロジーや循環を含むトポロジーは、列挙が出力するよりも多くの異なる経路を持つことがあり、上限に達すると、その開始ノードからの残りの経路は列挙されません。したがって、存在するパスは実在するものですが、パスがないことはパスが存在しないことの証明にはなりません。到達不能であることを判定の根拠とするポリシーは、パスリストだけに頼らず、ペイロードに完全な形で含まれるノードとエッジからそれを確認してください。グラフの中で 1 つだけ記述どおりでないものがあります。作成者が機密と宣言したすべての値 (アタッチメントの values または infra、境界アタッチメントの infra、ノード自身の values または infra、あるいは接続自身の values または infra にあるもの) は、秘匿マーカー {"aggrega_withheld": "declared"} として届きます。一方、そのキー、機密の指定、およびその横にある宣言されていないすべての値は記述どおりに届きます。ポリシーは、機密と宣言された内容がどこを流れるかを判定し、その内容自体を受け取ることはありません。詳しくはガバナンスポリシーが読み取るアタッチメントの事実を参照してください。ir-verdict ポリシーは、成果物が生成される前の静的解析ゲートで実行されます。アーキテクチャと配線に関するポリシー、つまりトポロジーの不変条件、境界をまたぐ認証、認証情報の流れの形など、何かをレンダリングする前にビルドを停止すべきものに使用します。
  • render-verdict — ゲストはレンダリング後に、レンダリングされた出力を対象に推論します。ペイロードには出力された成果物がパス順に並べて含まれるため、同一の入力に対する実行間でワイヤはバイト単位で同一になります。各成果物には出力パスとレンダリングされたテキストが含まれます。さらに、生成した provider が形式を宣言している場合はレンダリングされた形式が、内容がポリシーより前に解析される形式である場合は内容の解析済み構造化ビューが含まれます。render-verdict ポリシーはビルドが生成したものをそのまま参照し、そこには秘匿されるものはありません。Recipe が成果物にレンダリングした値は、レンダリングされたとおりに届きます。ポリシーが判定するのは成果物そのものだからです。具体的な出力に関するポリシー、たとえばレンダリングされた Docker Compose サービスや Kubernetes オブジェクトを検査するルールに使用します。

変換ロール: annotation-transform と label-transform

  • annotation-transform — ゲストは、解決中かつアノテーション展開の前に、追加するアノテーションを報告します。ペイロードには、アタッチメントがアノテーションを付与できるすべてのコンポーネントがそれぞれの既存のアノテーションとともに含まれ、さらに Manifest がバインディングを登録しているアノテーションキーが含まれます。登録済みのキーで注入されたアノテーションは Feature アタッチメントへと展開されます。このロールは、こうして開発者が入力していないケイパビリティをビルドに追加します。

    アノテーションを付与できるコンポーネントは、境界が components: の下で指定するすべてのコンポーネントと、境界の aggregates: ルーティングエントリがルーティングして取り込むすべてのコンポーネントです。ルーティングエントリは、自身の components: がそのすべてを指定しているか、一部か、何も指定していないか(documents: {} は何も指定しません)にかかわらず、そのモジュールのすべてのコンポーネントを、その中にネストされたモジュールのコンポーネントも含めて配置します。ペイロードはその一つひとつを持ちます。ルーティングされたコンポーネントは、ビルドグラフ内で持つ ID で指定されます。モジュール名、ドット、モジュール内でのコンポーネント名の順で、documents.backend のようになり、ネストされたモジュールごとにモジュール名とドットが 1 つずつ加わります。これはビルドグラフとその診断での表記であり、決定もそのように指定します。ルーティングエントリが指定せずに配置したコンポーネントは、ペイロード上で独自のアノテーションを持たず、そこに注入されたアノテーションは、ルーティングエントリの下でそこに書かれたものとして適用されます。

  • label-transform — ゲストは、トポロジー構築中、つまりグラフが構築された後、グラフが判定される前に、適用するラベルの変更を報告します。ペイロードには、ビルドのノードの射影 (各ノードがインスタンス化する Component、そのノードに解決されたバージョン、現在付いているラベル、そのインスタンスが宣言する値。値は読み取り専用で、その Component が機密と宣言した値はすべて、グラフ判定と同じように伏せられます) に加えて、Release の名前と環境が含まれます。コンプライアンスの範囲、所有者、コストの帰属など、開発者が入力する必要があってはならない派生メタデータや、開発者が宣言した設定によって付与されるケイパビリティラベルに使用します。

ロールごとにペイロードが異なるのは、それぞれが異なるタイミングで動作し、異なる問いに答えるためです。4 つのロールはいずれも、後述する、オペレーターが供給する同じ入力チャネルを持ちます。ペイロードについて読むのではなく実物を見るには、aggrega build --release <release> --policy-input <dir> を使います。これは各ロールがそこにアタッチされたプラグインに渡すペイロードを(何もアタッチされていないロールも含めて)、ロールごとに 1 つの JSON ファイルとして、あるいはロールのアタッチメントが異なるペイロードを受け取る場合はアタッチメントごとに書き出します。--dry-run と組み合わせると、それらのファイルだけを書き出し、それ以外は何もしません。annotation-transform、label-transform、ir-verdict では、そのファイルがポリシーの読む input ドキュメントです。render-verdict では、ポリシーが読む前にポリシーエンジンがペイロードを作り直します(各アーティファクトの documents はそこから解析されます)。そのため、コンパイラに組み込まれたエンジン上の render-verdict ポリシーは、ビルドをゲートする前にポリシーをテストするで示すとおり、warn または info でアタッチしてビルドの中でテストします。自分で .wasm をビルドしたプラグインであれば、aggrega plugin run-local --plugin <plugin.wasm> --export verdict_render --with @<dir>/render-verdict.json でそのファイルに対して実行できます。

判定と重大度

以下の重大度は、判定ロールの語彙です。変換ロールは判定ではなく変更を報告するため、重大度を持ちません。

ゲストは判定のリストを返します。各判定は、ビルドの動作を決める重大度を持ちます。

  • halt — ビルドを停止します。ホストは判定のメッセージを理由として提示します。 ビルドは成果物を生成しません。
  • warn — 判定を警告として示します。ビルドは続行します。
  • info — 判定を記録します。ビルドの結果は変わりません。

この 3 つがすべてであり、ほかのすべてのソケットの診断が使う 3 つと同じです。そのため、重大度はどこで読んでも同じ意味を持ちます。

それ以外の値を持つ判定は、4 つ目の経路ではなく契約違反です。ビルドは停止し、メッセージはプラグイン、判定が持っていた値、契約が宣言する 3 つの値を示します。そのため、綴りを誤った重大度は、何も処理しない判定として通過するのではなく、ビルドエラーとして報告されます。3 つの値から報告するゲストは影響を受けません。

許可する評価は何も返しません。ゲストはルールが発火したときにのみ判定を出力するため、空の判定リストはポリシーがビルドを許可したことを意味します。出力すべき「pass」判定はありません。沈黙が許可です。

ゲストは 1 回の評価で、重大度を混在させた複数の判定を返すことができます。ホストはそのすべてを走査します。いずれかの halt があればビルドを停止し(すべての halt メッセージが提示されます)、warn と info の判定はブロックせずに報告されます。これは、ビルドを停止するポリシーと助言的な lint チェックを分ける、停止と助言の区別を反映しています。

with チャネル: sources と settings

ポリシーゲストは通常、適用する具体的なルールに対して汎用的です。エンジンはゲストに組み込まれていますが、ルールはアタッチメントごとに供給されます。 with チャネルは、このアタッチメントごとの入力を運びます。エンジンに依存しない 2 つのフィールドがあります:

  • sources — ゲストが読み込むポリシー定義ファイルです。ホストはビルド時に 指定された各ファイルを読み取り、そのバイト列を不透明なままゲストに渡します。ホストが ソースを解析することはなく、ゲストに渡すパスはファイルのベース名であり、 ホストの絶対パスではありません。バイト列が何を意味するかは完全にゲスト側の 問題です。あるゲストにとっては .rego ファイル、別のゲストにとっては他のポリシー形式、 そしてポリシーセット全体の base64 エンコードされたアーカイブを読むゲストにとってはそのアーカイブです。
  • settings — ゲストが自身のエンジンに対応付ける設定マップです。ゲストは 調整可能な値(レプリカ数の上限、必須ラベルのキーなど)をこのマップから読み取ります。 デフォルトでは、ホストはこれに手を加えずそのまま渡します。ゲストはさらに このマップのスキーマを宣言することもでき(後述)、その場合ホストは ゲストを実行する前にそのスキーマに対してマップを検証します。

完全に組み込み済みのゲスト、つまりルールがアタッチ時に供給されるのではなくコンパイル時に組み込まれているゲストは、 with を完全に省略します。このチャネルはどのロールでも省略可能です。

型付き settings

ゲストは、期待する settings の JSON Schema を宣言できます。宣言した場合、 ホストはアタッチメントの settings をそのスキーマに対して ゲストを実行する前に 検証します。 適合しない settings は、問題のキーとスキーマが期待した内容を示すメッセージとともにビルドを停止させます。 必須キーの欠落、誤った型の値、未知のキー、範囲外の値は、分かりにくいゲストの失敗として、 あるいはさらに悪いことに誤っているのに成功したビルドとして表面化するのではなく、事前に検出されます。

型付き settings は省略可能で、ホストではなくゲストが宣言します。settings のスキーマを 宣言しないゲストは自由形式の動作のままです。ホストはその settings を検査せずに渡します。ホストは、ゲストが宣言したスキーマに対して通常の JSON Schema 検証を 実行するだけで、settings の意味は解釈しません。これにより検査はエンジン中立に保たれます。 各ゲストは自身が読む settings の形を記述し、ホストはまさにその形だけを適用し、 それ以上のことはしません。

settings を宣言しないアタッチメントは JSON null として検証されます。 これにより、ゲストは settings を必須にできます。オブジェクトのみを許容するスキーマは、settings を供給しないアタッチメントを拒否し、ビルドは停止します。この帰結は逆方向にも働き、意識して対処すべきなのはこちらです: settings が本当に省略可能なゲストは、オブジェクトに加えて null も許容するスキーマを宣言しなければなりません。そうしないと、settings なしでは一切アタッチできません。コンパイラに組み込まれた 2 つのポリシーエンジンは、まさにこの理由で "type": ["object", "null"] を宣言しています。with: ブロックなしでアタッチすると、デフォルト値で実行されます。"type": "object" のみを宣言するゲストは、意図したかどうかにかかわらず、settings を必須にしています。

ABI は Aggrega 独自のものです

ソケット契約は Aggrega 独自の ABI であり、特定のポリシーエンジンの ABI ではありません。そのため、Wasm にコンパイルされたどのポリシー技術でも、そのまま差し替え可能なゲストとして使用できます。ゲストは外部に向けて Aggrega のインターフェース(describe() と、ゲストが担うロールが呼び出すエクスポート)を提供し、どのエンジンを使うかはそのインターフェースの背後にある実装の詳細にすぎません。

外部のポリシーエンジンをラップするゲストは、そのエンジンの ABI を自身の内部に取り込みます。エンジンが独自の Wasm ABI、独自のエントリポイント、または独自のホストコールバックプロトコルを持つ場合、ラップするゲストはそれを内部でインスタンス化して駆動し、エンジンの判定をソケットの判定(verdict)の形式に変換します。コンパイラのホストから見えるのは標準のガバナンス判定インターフェースだけです。ホストはどのエンジンが関与しているかを知ることはなく、エンジン固有のコードも持ちません。ポリシーをあるエンジンから別のエンジンに切り替えることは、アタッチメントの変更であり、ホストの変更ではありません。

コンパイラに同梱される 2 つのポリシーエンジン

CLI バイナリには 2 つのポリシーエンジンがコンパイルされて組み込まれており、オペレーターはそのいずれか、または両方を、他のガバナンスプラグインと同じ方法でアタッチします。

コーディネートポリシー言語アタッチするソース
governance/regoRego.rego ファイル、またはポリシーセット全体を base64 エンコードしたアーカイブ
governance/celCommon Expression Language (CEL).cel 式ファイル、または .yaml / .yml ルールドキュメント

言語以外の部分はすべて共通です。どちらも 4 つのロールすべてに対応し、どちらもロールごとの同じペイロードを同じフィールド名で読み取り、どちらも同じ translation 設定によって判定を同じ 3 つの判定重大度に対応付け、どちらも評価できなかったビルドを許可せずに明示的に失敗します。それぞれ、自身を同梱するコンパイラのリリースをバージョンとして持ち、外部ツールチェーンを必要とせず、ビルド時に何も取得しません。共通でないのは、各言語が何を表現できるかです。Rego では数個のヘルパールールで済むルールが、CEL では設定と繰り返しを必要とする場合があります。ルートをたどるルールを書く前に、式で表現できることを参照してください。

異なるのはルールを記述する言語であり、それが選択の唯一の根拠です。すでに Rego のコーパスを保有している環境や、他の場所でアドミッション制御のために Rego を書いているチームは、Rego エンジンをアタッチすれば、そのポリシーをそのまま実行できます。Kubernetes の validating admission policy のように、ルールをドキュメントに対する単一の式として表現するチームは、CEL エンジンをアタッチします。2 つはロールごとにアタッチされるため、ワークスペースではあるロールで Rego を、別のロールで CEL を実行することも、同じロールで両方を 2 つのアタッチメントとして実行することもできます。

ホストは、判定がどちらから来たかに依存しません。ペイロードをルーティングし、判定または変更を読み戻し、それに基づいて動作します。ポリシーを一方の言語からもう一方へ切り替えることは、アタッチメントの変更とルールの書き直しであり、ホストの変更には決してなりません。

Rego ポリシー:2 つの道

Rego は一般的なポリシー言語であり、それを実行する道は 2 つあります。コンパイラに同梱された手軽なエンジンと、完全な忠実度を持つエスケープハッチです。

コンパイラ内の Rego エンジンは手軽な道です。Wasm ネイティブの Rego エバリュエータを備えているため、オペレーターは .rego ファイルを sources に置いてプラグインをアタッチするだけで済みます。外部ツールチェーンは不要で、ビルド時に何も取得しません。4 つのロールすべてに対応し、同じプラグインが、アタッチされたロールに応じて、ビルドグラフを判定し、レンダリングされた出力を判定し、ラベルを整形し、またはアノテーションを注入します。カタログ上の識別子は pluginType: governance の下の素の名前 rego、つまりコーディネート governance/rego であり、バージョンはそれを同梱するコンパイラのリリースです。このエンジン向けのポリシーの書き方は次のセクションで説明します。

このエバリュエータはリファレンス実装を組み込むのではなく Rego を独自に再実装しており、すべての Rego ビルトインを実装しているわけではありません。エバリュエータが実装していないビルトインをポリシーが呼び出すと、アタッチメントは明示的に失敗します。つまり、許可ではなくフォールトを返します。その後、ビルドはプラグイン名を示すフォールトで停止します。これは意図的に halt 判定とは区別されており、「エンジンがこのポリシーを評価できない」ことが「ポリシーがビルドを許可する」ことと取り違えられることはありません。評価できないポリシーはビルドを停止させ、黙って通過することはありません。

opa build -t wasm エスケープハッチは完全な忠実度を持つ道です。ポリシーが完全なビルトイン群やリファレンスエンジンと厳密に同じセマンティクスを必要とする場合は、OPA 自身のツールチェーンで Wasm モジュールにコンパイルし、そのモジュールを薄いアダプターゲストの背後で実行します。アダプターは OPA の Wasm ABI を完全に自身の内部で吸収します(上記の ABI は Aggrega 独自のものを参照)。OPA でビルドされたモジュールをインスタンス化し、入力を設定し、評価を呼び出し、決定を判定の形にマッピングし直します。ホストからは標準のガバナンス判定インターフェースしか見えません。

リファレンスのアダプターゲストが実例として同梱されています。これは Rego で記述され opa build -t wasm で WebAssembly モジュールに事前コンパイルされたポリシーを組み込んでいます。このモジュールはバージョン固定されリポジトリにチェックインされた成果物であるため、評価は OPA プロセスなしで、何も取得せず、完全にゲスト内で実行されます。各ビルドでアダプターは、組み込みの Wasm インタープリタを使ってその焼き込み済みモジュールを自身の内部でインスタンス化し、モジュール自身のインポート(線形メモリとビルトインのコールバック)を満たし、ペイロードを OPA の input ドキュメントとして、アタッチメントの settings を OPA の data ドキュメントとして読み込み、コンパイル済みの各エントリポイントを評価して、各エントリポイントの deny / warn / audit というエントリポイント名をそれぞれ判定の重大度 halt、warn、info にマッピングします。焼き込み済みポリシーが、アダプターの実装していないホスト提供のビルトインを必要とする場合、アダプターは明示的に失敗します。許可を返すのではなくモジュールを拒否するため、評価できないポリシーは黙って通過せずにビルドを停止させます。焼き込み済みモジュールを Rego ソースから再生成するのは OPA CLI で行うオーサリング手順であり、ビルド時の依存関係ではありません。../examples/policy-data-class-route/ は独自のモジュールを中心にそのアダプターをビルドし、両方を再生成するコマンドを示しています。

2 つの道は同じホスト契約を共有しているため、ポリシーをコンパイラ内のエンジンから完全なエンジンへ移行するのはアタッチメントの変更だけで済みます。

Rego エンジン向けのポリシーを書く

エンジンは、オペレーターが記述した Rego を、アタッチされた 4 つの役割のいずれにおいても、完全にゲスト内で評価します。2 つの役割に、2 つの異なるポリシーファイルで 2 回アタッチすることで、1 つのエンジンが同じビルドの 2 つの時点をカバーします。

アタッチメントの役割に対応するペイロードがポリシーの input ドキュメントとなり、アタッチメントの settings オブジェクトがポリシーの data ドキュメントとなります。そのため、ポリシーはオペレーターが指定したしきい値を data.max_replicas として読み取ります。アタッチメントが sources の下に宣言するすべてのファイルはポリシーモジュールとなり、それらのファイルが宣言するすべてのパッケージが評価されます。

ポリシーがどのルール構文で書かれているか

Rego には 2 つのルール構文があり、エンジンはモジュールごとに両方を受け付けます。そのため、現行の構文が登場する前に組み立てられたポリシーセットも、今日書かれたポリシーと同じアタッチメント内で並べて評価されます。

現行の構文では、ルール本体は if で始まり、セットに収集するルールは contains でそれを示します。また、モジュールはパッケージ宣言の下の独立した行に import rego.v1 を宣言することで、どの構文で書かれているかを示します:

package example
import rego.v1
deny contains msg if {
count(input.graph.spec.nodes) > 20
msg := "this build declares more than twenty nodes"
}

旧来のブラケット付きヘッド構文では、ルールが収集する値はルールヘッドのブラケット内に置かれ、本体はその直後に続きます。この構文のモジュールは何も宣言しません。現行の構文としてパースされないことによって識別されるためです:

package example
deny[msg] {
count(input.graph.spec.nodes) > 20
msg := "this build declares more than twenty nodes"
}

何も宣言せずに現行の構文としてパースされるモジュールは、名前を示して拒否されます。 宣言こそが解釈を確定させるものであり、宣言がなければ同じルールのテキストが正反対の判定に至ることがあります。成立しないルール本体は、現行の構文では判定を何も生みませんが、旧来の構文では判定を 1 つ生みます。そのため、何も出力しないはずだったポリシーがビルドを停止させ、逆のケースでは、停止させるために書かれたルールがあるビルドを通してしまいます。エンジンはそのようなモジュールに対して解釈を選ぶのではなく、拒否したうえで何を追加すべきかを示します:

policy source "policy.rego" must declare `import rego.v1`. Both Rego rule syntaxes are accepted, and this module parses as either one — so without the import its rules could be read in the older syntax, where the same text can reach the opposite decision. Add `import rego.v1` on its own line below the package declaration.

この拒否は判定ではなく、プラグインを名指しするビルドフォールトです。そのため、評価不能なポリシーと同様にビルドを停止させ、ビルドを許可したポリシーとして読まれることはありません。

想定外の事態を避けるため、知っておくべき境界ケースが 2 つあります。ルール本体をまったく持たないモジュール(データを宣言するだけのモジュール)は現行の構文としてパースされるため、2 つの解釈が異なり得ないにもかかわらず、宣言が求められます。また、旧来の構文で書かれたモジュールは現行の構文としてパースされないため、拒否されることはありません。2 つを区別するのはエンジン自身であるため、意図的なブラケット付きヘッドのポリシーが、宣言を忘れた現行構文のポリシーと誤認されることはありません。

ポリシーは判定を判定キーの下に収集する

すべての役割は、ポリシーの判定を判定キー(ポリシーが収集先とする、名前の付いたルール)から読み取ります。どのキーが読み取られ、その下の判定が何を意味するかは、役割によって決まります。

**判定(verdict)**の役割では、判定はメッセージであり、それが収集されたキーによって、そのメッセージが報告される重大度が決まります。デフォルトでは、キーは慣例的な Rego の収集名です:

収集先報告される重大度ビルドへの影響
denyhaltビルドを停止する
warnwarn完了するビルドとともに表示される
auditinfo記録される。ビルド結果は変わらない

2 つの語彙は別物なので、区別してください。deny、warn、audit はポリシー側の名前であり、halt、warn、info はソケットが報告する重大度です。左の列は自由に名前を変えられますが、右の列はすべてのソケットが共有する閉じた集合です。

判定に別の名前を付けるポリシーは、アタッチメントの settings でマッピングを宣言します:

with:
settings:
translation:
- key: blocked
severity: halt
- key: advisory
severity: warn

宣言されたマッピングはデフォルトを拡張するのではなく置き換えます。マッピングが指定するキーだけが読み取られるため、上記のマッピングを宣言すると、引き続き deny に収集するポリシーはどの判定にも至りません。ルールが宣言された順序が、判定が報告される順序になります。ポリシーが宣言しないキーは失敗ではなく判定の不在として扱われるため、1 つのポリシーファイルを複数のアタッチメントで使えます。

3 つ以外の重大度や、空として宣言されたマッピングは、プラグインが宣言する settings スキーマによって拒否されます。ホストはディスパッチの前に、アタッチメントの settings をこのスキーマに照らして検証します。同じキーが 2 回マッピングされている場合は、マッピングの読み取り時に拒否されます。これもポリシーの実行前です。いずれの場合も、ビルドは判定に至る前に停止し、マッピングが中途半端に適用された状態になることはありません。

それ以外の点では、settings はポリシー自身のデータです。マッピングはオブジェクトから読み取られ、オブジェクトは変更されずにポリシーの data ドキュメントに渡ります。そのため、デフォルトのキー向けに書かれたポリシーは、マッピングがまったく設定されていない場合とまったく同じ data ドキュメントを参照します。

**変換(transform)**の役割では、判定はメッセージではなく加えるべき変更です。そのため決めるべき重大度はなく、代わりにキーが固定されています。ラベル整形の役割では labels、アノテーション注入の役割では annotations です。translation 設定は判定が報告される場所でのみ読み取られるため、これを宣言する変換アタッチメントは、その役割が使用しない設定を持っていることになります。

判定キーは、アタッチメントが読み込むすべてのパッケージから読み取られます。 そのため、ポリシーセットはルールを複数のパッケージに分散でき、各パッケージが収集したものを提供します。その裏返しとして、問題になる前に知っておくべきことがあります。1 つのアタッチメント内では、判定キーはすべてのパッケージで予約されたルール名となるため、たまたま独自の目的で labels に収集するヘルパーパッケージは、そのエントリがラベルの判定として読み取られます。これは暗黙にではなく明示的に失敗します(アタッチメントは、キーの下に収集された何かがその形の判定ではないと報告します)。しかし、そのようなメッセージは名前の衝突として読むのが最も早道です。キーは判定のために取っておき、ヘルパールールには別の名前を付けてください。

各役割のペイロードが公開する内容

ペイロードはポリシーの input ドキュメントであるため、ポリシーはワイヤ上で与えられた名前でそれを読み取ります。

**ビルドグラフを持つ 2 つの役割では、グラフの位置するパスが異なります。**グラフに対する判定はグラフドキュメント全体を受け取るため、そのノードは input.graph.spec.nodes にあります。ラベル整形の役割はノードの射影を受け取るため、そのノードは input.graph.nodes にあります。したがって、この 2 つの役割の間でルールを移す場合は、コピーではなく編集が必要です。これを忘れた場合の症状はエラーではなく、決して発火しないルールです。存在しないパスは単に未定義になるためです。

役割ポリシーが読み取る内容
ir-verdictinput.graph — ビルドグラフドキュメント全体です。ノードはノード ID をキーとして input.graph.spec.nodes に、エッジは input.graph.spec.edges にあります。作成者が機密と宣言した値は {"aggrega_withheld": "declared"} として読み取られます。input.precalculated_paths — 列挙されたルーティングパスです。各パスは順序付きの nodes リストと、そのパス上のいずれかにアタッチされた Feature 型である attached_features を持ちます(後述)。このリストは常に存在します。コンポーネント間にルートのないビルドは空のリストを持ちます。
render-verdictinput.artifacts — 出力されたファイルごとに 1 つのエントリで、それぞれ path、content、format、およびファイルを解析したドキュメントである documents を持ちます。format は、そのファイルをレンダリングしたプロバイダーがファイルに対して宣言した形式です。Terraform プロバイダーは、出力するすべての .tf ファイルに hcl を、すべての .tf.json ファイルに json を宣言し、ベンダリングされたモジュールのファイルもこれに含まれます。どのプロバイダーも形式を宣言していない場合は空文字列で、Recipe が境界の共有出力に寄与するファイルがその例です。そのようなファイルも拡張子によって解析されるため、どちらの場合でも documents は存在します。構造的に読み取れなかったアーティファクトは parse_error を持ち、ドキュメントを持ちません。そのため、ポリシーは読み取れないファイルを未検査のまま通すのではなく、失敗そのものを理由に拒否できます。
label-transforminput.graph.nodes — ノード ID をキーとするビルドのノードで、それぞれ component、resolved_version、labels、values を持ちます。最後のものは、ノードのインスタンスが Aggregate で宣言する値で、テンプレートはそのパラメーターに対して評価済みです。何も宣言していない場合は存在しません。ノードの Component が機密と宣言した値は、ir-verdict の場合と同様に {"aggrega_withheld": "declared"} として読まれ、宣言されていない兄弟の値は書かれたとおりに読まれます。ルールはラベルを決めるために input.graph.nodes[id].values を読みますが、値を変更することはできません。input.compilation_context — Release の release_name と environment です。これにより、ポリシーは環境ごとに異なる判断ができます。
annotation-transforminput.targets — アタッチメントがアノテーションを付与できるすべてのコンポーネントで、それぞれ boundary_path、component_name(ルーティングエントリが配置するコンポーネントの場合は、metrics.query のようなビルドグラフ内の ID)、および Release がそのコンポーネント自体に書いた annotations を持ちます。各値は書かれたとおりで、文字列、サブキーのオブジェクト、またはコンポーネントが継承するはずのアノテーションをオプトアウトする場合は null です。コンポーネントが持つすべてのキーは値にかかわらず存在するため、ルールは誰かがすでに書いたキーに手を付けずにおくことができます。input.binding_keys — Manifest がバインディングを登録しているアノテーションキーです。

**Terraform リソースは、Terraform の 2 つの形式のそれぞれで異なるパスで読み取られます。**ネイティブの .tf ファイルの documents では、ブロックはその型の下に、次にそれぞれのラベルの下にネストし、最後のラベルはブロックのリストを保持します。型とラベルが同じブロックはソース順に 1 つのリストにまとめられるためです。したがって、リソース属性は input.artifacts[_].documents[_].resource.<type>.<name>[_].<attr> で読み取ります。任意の名前の RDS インスタンスであれば input.artifacts[_].documents[_].resource.aws_db_instance[_][_].allocated_storage です。.tf.json ファイルは Recipe が書いたとおりに読まれるため、名前がブロックそのものを保持する通常のオブジェクト形式は resource.<type>.<name>.<attr> で読み取られ、両方の形式を対象とするポリシーは両方のパスを読みます。これはコンパイラ内の両方のポリシーエンジンに当てはまります。もう一方の形式向けに書かれた Rego ルールでは、指定したパスが未定義になります。そこで値を検査するルールは決して発火せず、not を使って値の不在を理由に拒否するルールはすべてのリソースで発火します。もう一方の形式にインデックスや選択を行う CEL 式は、ポリシーファイルを示す評価フォールトでビルドを停止します。後述の レンダーステージのポリシーアダプター で説明するリファレンスの Rego レンダーアダプターは、ネイティブの .tf ファイルを自ら解析し、単一のブロックをオブジェクトとして読み取ります。そのため、ポリシーをこのアダプターとコンパイラ内のエンジンの間で移す場合、Terraform のパスはコピーではなく編集が必要です。

すべての役割は、さらに input.sources(アタッチメント自身のファイルで、それぞれベース名の path と content を持ちます)を持ちます。ポリシーはそれらのファイルの 1 つとしてのみ実行されるため、ルールがこのリストを読む場所では、リストには少なくともそのファイルが含まれます。

input.settings はアタッチメントの設定オブジェクトで、ポリシーの data ドキュメントと同じオブジェクトであり、アタッチメントが設定を宣言している場合に存在します。アタッチメントが何も宣言していない場合、ルールが何を見つけるかは役割によって異なります。ir-verdict、label-transform、annotation-transform ではこのフィールドは存在しないため、input.settings はペイロードが持たない他のパスと同様に未定義になり、render-verdict では空のオブジェクトになります。したがって、ある設定が構成されたかどうかに依存するルールは、オブジェクトではなく読み取る設定そのものを検査します。こうすればどの役割でも同じように動作します。構成された max_nodes は読み取られ、構成されていない場合は input.settings.max_nodes が未定義のままとなり、ルールは何も出力しません:

package example
import rego.v1
deny contains msg if {
limit := input.settings.max_nodes
count(input.graph.spec.nodes) > limit
msg := sprintf("this build declares more than %v nodes", [limit])
}

CEL エンジンは宣言されていない設定オブジェクトを異なる方法で扱い、その点は後述の CEL エンジン自身のセクションで説明します。

attached_features と binding_keys はオブジェクトではなくリストであるため、ポリシーは in でメンバーシップを判定します。

package security
import rego.v1
deny contains msg if {
some path in input.precalculated_paths
some gateway in path.nodes
input.graph.spec.nodes[gateway].labels["dataplane.aggrega.ai/content-masking"]
not "core/data-masking" in path.attached_features
msg := sprintf("path %v passes through %v with no masking Feature attached.", [concat(" -> ", path.nodes), gateway])
}

attached_features は、パス上のいずれかのノードが持つすべてのアタッチメントの Feature 型の和集合です。そのノードの接続の 1 つに記述されたアタッチメントも、どの接続に記述されたかにかかわらず含まれます。そのため、このルールはゲートウェイ自体にある core/data-masking アタッチメントによって満たされます。この Feature はゲートウェイにアタッチされるものであり、ゲートウェイが宣言するコンテンツマスキング機能を選択します。アタッチメントがマスクするのは、そのゲートウェイを通過するチャットおよび補完のテキストです。ルールが確認するのはアタッチメントが存在することであり、その内容ではありません。

パス全体にわたる和集合であるため、このリストは Feature がルート上のどこかにアタッチされていることを示しますが、その場所は示しません。Feature がルートの特定の 2 つのコンポーネント(制限付きデータを保持するものと、それが到達するもの)の間にあるかどうかを知る必要があるルールは、ルートの nodes を順に読み、各ノード自身のアタッチメントを input.graph.spec.feature_values_mapping[<node>] で読み取ります。同じ問いを attached_features に対して行うと、Feature が 2 つ目のコンポーネントより先にあるルートを通してしまいます。../examples/policy-data-class-route/ は、Rego エンジン、CEL エンジン、OPA のそれぞれについてこの方法で記述されています。

ノードオブジェクトは自身の ID を持ちません。ID は input.graph.spec.nodes 内でそのノードが置かれているキーです。そのため、上記のルールは id フィールドを読むのではなく、 path.nodes から読み取った ID をメッセージに含めています。

ポリシーがマップのキーに出会う順序

グラフは作成者が記述した順序を保持します。ノードはコンポーネントが宣言された順序で、各ノードのラベルはノードが持つ順序で保持されます。この順序はそのままゲストに渡ります。ペイロードは両方を順序付きのエントリとして運びます (順序を保持するマップを参照)。 ポリシーがその順序に出会うかどうかは、ペイロードではなく、ポリシーを評価するエンジンがオブジェクトをどのように保持するかによって決まります。

  • Rego エンジンはオブジェクトのキーをソートして保持します。 input.graph.spec.nodes、ノードの labels、またはその他のオブジェクト(ポリシー自体に記述されたものも含む)を反復するルールは、キーにソート順で出会います。 web、api、metrics の順に宣言されたコンポーネントは、api、metrics、web の順で現れます。
  • CEL エンジンはマップの順序を固定しません。 input.graph.spec.nodes やノードの labels に対する内包表記は、同一入力の 2 回のビルドで異なる順序でキーに出会うことがあり、1 つの式の中での同じマップの 2 回の走査も互いに異なることがあります。 そのため 1 つの判定キーの下のメッセージはソートされます。 判定がキーの位置に依存しないルールを記述してください。
  • プラグインキットを使って記述されたゲストは、作成者の順序に出会います。 キットを通じてデコードされると、ノードと各ノードのラベルは、ペイロードが運ぶ順序のまま、キットの順序保持コンテナに格納されます。また、各キットが提供するガバナンスアダプターのスケルトンは、その同じ順序で記述された JSON ドキュメントをエンジンに渡します。そのドキュメントを独自の値型に変換するエンジンは、 順序を保持するマップ で説明するとおり、代わりにその型の順序に出会います。

ラベルの整形:ポリシーはラベルを指定し、エンジンがそれをアドレス指定する

ラベル整形の役割では、ポリシーは labels の下にラベルごとに 1 つの判定を収集し、 ノード、ラベルキー、ラベルがとる値を指定します。

package tagging
import rego.v1
labels contains {"node": id, "key": "compliance.example.com/tier", "value": "gold"} if {
some id, node in input.graph.nodes
node.labels["component.aggrega.ai/type"] == "stateful-server"
}

既に存在するキーを設定すると、その値が置き換えられます。代わりに、キーの削除を要求する判定も可能です。

labels contains {"node": id, "key": "draft.example.com/scratch", "op": "remove"} if {
some id, node in input.graph.nodes
node.labels["draft.example.com/scratch"]
}

ポリシーはビルドが適用する編集命令を記述するのではなく、ラベルを指定します。その理由は知っておく価値があります。命令はラベルをパスでアドレス指定しますが、 Aggrega のラベルキーには通常 / が含まれ、これはパス区切り文字です。そのため、手書きのパスは 1 つのラベルではなくネストされた位置を指してしまいます。エンジンが判定の指定するラベルをアドレス指定するため、エスケープはすべてのポリシーではなく一度だけ記述され、ポリシーはパスではなくラベルについての記述として読みやすいままになります。

判定が変更できるのはラベルのみです。エンジンが出力するすべての命令は 1 つのノード上の 1 つのラベルを指すため、ポリシーにはノードの Component、解決済みバージョン、ノードの集合、または文字列でないラベル値への変更を表現する方法がありません。ビルドに存在しないノードを指定する判定や、ノードが持たないラベルを削除する判定は、命令を示すメッセージとともにビルドによって拒否されます。黙って無視されることはありません。

../examples/policy-label-transform/ は、2 つの組み込みタグ付けプラグインと並べてこのようなポリシーをアタッチし、さらにそれらが書くラベルを読むグラフに対する判定もアタッチします。各プラグインが何を読み書きするかは 組み込みのタグ付けプラグイン にあります。

アノテーションの注入

アノテーション注入の役割では、ポリシーは annotations の下にアノテーションごとに 1 つの判定を収集し、 ターゲット自身が持つ座標でターゲットを指定し、さらにキーとその値を指定します。

package tagging
import rego.v1
annotations contains {
"boundary_path": target.boundary_path,
"component_name": target.component_name,
"annotation_key": "backup.example.com/schedule",
"annotation_value": "nightly",
} if {
some target in input.targets
not target.annotations["backup.example.com/schedule"]
}

判定が記述するフィールド名は、ターゲットを読み取ったときのフィールド名と同じであるため、この慣例はペイロードだけから習得できます。input.binding_keys を読むことで、ポリシーは Manifest が意味を登録したキーのみを注入できます。それらが Feature アタッチメントに展開されるキーです。

決定の値は、そのアノテーションに自分で書けるもの、つまり文字列またはサブキーのオブジェクトです。1 つのサブキーをルーティングするバインディングは文字列を受け取り、複数をルーティングするバインディングは、オペレーターが Release に書くのとまったく同じように、それぞれを指定したオブジェクトを受け取ります:

annotations contains {
"boundary_path": target.boundary_path,
"component_name": target.component_name,
"annotation_key": "feature.aggrega.ai/monitoring",
"annotation_value": {"interval": "30s", "port": "metrics", "path": "/metrics"},
} if {
some target in input.targets
not target.annotations["feature.aggrega.ai/monitoring"]
}

ビルドは注入された値を、Release に書かれた同じ値を読むのとまったく同じように読み取るため、同じように展開され、バインドされた Feature に対して同じように検査されます。エンジンはオブジェクトのキーをソートして保持するため、サブキーはソート順でビルドに届きます。それ以外の形の値(null、リスト、数値、真偽値、またはサブキーのないオブジェクト)は、注入を示してビルドによって拒否されます。この役割はアノテーションを追加するものであり、null や空のオブジェクトは、作成者がアノテーションを削除するために書くオプトアウトとして読まれるためです。ペイロードに含まれないコンポーネントを指定する決定も同じように、座標とアノテーションを示して拒否されます。

ビルドが、注入されたアノテーションをそのルーティング方法や内容を理由に拒否する場合(複数のサブキーをルーティングするバインディングに渡された文字列、バインドされた Feature のスキーマが許可しないサブキー値、または Release 側のアノテーションが使用できない values の柱を通じてルーティングされたサブキーなど)、拒否はそれを注入したプラグインと、そのプラグインがアタッチされているガバナンスの役割を示します。これにより、その値は誰も書いていない Release の行ではなく、それを決定したポリシーまで追跡されます。

../examples/policy-annotation-transform/ は、このようなポリシーをアタッチし、あるバインディングには文字列を、別のバインディングにはサブキーのオブジェクトを注入して、それらのアノテーションを手書きした Release と同じファイルをビルドします。

ポリシーセット全体を 1 つのアーカイブとしてアタッチする

ポリシーセットは、ファイルごとにアタッチすることも、ポリシーファイルとデータドキュメントをまとめて格納した単一のアーカイブとしてアタッチすることもできます。後者は Rego ツールチェーンが生成する形です。アタッチされたファイルの内容はテキストとしてゲストに渡されますが、圧縮アーカイブはテキストではなく任意のバイト列であるため、アーカイブは base64 エンコードしたうえで、名前が .base64 で終わるように命名してアタッチします。

Terminal window
tar czf bundle.tar.gz policy.rego data.json
base64 -w0 bundle.tar.gz > bundle.tar.gz.base64
with:
sources:
- ./policies/bundle.tar.gz.base64

ファイルをポリシーテキストではなくアーカイブとして扱わせるのはその名前であり、これによりその選択はオペレーター自身の表明となります。そのため、破損したアーカイブは、解析できないポリシーファイルとして読まれるのではなく、ファイル名と失敗したステップを示して、破損したアーカイブとして報告されます。アーカイブのエンコードは、ツールチェーンがアーカイブを生成した後にオペレーターが追加するステップです。

アーカイブ内では、すべての .rego メンバーがポリシーモジュールであり、すべての data.json または data.yaml メンバーは、それが置かれたディレクトリの下にネストされたデータドキュメントです。たとえば {"max": 3} を保持する limits/data.json は、ポリシーからは data.limits.max として読まれます。それ以外の種類のメンバーは、アーカイブ自身のツールチェーンのためにアーカイブに含まれているものであり、ポリシーの入力にはなりません。

開けないアーカイブは、アタッチされたファイルを示す失敗になります。デコードできないエンコード、展開できないストリーム、途中で切れたアーカイブ、読み込めないデータファイル、あるいはポリシーをまったく含まないアーカイブがこれにあたります。いずれの場合も空のポリシーセットにはなりません。空のポリシーセットは何の決定にも達しないためです。「アーカイブが読めなかった」ことが「ポリシーがビルドを許可した」ことと区別できなくなることは、決してあってはなりません。

CEL エンジン向けのポリシーの書き方

このエンジンは、オペレーターが記述した CEL を、4 つのロールのうちアタッチされたロールにおいて、完全にゲスト内で評価します。カタログ上の識別子は pluginType: governance の下の素の名前 cel、つまり座標 governance/cel であり、そのバージョンはこれを同梱するコンパイラのリリースです。2 つのロールに、2 つの異なるポリシーファイルでこれを 2 回アタッチすることで、1 つのエンジンが同じビルドの 2 つの時点をカバーします。

plugins:
governance:
- uri: governance/cel:<version>
role: ir-verdict
with:
sources:
- ./policies/topology.cel
settings:
max_nodes: 20

ポリシーはペイロード全体を 1 つの名前 input で参照するため、ポリシーが読む名前はワイヤ上の名前そのものです。ビルドグラフは input.graph、列挙されたルーティングパスは input.precalculated_paths、レンダリングされたファイルは input.artifacts、アノテーションの対象は input.targets にあります。これらのロールごとのパスは、前述の各ロールのペイロードが公開するもので表にまとめたものであり、両方のエンジンで同一です。1 つのワイヤを、1 つのルート名の下で読みます。

アタッチメント自身のファイルは input.sources、その設定は input.settings にあるため、オペレーターが指定したしきい値は input.settings.max_nodes として読みます。覚えるべき第二のドキュメントはありません。設定も他のすべてと同様に input の一部です。どちらも常に値として存在し、アタッチメントが何も宣言していない場合、設定はどの役割でも空のオブジェクトになるため、これらを参照する式で不在に備える必要はありません。ある設定が構成されたかどうかは、そのキーに対する検査で判断します:has(input.settings.max_nodes)。

2 つの記述形式と、それを選ぶファイル名

ポリシーは 2 つの形式のいずれかでアタッチされ、どちらであるかはファイル名が示します。

ファイル名の末尾読み取り方
.cel1 つの式として、そのまま評価
.yaml または .ymlルールドキュメント(ルールのリスト)
その他1 つの式

規則は名前だけです。形式を選ぶ設定はなく、形式を推測するためにファイルのテキストが調べられることもありません。いずれにせよテキストではこの問いに答えられません。式自体の最も外側の値はマップであり、ルールドキュメントのそれもマップであるため、2 つの形式は形では区別できないからです。

したがってこの規則はどちら向きにも働き、どちらの誤りも誤読されるのではなく拒否されます。 policy.cel という名前のルールドキュメントは、YAML ルールのリストが式ではないため拒否され、policy.yaml という名前の式は、式がルールのリストではないため拒否されます。いずれの拒否もファイル名を示します。どちらの場合も、ファイル名を変更すれば解決します。

ポリシーセットは必要なだけのファイルで構成でき、1 つのアタッチメント内で 2 つの形式を自由に混在させられます。

.cel という名前のファイルに書く式

式言語には決定をまとめるためのルール名がないため、決定は式が生成する値そのものです。すなわち、決定キーから、そのキーが収集するものへのマップです。判定のロールでは、キーはその下で到達したメッセージを収集し、ビルドを形作るロールでは、適用する決定を収集します。

{
"deny": input.graph.spec.nodes
.filter(n, input.graph.spec.nodes[n].resolved_version == "latest")
.map(n, "component " + n + " tracks the latest version; pin it"),
"warn": size(input.graph.spec.nodes) > input.settings.max_nodes ? ["this build declares a lot of components"] : [],
}

ファイルが省略したキーはそこで何の決定にも到達していないため、ファイルはすべてのキーを指定する必要はありません。また、各ロールは自身に関係するキーだけを読むため、1 つのポリシーセットが同じファイルから判定のロールとビルドを形作るロールの両方に対応できます。キーは、収集するもののリスト、その単一の要素、または何もないことを示す null 値を持ちます。

マップ以外のものに評価される式は拒否され、書くべき形が示されます。想定しておくべき誤りは素の size(input.graph.spec.nodes) <= 5 です。これはブール値であり、false を停止として読むことは、作成者が書いていないメッセージを捏造することになります。

.yaml または .yml という名前のファイルに書くルールドキュメント

ルールドキュメントはルールのリストであり、各ルールは、到達する決定キー、到達するかどうかを決める式、および到達したときに報告する内容を指定します。

- key: deny
expression: size(input.graph.spec.nodes) > 20
message: this build declares a lot of components
- key: warn
expression: has(input.settings.max_nodes)
message: a component ceiling is configured for this environment

ルールが報告する内容は、式の場合とまったく同様に、到達する決定キーに従います。テキストは判定が持つメッセージです。マッピングは、ビルドを形作るロールが読む 1 つの決定のフィールドです。

- key: labels
expression: input.compilation_context.environment == "production"
message:
node: app
key: compliance.example.com/tier
value: gold

ルールがどちらを書くかはルールだけで決まり、それを選ぶ設定はありません。キーに対して誤った方を書いたルールは、名前を示して拒否されます。

問題になる前に知っておくべき YAML の注意点が 1 つあります。二重引用符で始まる式は、ドキュメントのリーダーのために引用符で囲む必要があります。" で始まる値は、引用符で始まるテキストではなく、引用符付きスカラーとして読まれるためです。

- key: annotations
expression: '"backup.example.com/schedule" in input.binding_keys'
message:
boundary_path: main
component_name: app
annotation_key: backup.example.com/schedule
annotation_value: nightly

ルールドキュメントは、何かが評価される前に、それが表す式として読まれます。 各ルールは、式が成り立つときにはその報告を持ち、成り立たないときには何も持たない決定キーとなり、同じキーを共有するルールは結合されます。したがって 1 つの評価器が両方の形式を実行し、ルールドキュメントは、それが表す式が決定するものとまったく同じものを、すべてのロールで、判定とビルドを形作る決定の両方について決定します。ここから 2 つの帰結が生じます。ドキュメントと、それが表す手書きの式は、同じ評価であるため同じ決定に到達します。また、後述の順序の規則はドキュメントではなく評価後の形式に対するものであり、ドキュメントのルールは書かれた順には報告されません。

どちらの形式が適しているか(両者は互換ではありません)

両方の形式は 1 つの評価器で実行されるため、どちらかが他方より速い、あるいは信頼できるということはありません。異なるのは、それぞれが何を表現できるかです。また、2 つの形式は覚えるべきことが 2 つあることを意味するため、使い分けは好みに任せず、はっきり述べておく価値があります。 ルールが報告する内容で選んでください。

  • 報告が固定されている場合は、ルールドキュメント。 メッセージや決定は、それに到達する式の隣に一度だけ書かれ、ファイルはガードのリストとして読めます。「これが真なら、まさにこれを言う」には、こちらが短い形式です。
  • 報告が見つけたものを名指しする場合は、式。 1 つの式でビルドのコンポーネントを絞り込み、コンポーネントごとにメッセージ(または決定)を生成するため、読み手は件数についての 1 文ではなく、違反するものごとに component payments tracks the latest version; pin it を受け取ります。

この 2 つ目の役割は、ルールドキュメントにはできないものです。各ルールはあらかじめ書かれた 1 つの報告を持つため、どのコンポーネントがそれに引っかかったかについては何も言えません。ドキュメント形式を選んだ後でメッセージに違反者の名前を入れたくなると、結局ルールを式として書き直すことになるため、最初にこの問いで選んでおく価値があります。

式で表現できること

このエンジンが評価する式では、filter、map、exists の内包表記、文字列とリストに対する +、size、in、startsWith、string()、条件演算子、および計算された整数によるリストのインデックス参照を使用できます。一部の CEL 環境が追加する拡張関数は提供されません。join、split、substring、indexOf、flatten、cel.bind、lists.range はいずれも未宣言の参照として拒否されます。また、内包表記は 1 つの変数を取るため、exists(i, v, …) のような 2 変数形式も同様に拒否されます。拒否は、ファイルと参照を示すビルドフォールトです。

policy source "routes.cel" could not be evaluated: Undeclared reference to 'join'

ルートをたどるルールには、次の 3 つの帰結が影響します。

  • 中間値に名前を付ける方法はありません。 2 回使う部分式は 2 回書くか、1 要素のリストをマップして束縛します。[value].map(name, …)[0] は、name を value に束縛して本体を一度評価します。
  • リストの位置をたどる方法はありません。 ルートのコンポーネントを位置で比較するルールは、設定から位置([0, 1, 2, …] のような positions リスト)を受け取り、それぞれの位置でルートをインデックス参照します。そのため、リスト自体より長いルートには、部分的に読むのではなく、停止させることで備える必要があります。
  • 決定キーが収集するのはメッセージであり、メッセージのリストではありません。 ルートごとに 1 つのメッセージのリストを生成する式は決定キーの下では拒否されます(フォールトは、メッセージではなくリスト型の値を収集したことを示します)。そのため、ルールはルートごとに 1 つのレコードを生成し、そこからメッセージを組み立てます。また、式が 2 回生成したメッセージは 2 回報告されます。後述のソートはキーが収集したものを並べるだけで、重複は取り除きません。

../examples/policy-data-class-route/ には、これら 3 つすべてを踏まえて書かれた CEL ルールが、Rego エンジン向けの同じルールと並べて収められています。

決定キーと重大度

決定キー、重大度へのデフォルトの対応付け、およびそれらの名前を変更する translation 設定は、Rego エンジンの場合と同じです。上記のポリシーは決定を決定キーの下に収集するを参照してください。デフォルトでは、deny は halt、warn は warn、audit は info で報告されます。宣言された translation はこのデフォルトを拡張するのではなく置き換え、そこで宣言された順序が判定の報告される順序になります。

両エンジンはこれに対して同じ設定スキーマを宣言しているため、translation ブロックは決定をどちらの言語で表現しても同じ意味を持ち、不正な形式のものはポリシーが実行される前に拒否されます。

ビルドを形作るロールでは、キーは対応付けられるのではなく固定されています。ラベルを形作るロールでは labels、アノテーションを注入するロールでは annotations です。

順序:キー内ではソートされ、決定全体には全順序がある

1 つの決定キーの下のメッセージは、ソートされた順序で報告されます。 これは表示上の選択ではなく契約の一部であり、その理由は理解しておく価値があります。マップに対する内包表記(input.graph.spec.nodes に対する .filter(...) や .map(...)。これはコンポーネントごとのルールを書く最も自然な方法です)は、評価器が固定しない順序でそのマップを走査します。そのままでは、同一の入力でもビルドのたびに同じメッセージが異なる順序で報告されることになります。ソートによってそれが解消されます。

バグのように見えて実はバグではない点が 2 つあります。

  • ルール文書のルールもソートされて報告されます。 記述された順序ではありません。文書はそれが表す式として評価され、ソートはキーが収集したものに適用されるためです。
  • 手書きのリストもソートされます。 ["second", "first"] を持つキーは、first を second より先に報告します。評価結果には、作成者が手で入力したリストと内包表記が生成したリストを区別するものが何もないため、保持すべき記述順序は存在しません。

キーをまたぐ順序は、translation で宣言された順序です。ファイルをまたぐ順序はファイル名の順序です。アタッチメントのソースは、アタッチメントが列挙した順序ではなく、名前順にソートされて届くためです。

ビルドを形作るロールでは、同じ考え方が決定そのものに適用され、順序はさらに厳密になります。決定は、それが指定するすべての要素の昇順で報告されます。 これは決定が表現できるものに対する全順序であり、ノード、次にラベルキー、次にラベルが追加されるか削除されるか、次に値の順です。注入の場合は、境界、次にコンポーネント、次にアノテーションキー、次にその値の順です。ラベルやアノテーションの変更はレンダリング出力に反映されるため、任意の順序では、同一の入力がビルドごとに異なるレンダリング結果になってしまいます。

ラベルの整形

ラベル整形の役割では、ポリシーは labels の下にラベルごとに 1 つの判定を収集し、 ノード、ラベルキー、ラベルがとる値を指定します。

{
"labels": input.graph.nodes
.filter(n, input.graph.nodes[n].labels["component.aggrega.ai/type"] == "stateful-server")
.map(n, {
"node": n,
"key": "compliance.example.com/tier",
"value": input.compilation_context.environment == "production" ? "gold" : "bronze",
}),
}

既に存在するキーを設定すると、その値が置き換えられます。代わりに、op を remove と指定することで、キーの削除を求める決定にすることもできます。

{
"labels": input.graph.nodes
.filter(n, "draft.example.com/scratch" in input.graph.nodes[n].labels)
.map(n, {"node": n, "key": "draft.example.com/scratch", "op": "remove"}),
}

決定が 1 つだけの場合はリストで囲む必要はなく、labels キーを指定しないファイルはラベルについて何も決定しません。

ポリシーは、ビルドが適用する編集命令を書くのではなくラベルを指定します。その理由は Rego エンジンのラベル整形のセクションで説明したとおりです。Aggrega のラベルキーには通常 / が含まれ、手書きのパスでは 1 つのラベルではなく入れ子になった場所を指してしまいます。エンジンは、決定が指定したラベルを指し示します。

ノードが持たない可能性のあるラベルを読み取ると、空の値ではなく失敗になります。 そのため、2 つ目の例ではキーを読み取る前に存在するかどうかを確認しています。これは存在しないキーの読み取りに関する式言語自体のルールであり、明示的に失敗します。どのノードも持たないラベルを参照するポリシーは、何も決定せずに黙って終わるのではなく、評価できなかったことを報告します。

決定が変更できるのはラベルだけです。ビルドに存在しないノードを指定する決定や、ノードが持たないラベルを削除する決定は、その命令を示すメッセージとともにビルドによって拒否されます。黙って無視されることはありません。

ノードとラベルキーごとに 1 つの決定に到達するようにします。 同じノードの同じラベルに対して 2 つの異なる値を生成しうるルールは、仕様が不十分です。両方の決定を出力するのではなく、条件演算子や一方の分岐だけを通すフィルタを使って、式の中で値を確定させてください。

../examples/policy-label-transform/ は、ラベル整形の役割をエンドツーエンドで示しており、そのポリシーは Rego エンジン向けに書かれています。

登録済みのキーでのアノテーションの注入

アノテーションを注入するロールでは、ポリシーはアノテーションごとに 1 つの決定を annotations の下に収集し、ターゲット自身が持つ座標でターゲットを指定し、さらにキーとその値を指定します。

{
"annotations": input.targets
.filter(t, "backup.example.com/schedule" in input.binding_keys)
.map(t, {
"boundary_path": t.boundary_path,
"component_name": t.component_name,
"annotation_key": "backup.example.com/schedule",
"annotation_value": "nightly",
}),
}

決定が書くフィールド名は、そのターゲットを読み取ったときのフィールド名と同じであるため、この慣例はペイロードだけから把握できます。input.binding_keys を読み取ることで、ポリシーは Manifest が意味を登録したキーだけを注入できます。それらが Feature のアタッチメントに展開されるキーです。すべてのフィールドは必須です。キーやコンポーネント名が空のアノテーションは、ポリシーが意図して求めるものではありません。コンポーネントが属する境界は正当に空文字列で指定されうるため、そのフィールドは存在する必要がありますが、空であってもかまいません。

値は、そのアノテーションに自分で書けるもの、つまり文字列またはサブキーのマップで、後者は複数のサブキーを一度にルーティングするバインディングに渡すものです:"annotation_value": {"interval": "30s", "port": "metrics", "path": "/metrics"}。式言語はマップに順序を定めないため、エンジンはマップのサブキーをソート順で書き出し、値は式が生成したとおりに渡します。JSON モデルが保持できない値(バイト列、タイムスタンプ、期間)は、テキストに変換されるのではなく拒否されます。その後ビルドは、Release に書かれた同じ値を読むのとまったく同じように値を読み取り、null、リスト、数値、真偽値、空のマップを、注入を示して拒否します。1 つのコンポーネントとキーに対する、値の異なる 2 つの決定は、値の JSON によって順序付けられます。ターゲットの annotations は既存の各値を書かれたとおりに持ちます(文字列、マップ、またはオプトアウトを表す null)。そのため "feature.aggrega.ai/monitoring" in t.annotations を検査すれば、値にかかわらずキーを見つけられます。

ペイロードに含まれないコンポーネントを指定する決定は、その座標とアノテーションを示してビルドによって拒否されます。ビルドが、注入されたアノテーションをそのルーティング、サブキー値、または柱を理由に拒否する場合、拒否はそれを注入したプラグインと、そのプラグインがアタッチされている役割を示します。ラベルの場合と同様に、コンポーネントとアノテーションキーごとに 1 つの決定に到達するようにし、1 つのキーに対して 2 つの決定を出力するのではなく、式の中で値を確定させてください。

../examples/policy-annotation-transform/ は、アノテーション注入の役割をエンドツーエンドで示しており、そのポリシーは両方のエンジン向けに書かれています。

ポリシーや決定を読み取れない場合

エンジンが読み取れないポリシー、評価できないポリシー、または文書化された形式の決定以外のものを生成するポリシーは、判定や変更を返すのではなく、ビルドを失敗させます。この失敗は、ファイルを示し、障害がファイルの一部に属する場合はその中の位置も示すビルド障害として報告されます。これは意図的に halt 判定とは区別されており、「このポリシーは評価できなかった」が「このポリシーはビルドを許可する」と取り違えられることはありません。

式の場合、これには解析できないソース(パーサー自身の行と列、および問題の位置の下にキャレットを付けて報告されます)と、決定キーからそのキーが収集するものへのマップ以外に評価されるソースが含まれます。

ルール文書の場合、これにはルールのリストではないテキスト、ルールを含まないリスト、フィールドが欠けているか空のフィールドを持つルール、この形式で定義されていないフィールド、テキストでもテキストからテキストへのマッピングでもない報告内容、および読み取れない式が含まれます。1 つのルールに属する障害は、そのルールの位置(作成者が自分のファイルを数えるのと同じように 1 から数えます)とその決定キーを示します。式が解析できないルールは評価前に拒否されるため、キャレットは作成者が見たことのない変換後のテキスト内の位置ではなく、作成者が書いた式の中を指します。

ビルドを形作るロールでの決定の場合、これには決定があるべき場所にあるメッセージ、欠けている座標、およびこのエンジンの決定形式で定義されていないフィールドが含まれます。最後の点は特に述べておく価値があります。綴りを誤った annotation_valu は無視されるのではなく拒否されるため、空の値が黙って注入され変更のないままビルドが完了するのではなく、誤りが報告されます。このような拒否はいずれもファイルを示し、その種類の決定が指定しなければならないものを示して終わります。

レンダーステージのポリシーアダプター

レンダーステージのアダプターは、ビルドの IR グラフではなくレンダリングされた出力について推論します。レンダーペイロードは、出力された成果物(それぞれの出力パスとレンダリングされた内容、および該当する場合はレンダリングされた形式とその解析済みの構造化ビュー)に加えて、アタッチメント自身の sources と settings(それぞれアタッチメントが宣言している場合)を運びます。アダプターは対象とする出力形状に応じてその内容を読み取り、構造化された結果に対してポリシーを評価し、その結果を halt / warn / info の判定にマッピングします。ペイロード自体は出力形状を指定しないため、1 つのアダプターパターンであらゆるレンダーターゲットに対応できます。新しい出力形状は新しいアダプターであり、ホストの変更ではありません。

各レンダーステージのアダプターは、上で述べた意味でのアダプターです。外側に向かっては Aggrega ABI を話し、内側ではターゲット固有の形式や外部のポリシーエンジンの契約を吸収するため、コンパイラは出力形式やポリシーのロジックを一切持たずに済みます。コンパイラ内の Rego エンジンと CEL エンジンは render-verdict ロールを直接担います。それらに加えて、一般的な出力形状ごとに 1 つずつ、2 つのリファレンスのレンダーステージアダプターが、プラグイン開発キットの Rust サンプルの中に実例として同梱されています。

../examples/policy-render-verdict/ は、4 つのターゲット(Kubernetes オブジェクト、Docker Compose ファイル、Terraform のルート構成、CloudFormation テンプレート)の出力に対して render-verdict で 1 つのルールをアタッチします。このルールはコンパイラ内の各エンジン向けに 1 回ずつ書かれており、各ターゲットに仕込まれた違反がビルドを停止させ、対照が通過することを確認します。

独自のアダプターを書くには、この役割でも他の役割でも、各プラグイン開発キットに同梱されているガバナンスアダプターのスケルトンから始めます。独自のガバナンスプラグインを書く では、スケルトンから、それが拒否するビルドまでを順に説明しています。

YAML、JSON、Terraform HCL の出力 — リファレンス Rego レンダーアダプター

リファレンス Rego レンダーアダプターは、オペレーターが提供する Rego を、あらゆる YAML または JSON のレンダー出力、および Terraform のネイティブ HCL 出力に対して実行します。これはレンダーステージの形状の実例です。コンパイラ内のエンジンと同じ Wasm ネイティブの Rego エバリュエーターを使い、同じ deny / warn / audit の収集の慣例を同じ 3 つの判定の重大度にマッピングし、ビルドグラフではなくレンダリングされたファイルについて推論します。

YAML/JSON のターゲット全体にわたって、出力形状に依存しません。アダプターは各成果物の内容を 1 つ以上の YAML または JSON ドキュメントとして解析し(YAML は JSON のスーパーセットであるため、CloudFormation スタックのような JSON テンプレートも同じパーサーで解析されます)、解析済みのドキュメントを生の内容とともにポリシーに公開します。ポリシーは通常の Rego で、そうしたターゲットの構造化されたレンダー出力について推論します。input.artifacts[_].documents[_] は解析済みのドキュメント(Docker Compose ファイルの services、CloudFormation テンプレートの Resources)を、input.artifacts[_].content は生のテキストを返し、アタッチメントの settings オブジェクトは Rego の data ドキュメントになります。たとえば Docker Compose 出力に対する承認済みレジストリを要求するポリシーは、イメージにレジストリのプレフィックスがないサービスをすべて拒否します。

このアダプターは Terraform のネイティブ HCL のレンダー出力についても推論します。ネイティブの .tf ファイルは YAML でも JSON でもないため、アダプターはそれを Terraform-JSON(.tf.json)ファイルが解析されるのと同じ正規のオブジェクトに射影します。ポリシーはリソース属性を input.artifacts[_].documents[_].resource.<type>.<name>.<attr> で読み取ります。RDS インスタンスであれば input.artifacts[_].documents[_].resource.aws_db_instance[_].allocated_storage です。コンパイラがどちらの Terraform 形式を出力しても、読み取り方は同じです。属性の型は保持され(数値は数値、真偽値は真偽値のまま)、解決されていない Terraform の式は ${ ... } 形式の文字列のままです。Terraform-JSON の本体 (.tf.json、.auto.tfvars.json)は YAML/JSON の経路でそのまま解析されます。Terraform テンプレートファイル(.tftpl)は単独の設定ではなくテンプレートのテキストであるため射影されず、他の非構造化コンテンツと同様に parse_error を出します。

この一覧はアダプターのパーサーが受け付けるものを示しており、コンパイラが出力するものではありません。 両者は同じ集合ではなく、自動読み込みされる変数ファイルがその違いの現れる例です。コンパイラはどの経路でもそのようなオーバーレイを出力しません(ソースされたモジュールの入力は、境界のルート設定にあるそのコンポーネントのモジュールブロックの引数です)。そのため、この形状がポリシーの視野に入るのは、ベンダリングされたモジュールが独自に同梱している場合のみで、ソースされた経路がそれを出力にそのままコピーします。コンパイラがそれを生成すると想定して書かれたポリシーは、決して発火しません。

成果物の内容が解析できない場合、アダプターはそれを黙って許可しません。生の内容を保持し、その成果物については解析済みドキュメントを公開せず、パーサーのメッセージを input.artifacts[_].parse_error に記録するため、ポリシーは不正な成果物に対して明示的にビルドを停止できます。コンパイラ内の Rego エンジンと同様に、埋め込みのエバリュエーターが実装していない組み込み関数を呼ぶポリシーは明示的に失敗します。プラグインを名指しするフォールトとなり、黙って許可されることはありません。

Kubernetes の出力 — Kubewarden レンダーアダプター

Kubewarden レンダーアダプターは、Kubewarden 形式のアドミッションポリシーを、レンダリングされた Kubernetes マニフェストに対して実行します。Kubernetes の admission-review の契約を内側で吸収します。Kubewarden のポリシーは単一のオブジェクトを包んだリクエストを受け取り、受理または拒否のレスポンスを返します。レンダーステージでは、ビルドの出力はすでに Kubernetes リソースの集合そのものであるため、このステージはアドミッション形式のポリシーを実行する自然な場所です。アダプターはレンダリングされた各オブジェクトについて、解析済みのオブジェクト自体からアドミッションのフィールドを導出し、ゲスト内でそのオブジェクトを admission-review 形式のリクエストに包み、ポリシーを実行し、レスポンスを判定にマッピングします。拒否は 1 つの判定になり、受理は何も出力しません。同梱のリファレンスポリシーはラベル必須のルールで、すべてのオブジェクトが settings で指定されたラベルキーを持つ必要があります。これは Kubewarden の一般的なパターンです。

レンダーステージのアダプターに共通する範囲

  • レンダーステージ、アダプターごとに 1 つの出力形状。 レンダーステージのアダプターは IR グラフではなくレンダリングされた成果物について推論し、自身が解析する出力形状を対象とします。リファレンス Rego レンダーアダプターでは YAML/JSON と Terraform のネイティブ HCL、Kubewarden アダプターでは Kubernetes オブジェクトです。グラフステージのポリシーや、同梱のどのアダプターも解析しない出力形状に対するポリシーは、別のゲストになります。
  • 検証のみ。 レンダーステージのアダプターは受理または拒否を行い、変更されたオブジェクトを返すことはありません。変更を行うポリシーの変更後のオブジェクトは無視されます。コンパイラがポリシーの判定に基づいてレンダリング済みの出力を書き換えることはありません。ポリシーは判断するものであり、編集はしません。

ポリシーのアタッチ

オペレーターは、ワークスペース設定(.aggrega-config.yaml)の plugins.governance リストを通じてガバナンスプラグインをアタッチします。各エントリは、プラグイン、それをアタッチする role、および任意でそのルールと調整値を供給する with チャネルを指定します。

plugins:
governance:
- uri: <resolvable-plugin-reference>
role: ir-verdict
with:
sources:
- ./policies/replicas.rego
settings:
max_replicas: 3

uri はプラグインに解決されます。ホストはビルド時に各 sources ファイルを読み込んでそのバイト列をゲストに渡し、settings はそのまま受け渡します。ガバナンスプラグインがアタッチされていないビルドではソケットは何もしない処理として実行されるため、アタッチはワークスペースに対して純粋に追加的なものです。

複数のロールを担う 1 つのプラグインは、ロールごとに 1 回ずつアタッチし、各アタッチメントはそれぞれ独自のルールと独自の設定を持ちます。

plugins:
governance:
- uri: governance/rego:<version>
role: label-transform
with:
sources:
- ./policies/tagging.rego
- uri: governance/rego:<version>
role: ir-verdict
with:
sources:
- ./policies/topology.rego
settings:
translation:
- key: blocked
severity: halt

アタッチメントが指定するバージョン。uri は Plugin エンティティを指定します。すなわち <pluginType>/<name> の座標と、コロンの後のバージョンであり、バージョンは解決に関与します。CLI にコンパイルされた 2 つのエンジンでは、エンティティは 2 つの場所のいずれかから来ます。コンパイラの各リリースは、governance/rego と governance/cel の Plugin エンティティを自身のバージョンで公開し、標準ライブラリのカタログは、それぞれを公開したリリースのバージョンでそれらを収録しています。ワークスペースは、自身が列挙するカタログディレクトリからそれらを読み取ります。aggrega バイナリは、それぞれのエンティティを 1 つずつ、自身のリリースのバージョンでのみ持ちます。どちらも持たず、どの pull もコンテンツキャッシュに取得していないバージョンを指定したアタッチメントは、E0137 で参照を示してビルドを停止します。

したがって、アタッチメントはワークスペースが読むカタログが持つバージョンを指定します。そのバージョンは、自身以外の aggrega のリリースでもカタログから解決されます。一方、バイナリだけが持つバージョン(自身のリリースのバージョン)は、そのリリースでのみ解決されます。これは判定の役割でも変換の役割でも同じです。変換の役割では、pull は解決したバージョンをロックファイルに固定し、ワークスペースが読むカタログもバイナリも持たないバージョンを E0103 で拒否します。バージョンが選択するのは、プラグインのエクスポートとランタイム制限を記録する Plugin エンティティであり、エンジンではありません。参照が解決されると、実行されるエンジンはビルドを実行しているバイナリにコンパイルされたものです。バイナリに組み込まれたプラグインが、プラグインのモジュールを最初に読み取る場所だからです。ワークスペースが自ら宣言するガバナンスプラグイン(自身のカタログディレクトリにある Plugin エンティティと、その横の .wasm)は、そのエンティティが記録するバージョンで指定します。

各ロールはデフォルトのエントリ関数を選択します。グラフを判定するロールには verdict_ir、レンダリングされた成果物を判定するロールには verdict_render、ラベルを整形するロールには mutate、アノテーションを注入するロールには transform_annotations です。アタッチメントは function: でロールを別のエクスポートに向けることもできます。ホストは、ゲストが describe() の自己申告で宣言していないエクスポートへのディスパッチを拒否するため、ゲストが担わないロールを指定したアタッチメントは、何もせずに終わるのではなく、ゲストの実行前に名前付きで報告されます。

function: は、uri が指定するプラグイン上のエクスポートを指定します。判定ロール(ir-verdict または render-verdict)のアタッチメントで、function: を指定していて uri: を指定していないものは、どのプラグインにも属さない関数を指定していることになるため、設定は読み込まれた時点で E0224 として拒否され、ファイルとリスト内でのエントリの位置が示されます。その関数をエクスポートするプラグインの uri を追加してください。

plugins.governance リストには追加用の対となる plugins.governance_append があります。この対のエントリは各設定レイヤーで解決済みの governance リストに連結されるため、ワークスペースやグローバル設定は、ベースリストを覆い隠すのではなく、ポリシーのアタッチメントを合成します。

CI が所有するオーバーレイ

手書きの .aggrega-config.yaml とは別に、自動化パイプラインは独立したオーバーレイファイル .aggrega-config-append-ci.yaml を所有できます。これは、開発者が手書きしたベース設定を一切編集することなく、パイプラインが自身の管理するポリシー(またはその他のリスト値の設定)をアタッチできるようにするためのものです。パイプラインは自身のオーバーレイファイルを丸ごと上書きしてもかまいません。

オーバーレイは厳密に追加的です。ベースファイルと同じ設定スキーマに対して検証され、リスト値の各フィールドについて、そのエントリが解決済みのリストに連結されます。できるのは追加のみです。ベースのエントリを削除することも、ベースの値をスカラーで上書きすることもできません。オーバーレイに含まれるスカラーやマップのキーには追加としての意味がないため、適用されずに無視されます(解決時の警告でその名前が示されます)。また、オーバーレイがワークスペースのルートを定めることはありません。それを行うのは workspace: ブロックを持つ .aggrega-config.yaml のみであるため、オーバーレイをディレクトリに置いても、ワークスペースの開始位置を変えずにアタッチメントが追加されます。

これにより、パイプラインは組織全体のポリシーを適用するための明確な境界を得ます。パイプラインが必須のポリシープラグインを指定した .aggrega-config-append-ci.yaml を配置すると、それらのアタッチメントは開発者が記述した内容を置き換えるのではなく、その上にマージされます。

# .aggrega-config-append-ci.yaml — owned by the pipeline, additive only
plugins:
governance_append:
- uri: <organization-policy-plugin-reference>
role: render-verdict
with:
settings:
required_label: app.kubernetes.io/name

examples/policy-org-overlay/ は、チームのアタッチメント、グローバル構成ファイルの governance_append で追加された組織のアタッチメント、そしてこのオーバーレイで追加されたパイプラインのアタッチメントを持つ 1 つのワークスペースをビルドし、各組み合わせが何を出力し、完了するかどうかを確認します。

ビルドをゲートする前にポリシーをテストする

役割のペイロードが持たないパスを指定する Rego ルールはエラーにはなりません。パスは未定義となり、ルールは決して成立せず、ビルドはポリシーが許可したかのように完了します。そのため、新しいポリシーは 3 つの手順を経て halt に至らせます。停止せずに報告する重大度でアタッチし、指定するすべてのパスをその役割が受け取るペイロードと照合し、判定対象となるビルドで何を報告するかを読みます。

以下のコマンドは、examples/policy-org-overlay/ のコピーで実行します。そのコピーの .aggrega-config.yaml は、チームのポリシーの代わりに新しいポリシーを 1 つアタッチしています。このポリシーは高可用性を無効にして稼働するデータストアを拒否するためのもので、そのルールはラベル整形のポリシーからコピーされました:

package datastores
import rego.v1
deny contains msg if {
some id, node in input.graph.nodes
node.labels["component.aggrega.ai/category"] == "datastore"
input.graph.spec.infra_mapping[id].ha.enabled == false
msg := sprintf("%v is a datastore running with high availability off", [id])
}

**報告するようにアタッチします。**このポリシーは deny の下に収集し、これはデフォルトでビルドを停止します。deny のみを warn で指定する translation は、その各決定を警告として報告し、ビルドを完了させます。info では代わりに記録します。ポリシー自体は、強制されるときのままにしておきます:

plugins:
governance:
- uri: governance/rego:0.9.0
role: ir-verdict
with:
sources:
- policies/datastore-ha.rego
settings:
translation:
- key: deny
severity: warn

**ペイロードを書き出し、その中でパスを調べます。**ビルドが Release のロックファイルを埋めた後、

Terminal window
aggrega build --release release.yaml --dry-run --policy-input payloads

は、各役割がアタッチメントに渡すペイロードを payloads/ に書き込み、それ以外は何も書かずに、次のように報告します(<workspace> はビルドを実行したディレクトリを表します):

policy input: 4 file(s) written to <workspace>/payloads
[… omitted: a lint notice about core/secret-value, the rendered files the run prints in place of writing them, the build's time, and the line saying only the policy inputs were written]

4 つのファイルは annotation-transform.json、ir-verdict.json、label-transform.json、render-verdict.json です。何もアタッチされていない役割のファイルも書き出されるため、ポリシーはどこかにアタッチする前に、その役割に対して確認できます。ir-verdict、label-transform、annotation-transform では、このファイルがポリシーの読む input ドキュメントそのものであるため、ルールを信頼する前に、ルールが指定する各パスを任意の JSON ツールで読み出せます:

Terminal window
jq '.graph.nodes' payloads/ir-verdict.json
# null
jq -c '.graph.spec.nodes | keys' payloads/ir-verdict.json
# ["db","web"]
jq -c '.graph.spec.infra_mapping.db.ha' payloads/ir-verdict.json
# {"enabled":false,"read_replicas":0}

ルールのノードはそこにはありません。input.graph.nodes はラベル整形の役割がノードを持つ場所であり、ir-verdict ではノードは input.graph.spec.nodes にあります(各役割のペイロードが公開するもの を参照)。ファイルは、修正したルールが何を決定すべきかも示しています。db はデータストアで、その高可用性は無効であり、報告されるべきです。

OPA がインストールされている環境では、Rego ポリシーを同じファイルに対して直接評価できます:opa eval -i payloads/ir-verdict.json -d policies/datastore-ha.rego 'data.datastores.deny'。コンパイラ内の Rego エンジンは独立した実装であるため、判断を下すのは依然としてビルドでの評価です。エンジンが実装していない組み込み関数は、評価されるのではなくビルドを停止させます。

render-verdict では、このファイルはポリシーの input ではありません。その中の各アーティファクトは path、content、format を持ちます。ルールが読む documents は、ポリシーエンジンがペイロードを受け取った時点で内容から解析されるため、documents を対象とするルールはこのファイルの中に何も見つけません。この役割のポリシーは、エンジンがそれらを解析する場所、つまり次の手順で示すようにビルドの中でテストします。

**ビルドし、報告内容をペイロードの内容と比較します。**コピーしたパスのままでは、

Terminal window
aggrega build --release release.yaml --auto-pull

は完了し、何も報告しません:

Pull 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]

ペイロードには高可用性が無効のデータストアがあるのに、ポリシーはそれについて何も言いませんでした。この沈黙こそが誤りであり、ビルドの中にそれを指し示すものは他に何もありません。ルールが input.graph.spec.nodes を読むようにすると、同じコマンドは db を報告して完了します:

policy plugin "rego" warning: db is a datastore running with high availability off
Pull 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]

--dry-run を追加すると、同じ判定を報告し、dist/ を書き出さないため、ワークスペースの出力を乱さずにこのループを実行できます。

CEL エンジン向けに書かれた同じルールは、黙って失敗することはありません。そこではペイロードが持たないキーを読むことは評価フォールトになるため、同じ translation でアタッチされた policies/datastore-ha.cel にコピーしたパスを置くと、

{
"deny": input.graph.nodes
.filter(n, input.graph.nodes[n].labels["component.aggrega.ai/category"] == "datastore"
&& input.graph.spec.infra_mapping[n].ha.enabled == false)
.map(n, n + " is a datastore running with high availability off"),
}

は warn であってもビルドを停止します。終了コードは 1 で、最後の行はポリシーファイルとキーを示します:

ir-verdict: plugin "governance/cel:0.9.0": call "verdict_ir": wasm: plugin "cel" call to verdict_ir: policy source "datastore-ha.cel" could not be evaluated: No such key: nodes

render-verdict のポリシーも同じ方法でテストします。同じワークスペースで同じ translation を使って render-verdict にアタッチした、ホストでポートを公開する Compose サービスを拒否するルール

package published
import rego.v1
deny contains msg if {
some artifact in input.artifacts
some doc in artifact.documents
some name, service in doc.services
count(service.ports) > 0
msg := sprintf("%v publishes a port on the host", [name])
}

は、該当する 1 つのサービスを報告します:

policy plugin "rego" warning: web publishes a port on the host
[… omitted: the pull's line, a lint notice about core/secret-value, the build's time and the line naming the dist/ directory it wrote]

その後、強制します。translation を削除すると deny は halt に戻り、db を報告していたビルドはそこで停止し、1 で終了し、dist/ を書き出しません:

[… omitted: the lines printed while the lockfile is resolved, which carry the refusal below once more, and a lint notice about core/secret-value]
[POLICY_ERROR E0005]
policy plugin "rego" rejected the build: db is a datastore running with high availability off
caused by: policy violation

報告用のアタッチメントを一度にすべての場所から削除する必要はありません。ある構成ファイルではアタッチメントの translation を warn のままにしつつ、パイプラインのオーバーレイでは同じポリシーを deny を halt にしてアタッチできます。examples/policy-org-overlay/ は、このようにして組織のルールを展開しています。開発者のビルドでは警告となり、パイプラインのビルドでは停止の理由となります。

CI でビルド出力に対してポリシーを実行する

ここまでの内容はすべて、ビルドの内部でポリシーをアタッチするものです。もう一つの経路があり、こちらはソケットを一切必要としません。ビルドが書き出したファイルに対して、パイプライン内で独自のツールを実行します。

これが機能するのは、ビルドが出力するものによります。Kubernetes と Compose のターゲットは YAML を書き出し、Terraform ターゲットはネイティブの HCL、または .tf.json 形式の JSON を書き出します。 これらはエコシステムの設定ツールがすでに読み込める形式です。また、 aggrega build はラッパー形式もインデックスもなく、展開すべきものもない、プレーンなファイルをディレクトリに書き出します。そのため、YAML、JSON、HCL を読むツールは、人が手で書いた設定に対して実行するのと同じ方法でビルド出力に対して実行でき、Aggrega はそのためのソケットも、プラグインの種類も、設定キーも追加しません。

したがって、既存のルール群を移植する必要はありません。Conftest、 Kyverno CLI、kubeconform、Checkov、OPA ですでにルールを管理している場合、それらのルールはそのまま Aggrega のビルド出力に対して実行でき、評価するツールはパイプラインにすでにインストールされているものです。

すぐに使えるルールスクリプト 2 つが、それぞれを呼び出すパイプラインステップと、実際のビルドに対して出した 2 件の拒否結果とともに、examples/policy-in-ci/ にあります。これらは yq だけを使うため、ポリシーツールチェーンをインストールしなくても実行できます。示されている形、すなわち出力ディレクトリを読み、判定し、問題のある成果物を名指しして非ゼロで終了するという形は、この位置に置かれるどのツールにも共通する形です。

ルールがどちらの経路に属するか

どちらの経路も第一級のもので、ワークスペースでは両方を使うのが一般的です。決め手となるのは、ルールが何を見る必要があり、いつ動作する必要があるかです。

次の場合はソケットにアタッチします:

  • ビルドが成果物をまったく生成してはならない場合。 ir-verdict ポリシーは 静的解析ゲートで、何かがレンダリングされる前に実行されるため、そこで停止すれば 何も書き出されません。レビューや隔離の対象となる出力ファイルも、誤って適用される出力ファイルも残りません。パイプラインでのチェックは、必然的にファイルが存在した後に実行されます。
  • ルールがビルドだけが持つ事実を必要とする場合。 ir-verdict ロールは 組み立てられたグラフを読みます。ノード、エッジとそのソケット、埋めたスロットを伴うすべてのアタッチメント、作成者が機密と宣言した値、ルーティングパスです。これらは いずれもレンダリングされた出力には残りません。Kubernetes の manifest は、どのソケットが値を届けたか、どの Feature がリソースを提供したかを記録しません。そのため、トポロジーや来歴に関するルールの置き場所は一つだけであり、それがソケットです。
  • ビルドがどこで実行されてもルールが成り立つ必要がある場合。 ガバナンスのアタッチメントは ワークスペース設定に置かれるため、パイプラインのビルドと同様に開発者のローカルビルドにも適用されます。パイプラインでのチェックは、パイプラインが実行される場所で適用されます。
  • ルールがビルドを判定するのではなく形作るべき場合。 それを行うのは transform ロールだけであり、 それもオペレーターがアタッチした場合に限られます。

次の場合は CI で実行します:

  • ルールがすでに存在する場合、つまりチームが実行・レビューしているツールの中に、 そのツールがすでに解析できる形式に対するルールとしてある場合です。それをソケットのポリシー内容として書き直しても、 作業が増えるだけで新たなカバレッジは得られません。
  • ルールがターゲットが受け取る形の成果物に関するものである場合。つまり、すべての transform を経た後の、 適用される形式での最終的なファイル群です。これは render-verdict ロールの対象でもあるため、この点だけで言えば 2 つの経路は同じものを見ており、選択は他の点で決まります。
  • 検出結果がビルドではなくレビュアー向けである場合。 成果物と検出結果を並べて公開するパイプラインは、 レビュアーに両方を提供します。停止したビルドが提供するのはメッセージだけです。
  • チェックが 1 つのビルドを超える範囲に及ぶ場合。たとえば、このビルドの出力を 前回のビルドの出力、クラスターのライブ状態、あるいはどのビルドのペイロードにも含まれないインベントリと比較する場合です。いずれの verdict ロールのポリシーも、アタッチされたビルドを見るだけであり、それ以外は見ません。

2 つの経路は競合するのではなく組み合わされます。トポロジーの不変条件が ir-verdict でビルドを停止させ、同じパイプラインがその後、そのビルドが書き出したものに対して既存の成果物ルールを実行します。

相互参照

  • plugin-contract.md — ソケットのパイプライン上の位置、 ソケットが運ぶ型付きのワイヤ形式、およびすべてのプラグインが実行されるサンドボックス。
  • plugin-developer-guide.md — プラグインの作成、 describe() による自己申告、および publish → pull → build のライフサイクル。
  • ../entities/plugin.md — プラグインをカタログに取り込む Plugin エンティティ。
  • ../cli/aggrega-build.md — ソケットをディスパッチする build コマンド。
  • ../schema/other/aggrega-config.md — plugins.governance のアタッチ面を含む、ワークスペース設定のスキーマ。
  • ../examples/policy-in-ci/ — ビルドの出力に対して実行できる 2 つのルールスクリプトと、それぞれのパイプラインステップ。
  • ../examples/policy-data-class-route/ — ルートに対する 1 つの ir-verdict ルールを、Rego エンジン、CEL エンジン、およびリファレンスアダプターゲストの背後にある OPA 向けに記述し、エンジンごとに 1 つの --config ファイルでビルドごとにアタッチしたもの。3 つすべてがすべての Release で同じ結果に達することを確認するスクリプトが付属します。