從 GKE 工作負載向 Google Cloud API 驗證身分

本頁面說明如何使用 Workload Identity Federation for GKE，從 Google Kubernetes Engine (GKE) 叢集中執行的工作負載，以更安全的方式存取 Google Cloud API。

本頁面適用於身分和帳戶管理員、作業人員和開發人員，他們負責建立及管理與使用者權限相關的政策。如要進一步瞭解我們在 Google Cloud 內容中提及的常見角色和範例工作，請參閱「常見的 GKE Enterprise 使用者角色和工作」。

閱讀本頁面之前，請先熟悉 GKE 適用的工作負載身分聯盟概念。

事前準備

開始之前，請確認你已完成下列工作：

• 啟用 Google Kubernetes Engine API。
啟用 Google Kubernetes Engine API
• 如要使用 Google Cloud CLI 執行這項工作，請安裝並初始化 gcloud CLI。如果您先前已安裝 gcloud CLI，請執行 gcloud components update，取得最新版本。

• 確認您要存取的 API 支援 Workload Identity Federation for GKE。 Google Cloud 如需支援的 API 清單，請參閱「支援的產品和限制」。如果 API 不受支援，或您的用途因該服務的 Workload Identity Federation 限制而遭到封鎖，請參閱本頁的「替代方案：將 Kubernetes ServiceAccount 連結至 IAM」。

• 確認您已啟用 IAM Service Account Credentials API。

  啟用 IAM 憑證 API

• 確認您具備下列 IAM 角色：

  • roles/container.admin
  • roles/iam.serviceAccountAdmin

• 請務必瞭解 Workload Identity Federation for GKE 的限制。

• 確認您有現有的 Autopilot 或 Standard 叢集。如要建立新叢集，請參閱「建立 Autopilot 叢集」。

在叢集和節點集區上啟用 Workload Identity Federation for GKE

在 Autopilot 中，系統一律會啟用 Workload Identity Federation for GKE。直接前往「設定應用程式以使用 Workload Identity Federation for GKE」一節。

在 Standard 中，您可以使用 Google Cloud CLI 或 Google Cloud 控制台，為叢集和節點集區啟用 GKE 適用的工作負載身分聯盟。您必須先在叢集層級啟用 Workload Identity Federation for GKE，才能在節點集區啟用這項功能。

您可以使用 gcloud CLI 或 Google Cloud 控制台，在現有標準叢集上啟用 Workload Identity Federation for GKE。現有的節點集區不會受到影響，但叢集中的所有新節點集區都會使用 Workload Identity Federation for GKE。

將現有工作負載遷移至 Workload Identity Federation for GKE

在現有叢集上啟用 Workload Identity Federation for GKE 後，您可能想遷移執行中的工作負載，改用 Workload Identity Federation for GKE。選取最適合您環境的遷移策略。您可以建立啟用 Workload Identity Federation for GKE 的新節點集區，也可以更新現有節點集區來啟用這項功能。

只有在叢集上啟用 Workload Identity Federation for GKE 時，才能在節點集區上啟用這項功能。

建立新的節點集區

如果叢集已啟用 Workload Identity Federation for GKE，您建立的所有新節點集區預設都會使用這項功能。如要建立啟用 GKE 工作負載身分聯盟的新節點集區，請執行下列指令：

gcloud container node-pools create NODEPOOL_NAME \
    --cluster=CLUSTER_NAME \
    --location=CONTROL_PLANE_LOCATION \
    --workload-metadata=GKE_METADATA

更改下列內容：

• NODEPOOL_NAME：新節點集區的名稱。
• CLUSTER_NAME：已啟用 Workload Identity Federation for GKE 的現有叢集名稱。
• CONTROL_PLANE_LOCATION：叢集控制層的 Compute Engine 位置。為地區叢集提供地區，或為區域叢集提供區域。

--workload-metadata=GKE_METADATA 標記會將節點集區設定為使用 GKE 中繼資料伺服器。

更新現有節點集區

在叢集上啟用 Workload Identity Federation for GKE 後，您可以在現有節點集區上，手動啟用 Workload Identity Federation for GKE。

設定應用程式，以便使用 Workload Identity Federation for GKE

