在 GKE 上啟用 Workload Identity

本主題說明如何在 GKE 上為 Apigee Hybrid 啟用 Workload Identity。

如果您使用 Apigee Hybrid AKS 或 EKS，請按照「在 AKS 和 EKS 上啟用 Workload Identity Federation」一文中的操作說明進行。

總覽

Workload Identity 可讓 GKE (Google Kubernetes Engine) 中執行的應用程式存取 Google Cloud 服務。如要瞭解 Workload Identity 的總覽，請參閱：

• 推出 Workload Identity：為 GKE 應用程式提供更完善的驗證機制
• 使用 Workload Identity

Google Cloud IAM 服務帳戶是應用程式用來向 Google API 提出要求的身分。本文將這些服務帳戶稱為 GSA (Google 服務帳戶)。如要進一步瞭解 GSA，請參閱服務帳戶。

此外，Kubernetes 也有服務帳戶的概念。服務帳戶會為 Pod 中執行的程序提供身分。Kubernetes 服務帳戶是 Kubernetes 資源，而 Google 服務帳戶則專屬於 Google Cloud。如要瞭解 Kubernetes 服務帳戶，請參閱 Kubernetes 說明文件中的「 為 Pod 設定服務帳戶」。

首次安裝這些元件的 Helm 資訊套件時，Apigee 會為每種元件建立並使用 Kubernetes 服務帳戶。啟用 Workload Identity 後，混合式元件就能與 Kubernetes 服務帳戶互動。

這些程序中使用的環境變數

這些程序會使用下列環境變數。您可以在指令殼層中設定這些值，或在程式碼範例中將這些值替換為實際值：

• PROJECT_ID：您的 Google Cloud 專案 ID。
• ORG_NAME：Apigee 機構的名稱。
• ENV_NAME：Apigee 環境的名稱。
• NAMESPACE：您的 Apigee 命名空間 (通常為 apigee)。
• CLUSTER_LOCATION：Kubernetes 叢集的區域或可用區，例如：us-west1。
• CLUSTER_NAME：叢集名稱。

確認環境變數：

echo $PROJECT_ID
echo $ORG_NAME
echo $ENV_NAME
echo $NAMESPACE
echo $CLUSTER_LOCATION
echo $CLUSTER_NAME

初始化任何需要的變數：

export PROJECT_ID=MY_PROJECT_ID
export ORG_NAME=MY_ORG_NAME
export ENV_NAME=MY_ENV_NAME
export NAMESPACE=APIGEE_NAMESPACE
export CLUSTER_LOCATION=MY_CLUSTER_LOCATION
export CLUSTER_NAME=MY_CLUSTER_NAME

Workload Identity 和服務帳戶金鑰檔案

在 GKE 上執行 Apigee Hybrid 時，標準做法是為每個服務帳戶建立並下載私密金鑰 (.json 檔案)。使用 Workload Identity 時，您不需要下載服務帳戶私密金鑰，也不必將金鑰新增至 GKE 叢集。

如果您已在 Apigee Hybrid 安裝程序中下載服務帳戶金鑰檔案，啟用 Workload Identity 後即可刪除這些檔案。在大多數安裝作業中，這些檔案位於每個元件圖表的目錄中。

為 Apigee Hybrid 啟用 Workload Identity

請按照下列指示，為專案設定 Workload Identity。

準備設定 Workload Identity

1. 確認覆寫檔案中已啟用 Workload Identity。您應在覆寫檔案中啟用這項功能，並為下列設定屬性中的值：
   • 所有安裝作業都必須： gcp.workloadIdentity.enabled 應為 true。例如：

     gcp:
       workloadIdentity:
         enabled: true

   • 如要安裝正式版：
     • connectAgent.gsa
     • envs.gsa.runtime
     • envs.gsa.synchronizer
     • envs.gsa.udca
     • logger.gsa
     • mart.gsa
     • metrics.gsa
     • udca.gsa
     • watcher.gsa
   • 對於非實際工作環境安裝作業，請在 gcp.workloadIdentity.gsa 屬性中提供非實際工作環境 GSA 的地址 (包含所有必要的 IAM 角色)。
