使用 REST API 配置政策

本页面介绍如何使用 REST API 配置 Binary Authorization 政策。作为替代方案,您还可以使用 Google Cloud CLIGoogle Cloud 控制台执行这些任务。这个步骤是设置 Binary Authorization 的一部分。

概览

政策是一组规则,用于管理一个或多个容器映像的部署。

使用 REST API 配置政策时,您需要以 JSON 格式填充值,它们的结构与 gcloud 与该服务的交互中所用的 YAML 结构相同。如需了解详情,请参阅 YAML 格式政策参考文档

配置政策时,您需要执行以下操作:

  • 导出 JSON 格式的政策文件
  • 添加任何其他豁免映像(可选)
  • 设置默认规则
  • 添加任何针对集群的规则(可选)
  • 导入 JSON 格式的政策文件

大多数实际政策都会进行检查,了解是否所有必需的证明者都已验证容器映像已准备好进行部署。在这种情况下,您还必须在配置政策时创建证明者

设置默认项目

设置默认 Google Cloud 项目(如果尚未设置):

PROJECT_ID=PROJECT_ID
gcloud config set project ${PROJECT_ID}

其中,PROJECT_ID 是项目 ID。

导出政策

本部分适用于 GKE、Distributed Cloud、Cloud Run 和 Cloud Service Mesh

将政策导出为本地系统上的 JSON 文件:

curl \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "x-goog-user-project: ${PROJECT_ID}" \
    "https://binaryauthorization.googleapis.com/v1/projects/${PROJECT_ID}/policy" \
    -o "/tmp/policy.json"

默认情况下,该文件包含以下内容:

{
  "name": "projects/PROJECT_ID/policy",
  "globalPolicyEvaluationMode": "ENABLE",
  "defaultAdmissionRule": {
    "evaluationMode": "ALWAYS_ALLOW",
    "enforcementMode": "ENFORCED_BLOCK_AND_AUDIT_LOG"
  }
}

管理豁免映像

本部分适用于 GKE、Distributed Cloud、Cloud Run 和 Cloud Service Mesh

豁免映像是一种无需遵守政策规则的容器映像。Binary Authorization 始终允许部署豁免映像。

如需指定豁免映像,请在 admissionWhitelistPatterns 中列出其注册表路径。该路径可以引用 Container Registry 或其他映像注册表。强制执行程序会先处理由系统政策评估模式豁免的映像,然后再处理 admissionWhitelistPatterns 中的豁免映像。

如需添加豁免映像,请在 JSON 格式的政策文件中的 admissionWhitelistPatterns 列表下添加一个 namePattern 节点:

{
  "name": "projects/PROJECT_ID/policy",
  "admissionWhitelistPatterns": [
    {
      "namePattern": "MATCHING_PATTERN"
    }
  ],
  ...
}

其中,MATCHING_PATTERN 是指向完全匹配的单个映像的路径,或者是指向与使用通配符符号(***)的模式匹配的任何映像的路径。

Cloud Run

本部分适用于 Cloud Run

您无法直接指定包含标记的映像名称。例如,您不能指定 IMAGE_PATH:latest。