如要讓 GKE 應用程式使用 Workload Identity Federation for GKE 向 API 驗證身分，請為特定 API 建立 IAM 政策。 Google Cloud這些政策中的主體是 IAM 主體 ID，對應至工作負載、命名空間或 Kubernetes ServiceAccount。這個程序會傳回聯邦存取權杖，工作負載可用於 API 呼叫。

或者，您也可以設定 Kubernetes ServiceAccount 來模擬 IAM 服務帳戶，這會設定 GKE 將同盟存取權權杖換成 IAM 服務帳戶憑證 API 的存取權權杖。詳情請參閱「替代方案：將 Kubernetes ServiceAccount 連結至 IAM」一節。

設定授權和主體

1. 取得叢集憑證：

   gcloud container clusters get-credentials CLUSTER_NAME \
       --location=CONTROL_PLANE_LOCATION
   

   更改下列內容：

   • CLUSTER_NAME：叢集名稱，該叢集已啟用 Workload Identity Federation for GKE。
   • CONTROL_PLANE_LOCATION：叢集控制層的 Compute Engine 位置。為地區叢集提供地區，或為區域叢集提供區域。

2. 建立要用於 Kubernetes 服務帳戶的命名空間。您也可以使用 default 命名空間或任何現有命名空間。

   kubectl create namespace NAMESPACE
   

3. 為應用程式建立要使用的 Kubernetes ServiceAccount。您也可以在任何命名空間中使用現有的 Kubernetes ServiceAccount。如果沒有為工作負載指派 ServiceAccount，Kubernetes 會指派命名空間中的 default ServiceAccount。

   kubectl create serviceaccount KSA_NAME \
       --namespace NAMESPACE
   

   更改下列內容：

   • KSA_NAME：新 Kubernetes ServiceAccount 的名稱。
   • NAMESPACE：ServiceAccount 的 Kubernetes 命名空間名稱。

4. 建立參照 Kubernetes ServiceAccount 的 IAM 允許政策。最佳做法是授予應用程式存取特定Google Cloud 資源的權限。您必須具備相關 IAM 權限，才能在專案中建立允許政策。

   舉例來說，下列指令會將您建立的 ServiceAccount 授予 Kubernetes Engine 叢集檢視者 (roles/container.clusterViewer) 角色：

   gcloud projects add-iam-policy-binding projects/PROJECT_ID \
       --role=roles/container.clusterViewer \
       --member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME \
       --condition=None
   

   更改下列內容：

   • PROJECT_ID：您的 Google Cloud 專案 ID。
   • PROJECT_NUMBER：您的數字 Google Cloud專案編號。

   您可以在任何支援 IAM 允許政策的 Google Cloud 資源上授予角色。主體 ID 的語法取決於 Kubernetes 資源。如需支援的 ID 清單，請參閱「Principal identifiers for Workload Identity Federation for GKE」。

選用：設定服務網格選項

如果您使用 Istio 或 Cloud Service Mesh 管理環境，請在 Pod 規格的 metadata.annotations 欄位中新增下列註解：

metadata:
  annotations:
    proxy.istio.io/config: '{ "holdApplicationUntilProxyStarts": true }'

這項註解可防止容器啟動，直到服務網格 Proxy 準備好重新導向應用程式的流量為止。

驗證 Workload Identity Federation for GKE 設定

在本節中，您將建立 Cloud Storage bucket，並授予先前建立的 Kubernetes ServiceAccount 該 bucket 的檢視存取權。接著部署工作負載，並測試容器是否可以列出專案中的叢集。

1. 建立空白的 Cloud Storage 值區：

   gcloud storage buckets create gs://BUCKET
   

   將 BUCKET 替換為新值區的名稱。

2. 將「Storage 物件檢視者」(roles/storage.objectViewer) 角色授予您建立的 ServiceAccount：

   gcloud storage buckets add-iam-policy-binding gs://BUCKET \
       --role=roles/storage.objectViewer \
       --member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME \
       --condition=None
   

   更改下列內容：

   • PROJECT_ID：您的 Google Cloud 專案 ID。
   • PROJECT_NUMBER：您的數字 Google Cloud專案編號。
   • NAMESPACE：包含 ServiceAccount 的 Kubernetes 命名空間。
   • KSA_NAME：ServiceAccount 的名稱。

