ポリシー YAML リファレンス

注: このドキュメントでは、Google が不快感を与えるコンテンツまたは不適切なコンテンツと見なす用語が使用されています。これらの用語は、ドキュメントで説明するソフトウェアでキーワードとして使用されているため、こうした用語について言及しています。

キーワード: whitelist

このページには、YAML 形式の Binary Authorization ポリシーのリファレンス情報が記載されています。コマンドライン インターフェースを使用してポリシーを構成する場合は、この仕様に準拠した YAML 形式のファイルを編集します。YAML 形式のポリシーの例については、サンプル ポリシーをご覧ください。

ポリシー YAML ファイルの形式は次のとおりです。

name: projects/<PROJECT_ID>/policy
admissionWhitelistPatterns:
- namePattern: <MATCHING_PATTERN>
- ...
globalPolicyEvaluationMode: <GLOBAL_EVAL_MODE>
defaultAdmissionRule:
  <ADMISSION_RULE>
clusterAdmissionRules:
  <CLUSTER_SPECIFIER>:
    <ADMISSION_RULE>
  ...

ノード

YAML 形式の最上位ノードは次のとおりです。

ノード	説明	必須
name	ポリシーの名前。	○
admissionWhitelistPatterns	常にデプロイを許可するコンテナ イメージを指定します。	×
globalPolicyEvaluationMode	Google 所有のシステム イメージを除外するシステム ポリシーを適用するかどうかを指定します。	×
defaultAdmissionRule	特にルールが適用されない場合に使用するルール。	○
clusterAdmissionRules	特定のクラスタに適用するルールを指定します。	×

name

name ノードには、次の形式でポリシーの名前が含まれます。

name: projects/PROJECT_ID/policy

ここで、PROJECT_ID は、ポリシーが定義されている Google Cloud プロジェクトの名前です。

例:

name: projects/example-project/policy

admissionWhitelistPatterns

注: admissionWhitelistPatterns を使用して Google 管理のシステム イメージを許可リストに登録することはおすすめしません。globalPolicyEvaluationMode が ENABLE（デフォルト設定）に設定されている場合、Google 管理のシステム イメージを使用できます。詳しくは、globalPolicyEvaluationMode をご覧ください。

admissionWhitelistPatterns は、ポリシーの適用対象外のコンテナ イメージの許可リストを指定します。Container Registry と Artifact Registry のイメージへのパス、別のレジストリ、または namePattern サブノード内のローカル参照を指定します。

admissionWhitelistPatterns:
  - namePattern: MATCHING_PATTERN
  - ...

MATCHING_PATTERN は、単一のイメージのパス、またはワイルドカード記号（*、**）のいずれかを含む一致パターンに置き換えます。

ワイルドカードはパターンの最後でのみ有効です。たとえば、gcr.io/my-project/nginx* は有効なパターンですが、gcr.io/my-project/n*x は無効です。ワイルドカード * は、指定されたディレクトリ内のイメージにのみ一致します。たとえば、gcr.io/my-project/nginx* は gcr.io/my-project/nginx:latest と一致しますが、gcr.io/my-project/nginx-images/nginx とは一致しません。ワイルドカード ** を使用すると、サブディレクトリ内のイメージが一致します。たとえば、パス gcr.io/my-project/nginx** は gcr.io/my-project/nginx-1.14.2/image:latest と一致します。

注意: ワイルドカード ** をプロジェクト ID に使用する場合は、異なるプロジェクトのイメージとも一致することに注意してください。たとえば、パス gcr.io/my-project** を使用すると、gcr.io/my-project/nginx と gcr.io/my-project-exploit/nginx-exploit の両方のイメージがデプロイされます。

次の例では、よく使用される Google Kubernetes Engine（GKE）イメージ、gcr.io/example-project/helloworld にあるイメージ、イメージへのローカル参照を含むレジストリをポリシーの除外イメージリストに追加します。

