为 Autopilot 中的特权工作负载创建许可名单

Autopilot

注意： 在 Autopilot 中运行自有特权工作负载仅适用于符合条件的 Google Cloud 客户。如需申请访问此功能，请与 Cloud Customer Care 联系。

本文档介绍了如何创建许可名单，以便您在 Autopilot 节点中部署特权工作负载。您将这些许可名单存储在 Cloud Storage 存储分区中。本文档适用于希望针对特定 Kubernetes 工作负载，将特定客户自有工作负载从默认 Autopilot 安全限制中排除的平台管理员和运维人员。您应该已经熟悉 Autopilot 中的特权工作负载准入控制。

关于 Autopilot 中的特权工作负载

Autopilot 模式会对工作负载强制执行一组默认限制，以提升安全性。您可以安装与特定特权工作负载对应的许可名单，从而绕过这些限制来运行这些工作负载。默认情况下，任何 Autopilot 或 Standard 集群都允许您安装来自 Autopilot 合作伙伴和特定开源项目的许可名单。

符合条件的 GKE 客户可以为其不兼容默认 Autopilot 限制的特权工作负载创建和管理许可名单。这些许可名单是 WorkloadAllowlist Kubernetes 自定义资源，您可以在 YAML 文件中定义这些资源，并将其存储在 Cloud Storage 存储分区中。身份和账号管理员可以使用组织政策，让您配置集群以识别这些客户管理的许可名单和存储分区。集群管理员可以安装这些许可名单，以便特权工作负载可以在 Autopilot 模式下运行。

如需详细了解相关流程和人员，请参阅特权 Autopilot 工作负载准入控制机制的工作原理。

准备工作

在开始之前，请确保您已执行以下任务：

• 启用 Google Kubernetes Engine API。
启用 Google Kubernetes Engine API
• 如果您要使用 Google Cloud CLI 执行此任务，请安装并初始化 gcloud CLI。如果您之前安装了 gcloud CLI，请通过运行 gcloud components update 命令来获取最新版本。较早版本的 gcloud CLI 可能不支持运行本文档中的命令。
  注意：对于现有 gcloud CLI 安装，请务必设置 compute/region 属性。如果您主要使用可用区级集群，请改为设置 compute/zone。通过设置默认位置，您可以避免 gcloud CLI 中出现如下错误：One of [--zone, --region] must be supplied: Please specify location。如果集群的位置与您设置的默认位置不同，您可能需要在某些命令中指定位置。

• 启用 Cloud Storage API。

  启用 API 所需的角色

  如需启用 API，您需要拥有 Service Usage Admin IAM 角色 (roles/serviceusage.serviceUsageAdmin)，该角色包含 serviceusage.services.enable 权限。了解如何授予角色。

  启用 API

• 确保您拥有运行 1.35 版或更高版本的 GKE 集群。您还可以创建 Autopilot 集群来完成此任务。
• 验证您是否拥有可用于存储许可名单文件的 Cloud Storage 存储桶。您还可以为此任务创建一个存储桶。
• 打开用于定义要在 Autopilot 中运行的特权工作负载的 YAML 清单。

所需的角色

如需获得在 Cloud Storage 中存储许可名单和配置同步所需的权限，请让管理员向您授予存储桶的以下 IAM 角色：

• 在存储桶中存储许可名单： Storage Object User (roles/storage.objectUser)
• 授予对 GKE 服务代理的访问权限：Storage Admin (roles/storage.admin)

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

创建并上传 WorkloadAllowlist

许可名单是您在 YAML 文件中定义的 WorkloadAllowlist 自定义资源。WorkloadAllowlist 规范中的字段与 Kubernetes Pod 规范中的字段类似。在集群中安装许可名单并部署特权工作负载时，GKE 会根据已安装的许可名单验证特权工作负载规范。只有当许可名单规范中的所有字段都与工作负载规范中的相应字段匹配时，工作负载才能运行。

