Workload Identity を使用する

このドキュメントでは、Google Kubernetes Engine(GKE)クラスタで Workload Identity を有効にして構成する方法を説明します。Workload Identity を使用すると、GKE クラスタ内のワークロードが Identity and Access Management(IAM)サービス アカウントに代わって Google Cloud サービスにアクセスできます。Autopilot クラスタでは、Workload identity はデフォルトで有効になります。

Workload Identity の仕組みの詳細については、Workload Identity をご覧ください。

制限事項

  • GKE は、Google Cloud プロジェクトごとに固定の Workload Identity プールを PROJECT_ID.svc.id.goog という形式で作成します。

  • Workload Identity はメタデータ隠蔽機能に代わるものです。メタデータ隠蔽機能で保護された機密メタデータは Workload Identity でも保護されます。

  • GKE がノードプールで GKE メタデータ サーバーを有効にすると、Pod は Compute Engine メタデータ サーバーにアクセスできなくなります。GKE メタデータ サーバーは、ホスト ネットワークで実行されている Pod を除き、これらの Pod からメタデータ エンドポイントへのリクエストをインターセプトします。

  • ホスト ネットワークで実行されている Pod で Workload Identity を使用することはできません。これらの Pod からメタデータ エンドポイントへのリクエストは、Compute Engine のメタデータ サーバーに転送されます。

  • GKE メタデータ サーバーが新しく作成された Pod でのリクエストの承認を開始するまでに数秒かかります。したがって、Pod の有効期間の最初の数秒以内に Workload Identity を使用して認証を試みると、失敗する可能性があります。この問題は、呼び出しを再試行することで解決します。詳細については、トラブルシューティングのセクションをご覧ください。

  • GKE の組み込みの Logging エージェントと Monitoring エージェントは、引き続きノードのサービス アカウントを使用します。

  • Workload Identity を有効にしても Cloud Run for Anthos がリクエスト指標のリリースを継続するには手動による設定が必要になります。

  • Workload Identity は、クラスタが --disable-default-snat フラグなしで作成された場合に ip-masq-agent をインストールします。

  • Workload Identity は、メモリの問題を回避するため、ノードごとに GKE メタデータ サーバーへの接続を 200 に制限します。ノードがこの上限を超えると、タイムアウトが発生することがあります。

  • Windows Server ノードの Workload Identity は、GKE バージョン 1.18.16-gke.1200、1.19.8-gke.1300、1.20.4-gke.1500 以降で使用できます。

始める前に

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

  • Google Kubernetes Engine API が有効になっていることを確認します。
  • Google Kubernetes Engine API の有効化
  • Google Cloud CLI がインストールされていることを確認します。
  • 次のいずれかの方法で、プロジェクトにデフォルトの Google Cloud CLI 設定をセットアップします。
    • プロジェクトのデフォルトの設定全般を確認する場合は、gcloud init を使用します。
    • gcloud config を使用して、プロジェクト ID、ゾーン、リージョンを個別に設定します。

    gcloud init

    1. gcloud init を実行して、次の操作を行います。

      gcloud init

      リモート サーバーで SSH を使用している場合は、--console-only フラグを指定して、コマンドがブラウザを起動しないようにします。

      gcloud init --console-only
    2. Google Cloud アカウントを使用できるように、gcloud CLI の承認手順を行います。
    3. 新しい構成を作成するか、既存の構成を選択します。
    4. Google Cloud プロジェクトを選択します。
    5. デフォルトの Compute Engine ゾーンを選択します。
    6. デフォルトの Compute Engine リージョンを選択します。

    gcloud config

    1. デフォルトのプロジェクト ID を設定します。
      gcloud config set project PROJECT_ID
    2. デフォルトの Compute Engine リージョン(例: us-central1)を設定します。
      gcloud config set compute/region COMPUTE_REGION
    3. デフォルトの Compute Engine ゾーン(例: us-central1-c)を設定します。
      gcloud config set compute/zone COMPUTE_ZONE
    4. gcloud を最新バージョンに更新します。
      gcloud components update

    デフォルトの場所を設定することで、gcloud CLI のエラー(One of [--zone, --region] must be supplied: Please specify location など)を防止できます。

Workload Identity を有効にする

Workload Identity は、Google Cloud CLI または Google Cloud コンソールを使用して、クラスタとノードプールで有効にできます。

