政策 YAML 參考資料

注意： 本文件或章節提及一或多個 Google 認為不敬或冒犯的字詞。這些字詞是說明文件中軟體的關鍵字，因此才會使用。

條款：whitelist

本頁面提供以 YAML 格式指定的二進位授權政策參考資訊。使用指令列介面設定政策時，您會編輯符合這項規格的 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 會指定容器映像檔的允許清單，這些映像檔可免除政策強制執行。您可以在 namePattern 子節點中，指定 Container Registry 和 Artifact Registry、其他登錄檔或本機參照中的映像檔路徑：

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

系統政策評估模式是一種政策設定，可讓二進位授權先評估系統政策，再評估您設定的政策。系統政策由 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

以下範例顯示預設規則，只允許部署已由指定驗證者授權的容器映像檔。如果所有必要的驗證者都未授權映像檔，二進位授權會封鎖部署作業，並寫入稽核記錄。

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

clusterAdmissionRules

clusterAdmissionRules 宣告政策的叢集專屬規則。這些規則中的限制只會套用至指定的叢集。如果二進位授權對部署作業套用叢集專屬規則，系統就不會考慮預設規則。與預設規則相同，您可以使用 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 指定二進位授權執行的作業，以評估是否要部署容器映像檔。可能的值包括：

• ALWAYS_ALLOW：一律允許部署此規則評估的映像檔
• ALWAYS_DENY：一律拒絕部署這項規則評估的圖片
• REQUIRE_ATTESTATION：要求一或多位認證者授權發布版本，才能部署

如果 evaluationMode 為 REQUIRE_ATTESTATION，您必須在 requireAttestationsBy 中提供必要認證者的參照。

enforcementMode

enforcementMode 指定二進位授權在容器映像檔不符合規則中定義的限制時採取的動作。可能的值包括：

• 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