Workload Identity Federation 可讓 Azure Kubernetes Service (AKS)、Amazon Elastic Kubernetes Service (Amazon EKS) 或自行託管 Kubernetes 叢集中的工作負載向 Google Cloud進行驗證。Kubernetes 可讓您設定叢集,以便工作負載從投影磁碟區取得 Kubernetes ServiceAccount 權杖。工作負載可以將這些權杖換成短期憑證,以便存取Google Cloud API,而不必使用服務帳戶金鑰。
如果是 Google Kubernetes Engine (GKE) 執行的工作負載,請改用 Workload Identity Federation for GKE。
事前準備
設定 Workload Identity Federation 之前,請確認 Kubernetes 叢集符合下列條件:
GKE
如果您是 Google Kubernetes Engine (GKE) 使用者,請參閱「從 GKE 工作負載向 Google Cloud API 進行驗證」。
AKS
請確認叢集符合下列條件:
您已啟用 OIDC 核發者功能。
您必須啟用這項功能,Workload Identity Federation 才能存取叢集的 OpenID Connect 中繼資料和 JSON Web Key Set (JWKS)。
EKS
您不需要變更 EKS 設定。
Kubernetes
請確認叢集符合下列條件:
您執行的是 Kubernetes 1.20 以上版本。
舊版 Kubernetes 使用的 ServiceAccount 權杖格式與本文件中的操作說明不相容。
您已設定
kube-apiserver,支援ServiceAccount詞元數量預測。
叢集不一定要能透過網際網路存取。
設定 Workload Identity Federation
每個 Kubernetes 叢集只需執行一次這些步驟。接著,您可以在多個 Kubernetes Pod 和多個 Google Cloud 專案中使用相同的 workload identity pool 和提供者。
如要開始設定 Workload Identity Federation,請按照下列步驟操作:
-
在 Google Cloud 控制台的專案選取器頁面中,選取或建立 Google Cloud 專案。
選取或建立專案所需的角色
- 選取專案:選取專案時,不需具備特定 IAM 角色,只要您在專案中獲派角色,即可選取該專案。
-
建立專案:如要建立專案,您必須具備專案建立者角色 (
roles/resourcemanager.projectCreator),其中包含resourcemanager.projects.create權限。瞭解如何授予角色。
建議您使用專屬專案管理 workload identity pool 和提供者。
啟用 IAM、Resource Manager、服務帳戶憑證和 Security Token Service API (如有尚未啟用的項目)。
啟用 API 所需的角色
如要啟用 API,您必須具備 serviceusage.services.enable 權限。如果您建立了專案,可能已透過擁有者角色 (roles/owner) 取得這項權限。否則,您可以透過 Service Usage 管理員角色 (roles/serviceusage.serviceUsageAdmin) 取得這項權限。瞭解如何授予角色。
定義屬性對應和條件
Kubernetes ServiceAccount 權杖包含多個聲明,包括:
sub:包含 ServiceAccount 的命名空間和名稱,例如system:serviceaccount:NAMESPACE:KSA_NAME,其中NAMESPACE是 ServiceAccount 的命名空間,KSA_NAME是 ServiceAccount 的名稱。"kubernetes.io".namespace:包含 ServiceAccount 的命名空間。"kubernetes.io".serviceaccount.name:包含 ServiceAccount 的名稱。"kubernetes.io".pod.name:包含 Pod 的名稱。
如要在 Google Cloud中使用 sub 做為主體 ID (google.subject),請使用下列對應:
google.subject=assertion.sub
您也可以視需要對應其他屬性。然後在授予資源存取權時,參考這些屬性。例如:
google.subject=assertion.sub, attribute.namespace=assertion['kubernetes.io']['namespace'], attribute.service_account_name=assertion['kubernetes.io']['serviceaccount']['name'], attribute.pod=assertion['kubernetes.io']['pod']['name']
視需要定義屬性條件。屬性條件是 CEL 運算式,可檢查斷言屬性和目標屬性。如果特定憑證的屬性條件評估結果為 true,系統就會接受該憑證。否則,憑證會遭到拒絕。
您可以使用屬性條件,限制哪些 Kubernetes ServiceAccount 可透過 Workload Identity Federation 取得短期 Google Cloud權杖。舉例來說,下列條件會限制從 backend 和 monitoring 命名空間存取 Kubernetes ServiceAccount:
assertion['kubernetes.io']['namespace'] in ['backend', 'monitoring']
建立 workload identity pool 和提供者
必要的角色
如要取得設定 Workload Identity Federation 所需的權限,請要求管理員授予您專案的下列 IAM 角色:
- Workload Identity 集區管理員 (
roles/iam.workloadIdentityPoolAdmin) - 服務帳戶管理員 (
roles/iam.serviceAccountAdmin)
如要進一步瞭解如何授予角色,請參閱「管理專案、資料夾和組織的存取權」。
或者,IAM 擁有者 (roles/owner) 基本角色也包含設定身分聯盟的權限。請勿在正式環境中授予基本角色,但可以在開發或測試環境中授予。
如要建立 workload identity pool 和提供者,請按照下列步驟操作:
AKS
判斷 AKS 叢集的核發者網址:
az aks show -n NAME -g RESOURCE_GROUP --query "oidcIssuerProfile.issuerUrl" -otsv
更改下列內容:
NAME:叢集名稱RESOURCE_GROUP:叢集的資源群組
指令輸出核發者網址。您在後續步驟中會需要核發者網址。
如果指令未傳回核發者網址,請確認您已啟用 OIDC 核發者功能。
建立新的 workload identity pool:
gcloud iam workload-identity-pools create POOL_ID \ --location="global" \ --description="DESCRIPTION" \ --display-name="DISPLAY_NAME"更改下列內容:
POOL_ID:集區的專屬 ID。DISPLAY_NAME:集區名稱。DESCRIPTION:所選集區的說明。授予集區身分的存取權時,會顯示這段說明。
將 AKS 叢集新增為 workload identity pool 提供者:
gcloud iam workload-identity-pools providers create-oidc WORKLOAD_PROVIDER_ID \ --location="global" \ --workload-identity-pool="POOL_ID" \ --issuer-uri="ISSUER" \ --attribute-mapping="MAPPINGS" \ --attribute-condition="CONDITIONS"更改下列內容:
EKS
判斷 EKS 叢集的核發者網址:
aws eks describe-cluster --name NAME --query "cluster.identity.oidc.issuer" --output text
將
NAME替換為叢集名稱。指令輸出核發者網址。您在後續步驟中會需要核發者網址。
建立新的 workload identity pool:
gcloud iam workload-identity-pools create POOL_ID \ --location="global" \ --description="DESCRIPTION" \ --display-name="DISPLAY_NAME"更改下列內容:
POOL_ID:集區的專屬 ID。DISPLAY_NAME:集區名稱。DESCRIPTION:所選集區的說明。授予集區身分的存取權時,會顯示這段說明。
將 EKS 叢集新增為 workload identity pool 提供者:
gcloud iam workload-identity-pools providers create-oidc WORKLOAD_PROVIDER_ID \ --location="global" \ --workload-identity-pool="POOL_ID" \ --issuer-uri="ISSUER" \ --attribute-mapping="MAPPINGS" \ --attribute-condition="CONDITIONS"更改下列內容:
Kubernetes
連線至 Kubernetes 叢集,並使用
kubectl判斷叢集的核發者網址:kubectl get --raw /.well-known/openid-configuration | jq -r .issuer
您在後續步驟中會需要核發者網址。
下載叢集的 JSON Web Key Set (JWKS):
kubectl get --raw /openid/v1/jwks > cluster-jwks.json
在後續步驟中,您會上傳 JWKS,讓 Workload Identity Federation 驗證叢集核發的 Kubernetes ServiceAccount 權杖是否真實。
建立新的 workload identity pool:
gcloud iam workload-identity-pools create POOL_ID \ --location="global" \ --description="DESCRIPTION" \ --display-name="DISPLAY_NAME"更改下列內容:
POOL_ID:集區的專屬 ID。DISPLAY_NAME:集區名稱。DESCRIPTION:所選集區的說明。授予集區身分的存取權時,會顯示這段說明。
將 Kubernetes 叢集新增為 workload identity pool 提供者,並上傳叢集的 JWKS:
gcloud iam workload-identity-pools providers create-oidc WORKLOAD_PROVIDER_ID \ --location="global" \ --workload-identity-pool="POOL_ID" \ --issuer-uri="ISSUER" \ --attribute-mapping="MAPPINGS" \ --attribute-condition="CONDITIONS" \ --jwk-json-path="cluster-jwks.json"更改下列內容:
授予 Kubernetes 工作負載存取權
本節說明如何設定 Kubernetes 工作負載,使用 Workload Identity Federation 直接存取資源或服務帳戶模擬功能,存取Google Cloud API。
您必須為每個需要存取 Google Cloud的 Kubernetes 工作負載執行這些步驟一次。
建議您使用 Workload Identity Federation。不過,使用身分聯盟時,某些 API 方法可能有限制。如需限制清單,請參閱「身分聯盟:產品和限制」。
如果工作負載使用的方法有這類限制,您可以改用 IAM 模擬。
使用 Workload Identity Federation 直接授予資源存取權
在本節中,您將使用 Workload Identity Federation,將 IAM 角色授予 Kubernetes ServiceAccount,以便直接存取 Google Cloud 資源。
如要建立 Kubernetes ServiceAccount 並授予角色,請按照下列步驟操作:
建立 Kubernetes ServiceAccount:
kubectl create serviceaccount KSA_NAME --namespace NAMESPACE
更改下列內容:
KSA_NAME:ServiceAccount 的名稱。NAMESPACE:要在其中建立 ServiceAccount 的命名空間。
將Google Cloud 資源的 IAM 存取權授予 Kubernetes ServiceAccount。
根據最小權限原則,建議您只授予應用程式必須存取的資源專屬角色。
在以下範例中,指令會將 Kubernetes Engine 叢集檢視者 (
roles/container.clusterViewer) 角色授予您建立的 ServiceAccount。這個指令會使用您稍早在本文件中對應的主體。gcloud projects add-iam-policy-binding projects/PROJECT_ID \ --role=roles/container.clusterViewer \ --member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/MAPPED_SUBJECT \ --condition=None更改下列內容:
PROJECT_ID:要授予存取權的 Google Cloud專案 ID。PROJECT_NUMBER:workload identity pool 所在專案的專案編號。POOL_ID:workload identity pool 的 ID。MAPPED_SUBJECT:ID 權杖中對應至google.subject的 Kubernetes ServiceAccount。舉例來說,如果您對應google.subject=assertion.sub,且 ID 權杖包含"sub": "system:serviceaccount:default:my-kubernetes-serviceaccount",則MAPPED_SUBJECT為system:serviceaccount:default:my-kubernetes-serviceaccount。
您可以對支援 IAM 允許政策的任何 Google Cloud 資源授予角色。主體 ID 的語法取決於 Kubernetes 資源。如需支援的 ID 清單,請參閱「Workload Identity Federation for GKE 的主體 ID」。
現在可以部署工作負載,使用 Kubernetes ServiceAccount 存取您授予存取權的 Google Cloud 資源。
替代方案:使用 IAM 服務帳戶模擬功能授予存取權
如要將 Kubernetes ServiceAccount 設為使用 IAM 服務帳戶模擬功能,請按照下列步驟操作:
如果您尚未建立 Kubernetes ServiceAccount,請先建立:
kubectl create serviceaccount KSA_NAME --namespace NAMESPACE
更改下列內容:
KSA_NAME:ServiceAccount 的名稱。NAMESPACE:要在其中建立 ServiceAccount 的命名空間。
建立代表工作負載的 IAM 服務帳戶。
服務帳戶不一定要與 workload identity pool 位於相同專案,但參照服務帳戶時,必須指定服務帳戶所在的專案。
gcloud iam service-accounts create IAM_SA_NAME \ --project=IAM_SA_PROJECT_ID更改下列內容:
IAM_SA_NAME:服務帳戶的名稱。IAM_SA_PROJECT_ID:服務帳戶的專案 ID。
授予 IAM 服務帳戶存取權,讓 Kubernetes 工作負載存取特定 Google Cloud 資源。
gcloud projects add-iam-policy-binding IAM_SA_PROJECT_ID \ --member="serviceAccount:IAM_SA_NAME@IAM_SA_PROJECT_ID.iam.gserviceaccount.com" \ --role="ROLE"更改下列內容:
IAM_SA_PROJECT_ID:您建立服務帳戶的專案 ID。IAM_SA_NAME:服務帳戶的名稱。ROLE:要授予的角色名稱,例如roles/container.clusterViewer。
授予 Kubernetes ServiceAccount 模擬 IAM 服務帳戶的權限:
gcloud iam service-accounts add-iam-policy-binding \ IAM_SA_NAME@IAM_SA_PROJECT_ID.iam.gserviceaccount.com \ --member="principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/subject/MAPPED_SUBJECT" \ --role=roles/iam.workloadIdentityUser更改下列內容:
IAM_SA_NAME:服務帳戶的名稱。IAM_SA_PROJECT_ID:您建立服務帳戶的專案 ID。PROJECT_NUMBER:workload identity pool 所在專案的專案編號。POOL_ID:workload identity pool 的 ID。MAPPED_SUBJECT:ID 權杖中對應至google.subject的 Kubernetes ServiceAccount。舉例來說,如果您對應google.subject=assertion.sub,且 ID 權杖包含"sub": "system:serviceaccount:default:my-kubernetes-serviceaccount",則MAPPED_SUBJECT為system:serviceaccount:default:my-kubernetes-serviceaccount。
如要瞭解如何授權 IAM 服務帳戶存取Google Cloud API,請參閱「瞭解服務帳戶」。
您現在可以部署工作負載,使用 Kubernetes ServiceAccount 和 IAM 服務帳戶,存取您授予存取權的 Google Cloud資源。
部署 Kubernetes 工作負載
如要部署可存取 Google Cloud 資源的 Kubernetes 工作負載,請按照下列步驟操作:
建立憑證設定檔:
gcloud iam workload-identity-pools create-cred-config \ projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/WORKLOAD_PROVIDER_ID \ --service-account=SERVICE_ACCOUNT_EMAIL \ --credential-source-file=/var/run/service-account/token \ --credential-source-type=text \ --sts-location=REGION \ --output-file=credential-configuration.json
更改下列內容:
PROJECT_NUMBER:workload identity pool 所在專案的專案編號POOL_ID:workload identity pool 的 IDWORKLOAD_PROVIDER_ID:workload identity pool 提供者的 IDSERVICE_ACCOUNT_EMAIL:如果您將 Kubernetes ServiceAccount 設為使用 IAM 服務帳戶模擬功能,則為服務帳戶的電子郵件地址。如果您已將 Kubernetes ServiceAccount 設為使用直接資源存取權,請省略這個旗標。REGION:選用。指定區域 Security Token Service 端點的區域 (如有)。
憑證設定檔可讓 Cloud 用戶端程式庫、gcloud CLI 和 Terraform 判斷下列事項:
- 外部憑證的取得來源
- 要使用的 workload identity pool 和提供者
- 要模擬的服務帳戶
將憑證設定檔匯入為 ConfigMap
kubectl create configmap CONFIGMAP_NAME \ --from-file credential-configuration.json \ --namespace NAMESPACE
更改下列內容:
CONFIGMAP_NAME:ConfigMap 的名稱。NAMESPACE:要在其中建立 ConfigMap 的命名空間。
部署工作負載,並讓工作負載使用 Kubernetes ServiceAccount 和 ConfigMap。
建立資訊清單並按照下列方式設定:
- 掛接預計權杖磁碟區,讓工作負載能從本機檔案取得 Kubernetes ServiceAccount 權杖。設定磁碟區,讓 Kubernetes ServiceAccount 權杖使用 workload identity pool 提供者預期的目標對象。
- 掛接包含憑證設定檔的 ConfigMap,讓工作負載可以存取使用 Workload Identity Federation 所需的設定。
- 新增環境變數
GOOGLE_APPLICATION_CREDENTIALS,其中包含憑證設定檔的路徑,讓工作負載能找到該檔案。
以下資訊清單範例使用 Kubernetes ServiceAccount 和 ConfigMap,讓 Google Cloud CLI 向 Google Cloud進行驗證:
apiVersion: v1 kind: Pod metadata: name: example namespace: NAMESPACE spec: containers: - name: example image: google/cloud-sdk:alpine command: ["/bin/sh", "-c", "gcloud auth login --cred-file $GOOGLE_APPLICATION_CREDENTIALS && gcloud auth list && sleep 600"] volumeMounts: - name: token mountPath: "/var/run/service-account" readOnly: true - name: workload-identity-credential-configuration mountPath: "/etc/workload-identity" readOnly: true env: - name: GOOGLE_APPLICATION_CREDENTIALS value: "/etc/workload-identity/credential-configuration.json" serviceAccountName: KSA_NAME volumes: - name: token projected: sources: - serviceAccountToken: audience: https://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/WORKLOAD_PROVIDER_ID expirationSeconds: 3600 path: token - name: workload-identity-credential-configuration configMap: name: CONFIGMAP_NAME
您也可以採用相同方法,讓使用下列任一用戶端程式庫的工具和工作負載自動尋找憑證:
C++
Google Cloud C++ 適用的用戶端程式庫自 v2.6.0 版起支援 Workload Identity Federation。如要使用 Workload Identity Federation,您必須使用 1.36.0 以上版本的 gRPC 建構用戶端程式庫。
Go
如果 Go 的用戶端程式庫使用
golang.org/x/oauth2模組的 v0.0.0-20210218202405-ba52d332ba99 以上版本,則支援 Workload Identity Federation。如要查看用戶端程式庫使用的模組版本,請執行下列指令:
cd $GOPATH/src/cloud.google.com/go go list -m golang.org/x/oauth2Java
如果 Java 用戶端程式庫使用 0.24.0 以上版本的
com.google.auth:google-auth-library-oauth2-http構件,則支援 Workload Identity Federation。如要查看用戶端程式庫使用的構件版本,請在應用程式目錄中執行下列 Maven 指令:
mvn dependency:list -DincludeArtifactIds=google-auth-library-oauth2-httpNode.js
如果 Node.js 用戶端程式庫使用 7.0.2 以上版本的
google-auth-library套件,則支援 Workload Identity Federation。如要查看用戶端程式庫使用的套件版本,請在應用程式目錄中執行下列指令:
npm list google-auth-library建立
GoogleAuth物件時,您可以指定專案 ID,也可以讓GoogleAuth自動尋找專案 ID。如要自動尋找專案 ID,設定檔中的服務帳戶必須具備專案的瀏覽器角色 (roles/browser),或具備同等權限的角色。詳情請參閱google-auth-library套件的README。Python
如果 Python 用戶端程式庫使用 1.27.0 以上版本的
google-auth套件,則支援 Workload Identity Federation。如要查看用戶端程式庫使用的套件版本,請在安裝套件的環境中執行下列指令:
pip show google-auth如要為驗證用戶端指定專案 ID,您可以設定
GOOGLE_CLOUD_PROJECT環境變數,或允許用戶端自動尋找專案 ID。如要自動尋找專案 ID,設定檔中的服務帳戶必須具備專案的瀏覽器角色 (roles/browser),或具備同等權限的角色。詳情請參閱google-auth套件的使用手冊。gcloud
如要使用 Workload Identity Federation 進行驗證,請使用
gcloud auth login指令:gcloud auth login --cred-file=FILEPATH.json
將
FILEPATH替換為憑證設定檔的路徑。363.0.0 以上版本的 gcloud CLI 支援 Workload Identity Federation。
Terraform
如果您使用 3.61.0 以上版本,Google Cloud provider 支援 Workload Identity Federation:
terraform { required_providers { google = { source = "hashicorp/google" version = "~> 3.61.0" } } }bq
如要使用 Workload Identity Federation 進行驗證,請使用
gcloud auth login指令,如下所示:gcloud auth login --cred-file=FILEPATH.json
將
FILEPATH替換為憑證設定檔的路徑。gcloud CLI 390.0.0 以上版本支援 bq 中的 Workload Identity Federation。
(選用) 執行下列指令,確認驗證功能是否正常運作:
kubectl exec example --namespace NAMESPACE -- gcloud auth print-access-token
後續步驟
- 進一步瞭解 Workload Identity Federation。
- 瞭解使用 Workload Identity Federation 的最佳做法。
- 瞭解如何管理 workload identity pool 和提供者。