3. 將下列資訊清單儲存為 test-app.yaml：

   apiVersion: v1
   kind: Pod
   metadata:
     name: test-pod
     namespace: NAMESPACE
   spec:
     serviceAccountName: KSA_NAME
     containers:
     - name: test-pod
       image: google/cloud-sdk:slim
       command: ["sleep","infinity"]
       resources:
         requests:
           cpu: 500m
           memory: 512Mi
           ephemeral-storage: 10Mi
   

4. 僅限 Standard 叢集，在 template.spec 欄位中新增下列項目，將 Pod 放置在採用 Workload Identity Federation for GKE 的節點集區。

   在 Autopilot 叢集中，請略過這個步驟，因為每個節點都會使用 Workload Identity Federation for GKE，因此會拒絕這個 nodeSelector。

   spec:
     nodeSelector:
       iam.gke.io/gke-metadata-server-enabled: "true"
   

5. 將設定套用到叢集：

   kubectl apply -f test-app.yaml
   

6. 等待 Pod 準備就緒。如要檢查 Pod 的狀態，請執行下列指令：

   kubectl get pods --namespace=NAMESPACE
   

   Pod 就緒時，輸出內容會類似如下：

   NAME       READY   STATUS    RESTARTS   AGE
   test-pod   1/1     Running   0          5m27s
   

7. 在 Pod 中開啟殼層工作階段：

   kubectl exec -it pods/test-pod --namespace=NAMESPACE -- /bin/bash
   

8. 取得值區中的物件清單：

   curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
       "https://storage.googleapis.com/storage/v1/b/BUCKET/o"
   

   輸出內容如下：

   {
     "kind": "storage#objects"
   }
   

   這項輸出內容顯示 Pod 可以存取 bucket 中的物件。

替代做法：將 Kubernetes ServiceAccount 連結至 IAM

1. 建立 Kubernetes 命名空間：

   kubectl create namespace NAMESPACE
   

2. 建立 Kubernetes ServiceAccount：

   kubectl create serviceaccount KSA_NAME \
       --namespace=NAMESPACE
   

3. 建立 IAM 服務帳戶。您也可以使用組織中任何專案的現有 IAM 服務帳戶。

   gcloud iam service-accounts create IAM_SA_NAME \
       --project=IAM_SA_PROJECT_ID
   

   更改下列內容：

   • IAM_SA_NAME：新 IAM 服務帳戶的名稱。
   • IAM_SA_PROJECT_ID：IAM 服務帳戶的專案 ID。

   如要瞭解如何授權身分與存取權管理服務帳戶存取 Google CloudAPI，請參閱「瞭解服務帳戶」一文。

4. 在 Google Cloud 特定 API 上，授予 IAM 服務帳戶所需的角色：

   gcloud projects add-iam-policy-binding IAM_SA_PROJECT_ID \
       --member "serviceAccount:IAM_SA_NAME@IAM_SA_PROJECT_ID.iam.gserviceaccount.com" \
       --role "ROLE_NAME"
   

   將 ROLE_NAME 替換為角色名稱，例如 roles/spanner.viewer。

5. 建立 IAM 允許政策，授予 Kubernetes ServiceAccount 模擬 IAM 服務帳戶的存取權：

   gcloud iam service-accounts add-iam-policy-binding IAM_SA_NAME@IAM_SA_PROJECT_ID.iam.gserviceaccount.com \
       --role roles/iam.workloadIdentityUser \
       --member "serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE/KSA_NAME]"
   

   成員名稱必須包含命名空間和 Kubernetes ServiceAccount 名稱。例如 serviceAccount:example-project.svc.id.goog[example-namespace/example-serviceaccount]。

6. 為 Kubernetes ServiceAccount 加入註解，讓 GKE 看到服務帳戶之間的連結：

   kubectl annotate serviceaccount KSA_NAME \
       --namespace NAMESPACE \
       iam.gke.io/gcp-service-account=IAM_SA_NAME@IAM_SA_PROJECT_ID.iam.gserviceaccount.com
   

   使用這個方法時，您必須同時提供 IAM 允許政策和註解。

