透過 Helm 資訊套件啟用 Workload Identity

本主題說明如何使用 Helm 圖表為 Apigee hybrid 啟用 Workload Identity。

如果您使用 apigeectl 安裝及管理 Apigee Hybrid，請參閱「透過 apigeectl 啟用 Workload Identity」。

總覽

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 服務帳戶互動。

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

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

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

驗證環境變數：

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

初始化所需的任何變數：

export PROJECT_ID=my-project-id
export ORG_NAME=$PROJECT_ID
export ENV_NAME=my-environment-name
export NAMESPACE=apigee
export CLUSTER_LOCATION=my-cluster-location
export CLUSTER_NAME=hybrid-base-directory/apigeectl

Workload Identity 和服務帳戶金鑰檔案

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

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

為 Apigee Hybrid 啟用 Workload Identity

請按照下列操作說明，為專案設定 Workload Identity。

已遷移的安裝項目和 Workload Identity

如果您使用 Apigee hybrid Helm 遷移工具，從 apigeectl 管理遷移叢集，則 Workload Identity 的覆寫語法會有所變更。您需要在覆寫檔案中檢查下列屬性：

• 必須提供 namespace。例如：

  instanceID: "hybrid-instance-1"
  namespace: "apigee"
  

• gcp.workloadIdentity.enabled 屬性會取代 gcp.workloadIdentityEnabled 屬性。例如：

  gcp:
    workloadIdentity:
      enabled: true

• 對於正式安裝作業，每個元件都有 gsa 屬性。這些屬性的值是對應元件的 Google IAM 服務帳戶電子郵件地址。例如：

  watcher
    gsa: apigee-watcher@my-hybrid-project.iam.gserviceaccount.com
  

• 如果是非正式環境安裝作業，您可以在 gcp.workloadIdentity.gsa 屬性中提供單一 GSA。

  gcp
    workloadIdentity
      gsa: apigee-watcher@my-hybrid-project.iam.gserviceaccount.com
  

• 使用 Helm 圖表搭配 Apigee Hybrid，並將 Workload Identity 的 GSA 混合使用於正式版和非正式版。您可以為 gcp.workloadIdentity.gsa 屬性指定單一 ，並為特定元件指定個別 GSA。您為個別元件提供的值，會覆寫您為該元件提供的 gcp.workloadIdentity.gsa 值。

準備設定 Workload Identity

1. 確認覆寫檔案中已啟用 Workload Identity。應在覆寫檔案中啟用，且應在下列設定屬性中提供值：
   • 對於所有安裝作業： gcp.workloadIdentityEnabled 應為 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-telemetry
• apigee-org
• apigee-env

當您為 apigee-datastore、apigee-env、apigee-org 和 apigee-telemetry 圖表使用 --dry-run 旗標執行 helm upgrade 時，輸出內容會包含您需要用來設定 Workload Identity 的正確 GSA 和 KSA 名稱指令。

例如：

helm upgrade datastore apigee-datastore/ \
  --namespace $NAMESPACE \
  -f overrides.yaml \
  --dry-run

NAME: datastore
...
For C* 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  \
      --role roles/iam.workloadIdentityUser \
      --member "serviceAccount:my-project.svc.id.goog[apigee/apigee-cassandra-backup-sa]" \
      --project :my-project

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

   helm upgrade datastore apigee-datastore/ \
     --namespace $NAMESPACE \
     -f overrides.yaml \
     --dry-run

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

   helm upgrade telemetry apigee-telemetry/ \
     --namespace $NAMESPACE \
     -f overrides.yaml \
     --dry-run

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

   helm upgrade $ORG_NAME apigee-org/ \
     --namespace $NAMESPACE \
     -f overrides.yaml \
     --dry-run

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

   helm upgrade $ENV_NAME apigee-env/ \
     --namespace $NAMESPACE \
     --set env=ENV_NAME \
     -f overrides.yaml \
     --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：工作負載總覽」頁面中查看 Kubernetes 服務帳戶的狀態。

   前往「Workloads」(工作負載)