Workload Identity をノードプールで有効にするには、クラスタレベルで Workload Identity を有効にする必要があります

新しいクラスタの作成

Workload Identity は、gcloud CLI または Cloud コンソールを使用して新しい標準クラスタで有効にできます。

gcloud

新しいクラスタで Workload Identity を有効にするには、次のコマンドを実行します。

gcloud container clusters create CLUSTER_NAME \
    --region=COMPUTE_REGION \
    --workload-pool=PROJECT_ID.svc.id.goog

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

  • CLUSTER_NAME: 新しいクラスタの名前。
  • COMPUTE_REGION: クラスタの Compute Engine のリージョン。ゾーンクラスタの場合は、--zone=COMPUTE_ZONE を使用します。
  • PROJECT_ID: Google Cloud プロジェクト ID。

Console

新しいクラスタで Workload Identity を有効にする手順は、次のとおりです。

  1. Cloud コンソールで Google Kubernetes Engine ページに移動します。

    Google Kubernetes Engine に移動

  2. [ 作成] をクリックします。

  3. [クラスタを作成] ダイアログで、GKE Standard の [構成] をクリックします。

  4. ナビゲーション メニューの [クラスタ] セクションで、[セキュリティ] をクリックします。

  5. [ワークロード ID を有効にする] チェックボックスをオンにします。

  6. クラスタの構成を続行して、[作成] をクリックします。

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

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

gcloud

既存のクラスタで Workload Identity を有効にするには、次のコマンドを実行します。

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

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

  • CLUSTER_NAME: 既存のクラスタの名前。
  • COMPUTE_REGION: クラスタの Compute Engine のリージョン。ゾーンクラスタの場合は、--zone=COMPUTE_ZONE を使用します。
  • PROJECT_ID: Google Cloud プロジェクト ID。

Console

既存のクラスタで Workload Identity を有効にする手順は、次のとおりです。

  1. Cloud コンソールで Google Kubernetes Engine のページに移動します。

    Google Kubernetes Engine に移動

  2. クラスタのリストで、変更するクラスタの名前をクリックします。

  3. クラスタの詳細ページの [セキュリティ] セクションで、 [Workload Identity の編集] をクリックします。

  4. [Workload Identity の編集] ダイアログで、[Workload Identity を有効にする] チェックボックスをオンにします。

  5. [保存] をクリックします。

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

既存のクラスタで Workload Identity を有効にした後、稼働中のワークロードを Workload Identity を使用するように移行する場合があります。ご使用の環境に適した移行方法を選択します。Workload Identity が有効になっている新しいノードプールを作成するか、Workload Identity を有効にするように既存のノードプールを更新できます。

Workload Identity との互換性を保つためにアプリケーションを変更する必要もある場合は、新しいノードプールを作成することをおすすめします。

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

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

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

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

--workload-metadata=GKE_METADATA フラグにより、GKE メタデータ サーバーを使用するようにノードプールが構成されます。Workload Identity がクラスタで有効になっていない場合は、ノードプールの作成が失敗するようにこのフラグを含めることをおすすめします。

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

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

gcloud

Workload Identity が使用されるように既存のノードプールを変更するには、次のコマンドを実行します。

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

クラスタで Workload Identity が有効になっている場合、--workload-metadata=GCE_METADATA を明示的に指定することで特定のノードプールで選択的に無効にできます。詳しくは、クラスタ メタデータの保護をご覧ください。

Console

Workload Identity を使用するように既存のノードプールを変更する手順は、次のとおりです。

  1. Cloud コンソールで Google Kubernetes Engine のページに移動します。

    Google Kubernetes Engine に移動

  2. クラスタのリストで、変更するクラスタの名前をクリックします。

  3. [ノード] タブをクリックします。

  4. [ノードプール] セクションで、変更するノードプールの名前をクリックします。

  5. [ノードプールの詳細] ページで、[ 編集] をクリックします。

  6. [ノードプールの編集] ページの [セキュリティ] セクションで、[GKE メタデータ サーバーを有効にする] チェックボックスをオンにします。

  7. [保存] をクリックします。

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

Workload Identity を有効にしたら、アプリケーションを新しいノードプールに移行する前に、Workload Identity を使用して Google Cloud への認証を行うようにアプリケーションを構成する必要があります。