如需创建新的 WorkloadAllowlist 并将其上传到 Cloud Storage 存储桶，请按照以下步骤操作：

1. 确定要添加到许可名单中的特权工作负载。

2. 将以下注解添加到 Pod 规范中的 metadata.annotations 字段：

   cloud.google.com/generate-allowlist: "true"
   

   对于由控制器（例如 DaemonSet 或 Deployment）管理的 Pod，请将注解添加到 spec.template.metadata.annotations 字段。

   注意： 如需在项目或组织获得此功能的使用权限之前就已存在的集群上使用此注解，您必须先运行任意 gcloud container clusters update 命令，并将 --autopilot-privileged-admission 标志设置为 true。如果您尚未配置任何自定义许可名单路径，可以使用 --autopilot-privileged-admission=gke://* 标志来保持 GKE 默认行为。如需了解详情，请参阅 gcloud container clusters update 命令的文档。

3. 尝试在集群中创建特权工作负载：

   kubectl apply -f WORKLOAD_FILE_PATH
   

   将 WORKLOAD_FILE_PATH 替换为工作负载清单文件的路径。GKE 拒绝工作负载，并显示包含 WorkloadAllowlist 清单的错误消息。输出类似于以下内容：

   This workload can be enabled using the following Custom Resource. To be used in-cluster, the WorkloadAllowlist must be uploaded to Google Cloud Storage and then installed using an AllowlistSynchronizer. Refer to https://cloud.google.com/kubernetes-engine/docs/how-to/autopilot-privileged-allowlists.
   
   Note that many common partner workloads are already allowlisted. These can be installed directly using an AllowlistSynchronizer. Refer to https://cloud.google.com/kubernetes-engine/docs/resources/autopilot-partners.
   ---
   apiVersion: auto.gke.io/v1
   kind: WorkloadAllowlist
   metadata:
       name: test-pod-allowlist-2025-09-11t22-40-37
       annotations:
           autopilot.gke.io/no-connect: "true"
   exemptions:
       - autogke-disallow-privilege
   matchingCriteria:
       containers:
           - name: pause-container2
             image: k8s.gcr.io/pause2
             securityContext:
               privileged: true
   

4. 在文本编辑器中，创建一个包含生成的 WorkloadAllowlist 的 YAML 文件。

   最佳实践：

   为您的许可名单文件使用版本控制方案。版本控制功能有助于确保存储桶中的文件名保持唯一。

5. 设置许可名单的 metadata.name 字段。

   最佳实践：

   将许可名单名称设置为与文件名相同的值。此做法可确保许可名单名称在您的 Cloud Storage 存储桶中是唯一的。尝试安装多个同名的许可名单可能会导致意外行为。

6. 可选：将 WorkloadAllowlist 泛化，使其能够豁免类似的工作负载。请采用以下方法之一：

   • 某些字段支持正则表达式，例如 matchingCriteria.containers[*].image 和 matchingCriteria.containers[*].args。使用可匹配不同工作负载中的多个值的正则表达式。

   • 特定字段（例如 matchingCriteria.containers 和 matchingCriteria.securityContext.capabilities.add）与 WorkloadAllowlist 中具有部分值的所有工作负载相匹配。在 WorkloadAllowlist 中，指定其他值以匹配其他工作负载。

   如需详细了解您可以使用的所有受支持的字段和值，请参阅 WorkloadAllowlist CustomResourceDefinition。

7. 将清单文件上传到您的 Cloud Storage 存储桶。

如果组织政策允许从存储桶在集群中安装许可名单，集群管理员可以执行以下操作：

1. 将许可名单路径添加到集群。
2. 创建 AllowlistSynchronizer 以安装存储桶中的许可名单。

如需详细了解如何配置集群和安装许可名单，请参阅在 Autopilot 模式下控制特权工作负载准入。

许可名单配置示例

WorkloadAllowlist 规范中的 matchingCriteria 字段与 Kubernetes Pod 规范具有类似的结构。WorkloadAllowlist CustomResourceDefinition 是您可以使用的所有字段、值和表达式的可靠来源。

