GKE ワークロードから Google Cloud APIs に対する認証を行う

このページでは、Workload Identity Federation for GKE を使用して、Google Kubernetes Engine（GKE）クラスタで実行されているワークロードから Google Cloud APIs に安全にアクセスする方法について説明します。

このページは、ユーザー権限に関連するポリシーを作成、管理する ID とアカウントの管理者、オペレーター、デベロッパーを対象としています。Google Cloud のコンテンツで参照する一般的なロールとタスク例の詳細については、一般的な GKE Enterprise ユーザーロールとタスクをご覧ください。

このページを読む前に、GKE 用 Workload Identity 連携のコンセプトを理解しておく必要があります。

始める前に

作業を始める前に、次のことを確認してください。

• Google Kubernetes Engine API を有効にする。
Google Kubernetes Engine API の有効化
• このタスクに Google Cloud CLI を使用する場合は、gcloud CLI をインストールして初期化する。すでに gcloud CLI をインストールしている場合は、gcloud components update を実行して最新のバージョンを取得する。

• アクセスする Google Cloud APIs が、GKE 用 Workload Identity 連携でサポートされていることを確認します。サポートされている API のリストについては、サポートされているプロダクトと制限事項をご覧ください。API がサポートされていない場合、またはサービスの Workload Identity 連携の制限によってユースケースがブロックされている場合は、このページの代替方法: Kubernetes ServiceAccounts を IAM にリンクするをご覧ください。

• IAM Service Account Credentials API が有効になっていることを確認します。

  IAM Credentials API を有効にする

• 次の IAM ロールがあることを確認します。

  • roles/container.admin
  • roles/iam.serviceAccountAdmin

• GKE 用 Workload Identity 連携の制限事項を理解しておいてください。

クラスタとノードプールで GKE 用 Workload Identity 連携を有効にする

Autopilot では、GKE 用 Workload Identity 連携が常に有効になっています。GKE 用 Workload Identity 連携を使用するようアプリケーションを構成するセクションに進みます。

Standard では、Google Cloud CLI または Google Cloud コンソールを使用して、クラスタとノードプールで GKE 用 Workload Identity 連携を有効にします。ノードプールで GKE 用 Workload Identity 連携を有効にするには、クラスタレベルで GKE 用 Workload Identity 連携を有効にする必要があります。

新しいクラスタを作成する

新しい Standard クラスタで GKE 用 Workload Identity 連携を有効にするには、gcloud CLI または Google Cloud コンソールを使用します。

既存のクラスタを更新する

既存の Standard クラスタで GKE 用 Workload Identity 連携を有効にするには、gcloud CLI または Google Cloud コンソールを使用します。既存のノードプールは影響を受けませんが、クラスタ内の新しいノードプールでは GKE 用 Workload Identity 連携が使用されます。

既存のワークロードを GKE 用 Workload Identity 連携に移行する

既存のクラスタで GKE 用 Workload Identity 連携を有効にした後、GKE 用 Workload Identity 連携を使用するように実行中のワークロードを移行することをおすすめします。ご使用の環境に適した移行方法を選択します。GKE 用 Workload Identity 連携を有効にして新しいノードプールを作成することも、既存のノードプールを更新して GKE 用 Workload Identity 連携を有効にすることもできます。

ノードプールで GKE 用 Workload Identity 連携を有効にできるのは、クラスタで GKE 用 Workload Identity 連携が有効になっている場合のみです。

新しいノードプールを作成する

クラスタで GKE 用 Workload Identity 連携が有効になっている場合、新しいノードプールを作成すると、そのプールではデフォルトで GKE 用 Workload Identity 連携が使用されます。GKE 用 Workload Identity 連携を有効にした新しいノードプールを作成するには、次のコマンドを実行します。

gcloud container node-pools create NODEPOOL_NAME \
    --cluster=CLUSTER_NAME \
    --region=COMPUTE_REGION \
    --workload-metadata=GKE_METADATA

次のように置き換えます。

• NODEPOOL_NAME: 新しいノードプールの名前。
• CLUSTER_NAME: GKE 用 Workload Identity 連携が有効になっている既存のクラスタの名前。

--workload-metadata=GKE_METADATA フラグにより、GKE メタデータ サーバーを使用するようにノードプールが構成されます。