如果要指定包含标记的映像名称,则必须按如下方式使用通配符来指定映像名称:

  • 对于单个映像的所有版本,使用 *;例如 us-docker.pkg.dev/myproject/container/hello@*
  • 对于项目中的所有映像,使用 **;例如 us-docker.pkg.dev/myproject/**

您可以使用路径名称指定 IMAGE_PATH@DIGEST 格式的摘要。

系统政策评估模式

本部分适用于 GKE 和 Distributed Cloud

系统政策评估模式政策设置会使 Binary Authorization 先评估系统政策,然后再评估配置的政策。Google 会管理用于豁免 GKE 使用的一系列 Google 维护的系统映像的系统政策。系统政策中列出的映像不会因政策强制执行而被阻止。如果您未启用此设置,则必须自行管理豁免映像列表。了解如何管理豁免映像

您可以使用以下命令查看系统政策的内容:

gcloud alpha container binauthz policy export-system-policy

如需启用系统政策评估模式,请将以下顶级节点添加到 JSON 格式的政策文件中:

"globalPolicyEvaluationMode": "ENABLE"

如需停用系统政策评估模式,请添加以下代码:

"globalPolicyEvaluationMode": "DISABLE"

您可以导出与特定区域关联的系统政策,如下所示:

gcloud alpha container binauthz policy export-system-policy \
  --location=REGION > /tmp/policy.yaml

REGION 替换为与您要导出的系统政策关联的区域(或“global”)。例如:asia-east1europe-west1us-central1

如果您省略 --location 或指定 --location=global,该命令会从最后一个区域组中的一个区域中输出一项系统政策,以接收更新。由于对系统政策所做的大部分更改都是增加的,因此输出会显示当前允许在所有区域中使用的系统映像集。

设置默认规则

本部分适用于 GKE、Distributed Cloud、Cloud Run 和 Cloud Service Mesh

规则是政策的一部分,用于规定容器映像必须满足哪些限制条件才能部署。每个准入请求都有一个关联的 GKE 集群。如果请求与针对集群的规则不匹配,则使用默认规则。

默认规则在政策的 defaultAdmissionRule 节点中指定。如需详细了解此规则的各个部分,请参阅 YAML 格式政策参考文档中的 ADMISSION_RULEADMISSION_RULE如需查看默认规则的示例,请参阅示例政策

如需设置默认规则,请根据需要修改 JSON 格式的政策文件中的 defaultAdmissionRule 节点:

  "defaultAdmissionRule": {
    "evaluationMode": "EVAL_MODE",
    "enforcementMode": "ENFORCEMENT_MODE"
    requireAttestationsBy: [
      ATTESTOR,
      ...
    ]
  }

其中:

  • EVAL_MODE 用于指定在允许部署某个容器映像之前 Binary Authorization 评估的限制条件类型。EVAL_MODE
  • ENFORCEMENT_MODE 用于指定在容器映像不符合该规则中定义的限制条件时执行的操作。ENFORCEMENT_MODE
  • ATTESTOR 用于指定必须由哪些证明者(如果需要)先对容器映像签名,然后才能进行部署。使用指向证明者的完全限定路径,格式为 projects/PROJECT_ID/attestors/ATTESTOR_NAME

如果您的规则需要进行检查,了解是否所有必需的证明者都已对容器映像签名,您必须先创建证明者,然后再完成此步骤。

设置针对集群的规则(可选)

本部分适用于 GKE 和 Distributed Cloud

一个集群还可以有一条或多条针对集群的规则。这种类型的规则只适用于指定的 GKE 集群。如果集群没有自己的规则,则使用默认规则。针对集群的规则是政策的可选部分。

针对集群的规则在 JSON 格式的政策文件内的 clusterAdmissionRules 节点中定义。如需详细了解此规则的各个部分,请参阅 YAML 格式政策参考文档中的 ADMISSION_RULEADMISSION_RULE如需查看示例,请参阅示例政策中的使用针对集群的规则

如需添加针对集群的规则,请执行以下操作:

在 JSON 格式的政策文件中,添加 clusterAdmissionRules 节点:

"clusterAdmissionRules": {
    "us-central1-a.test-cluster": {
      "evaluationMode": "REQUIRE_ATTESTATION",
      "requireAttestationsBy": [
        "ATTESTOR",
        ...
      ],
      "enforcementMode": "ENFORCED_BLOCK_AND_AUDIT_LOG"
    }
  },

其中,CLUSTER_SPECIFIER 是规则适用的集群的资源 ID。

  • 对于 GKE、GKE 关联集群和 GKE on AWS,格式为 CLUSTER_LOCATION.CLUSTER_NAME - 例如 us-central1-a.test-cluster
  • 对于 Google Distributed Cloud 和 Google Distributed Cloud,格式为 FLEET_MEMBERSHIP_LOCATION.FLEET_MEMBERSHIP_ID,例如 global.test-membership

其他属性如本指南前面的设置默认规则部分中所述。如需查看集群专用规则的示例,请参阅示例政策

如果您的规则需要进行检查,了解是否所有必需的证明者都已对容器映像签名,您必须先创建证明者,然后再完成此步骤。

导入 JSON 格式的政策文件

本部分适用于 GKE、Distributed Cloud、Cloud Run 和 Cloud Service Mesh

输入以下命令,将 JSON 格式的政策文件重新导入 Binary Authorization:

curl -X PUT \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
    -H "x-goog-user-project: ${PROJECT_ID}" \
    --data-binary @/tmp/policy.json  \
    "https://binaryauthorization.googleapis.com/v1/projects/${PROJECT_ID}/policy"

后续步骤