2. 使用下列指令，確認目前的 gcloud 設定已設為您的 Google Cloud 專案 ID：

   gcloud config get project

視需要設定目前的 gcloud 設定：

gcloud config set project $PROJECT_ID

3. 確認 GKE 叢集已啟用 Workload Identity。在步驟 1：建立叢集中建立叢集時，步驟 6 是啟用 Workload Identity。如要確認是否已啟用 Workload Identity，請執行下列指令：

   地區性叢集

   gcloud container clusters describe $CLUSTER_NAME \
     --region $CLUSTER_LOCATION \
     --project $PROJECT_ID \
     --flatten 'workloadIdentityConfig'

   區域叢集

   gcloud container clusters describe $CLUSTER_NAME \
     --zone $CLUSTER_LOCATION \
     --project $PROJECT_ID \
     --flatten 'workloadIdentityConfig'

   輸出內容應如下所示：

     ---
   workloadPool: PROJECT_ID.svc.id.goog

   如果結果顯示 null，請執行下列指令，為叢集啟用 Workload Identity：

   地區性叢集

   gcloud container clusters update $CLUSTER_NAME \
     --workload-pool=$PROJECT_ID.svc.id.goog \
     --project $PROJECT_ID \
     --region $CLUSTER_LOCATION

   區域叢集

   gcloud container clusters update $CLUSTER_NAME \
     --workload-pool=$PROJECT_ID.svc.id.goog \
     --zone $CLUSTER_LOCATION \
     --project $PROJECT_ID

4. 使用下列指令，為每個節點集區啟用 Workload Identity。以每個節點來說，這項作業最多可能需要 30 分鐘才能完成：

   地區性叢集

   gcloud container node-pools update NODE_POOL_NAME \
     --cluster=$CLUSTER_NAME \
     --region $CLUSTER_LOCATION \
     --project $PROJECT_ID \
     --workload-metadata=GKE_METADATA

   區域叢集

   gcloud container node-pools update NODE_POOL_NAME \
     --cluster=$CLUSTER_NAME \
     --zone $CLUSTER_LOCATION \
     --project $PROJECT_ID \
     --workload-metadata=GKE_METADATA

   其中 NODE_POOL_NAME 是各節點集區的名稱。在大多數 Apigee Hybrid 安裝作業中，這兩個預設節點集區分別命名為 apigee-data 和 apigee-runtime。

5. 使用下列指令，確認節點集區已啟用 Workload Identity：

   地區性叢集

   gcloud container node-pools describe apigee-data \
     --cluster $CLUSTER_NAME \
     --region $CLUSTER_LOCATION \
     --project $PROJECT_ID \
     --flatten "config:"

   gcloud container node-pools describe apigee-runtime \
     --cluster $CLUSTER_NAME \
     --region $CLUSTER_LOCATION \
     --project $PROJECT_ID \
     --flatten "config:"

   區域叢集

   gcloud container node-pools describe apigee-data \
     --cluster $CLUSTER_NAME \
     --zone $CLUSTER_LOCATION \
     --project $PROJECT_ID \
     --flatten "config:"

   gcloud container node-pools describe apigee-runtime \
     --cluster $CLUSTER_NAME \
     --zone $CLUSTER_LOCATION \
     --project $PROJECT_ID \
     --flatten "config:"

   輸出內容應如下所示：

   ---
   diskSizeGb: 100
   diskType: pd-standard
   ...
   workloadMetadataConfig:
   mode: GKE_METADATA
     

設定 Workload Identity

請按照下列程序，為下列 Hybrid 元件啟用 Workload Identity：

• apigee-datastore
• apigee-telemetry
• apigee-org
• apigee-env

使用 apigee-datastore、apigee-env、apigee-org 和 apigee-telemetry 圖表的 --dry-run 或 --dry-run=server 旗標執行 helm upgrade 時，輸出內容會包含設定 Workload Identity 時所需的指令，並提供正確的 GSA 和 KSA 名稱。