admissionWhitelistPatterns:
  - namePattern: gcr.io/google-containers/*
  - namePattern: k8s.gcr.io/**
  - namePattern: gke.gcr.io/**
  - namePattern: gcr.io/gke-release/asm/*
  - namePattern: gcr.io/stackdriver-agents/*
  - namePattern: gcr.io/example-project/helloworld
  - namePattern: loc-ref

注: この例には、GKE がクラスタを起動するために必要なイメージが含まれています。globalPolicyEvaluationMode が無効になっている場合は、それらを含める必要があります。

許可リストパターン

注: イメージのローカル参照にも同じルールが適用されます。

レジストリの場所が指定したパスと一致するコンテナ イメージをすべて許可リストに登録するには:

admissionWhitelistPatterns:
  ...
  - namePattern: gcr.io/example-project/*

特定のイメージを許可リストに登録するには:

admissionWhitelistPatterns:
  ...
  - namePattern: gcr.io/example-project/helloworld

現在タグ付けされているバージョンを許可リストに登録するには:

admissionWhitelistPatterns:
  ...
  - namePattern: gcr.io/example-project/helloworld:latest
  - namePattern: gcr.io/example-project/helloworld:my-tag
  - namePattern: gcr.io/example-project/helloworld:v1.*

特定のバージョンのイメージをダイジェストで許可リストに登録するには:

admissionWhitelistPatterns:
  ...
  - namePattern: gcr.io/example-project/helloworld@sha256:77b0b75136b9bd0fd36fb50f4c92ae0dbdbbe164ab67885e736fa4374e0cbb8c

特定のパスのサブディレクトリにあるイメージを許可リストに登録するには:

admissionWhitelistPatterns:
  ...
  - namePattern: gcr.io/example-project/**

globalPolicyEvaluationMode

システム ポリシー評価モードは、Binary Authorization に構成するポリシーを評価する前に、システム ポリシーを評価するポリシーの設定です。システム ポリシーは Google から提供されるものです。Google 管理のシステム イメージのリストは以降のポリシー評価から除外されます。この設定を有効にすると、GKE で必要なイメージはポリシーの適用でブロックされません。admissionWhitelistPatterns を含め、システム ポリシーはユーザー ポリシーより先に評価されます。

Google 管理のすべてのシステム イメージを許可するには、globalPolicyEvaluationMode プロパティを ENABLE に設定します。

globalPolicyEvaluationMode: ENABLE

システム ポリシー評価モードを無効にするには、次のように設定します。

globalPolicyEvaluationMode: DISABLE

注: globalPolicyEvaluationMode はデフォルト設定の ENABLE のままにしておくことをおすすめします。GKE が正常に機能するには、クラスタ内で多くのシステム イメージを実行する必要があります。globalPolicyEvaluationMode を有効にすると、GKE のリリースごとに Google 管理のシステム イメージの許可リストが自動的に更新されます。システム イメージは admissionWhitelistPatterns で管理できますが、許可リストが最新の状態でないと、更新されたシステム イメージの実行が許可されない場合があります。

注: globalPolicyEvaluationMode を無効にする場合は、パス gcr.io/google-containers/*、k8s.gcr.io/**、gke.gcr.io/*、gcr.io/gke-release/someproject/*、gcr.io/stackdriver-agents/* が admissionWhitelistPatterns 許可リストに含まれている必要があります。これらのパスには、GKE がクラスタを正常に起動するために必要な Google Cloud リソースが含まれています。今後、追加のイメージパスが必要になる場合があります。GKE クラスタを想定どおり動作させるため、これらのパスも admissionWhitelistPatterns 許可リストに含める必要があります。

defaultAdmissionRule

defaultAdmissionRule には、ポリシーのデフォルト ルールを指定します。デフォルト ルールは、対象のすべてのコンテナ イメージに適用される制約を定義するルールです。ただし、クラスタ固有の独自のルールがあるものは除きます。デフォルト ルールは、ADMISSION_RULE コレクションで指定します。

defaultAdmissionRule:
  ADMISSION_RULE

次の例は、指定した認証者によって承認されたコンテナ イメージのみをデプロイするデフォルト ルールを示しています。必要なすべての認証者がイメージを承認していない場合、Binary Authorization はデプロイをブロックし、監査ログに書き込みます。

defaultAdmissionRule:
  evaluationMode: REQUIRE_ATTESTATION
  enforcementMode: ENFORCED_BLOCK_AND_AUDIT_LOG
  requireAttestationsBy:
  - projects/example-project/attestors/secure-build

clusterAdmissionRules

clusterAdmissionRules は、ポリシーでクラスタ固有のルールを宣言します。これらのルールの制約は、指定したクラスタにのみ適用されます。Binary Authorization がクラスタ固有のルールをデプロイに適用した場合、デフォルト ルールは考慮されません。デフォルト ルールと同様に、ADMISSION_RULE コレクションを使用してクラスタ固有のルールを指定します。

clusterAdmissionRules:
  CLUSTER_SPECIFIER:
    ADMISSION_RULE

CLUSTER_SPECIFIER は、ルールが適用されるクラスタのリソース ID です。形式は location.name です（例: us-east1-a.prod-cluster）。

次の例は、指定した認証者によって承認されたコンテナ イメージのみをデプロイするクラスタ固有のルールを示しています。

clusterAdmissionRules:
  us-east1-a.prod-cluster:
    evaluationMode: REQUIRE_ATTESTATION
    enforcementMode: ENFORCED_BLOCK_AND_AUDIT_LOG
    requireAttestationsBy:
    - projects/example-project/attestors/secure-build
    - projects/example-project/attestors/prod-qualified

ノード コレクション

ADMISSION_RULE

ADMISSION_RULE は、ルールの制約を指定するノードのコレクションです。形式は次のとおりです。

evaluationMode: EVAL_MODE
enforcementMode: ENFORCEMENT_MODE
requireAttestationsBy:
- ATTESTOR
- ...

defaultAdmissionRule と clusterAdmissionRule の両方がこのコレクションを参照します。

evaluationMode

evaluationMode は、コンテナ イメージをデプロイするかどうかを評価するために Binary Authorization が実行するオペレーションを指定します。使用できる値は次のとおりです。

• ALWAYS_ALLOW: このルールで評価されるイメージのデプロイを常に許可します。
• ALWAYS_DENY: このルールで評価されるイメージのデプロイを常に拒否します。
• REQUIRE_ATTESTATION: デプロイする前に、1 人以上の認証者がリリースを承認する必要があります。

evaluationMode が REQUIRE_ATTESTATION の場合、requireAttestationsBy で必要な認証者への参照を提供する必要があります。

enforcementMode

enforcementMode は、コンテナ イメージがルールで定義された制約を遵守していない場合に、Binary Authorization が実行するアクションを指定します。使用できる値は次のとおりです。

• ENFORCED_BLOCK_AND_AUDIT_LOG: デプロイをブロックして監査ログに書き込みます。
• DRYRUN_AUDIT_LOG_ONLY: 遵守していないイメージのデプロイを許可し、違反の詳細を監査ログに書き込みます。

ほとんどの本番環境のルールでは、ENFORCED_BLOCK_AND_AUDIT_LOG 適用モードが使用されます。DRYRUN_AUDIT_LOG_ONLY は主に、ポリシーを有効にする前に環境内でテストする場合に使用します。

requireAttestationsBy

requireAttestationsBy には、コンテナ イメージをデプロイする前にリリースを承認する必要がある認証者を指定します。これは REQUIRE_ATTESTATION ルールでのみ必要です。このノードの形式は次のとおりです。

requireAttestationsBy:
  - projects/PROJECT_ID/attestors/ATTESTOR_NAME
  - ...

PROJECT_ID は認証者が定義されているプロジェクトの名前で、ATTESTOR_NAME はリリースに署名する必要がある認証者の名前です。

次の例は、認証者の指定方法を示しています。

requireAttestationsBy:
- projects/example-project/attestors/secure-build
- projects/example-project/attestors/prod-qualified