Apigee ハイブリッドによる Workload Identity の有効化

現在、Apigee ハイブリッド バージョン 1.5 のドキュメントを表示しています。このバージョンのサポートは終了しています。新しいバージョンにアップグレードする必要があります。詳細については、サポートされているバージョンをご覧ください。

Version 1.5 (unsupported)

   Supported versions:

• v1.12 (latest)                        
• v1.11                         
• v1.10                                        
• List of supported versions

   Unsupported versions:

• v1.9                                         
• v1.8                                         
• v1.7                                         
• v1.6                                         
• v1.5                                         
• v1.4                                         
• v1.3                                         
• v1.2                                         
• v1.1                                         

このトピックでは、Apigee ハイブリッドを有効にする方法について説明します。

概要

Workload Identity は、GKE（Google Kubernetes Engine）内で実行されているアプリケーションが Google Cloud サービスにアクセスするための方法です。Workload Identity の概要については、以下をご覧ください。

• Workload Identity の概要: GKE アプリケーションの認証の改善
• Workload Identity の使用

Google Cloud IAM サービス アカウントは、アプリケーションが Google API へのリクエストに使用できる ID です。このドキュメントでは、これらのサービス アカウントを GSA（Google サービス アカウント）と呼びます。GSA の詳細については、サービス アカウントをご覧ください。

これとは別に、Kubernetes にもサービス アカウントという概念があります。サービス アカウントは、Pod で実行されるプロセスの ID を提供します。Kubernetes サービス アカウントは Kubernetes のリソースですが、Google サービス アカウントは Google Cloud 固有のものです。Kubernetes サービス アカウントの詳細については、Kubernetes ドキュメントの Pod のサービス アカウントを構成するをご覧ください。

Apigee ハイブリッド 1.4 以降では、コンポーネントのタイプごとに Kubernetes サービス アカウントを作成して使用します。Workload Identity を有効にすると、ハイブリッド コンポーネントが Kubernetes サービス アカウントとやり取りできます。

前提条件

Workload Identity を Apigee ハイブリッドで有効にする前に、Apigee を実行する GKE クラスタで Workload Identity を有効にする必要があります。

Anthos Service Mesh（ASM）向けの手順を実施している場合、Workload Identity はすでにクラスタで有効になっています。

次のコマンドを実行して、Workload Identity が有効になっているかどうかを確認できます。

gcloud container clusters describe $CLUSTER_NAME

出力は次のようになります。

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

GKE で Apigee ハイブリッドを実行するときには、通常、各サービス アカウントの秘密鍵（.json ファイル）を作成してダウンロードします。Workload Identity を使用する場合、サービス アカウントの秘密鍵をダウンロードして GKE クラスタに追加する必要はありません。

Workload Identity を有効にする

この手順は以下の 3 つのセクションに分かれています。

• Workload Identity を有効にする準備を行う。Workload Identity を有効にする前に、以下の手順に沿ってノードプールを更新して変数を初期化します。
• 新規インストール用に Workload Identity を有効にする。Apigee ハイブリッドを新規にインストールする場合、またはハイブリッド インストールに ASM をまだインストールしていない場合は、この手順に沿って操作してください。
• Workload Identity を使用するためにインストールをアップグレードする。既存の Apigee ハイブリッド インストールで Workload Identity を有効にするには、この手順に沿って操作してください。

Workload Identity を有効にする準備を行う

以下の手順では、Apigee ハイブリッド ランタイム向けに 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. 以下のハイライト表示された行を、gcp スタンザの下の overrides.yaml ファイルに追加します。

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

2. Google サービス アカウントを作成します。次の 2 つの方法があります。
   • 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

   各環境の場合:

   注: GSA_NAME がコンポーネントと一致していることを確認してください。以下の手順では、GSA_NAME は環境変数ではありません。
   • Runtime

     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 ハイブリッドのインストールを続けます。

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 ハイブリッド 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

ここで、ORG_NAME と ENV_NAME は、組織名と環境名の短縮版です。

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 Synchronizer の権限を設定する場合は、次のコマンドを実行します。

   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 Synchronizer の権限を設定する場合は、次のコマンドを実行します。

   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