Kubernetes サービス アカウントをアプリケーションに割り当て、その Kubernetes サービス アカウントが IAM サービス アカウントとして機能するように構成する必要があります。

次の手順は、クラスタで Workload Identity が有効になっている場合に、Workload Identity を使用するようにアプリケーションを構成する方法を示したものです。

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

    gcloud container clusters get-credentials CLUSTER_NAME
    

    CLUSTER_NAME は、Workload Identity が有効になっているクラスタの名前に置き換えます。

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

    kubectl create namespace NAMESPACE
    
  3. アプリケーションで使用する Kubernetes サービス アカウントを作成します。また、デフォルトの Namespace または既存の Namespace で、デフォルトの Kubernetes サービス アカウントを使用することもできます。

    kubectl create serviceaccount KSA_NAME \
        --namespace NAMESPACE
    

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

    • KSA_NAME: 新しい Kubernetes サービス アカウントの名前。
    • NAMESPACE: サービス アカウントの Kubernetes Namespace の名前。
  4. アプリケーションに IAM サービス アカウントを作成するか、既存の IAM サービス アカウントを使用します。組織内の任意のプロジェクトで、任意の IAM サービス アカウントを使用できます。Config Connector の場合は、選択したサービス アカウントに IAMServiceAccount オブジェクトを適用します。

    gcloud

    gcloud CLI を使用して新しい IAM サービス アカウントを作成するには、次のコマンドを実行します。

    gcloud iam service-accounts create GSA_NAME \
        --project=GSA_PROJECT
    

    以下を置き換えます。

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

    Config Connector

    Config Connector で新規または既存の IAM サービス アカウントを使用するには、次の構成ファイルを適用します。

    注: この手順には Config Connector が必要です。Config Connector をクラスタにインストールするには、インストール手順を実施してください。

    apiVersion: iam.cnrm.cloud.google.com/v1beta1
    kind: IAMServiceAccount
    metadata:
      name: [GSA_NAME]
    spec:
      displayName: [DISPLAY_NAME]
    このマニフェストをデプロイするには、service-account.yaml という名前でマシンにダウンロードします。

    kubectl を使用してマニフェストを適用します。

    kubectl apply -f service-account.yaml
    

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

  5. 必要なロールが IAM サービス アカウントにあることを確認します。次のコマンドを使用して、追加のロールを付与できます。

    gcloud projects add-iam-policy-binding PROJECT_ID \
        --member "serviceAccount:GSA_NAME@GSA_PROJECT.iam.gserviceaccount.com" \
        --role "ROLE_NAME"
    

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

    • PROJECT_ID: Google Cloud プロジェクト ID。
    • GSA_NAME: IAM サービス アカウントの名前。
    • GSA_PROJECT: IAM サービス アカウントの Google Cloud プロジェクトのプロジェクト ID。
    • ROLE_NAME: roles/spanner.viewer など、サービス アカウントに割り当てる IAM ロール。
  6. 2 つのサービス アカウントの間に IAM ポリシー バインディングを追加して、Kubernetes サービス アカウントが IAM サービス アカウントの権限の借用できるようにします。このバインドでは、Kubernetes サービス アカウントが IAM サービス アカウントとして機能します。

    gcloud

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

    Config Connector

    注: この手順には Config Connector が必要です。Config Connector をクラスタにインストールするには、インストール手順を実施してください。

    apiVersion: iam.cnrm.cloud.google.com/v1beta1
    kind: IAMPolicy
    metadata:
      name: iampolicy-workload-identity-sample
    spec:
      resourceRef:
        apiVersion: iam.cnrm.cloud.google.com/v1beta1
        kind: IAMServiceAccount
        name: [GSA_NAME]
      bindings:
        - role: roles/iam.workloadIdentityUser
          members:
            - serviceAccount:[PROJECT_ID].svc.id.goog[[K8S_NAMESPACE]/[KSA_NAME]]
    このマニフェストをデプロイするには、policy-binding.yaml という名前でマシンにダウンロードします。GSA_NAMEPROJECT_IDNAMESPACEKSA_NAME を、実際の環境での値に置き換えます。次のコマンドを実行します。

    kubectl apply -f policy-binding.yaml
    
  7. IAM サービス アカウントのメールアドレスで Kubernetes サービス アカウントにアノテーションを付けます。

    kubectl

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

    yaml

    apiVersion: v1
    kind: ServiceAccount
    metadata:
      annotations:
        iam.gke.io/gcp-service-account: GSA_NAME@PROJECT_ID.iam.gserviceaccount.com
      name: KSA_NAME
      namespace: NAMESPACE
    
  8. Workload Identity を使用するノード上のワークロードをスケジュール設定して、アノテーション付きの Kubernetes サービス アカウントを使用するように、Pod の仕様を更新します。

    spec:
      serviceAccountName: KSA_NAME
      nodeSelector:
        iam.gke.io/gke-metadata-server-enabled: "true"
    
  9. 更新された構成をクラスタに適用します。

    kubectl apply -f DEPLOYMENT_FILE
    

    DEPLOYMENT_FILE は、更新された Pod 仕様へのパスに置き換えます。

