CI でのポリシー: ビルド出力に対して
Aggrega のビルド出力ディレクトリを読み取り、ルールに違反している場合に拒否する、すぐに使える 2 つのルールスクリプトです。パイプライン内で aggrega build の後に、そのパイプラインが設定に対してすでに実行している他の処理と並んで実行されます。
このディレクトリは Aggrega ワークスペースではありません。Aggregate も Release もカタログエンティティも定義していません。自身のリポジトリにコピーする 2 つのスクリプトと、それぞれを呼び出すパイプラインステップから成ります。
これらが属する経路と、代わりにビルド内のガバナンスソケットが適切となる場合については、 ガバナンスソケットのページで説明しています。
2 つのルール
| スクリプト | 拒否する対象 |
|---|---|
require-pinned-image.sh | タグのないコンテナイメージ、またはタグ latest |
deny-inline-credential-material.sh | 認証情報をリテラルとして保持する、レンダリングされた Secret |
いずれも出力ディレクトリを唯一の引数として受け取り、そこにあるものをすべて走査します。どちらも、ビルドがどこで実行されたか、どのターゲットだったか、ワークスペースがどのように構成されているかについては一切関知しません。
./require-pinned-image.sh <output-directory>./deny-inline-credential-material.sh <output-directory>どちらも PATH 上に yq があることだけを必要とします。
JSON は YAML のサブセットであるため、yq は YAML ドキュメントと同じ式で JSON ドキュメントを読み取れます。そのため 1 つのスクリプトで両方の形式の出力に対応できます。
yq 以外に、このディレクトリが必要とするものはありません。カタログのチェックアウトも、aggrega バイナリも、ネットワークも不要です。./check.sh は、ビルドが出力する形で自ら書き出した小さな出力ディレクトリに対して両方のルールを実行し、各終了コードとレポートをそのディレクトリで期待されるものと比較します。一致しないものがあれば 1 で終了します。ルールを実行する対象として実際のビルドを作るには、ビルドする例が必要とするものが必要です。
終了コードは 2 つではなく 3 つ
0 no finding — the output satisfies the rule1 finding — the output breaks it, and every offending artifact is named2 cannot evaluate — bad usage, yq absent, or an artifact that does not parse3 つ目は意図的に 2 つ目と区別されています。「成果物を読み取れなかった」ことが「成果物が合格した」ことと区別できなくなってはなりません。これは、ガバナンスソケットで評価できないポリシーが許可ではなく障害として報告されるのと同じ理由です。ゼロ以外の終了をすべて失敗として扱うパイプラインは、どちらからも正しい動作を得られます。両者を区別したいパイプラインは区別できます。
何も検出しなかった実行は、どれだけの量を調べたかを示します。そのため、何にも一致しなかったルールが、一致して条件を満たしたルールと区別できない状態にはならず、見て分かるようになります。
OK: every image pinned across 3 container(s) in 43 document(s)OK: no inline credential material across 43 document(s), 1 of them credential-carryingルールの調整
各スクリプトは yq と判定を分離しており、両者が接する箇所のコメントでその旨を記しています。yq の式が各ドキュメントをタブ区切りの行に読み取り、シェル関数が各行について判定します。別のルールを表現するには、この 2 つを変更し、走査部分はそのままにします。
この分離は飾りではありません。似て見える 2 つのルールが、正反対の理由でこれを必要とします。
- キーだけでは不十分です。
ConfigMapはSecretとまったく同じようにdata:ブロックを持ちますが、ConfigMap のdata:は認証情報ではありません。そのため、キーだけでなく kind も認証情報ルールの一部になります。 - 再帰的な検索では過剰です。
CustomResourceDefinitionは独自のスキーマを宣言し、そのスキーマはimageという名前のプロパティを宣言できます。すべてのドキュメントでimageキーを検索するルールは、CRD のスキーマをピン留めされていないワークロードとして報告してしまいます。そのためrequire-pinned-image.shは 6 つの pod-spec パスを明示的に読み取り、ワークロードの kind を追加するにはパスを追加します。
サンプルを生成する
例の名前を付けた新しいフォルダーに例を書き出します。
aggrega scaffold --example policy-in-ciその後、次に実行するコマンドを表示します。最初のコマンドは新しいフォルダーに移動します。
cd policy-in-ciビルド
このフォルダーにはワークスペースがないため、ここでビルドするものはありません。./check.sh は、ビルドが出力する形で自ら書き出した小さな出力ディレクトリに対して両方のルールを実行し、それぞれの判定を確認します。
./check.sh実際のビルドに対してルールを実行するには、次のセクションのように、そのビルドの出力ディレクトリを渡します。
実行対象のビルドを作成する
このツリー内のビルド済みの例であれば、どれでも使えます。以下のコマンドは、後述の終了コードを生成したものです。
cd ../external-secrets-operatoraggrega build --release release.yamlcd ../ai-agent-and-model-routeraggrega build --release release.yamlロックファイルは同梱されず生成されるため、新しくクローンした状態には存在せず、最初のビルドで必要になります。例の概要に、これを解決する 2 つの方法が記載されています。
パイプラインステップ
以下のスニペットは GitHub Actions のものですが、この形はシェルコマンドを実行してその終了コードを読み取れるあらゆるパイプラインに適用できます。各 run: 行は、これらの終了コードを生成したコマンドです。
# every image a rendered workload runs is pinnedjobs: policy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v5 - name: Compile the Release run: aggrega build --release release.yaml --auto-pull working-directory: ai-agent-and-model-router - name: Images are pinned run: ./require-pinned-image.sh ../ai-agent-and-model-router/dist working-directory: policy-in-ci# no credential material reaches the artifacts as a literaljobs: policy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v5 - name: Compile the Release run: aggrega build --release release.yaml --auto-pull working-directory: external-secrets-operator - name: No inline credential material run: ./deny-inline-credential-material.sh ../external-secrets-operator/dist working-directory: policy-in-ci自身のリポジトリでは例のツリーではなく 1 つのワークスペースがあるため、引数はビルドの書き込み先(通常はワークスペースの隣の dist)になり、スクリプトはパイプラインツールを置いている場所に配置します。変わるのはこの 2 つのパスだけです。
各ルールが報告する内容
このディレクトリから、隣接する 3 つの例のビルドに対して実行したものです。拒否は問題のあるすべての成果物を名指しするため、パイプラインのログがそのまま指摘事項の一覧になります。
イメージがピン留めされている — Recipes がすべてのイメージをピン留めしている Release に対して:
$ ./require-pinned-image.sh ../ai-agent-and-model-router/distOK: every image pinned across 4 container(s) in 12 document(s)$ echo $?0Recipe が上流の Helm チャートを取り込み、チャート自身のイメージ参照を上書きしていない Release に対して:
$ ./require-pinned-image.sh ../advanced-platform/distREFUSED: data/helm/db-statefulset-default-db-mariadb.yaml: StatefulSet/db-mariadb container mariadb runs unpinned image registry-1.docker.io/bitnami/mariadb:latestREFUSED: data/helm/db-statefulset-default-db-mariadb.yaml: StatefulSet/db-mariadb container preserve-logs-symlinks runs unpinned image registry-1.docker.io/bitnami/mariadb:latestREFUSED: 2 finding(s) across 3 container(s) in 12 document(s)$ echo $?1インラインの認証情報がない — 唯一の Secret が値を含めてレンダリングされるのではなく、実行時にオペレーターによって埋められる Release に対して:
$ ./deny-inline-credential-material.sh ../external-secrets-operator/distOK: no inline credential material across 43 document(s), 1 of them credential-carrying$ echo $?03 つの認証情報スロットを値で埋める Release に対して:
$ ./deny-inline-credential-material.sh ../ai-agent-and-model-router/distREFUSED: helm/agent--router-zumodel-zdcredential--agent-secret-agent-router-model-credential.yaml (document 1): Secret/agent-router-model.credential carries inline material under api-keyREFUSED: helm/router--api-zukey--router-secret-router-api-key.yaml (document 1): Secret/router-api-key carries inline material under master-keyREFUSED: helm/router--provider-zukey--router-secret-router-provider-key.yaml (document 1): Secret/router-provider-key carries inline material under provider-keyREFUSED: 3 finding(s) across 12 document(s), 3 of them credential-carrying$ echo $?1最後の拒否は、環境が選択するルールであり、Release の欠陥ではありません。認証情報スロットを値で埋めることはサポートされている形です。作成者が認証情報を提供し、ターゲットがワークロードから読み取れる場所にそれをレンダリングします。コンパイラはこれについて意見を持ちません。これとは別に、作成者が機密と宣言した値がリテラルとして配信キーに渡る場合には、コンパイラは警告を出します。ただし値による認証情報のファミリーは意図的なものであるため、この警告は停止ではなく助言にとどまります。いずれにせよ、この形を禁止するのは環境の側であり、それはここか、ガバナンスソケットで表明します。2 つの経路とその選択についてはガバナンスソケットのページにあります。