本主題說明如何啟用 Apigee hybrid。

總覽

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 設定服務帳戶」一節。

在 Apigee hybrid 1.4 以上版本中，Apigee 會為每種類型的元件建立及使用 Kubernetes 服務帳戶。啟用 Workload Identity 後，混合式元件就能與 Kubernetes 服務帳戶互動。

必要條件

為 Apigee hybrid 啟用 Workload Identity 前，請先為執行 Apigee 的 GKE 叢集啟用 Workload Identity。

如果您已按照 Anthos 服務網格 (ASM) 的操作說明操作，叢集就已啟用 Workload Identity。

您可以執行下列指令，確認是否已啟用 Workload Identity：

gcloud container clusters describe $CLUSTER_NAME

輸出內容應如下所示：

…
…
status: RUNNING
subnetwork: default
workloadIdentityConfig:
  workloadPool: PROJECT_ID.svc.id.goog

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

啟用 Workload Identity

這些操作說明分為三個部分：

• 準備啟用 Workload Identity。請按照這些操作說明更新節點集區，並在啟用 Workload Identity 之前初始化變數。
• 為新安裝的叢集啟用 Workload Identity。如果您是新安裝 Apigee Hybrid，或是尚未在混合式安裝中安裝 ASM，請按照這些操作說明操作。
• 升級安裝項目以使用 Workload Identity。請按照這些操作說明，在現有的 Apigee Hybrid 安裝作業中啟用 Workload Identity。

準備啟用 Workload Identity

以下操作說明說明如何為 Apigee Hybrid 執行階段啟用 Workload Identity。

更新節點集區

使用下列指令，確認每個節點集區都已啟用 Workload Identity：

gcloud container node-pools update $NODE_POOL_NAME \
  --cluster=$CLUSTER_NAME \
  --workload-metadata=GKE_METADATA

初始化變數

初始化下列變數：

export PROJECT_ID=my-project-id
export ORG_NAME=$PROJECT_ID
export ENV_NAME=my-environment-name
export NAMESPACE=apigee #the namespace where apigee is installed

gcloud config set project $PROJECT_ID

為新安裝的叢集啟用 Workload Identity

1. 在 overrides.yaml 檔案的 gcp 段落下方，加入下方醒目顯示的程式碼行：

   gcp:
     projectID: "my-project"
     name: "my-project"
     region: "us-west1"
     workloadIdentityEnabled: true

2. 建立 Google 服務帳戶。您可以使用以下兩種方法：
   • 使用 create-service-account 工具，透過下列指令為每個元件建立 Google 服務帳戶：

     $APIGEECTL_HOME/tools/create-service-account --env prod --dir $APIGEECTL_HOME/../service-accounts

     這項指令會建立下列服務帳戶：

     • apigee-logger
     • apigee-metrics
     • apigee-cassandra
     • apigee-udca
     • apigee-synchronizer
     • apigee-mart
     • apigee-watcher
     • apigee-distributed-trace

     以下說明假設您已使用 create-service-account 工具產生服務帳戶。

   • 為每個環境定義自訂命名慣例和服務帳戶 (適用於進階使用者)
3. 建立 Kubernetes 服務帳戶。

   機構層級元件：

   • Cassandra

     kubectl create sa -n $NAMESPACE apigee-cassandra-schema-setup-$(apigeectl encode --org $ORG_NAME)-sa \
       && kubectl label sa -n $NAMESPACE -l app=apigee-cassandra,org=$ORG_NAME \
       && kubectl annotate serviceaccount \
       --namespace $NAMESPACE apigee-cassandra-schema-setup-$(apigeectl encode --org $ORG_NAME)-sa iam.gke.io/gcp-service-account=GSA_NAME@$PROJECT_ID.iam.gserviceaccount.com

     kubectl create sa -n $NAMESPACE apigee-cassandra-user-setup-$(apigeectl encode --org $ORG_NAME)-sa \
       && kubectl label sa -n $NAMESPACE -l app=apigee-cassandra,org=$ORG_NAME \
       && kubectl annotate serviceaccount \
       --namespace $NAMESPACE apigee-cassandra-user-setup-$(apigeectl encode --org $ORG_NAME)-sa iam.gke.io/gcp-service-account=GSA_NAME@$PROJECT_ID.iam.gserviceaccount.com

   • MART

     kubectl create sa -n $NAMESPACE apigee-mart-$(apigeectl encode --org $ORG_NAME)-sa \
       && kubectl label sa -n $NAMESPACE -l app=apigee-mart,org=$ORG_NAME \
       && kubectl annotate serviceaccount \
       --namespace $NAMESPACE apigee-mart-$(apigeectl encode --org $ORG_NAME)-sa iam.gke.io/gcp-service-account=GSA_NAME@$PROJECT_ID.iam.gserviceaccount.com

   • Apigee Connect

     kubectl create sa -n $NAMESPACE apigee-connect-$(apigeectl encode --org $ORG_NAME)-sa \
       && kubectl label sa -n $NAMESPACE -l app=apigee-connect,org=$ORG_NAME \
       && kubectl annotate serviceaccount \
       --namespace $NAMESPACE apigee-connect-$(apigeectl encode --org $ORG_NAME)-sa iam.gke.io/gcp-service-account=GSA_NAME@$PROJECT_ID.iam.gserviceaccount.com
     

   • Apigee Watcher

     kubectl create sa -n $NAMESPACE apigee-watcher-$(apigeectl encode --org $ORG_NAME)-sa \
       && kubectl label sa -n $NAMESPACE -l app=apigee-watcher,org=$ORG_NAME \
       && kubectl annotate serviceaccount \
       --namespace $NAMESPACE apigee-watcher-$(apigeectl encode --org $ORG_NAME)-sa iam.gke.io/gcp-service-account=GSA_NAME@$PROJECT_ID.iam.gserviceaccount.com

   針對每個環境：

   • 執行階段

     kubectl create sa -n $NAMESPACE apigee-runtime-$(apigeectl encode --org $ORG_NAME --env $ENV_NAME)-sa \
       && kubectl label sa -n $NAMESPACE -l app=apigee-runtime,org=$ORG_NAME,env=$ENV_NAME \
       && kubectl annotate serviceaccount \
       --namespace $NAMESPACE apigee-runtime-$(apigeectl encode --org $ORG_NAME --env $ENV_NAME)-sa iam.gke.io/gcp-service-account=GSA_NAME@$PROJECT_ID.iam.gserviceaccount.com

   • UDCA

     kubectl create sa -n $NAMESPACE apigee-udca-$(apigeectl encode --org $ORG_NAME --env $ENV_NAME)-sa \
       && kubectl label sa -n $NAMESPACE -l app=apigee-udca,org=$ORG_NAME,emv=$ENV_NAME \
       && kubectl annotate serviceaccount \
       --namespace $NAMESPACE apigee-udca-$(apigeectl encode --org $ORG_NAME --env $ENV_NAME)-sa iam.gke.io/gcp-service-account=GSA_NAME@$PROJECT_ID.iam.gserviceaccount.com

   • Synchronizer

     kubectl create sa -n $NAMESPACE apigee-synchronizer-$(apigeectl encode --org $ORG_NAME --env $ENV_NAME)-sa \
       && kubectl label sa -n $NAMESPACE -l app=apigee-synchronizer,org=$ORG_NAME,env=$ENV_NAME \
       && kubectl annotate serviceaccount \
       --namespace $NAMESPACE apigee-syncrhonizer-$(apigeectl encode --org $ORG_NAME --env $ENV_NAME)-sa iam.gke.io/gcp-service-account=GSA_NAME@$PROJECT_ID.iam.gserviceaccount.com