Workload Identity の設定を確認する

サービス アカウントが正しく構成されていることを確認します。Kubernetes サービス アカウントを使用して、OS 固有のコンテナ イメージを実行する Pod を作成し、インタラクティブなセッションで Pod に接続します。

Linux

アノテーション付きの Kubernetes サービス アカウントを使用し、service-accounts エンドポイントを curl する Pod を作成します。

  1. 次の構成を wi-test.yaml として保存します。

    apiVersion: v1
    kind: Pod
    metadata:
      name: workload-identity-test
      namespace: NAMESPACE
    spec:
      containers:
      - image: google/cloud-sdk:slim
        name: workload-identity-test
        command: ["sleep","infinity"]
      serviceAccountName: KSA_NAME
      nodeSelector:
        iam.gke.io/gke-metadata-server-enabled: "true"
    

    google/cloud-sdk イメージには Google Cloud CLI が含まれており、Google Cloud APIs を簡単に利用できます。イメージのダウンロードに時間がかかる場合があります。

  2. Pod を作成します。

    kubectl apply -f wi-test.yaml
    
  3. Pod でインタラクティブ セッションを開きます。

    kubectl exec -it workload-identity-test \
      --namespace NAMESPACE \
      -- /bin/bash
    
  4. Pod 内で次のコマンドを実行します。

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

    サービス アカウントが正しく構成されている場合、IAM サービス アカウントのメールアドレスがアクティブな唯一の ID になります。デフォルトでは、Google Cloud APIs を呼び出すときに Pod が IAM サービス アカウントの権限として動作します。

Windows

servercore コンテナ イメージを実行する Kubernetes サービス アカウントを使用して Pod を作成します。

  1. 次のマニフェストを保存します。

    apiVersion: v1
    kind: Pod
    metadata:
      name: workload-identity-test
      namespace: NAMESPACE
    spec:
      containers:
      - image: IMAGE_NAME
        name: workload-identity-test
        command: ["powershell.exe", "sleep", "3600"]
      serviceAccountName: KSA_NAME
      nodeSelector:
        kubernetes.io/os: windows
        cloud.google.com/gke-os-distribution: windows_ltsc
        iam.gke.io/gke-metadata-server-enabled: "true"
    

    IMAGE_NAME を、次のいずれかのコンテナ サーバーコア イメージの値に置き換えます。

    Windows Server ノードイメージ コンテナ servercore イメージ
    WINDOWS_LTSC
    WINDOWS_LTSC_CONTAINERD
    mcr.microsoft.com/windows/servercore:ltsc2019
    WINDOWS_SAC
    WINDOWS_SAC_CONTAINERD
    GKE ノード バージョンと Windows SAC バージョンの間のバージョン マッピングを確認します。Windows Server バージョン 1909 の場合は mcr.microsoft.com/windows/servercore:1909 を指定し、それ以外の場合は mcr.microsoft.com/windows/servercore:20H2 を指定します。
  2. Pod でインタラクティブ セッションを開きます。

    kubectl exec -it workload-identity-test \
      --namespace NAMESPACE -- powershell
    
  3. Pod 内で次の powershell コマンドを実行します。

    Invoke-WebRequest  -Headers @{"Metadata-Flavor"="Google"} -Uri  http://169.254.169.254/computeMetadata/v1/instance/service-accounts/default/email  -UseBasicParsing
    

    サービス アカウントが正しく構成されている場合、IAM サービス アカウントのメールアドレスがアクティブな唯一の ID になります。デフォルトでは、Google Cloud APIs を呼び出すときに Pod が IAM サービス アカウントの権限を使用します。

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

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