例如：

helm upgrade datastore apigee-datastore/ \
  --namespace $NAMESPACE \
  -f OVERRIDES_FILE \
  --dry-run=server

輸出內容如下所示：

NAME: datastore
...
For Cassandra backup GKE Workload Identity, please make sure to add the below membership to the IAM policy binding using the respective kubernetes SA (KSA).
gcloud iam service-accounts add-iam-policy-binding apigee-cassandra@PROJECT_ID.iam.gserviceaccount.com \
      --role roles/iam.workloadIdentityUser \
      --member "serviceAccount:PROJECT_ID.svc.id.goog[APIGEE_NAMESPACE/apigee-cassandra-default]" \
      --project PROJECT_ID

kubectl annotate serviceaccount apigee-cassandra-default \
      iam.gke.io/gcp-service-account=apigee-cassandra@PROJECT_ID.iam.gserviceaccount.com \
      --namespace APIGEE_NAMESPACE

其中：

• apigee-cassandra 是 Cassandra 的 Google 服務帳戶 (GSA) 名稱。請參閱「關於服務帳戶」。
• PROJECT_ID 會替換為您的 Google Cloud 專案 ID。
• APIGEE_NAMESPACE 會替換為您的 Apigee 命名空間，預設為 apigee。
• apigee-cassandra-default 是 apigee-datastore 資訊套件建立的 Cassandra Pod 的 Kubernetes 服務帳戶名稱。

1. 取得為 apigee-datastore 設定 Workload Identity 的指令，然後在輸出內容中執行 NOTES: 下的指令。

   helm upgrade datastore apigee-datastore/ \
     --namespace $NAMESPACE \
     -f OVERRIDES_FILE \
     --dry-run=server

2. 取得設定 apigee-telemetry 適用的 Workload Identity 指令，並在輸出內容的 NOTES: 下方執行這些指令。

   helm upgrade telemetry apigee-telemetry/ \
     --namespace $NAMESPACE \
     -f OVERRIDES_FILE \
     --dry-run

3. 取得設定 apigee-org 適用的 Workload Identity 指令，並在輸出內容的 NOTES: 下方執行這些指令。

   helm upgrade $ORG_NAME apigee-org/ \
     --namespace $NAMESPACE \
     -f OVERRIDES_FILE \
     --dry-run

4. 取得設定 apigee-env 適用的 Workload Identity 指令，並在輸出內容的 NOTES: 下方執行這些指令。

   helm upgrade $ENV_NAME apigee-env/ \
     --namespace $NAMESPACE \
     --set env=$ENV_NAME \
     -f OVERRIDES_FILE \
     --dry-run

   針對安裝中的每個環境重複這個步驟。

驗證 Workload Identity

1. 確認這些步驟是否有效：

   gcloud config set project $PROJECT_ID
   

   kubectl run --rm -it --image google/cloud-sdk:slim \
     --namespace $NAMESPACE workload-identity-test\
     -- gcloud auth list

   如果沒有看到命令提示字元，請嘗試按下 Enter 鍵。

   如果步驟執行正確，您應該會看到如下的回應：

                      Credentialed Accounts
   ACTIVE  ACCOUNT
   *       GSA@PROJECT_ID.iam.gserviceaccount.com

2. 如果從先前的安裝版本升級，請清除含有服務帳戶私密金鑰的密碼：

   kubectl delete secrets -n $NAMESPACE $(k get secrets -n $NAMESPACE | grep svc-account | awk '{print $1}')
   

3. 檢查記錄：

   kubectl logs -n $NAMESPACE -l app=apigee=synchronizer,env=$ENV_NAME,org=$ORG_NAME apigee-synchronizer
   

4. (選用) 您可以在 Google Cloud console的「Kubernetes: Workloads Overview」(Kubernetes：工作負載總覽) 頁面中，查看 Kubernetes 服務帳戶的狀態。

   前往「Workloads」(工作負載)