既存のノードプールを更新する

クラスタで GKE 用 Workload Identity 連携を有効にした後、既存のノードプールで GKE の Workload Identity 連携を手動で有効にできます。

GKE 用 Workload Identity 連携を使用するようにアプリケーションを構成する

GKE アプリケーションが GKE 用 Workload Identity 連携を使用して Google Cloud APIs に対して認証できるようにするには、特定の API の IAM ポリシーを作成します。これらのポリシーのプリンシパルは、ワークロード、Namespace、または ServiceAccount に対応する IAM プリンシパル識別子です。このプロセスは、ワークロードが API 呼び出しで使用できる連携アクセス トークンを返します。

または、IAM サービス アカウントの権限を借用するように Kubernetes ServiceAccount を構成することもできます。これにより、連携アクセス トークンを IAM Service Account Credentials API のアクセス トークンと交換するように GKE が構成されます。詳細については、代替方法: Kubernetes ServiceAccount を IAM にリンクするをご覧ください。

認可とプリンシパルを構成する

1. クラスタの認証情報を取得します。

   gcloud container clusters get-credentials CLUSTER_NAME \
       --location=LOCATION
   

   次のように置き換えます。

   • CLUSTER_NAME: GKE 用 Workload Identity 連携が有効になっているクラスタの名前。
   • LOCATION: クラスタのロケーション。

2. Kubernetes サービス アカウントに使用する Namespace を作成します。default Namespace を使用することも、既存の Namespace を使用することもできます。

   kubectl create namespace NAMESPACE
   

3. アプリケーションで使用する Kubernetes ServiceAccount を作成します。任意の Namespace で既存の Kubernetes ServiceAccount を使用することもできます。ワークロードに ServiceAccount を割り当てなかった場合、Kubernetes は Namespace に default ServiceAccount を割り当てます。

   kubectl create serviceaccount KSA_NAME \
       --namespace NAMESPACE
   

   次のように置き換えます。

   • KSA_NAME: 新しい Kubernetes ServiceAccount の名前。
   • NAMESPACE: ServiceAccount の Kubernetes Namespace の名前。

4. Kubernetes ServiceAccount を参照する IAM 許可ポリシーを作成します。アプリケーションがアクセスする必要がある特定の Google Cloud リソースに、権限を付与することをおすすめします。プロジェクトで許可ポリシーを作成するには、関連する IAM 権限が必要です。

   たとえば、次のコマンドは、作成した ServiceAccount に Kubernetes Engine Cluster 閲覧者（roles/container.clusterViewer）のロールを付与します。

   gcloud projects add-iam-policy-binding projects/PROJECT_ID \
       --role=roles/container.clusterViewer \
       --member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME \
       --condition=None
   

   次のように置き換えます。

   • PROJECT_ID: Google Cloud プロジェクト ID。
   • PROJECT_NUMBER: 数値による Google Cloud プロジェクト番号。

   IAM 許可ポリシーをサポートする任意の Google Cloud リソースにロールを付与できます。プリンシパル ID の構文は、Kubernetes リソースによって異なります。サポートされている ID のリストについては、Workload Identity Federation for GKE のプリンシパル ID をご覧ください。

省略可: サービス メッシュ オプションを構成する

Istio または Cloud Service Mesh を使用して環境を管理している場合は、Pod 仕様の metadata.annotations フィールドに次のアノテーションを追加します。

metadata:
  annotations:
    proxy.istio.io/config: '{ "holdApplicationUntilProxyStarts": true }'

このアノテーションにより、サービス メッシュ プロキシがアプリケーションからのトラフィックをリダイレクトする準備ができるまで、コンテナが起動されなくなります。

GKE 用 Workload Identity 連携の設定を確認する

このセクションでは、Cloud Storage バケットを作成し、前のセクションで作成した Kubernetes ServiceAccount にバケットの閲覧権限を付与します。次に、ワークロードをデプロイし、コンテナがプロジェクト内のクラスタを一覧取得できるかどうかをテストします。

1. 空の Cloud Storage バケットを作成します。

   gcloud storage buckets create gs://BUCKET
   

   BUCKET は、新しいバケットの名前に置き換えます。