クリーンアップ

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

アクセスの取り消し

  1. IAM サービス アカウントへのアクセス権を取り消します。

    gcloud

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

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

    • PROJECT_ID: GKE クラスタのプロジェクト ID。
    • NAMESPACE: Kubernetes サービス アカウントが配置されている Kubernetes Namespace の名前。
    • KSA_NAME: アクセス権が取り消される Kubernetes サービス アカウントの名前。
    • GSA_NAME: IAM サービス アカウントの名前。
    • GSA_PROJECT: IAM サービス アカウントのプロジェクト ID。

    Config Connector

    Config Connector を使用してサービス アカウントを作成した場合は、kubectl を使用してサービス アカウントを削除します。

    kubectl delete -f service-account.yaml
    

    キャッシュ内のトークンの有効期限は 30 分です。キャッシュ内のトークンが期限切れになっているかどうかは、次のコマンドで確認できます。

    gcloud auth list
    

    このコマンドの出力に GSA_NAME@GSA_PROJECT.iam.gserviceaccount.com が含まれない場合は、キャッシュ内のトークンはすでに期限切れです。

  2. Kubernetes サービス アカウントからアノテーションを削除します。IAM によってアクセス権が取り消されたため、このステップは省略可能です。

    kubectl annotate serviceaccount KSA_NAME \
        --namespace NAMESPACE iam.gke.io/gcp-service-account-
    

Workload Identity を無効にする

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

gcloud

  1. 各ノードプールで Workload Identity を無効にします。

    gcloud container node-pools update NODEPOOL_NAME \
        --cluster=CLUSTER_NAME \
        --workload-metadata=GCE_METADATA
    

    クラスタ内の各ノードプールに対してこのコマンドを繰り返します。

  2. クラスタで Workload Identity を無効にします。

    gcloud container clusters update CLUSTER_NAME \
        --disable-workload-identity
    

Console

  1. Cloud Console で Google Kubernetes Engine のページに移動します。

    Google Kubernetes Engine に移動

  2. クラスタのリストで、変更するクラスタの名前をクリックします。

  3. [ノード] タブをクリックします。

  4. 各ノードプールの Workload Identity を無効にするには、[ノードプール] セクションで各ノードプールに対して次の操作を行います。

    1. 変更するノードプールの名前をクリックします。
    2. [ノードプールの詳細] ページで、[ 編集] をクリックします。
    3. [ノードプールの編集] ページの [セキュリティ] セクションで、[GKE メタデータ サーバーを有効にする] チェックボックスをオフにします。
    4. [保存] をクリックします。
  5. クラスタの Workload Identity を無効にする手順は、次のとおりです。

    1. [詳細] タブをクリックします。
    2. [セキュリティ] セクションで、[Workload Identity] の横にある [編集] をクリックします。
    3. [Workload Identity の編集] ダイアログで、[Workload Identity を有効にする] チェックボックスをオフにします。
    4. [保存] をクリックします。

組織内で Workload Identity を無効にする

セキュリティの観点から、Workload Identity では GKE が、Kubernetes サービス アカウント ID を Google Cloud リソースに対して認証、認可できるものとして表明できるようになっています。サービス アカウント作成の無効化サービス アカウント キーの作成の無効化など、ワークロードを Google Cloud リソースから分離するための措置を講じた管理者は、組織の Workload Identity を無効にする場合もあります。

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

トラブルシューティング

Pod が Google Cloud に対して認証できない

