在 Autopilot 中建立具有特殊權限的工作負載許可清單

本文說明如何建立允許清單，在 Autopilot 節點中部署具備特殊權限的工作負載。您可以在 Cloud Storage 值區中儲存這些允許清單。本文件適用於平台管理員和營運人員，他們希望針對特定 Kubernetes 工作負載，免除特定客戶擁有的工作負載遵守預設 Autopilot 安全性限制。您應已熟悉 Autopilot 中的具備權限工作負載許可控制。

關於 Autopilot 中的具備特殊權限工作負載

Autopilot 模式會對工作負載強制執行一組預設限制，以提升安全防護機制。如要略過這些限制來執行特定具備權限的工作負載，請安裝與這些工作負載對應的許可清單。根據預設，任何 Autopilot 或 Standard 叢集都可讓您安裝 Autopilot 合作夥伴和特定開放原始碼專案的允許清單。

符合資格的 GKE 客戶可以為自己的特殊權限工作負載建立及管理允許清單，這類工作負載與預設的 Autopilot 限制不相容。這些允許清單是 WorkloadAllowlist Kubernetes 自訂資源，您可以在 YAML 檔案中定義，並儲存在 Cloud Storage bucket 中。身分和帳戶管理員可使用機構政策，讓您設定叢集來辨識這些客戶管理的允許清單和 bucket。叢集管理員可以安裝這些許可清單，讓特殊權限工作負載以 Autopilot 模式執行。

如要進一步瞭解相關程序和參與人員，請參閱「How privileged Autopilot workload admission control works」。

事前準備

開始之前，請務必先完成下列工作：

• 啟用 Google Kubernetes Engine API。
啟用 Google Kubernetes Engine API
• 如要使用 Google Cloud CLI 執行這項工作，請安裝並初始化 gcloud CLI。如果您先前已安裝 gcloud CLI，請執行 gcloud components update 指令，取得最新版本。較舊的 gcloud CLI 版本可能不支援執行本文件中的指令。

• 啟用 Cloud Storage API。

  啟用 API 時所需的角色

  如要啟用 API，您需要具備服務使用情形管理員 IAM 角色 (roles/serviceusage.serviceUsageAdmin)，其中包含 serviceusage.services.enable 權限。瞭解如何授予角色。

  啟用 API

• 請確認您擁有執行 1.35 以上版本的 GKE 叢集。您也可以建立 Autopilot 叢集來執行這項工作。
• 確認您有可儲存允許清單檔案的 Cloud Storage bucket。您也可以為這項工作建立 bucket。
• 開啟 YAML 資訊清單，定義要在 Autopilot 中執行的具備權限工作負載。

必要的角色

如要取得在 Cloud Storage 中儲存允許清單及設定同步所需的權限，請要求管理員授予您 bucket 的下列 IAM 角色：

• 在值區中儲存允許清單： Storage 物件使用者 (roles/storage.objectUser)
• 授予 GKE 服務代理存取權： 「Storage 管理員」 (roles/storage.admin)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

您或許也能透過自訂角色或其他預先定義的角色，取得必要權限。

建立及上傳 WorkloadAllowlist

允許清單是您在 YAML 檔案中定義的 WorkloadAllowlist 自訂資源。WorkloadAllowlist 規格中的欄位與 Kubernetes Pod 規格中的欄位類似。在叢集安裝許可清單並部署具備權限的工作負載時，GKE 會根據已安裝的許可清單驗證具備權限的工作負載規格。只有當許可清單規格中的所有欄位，都與工作負載規格中的對應欄位相符時，工作負載才能執行。

如要建立新的 WorkloadAllowlist 並上傳至 Cloud Storage bucket，請按照下列步驟操作：

1. 找出要加入許可清單的具備權限工作負載。

2. 在 Pod 規格的 metadata.annotations 欄位中新增下列註解：

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

   如果是由控制器管理的 Pod (例如 DaemonSet 或 Deployment)，請將註解新增至 spec.template.metadata.annotations 欄位。

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 欄位。

6. 選用：將 WorkloadAllowlist 一般化，以便豁免類似的工作負載。請使用下列其中一種方法：

   • 特定欄位支援規則運算式，例如 matchingCriteria.containers[*].image 和 matchingCriteria.containers[*].args。使用規則運算式，比對不同工作負載中的多個值。

   • 特定欄位 (例如 matchingCriteria.containers 和 matchingCriteria.securityContext.capabilities.add) 會比對 WorkloadAllowlist 中的值子集，找出相符的工作負載。在 WorkloadAllowlist 中，指定其他值來比對其他工作負載。

   如要進一步瞭解所有支援的欄位和值，請參閱 WorkloadAllowlist CustomResourceDefinition。

7. 將資訊清單檔案上傳至 Cloud Storage bucket。

如果貴機構政策允許從叢集中的 bucket 安裝允許清單，叢集管理員可以執行下列操作：

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 服務代理存取權

如要從叢集中的 bucket 同步處理允許清單，叢集專案中的 GKE 服務代理程式必須具備下列 IAM 角色：

• Storage Bucket 檢視者 (roles/storage.bucketViewer)
• Storage 物件檢視者 (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.iam.gserviceaccount.com \
       --project=BUCKET_PROJECT_ID \
       --role=roles/storage.bucketViewer
   

   更改下列內容：

   • BUCKET_NAME：Cloud Storage bucket 的名稱。
   • 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.iam.gserviceaccount.com \
       --project=BUCKET_PROJECT_ID \
       --role=roles/storage.objectViewer
   

後續步驟

• 將許可清單路徑新增至機構單位政策
• 設定叢集並安裝允許清單