2. 作成した ServiceAccount に Storage オブジェクト閲覧者（roles/storage.objectViewer）のロールを付与します。

   gcloud storage buckets add-iam-policy-binding gs://BUCKET \
       --role=roles/storage.objectViewer \
       --member=principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME \
       --condition=None
   

   次のように置き換えます。

   • PROJECT_ID: Google Cloud プロジェクト ID。
   • PROJECT_NUMBER: 数値による Google Cloud プロジェクト番号。
   • NAMESPACE: ServiceAccount を含む Kubernetes Namespace。
   • KSA_NAME: ServiceAccount の名前。

3. 次のマニフェストを test-app.yaml として保存します。

   apiVersion: v1
   kind: Pod
   metadata:
     name: test-pod
     namespace: NAMESPACE
   spec:
     serviceAccountName: KSA_NAME
     containers:
     - name: test-pod
       image: google/cloud-sdk:slim
       command: ["sleep","infinity"]
       resources:
         requests:
           cpu: 500m
           memory: 512Mi
           ephemeral-storage: 10Mi
   

4. Standard クラスタの場合のみ、template.spec フィールドに以下を追加して、GKE 用 Workload Identity 連携を使用するノードプールに Pod を配置します。

   すべてのノードが GKE 用 Workload Identity 連携を使用するので、Autopilot クラスタではこの手順をスキップします。Autopilot クラスタではこの nodeSelector が拒否されます。

   spec:
     nodeSelector:
       iam.gke.io/gke-metadata-server-enabled: "true"
   

5. クラスタに構成ファイルを適用します。

   kubectl apply -f test-app.yaml
   

6. Pod の準備ができるまで待ちます。Pod のステータスを確認するには、次のコマンドを実行します。

   kubectl get pods --namespace=NAMESPACE
   

   Pod の準備が整うと、出力は次のようになります。

   NAME       READY   STATUS    RESTARTS   AGE
   test-pod   1/1     Running   0          5m27s
   

7. Pod でシェル セッションを開きます。

   kubectl exec -it pods/test-pod --namespace=NAMESPACE -- /bin/bash
   

8. バケット内のオブジェクトのリストを取得します。

   curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
       "https://storage.googleapis.com/storage/v1/b/BUCKET/o"
   

   次のような出力が表示されます。

   {
     "kind": "storage#objects"
   }
   

   この出力は、Pod がバケット内のオブジェクトにアクセスできることを示しています。

代替方法: Kubernetes ServiceAccount を IAM にリンクする

1. Kubernetes Namespace を作成します。

   kubectl create namespace NAMESPACE
   

2. Kubernetes ServiceAccount を作成します。

   kubectl create serviceaccount KSA_NAME \
       --namespace=NAMESPACE
   

3. IAM サービス アカウントを作成します。組織内の任意のプロジェクトで既存の IAM サービス アカウントを使用することもできます。

   gcloud iam service-accounts create IAM_SA_NAME \
       --project=IAM_SA_PROJECT_ID
   

   次のように置き換えます。

   • IAM_SA_NAME: 新しい IAM サービス アカウントの名前。
   • IAM_SA_PROJECT_ID: IAM サービス アカウントのプロジェクト ID。

   IAM サービス アカウントから Google Cloud APIs へのアクセスを承認する方法については、サービス アカウントについてをご覧ください。

4. IAM サービス アカウントに、特定の Google Cloud APIs で必要なロールを付与します。

   gcloud projects add-iam-policy-binding IAM_SA_PROJECT_ID \
       --member "serviceAccount:IAM_SA_NAME@IAM_SA_PROJECT_ID.iam.gserviceaccount.com" \
       --role "ROLE_NAME"
   

   ROLE_NAME は、ロールの名前（roles/spanner.viewer など）に置き換えます。

5. Kubernetes ServiceAccount に IAM サービス アカウントの権限借用を許可する IAM 許可ポリシーを作成します。

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

   メンバー名には、Namespace と Kubernetes ServiceAccount の名前を含める必要があります。例: serviceAccount:example-project.svc.id.goog[example-namespace/example-serviceaccount]

6. GKE がサービス アカウント間のリンクを認識できるように、Kubernetes ServiceAccount にアノテーションを付けます。

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

   この方法を使用する場合は、IAM 許可ポリシーとアノテーションの両方が必要です。

コードから Workload Identity Federation for GKE を使用する