アプリケーションが Google Cloud に対する認証を行えない場合は、次の設定が正しく構成されていることを確認してください。

  1. GKE クラスタを含むプロジェクトで IAM Service Account Credentials API が有効になっているかを確認します。

    IAM Credentials API を有効にする

  2. Workload Identity がクラスタで有効になっていることを確かにするには、Workload Identity プールが設定されていることを確認します。

    gcloud container clusters describe CLUSTER_NAME \
        --format="value(workloadIdentityConfig.workloadPool)"
    

    gcloud のデフォルト ゾーンまたはデフォルト リージョンをまだ指定していない場合は、このコマンドの実行時に --region フラグまたは --zone フラグも指定する必要があります。

  3. GKE メタデータ サーバーが、アプリケーションが動作しているノードプールで構成されていることを確認します。

    gcloud container node-pools describe NODEPOOL_NAME \
        --cluster=CLUSTER_NAME \
        --format="value(config.workloadMetadataConfig.mode)"
    
  4. Kubernetes サービス アカウントに正しくアノテーションが付けられていることを確認します。

    kubectl describe serviceaccount \
        --namespace NAMESPACE KSA_NAME
    

    出力には、次のようなアノテーションが含まれます。

    iam.gke.io/gcp-service-account: GSA_NAME@PROJECT_ID.iam.gserviceaccount.com
    
  5. IAM サービス アカウントが正しく構成されていることを確認します。

    gcloud iam service-accounts get-iam-policy \
        GSA_NAME@GSA_PROJECT.iam.gserviceaccount.com
    

    出力には、次のようなバインディングが含まれます。

    - members:
      - serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE/KSA_NAME]
      role: roles/iam.workloadIdentityUser
    
  6. クラスタ ネットワーク ポリシーを導入している場合は、1.21.0-gke.1000 より前のバージョンの GKE を実行しているクラスタのポート 988 で、127.0.0.1/32 への下り(外向き)が許可されていることを確認します。また、GKE バージョン 1.21.0-gke.1000 以降を実行しているクラスタのポート 988 で、169.254.169.252/32 への下り(外向き)が許可されていることを確認します。

    kubectl describe networkpolicy NETWORK_POLICY_NAME
    

Pod の起動時にタイムアウト エラーが発生する

GKE メタデータ サーバーが新しい Pod でリクエストの受け入れを開始できるようになるまでに数秒かかります。したがって、Pod の有効期間の最初の数秒以内に Workload Identity を使用して認証を試みると、短いタイムアウトが構成されているアプリケーションと Google Cloud クライアント ライブラリで失敗する可能性があります。

タイムアウト エラーが発生した場合は、アプリケーション コードを変更して数秒待ってから再試行してください。また、Pod のメインコンテナを実行する前に、GKE メタデータ サーバーの準備が完了するまで待機する initContainer をデプロイすることもできます。

たとえば、次のマニフェストは initContainer を含む Pod 用です。

apiVersion: v1
kind: Pod
metadata:
  name: pod-with-initcontainer
spec:
  serviceAccountName: KSA_NAME
  initContainers:
  - image:  gcr.io/google.com/cloudsdktool/cloud-sdk:326.0.0-alpine
    name: workload-identity-initcontainer
    command:
    - '/bin/bash'
    - '-c'
    - |
      curl -s -H 'Metadata-Flavor: Google' 'http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token' --retry 30 --retry-connrefused --retry-max-time 30 > /dev/null || exit 1
  containers:
  - image: gcr.io/your-project/your-image
    name: your-main-application-container

コントロール プレーンが使用できないため Workload Identity が失敗する

クラスタ コントロール プレーンが使用できない場合、メタデータ サーバーは Workload Identity を返すことができません。メタデータ サーバーを呼び出すと、ステータス コード 500 が返されます。

ログ エクスプローラでは、ログエントリは次のようになります。

dial tcp 35.232.136.58:443: connect: connection refused

これにより、予想どおり、Workload Identity が利用できなくなることがあります。

IP のローテーション、コントロール プレーン VM のアップグレード、クラスタまたはノードプールのサイズ変更などのクラスタ メンテナンス時に、ゾーンクラスタでコントロール プレーンが使用できない場合があります。コントロール プレーンの可用性については、リージョンまたはゾーンのコントロール プレーンの選択をご覧ください。リージョン クラスタに切り替えることで、この問題がなくなります。

Workload Identity が失敗する

なんらかの理由で GKE メタデータ サーバーがブロックされていると、Workload Identity は失敗します。

Istio を使用している場合は、Workload Identity を使用するすべてのワークロードに次のアプリケーション レベルのアノテーションを追加する必要があります。

"traffic.sidecar.istio.io/excludeOutboundIPRanges=169.254.169.254/32"

global.proxy.excludeIPRanges Istio ConfigMap キーを変更して同じ処理を行うこともできます。

次のステップ