4. 繼續按照一般方式安裝 Apigee Hybrid。

升級安裝作業，以便使用 Workload Identity

以下範例說明為 Apigee 建立的 Google 服務帳戶 (GSA)：

gcloud iam service-accounts list | grep apigee

apigee-connect   apigee-connect@$PROJECT_ID.iam.gserviceaccount.com    False
apigee-runtime   apigee-runtime@$PROJECT_ID.iam.gserviceaccount.com    False
apigee-metrics   apigee-metrics@$PROJECT_ID.iam.gserviceaccount.com    False
apigee-mart      apigee-mart@$PROJECT_ID.iam.gserviceaccount.com       False
apigee-watcher   apigee-watcher@$PROJECT_ID.iam.gserviceaccount.com    False
apigee-sync      apigee-sync@$PROJECT_ID.iam.gserviceaccount.com       False
apigee-udca      apigee-udca@$PROJECT_ID.iam.gserviceaccount.com       False

以下是為 Apigee 建立的 Kubernetes 服務帳戶 (KSA) 範例 (假設已安裝 Apigee hybrid 1.4 以上版本)：

kubectl get sa -n $NAMESPACE

apigee-cassandra-schema-setup-ORG_NAME-cb84b88-sa                1         xxd
apigee-cassandra-user-setup-ORG_NAME-cb84b88-sa                  1         xxd
apigee-connect-agent-ORG_NAME-cb84b88-sa                         1         xxd
apigee-init                                                        1         xxd
apigee-mart-ORG_NAME-cb84b88-sa                                  1         xxd
apigee-metrics-apigee-telemetry                                    1         xxd
apigee-runtime-ORG_NAME-ENV_NAME-1d0dc5e-sa                    1         xxd
apigee-synchronizer-ORG_NAME-ENV_NAME-1d0dc5e-sa               1         xxd
apigee-udca-ORG_NAME-ENV_NAME-1d0dc5e-sa                       1         xxd
apigee-watcher-ORG_NAME-cb84b88                                  1         xxd

1. 將 Workload Identity 角色新增至每個服務帳戶：

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

   舉例來說，如果您要設定 Apigee 同步處理工具的權限，請執行以下命令：

   export KSA_NAME=$(kubectl get sa -n apigee -l app=apigee-synchronizer,env=$ENV_NAME,org=$ORG_NAME --output=jsonpath={.items..metadata.name})
   

   gcloud iam service-accounts add-iam-policy-binding --role roles/iam.workloadIdentityUser --member "serviceAccount:$PROJECT_ID.svc.id.goog[apigee/$KSA_NAME]" apigee-sync@$PROJECT_ID.iam.gserviceaccount.com
   

2. 請在每個 KSA 中加上 GSA 詳細資料的註解：

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

   舉例來說，如果您要設定 Apigee 同步處理工具的權限，請執行以下命令：

   export KSA_NAME=$(kubectl get sa -n apigee -l app=apigee-synchronizer,env=$ENV_NAME,org=$ORG_NAME --output=jsonpath={.items..metadata.name})
   

   kubectl annotate serviceaccount --namespace $NAMESPACE $KSA_NAME iam.gke.io/gcp-service-account=apigee-sync@$PROJECT_ID.iam.gserviceaccount.com
   

3. 驗證步驟是否有效：

   gcloud config set project $PROJECT_ID
   

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

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

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

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

4. 如果您是從先前的安裝作業升級，請清除包含服務帳戶私密金鑰的機密：

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

5. 檢查記錄：

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