コードで Google Cloud サービスに対する認証を行うプロセスは、Compute Engine のメタデータ サーバーを使用した認証と同じです。GKE 用 Workload Identity 連携を使用すると、インスタンス メタデータ サーバーへのリクエストが GKE メタデータ サーバーに転送されます。インスタンス メタデータ サーバーを使用して認証する既存のコードは（Google Cloud クライアント ライブラリを使用したコードと同様）、変更せずにそのまま使用できます。

GKE 用 Workload Identity 連携で別のプロジェクトの割り当てを使用する

GKE バージョン 1.24 以降を実行しているクラスタでは、IAM Service Account Credentials API の GenerateAccessToken メソッドと GenerateIdToken メソッドの呼び出し時に、別の Google Cloud プロジェクトの割り当てを使用するように、Kubernetes サービス アカウントを必要に応じて構成できます。これにより、メイン プロジェクトで割り当てのすべてを使用することを避け、クラスタ内のこれらのサービスに他のプロジェクトの割り当てを使用できます。

GKE 用 Workload Identity 連携を使用して割り当てプロジェクトを構成するには、次の操作を行います。

1. 割り当てプロジェクトの serviceusage.services.use 権限を Kubernetes サービス アカウントに付与します。

   gcloud projects add-iam-policy-binding QUOTA_PROJECT_ID \
       --role=roles/serviceusage.serviceUsageConsumer \
       --member='principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME' \
   

   QUOTA_PROJECT_ID は、割り当てプロジェクトのプロジェクト ID に置き換えます。

2. 割り当てプロジェクトを使用して Kubernetes サービス アカウントにアノテーションを付けます。

   kubectl annotate serviceaccount KSA_NAME \
       --namespace NAMESPACE \
       iam.gke.io/credential-quota-project=QUOTA_PROJECT_ID
   

構成が正しく機能することを確認するには、次の操作を行います。

1. Pod を作成し、シェル セッションを開始します。実行中のコンテナにシェルを用意する方法については、Kubernetes のドキュメントをご覧ください。

2. メタデータ サーバーにリクエストを行います。

   curl -H "Metadata-Flavor: Google" http://169.254.169.254/computeMetadata/v1/instance/service-accounts/default/token
   

3. Google Cloud コンソールで、割り当てプロジェクトの IAM Service Accounts Credentials API ページに移動します。

   [API] に移動

4. トラフィックの変化を確認します。

クリーンアップ

GKE 用 Workload Identity 連携の使用を停止するには、IAM サービス アカウントへのアクセス権を取り消して、クラスタで GKE 用 Workload Identity 連携を無効にします。

アクセス権の取り消し

プリンシパルへのアクセス権を取り消すには、GKE 用 Workload Identity 連携を使用するようにアプリケーションを構成するで作成した IAM 許可ポリシーを削除します。

たとえば、Artifact Registry リポジトリへのアクセス権を取り消すには、次のコマンドを実行します。

gcloud artifacts repositories remove-iam-policy-binding REPOSITORY_NAME \
    --location=REPOSITORY_LOCATION \
    --member='principal://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/PROJECT_ID.svc.id.goog/subject/ns/NAMESPACE/sa/KSA_NAME' \
    --role='roles/artifactregistry.reader' \
    --all

Workload Identity Federation for GKE を無効にする

GKE 用 Workload Identity 連携は、GKE Standard クラスタでのみ無効にできます。

組織で GKE 用 Workload Identity 連携を無効にする

セキュリティの面から見ると、GKE 用 Workload Identity 連携により、GKE は Google Cloud リソースの認証と認可が可能な Kubernetes サービス アカウント ID であることを表明しています。サービス アカウントの作成の無効化やサービス アカウント キーの作成の無効化など、ワークロードを Google Cloud リソースから分離するための措置を講じた場合、組織の GKE 用 Workload Identity 連携の無効化が必要になる場合もあります。

組織の GKE 用 Workload Identity 連携を無効にする手順をご覧ください。

トラブルシューティング

トラブルシューティング情報については、GKE 用 Workload Identity 連携のトラブルシューティングをご覧ください。

次のステップ

• GKE の Workload Identity 連携について理解する。
• GKE セキュリティの概要を確認する。
• クラスタ メタデータの保護について確認する。
• IAM サービス アカウントについて学習する。