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 用于指定无需执行政策的容器映像许可名单。您可以在 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

系统政策评估模式政策设置会使 Binary Authorization 先评估系统政策，然后再评估配置的政策。系统政策由 Google 提供，Binary Authorization 不会对 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 资源。将来可能需要使用其他映像路径。这些路径还需要添加到 admissionWhitelistPatterns 许可名单中，GKE 集群才能按预期运行。

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：要求一个或多个证明者在部署之前对版本进行授权

如果 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