本部分展示了一个许可名单示例，该许可名单与具有以下属性的工作负载相匹配：

• 工作负载中的 container-1 容器以特权模式运行。
• 工作负载以写入模式装载节点文件系统中的 /var/log/ 目录。

1. 查看示例工作负载：

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: example-privileged-workload
     labels:
       env: dev
   spec:
     selector:
       matchLabels:
         env: dev
     template:
       metadata:
         labels:
           env: dev
       spec:
         containers:
         - name: container-1
           image: example-image-1
           resources:
             requests:
               cpu: "400m"
               memory: "4Gi"
           # Run the container in privileged mode
           securityContext:
             privileged: true
         - name: container-2
           image: example-image-2
           volumeMounts:
           - name: write-varlog
             mountPath: /logs
             readOnly: false
         # Mount a host directory
         volumes:
         - name: write-varlog
           hostPath:
             path: /var/log
             type: Directory
   

   默认情况下，Autopilot 会拒绝此工作负载。

2. 查看示例 WorkloadAllowlist：

   apiVersion: auto.gke.io/v1
   kind: WorkloadAllowlist
   minGKEVersion: 1.32.0-gke.1000000
   metadata:
     name: example-privileged-workload
     annotations:
       autopilot.gke.io/no-connect: "true"
   # List of constraints that the allowlist modifies
   exemptions:
   - autogke-disallow-privilege
   - autogke-no-write-mode-hostpath
   matchingCriteria:
     containers:
     - name: container-1
       image: example-image-1
       securityContext:
         privileged: true
     - name: container-2
       image: example-image-2
       volumeMounts:
       - name: write-varlog
         mountPath: /logs
         readOnly: false
     volumes:
     - name: write-varlog
       hostPath:
         path: /var/log
   

   此 WorkloadAllowlist 具有以下属性：

   • exemptions 字段中的值用于指定许可名单绕过的 Autopilot 限制。
   • matchingCriteria 字段中的值指定了示例工作负载使用的容器以及通常会违反 Autopilot 限制的字段。

   许可名单仅包含违反限制的字段的值。工作负载中的其他字段（例如 resources.requests 字段）会被忽略。

在集群中安装此示例 WorkloadAllowlist 后，GKE 允许特权工作负载在该集群中运行。例如，在具有 Autopilot 节点的 Standard 集群中，安装此 WorkloadAllowlist 可让特权工作负载在 Autopilot 节点上运行。

向 GKE 服务代理授予访问权限

如需同步集群中存储桶的许可名单，集群项目中的 GKE 服务代理需要以下 IAM 角色：

• Storage Bucket Viewer (roles/storage.bucketViewer)
• Storage Object Viewer (roles/storage.objectViewer)

如需向服务代理授予这些角色，请按以下步骤操作：

1. 找到您的集群项目的项目编号：

   gcloud projects describe CLUSTER_PROJECT_ID \
       --format='value(projectNumber)'
   

2. 授予 roles/storage.bucketViewer 角色：

   gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
       --member=serviceAccount:service-CLUSTER_PROJECT_NUMBER@container-engine-robot. \
       --project=BUCKET_PROJECT_ID \
       --role=roles/storage.bucketViewer
   

   替换以下内容：

   • BUCKET_NAME：Cloud Storage 存储桶的名称。
   • CLUSTER_PROJECT_NUMBER：集群项目的项目编号（来自上一步的输出）。
   • BUCKET_PROJECT_ID：包含相应存储桶的项目的 ID。

3. 授予 roles/storage.objectViewer 角色：

   gcloud storage buckets add-iam-policy-binding gs://BUCKET_NAME \
       --member=serviceAccount:service-CLUSTER_PROJECT_NUMBER@container-engine-robot. \
       --project=BUCKET_PROJECT_ID \
       --role=roles/storage.objectViewer
   

后续步骤

• 将许可名单路径添加到组织政策
• 配置集群并安装许可名单