從程式碼使用 Workload Identity Federation for GKE

從程式碼向服務進行驗證的程序，與使用 Compute Engine 中繼資料伺服器進行驗證的程序相同。 Google Cloud 使用 Workload Identity Federation for GKE 時，對執行個體中繼資料伺服器的要求會轉送至 GKE 中繼資料伺服器。使用執行個體中繼資料伺服器進行驗證的現有程式碼 (例如使用 Google Cloud 用戶端程式庫的程式碼) 應可直接運作，無需修改。

透過 GKE 適用的工作負載身分聯盟，使用其他專案的配額

在執行 GKE 1.24 以上版本的叢集上，您可以選擇設定 Kubernetes 服務帳戶，在呼叫 IAM 服務帳戶憑證 API 中的 GenerateAccessToken 和 GenerateIdToken 方法時，使用不同 Google Cloud 專案的配額。這樣一來，您就不必在主要專案中使用整個配額，而是可以改用其他專案的配額，在叢集中使用這些服務。

如要透過 Workload Identity Federation for GKE 設定配額專案，請完成下列步驟：

1. 在配額專案中，將 serviceusage.services.use 權限授予 Kubernetes 服務帳戶。

   gcloud projects add-iam-policy-binding QUOTA_PROJECT_ID \
       --role=roles/serviceusage.serviceUsageConsumer \
       --member='principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME' \
   

   將 QUOTA_PROJECT_ID 替換為配額專案的專案 ID。

2. 使用配額專案註解 Kubernetes 服務帳戶：

   kubectl annotate serviceaccount KSA_NAME \
       --namespace NAMESPACE \
       iam.gke.io/credential-quota-project=QUOTA_PROJECT_ID
   

如要確認設定是否正常運作，請按照下列步驟操作：

1. 建立 Pod 並啟動 Shell 工作階段。請參閱 Kubernetes 說明文件，瞭解如何取得執行中容器的 Shell。

2. 向中繼資料伺服器發出要求：

   curl -H "Metadata-Flavor: Google" http://169.254.169.254/computeMetadata/v1/instance/service-accounts/default/token
   

3. 在配額專案的 Google Cloud 控制台中，前往「IAM Service Accounts Credentials API」(IAM 服務帳戶憑證 API) 頁面：

   前往 API 頁面

4. 檢查流量變化。

清除所用資源

如要停止使用 Workload Identity Federation for GKE，請撤銷 IAM 服務帳戶的存取權，並在叢集上停用 Workload Identity Federation for GKE。

撤銷存取權

如要撤銷主體的存取權，請移除您在「設定應用程式以使用 GKE 適用的工作負載身分聯盟」一節中建立的 IAM 允許政策。

舉例來說，如要撤銷對 Artifact Registry 存放區的存取權，請執行下列指令：

gcloud artifacts repositories remove-iam-policy-binding REPOSITORY_NAME \
    --location=REPOSITORY_LOCATION \
    --member='principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME' \
    --role='roles/artifactregistry.reader' \
    --all

停用 GKE 適用的工作負載身分聯盟

您只能在標準叢集上停用 Workload Identity Federation for GKE。

在貴機構中停用 Workload Identity Federation for GKE

從安全性的角度來看，Workload Identity Federation for GKE 可讓 GKE 聲明 Kubernetes 服務帳戶身分，這些身分可通過驗證並授權存取資源。 Google Cloud如果您是管理員，已採取行動將工作負載與Google Cloud 資源隔離，例如停用服務帳戶建立功能或停用服務帳戶金鑰建立功能，您可能也想為貴機構停用 GKE 的 Workload Identity 聯盟。

請參閱這些操作說明，瞭解如何為貴機構停用 GKE 適用的工作負載身分聯盟。

疑難排解

如需疑難排解資訊，請參閱「排解 GKE 適用的工作負載身分聯盟問題」。

後續步驟

• 進一步瞭解 GKE 適用的工作負載身分聯盟。
• 閱讀 GKE 安全性總覽。
• 瞭解如何保護叢集中繼資料。
• 瞭解 IAM 服務帳戶。