Workload Identity の使用

このページでは、Google API によって提供されるサービスを Google Kubernetes Engine（GKE）アプリケーションで使用する際に推奨される方法を説明します。

概要

Workload Identity を使用して GKE 内で実行しているアプリケーションから Google Cloud サービスにアクセスすることをおすすめするのは、セキュリティのプロパティと管理性が優れているからです。GKE から Google Cloud APIs にアクセスする別の方法については、下の別の方法セクションをご覧ください。

用語

このドキュメントでは、Kubernetes サービスアカウントと Google サービスアカウントを区別しています。Kubernetes サービスアカウントは Kubernetes のリソースですが、Google サービスアカウントは Google Cloud 固有のものです。Google Cloud の他のドキュメントでは、Google サービスアカウントを「サービスアカウント」と表記しています。

コンセプト

GKE で実行されるアプリケーションで、Compute API、Storage API、Database API、Machine Learning API などの Google Cloud APIs を使用するには認証が必要です。

Workload Identity では、Kubernetes サービスアカウントを構成して Google サービスアカウントとして使用します。Kubernetes サービスアカウントとして実行される Pod は、Google Cloud APIs にアクセスする際に、Google サービスアカウントとして自動的に認証されます。これにより、クラスタ内のアプリケーションごとに詳細に設定した個別の ID と認証を割り当てることができます。

Kubernetes サービスアカウントと Google サービスアカウント間の安全なマッピングを実現するために、Workload Identity は、クラスタのワークロード ID プールのコンセプトを導入します。これにより、Identity and Access Management（IAM）は Kubernetes サービスアカウントの認証情報を信頼して確認できます。

GKE クラスタで Workload Identity を有効にすると、クラスタの Workload Identity プールが PROJECT_ID.svc.id.goog に設定されます。これにより、IAM は次のメンバー名で Kubernetes サービスアカウントを認証できます。

serviceAccount:PROJECT_ID.svc.id.goog[K8S_NAMESPACE/KSA_NAME]

このメンバー名で:

PROJECT_ID.svc.id.goog は、クラスタで設定された Workload Identity プールです。
KSA_NAME は、リクエストを行っている Kubernetes サービスアカウントの名前です。
K8S_NAMESPACE は、Kubernetes サービスアカウントが定義されている Kubernetes 名前空間です。

GKE は、Google Cloud プロジェクトごとに固定の Workload Identity プール PROJECT_ID.svc.id.goog を自動的に作成します。この Workload Identity プールは、プロジェクト内のすべての GKE クラスタに使用されます。

クラスタ間での ID の同一性

名前、名前空間名、workload identity プールを共有するすべての Kubernetes サービスアカウントが同じメンバー名に解決されて、Google Cloud リソースへのアクセスが共有されます。この共通 ID によって、Workload Identity プール内のアプリケーションに、クラスタ単位ではなく外部リソースへのアクセス権をまとめて付与できます。

この点についてより具体的に理解するため、次の例を考えてみましょう。クラスタ A、B、C が同じ Workload Identity プールに登録されています。backend 名前空間のアプリケーションが Google Cloud リソースにアクセスすると、アプリケーションがホストされているクラスタに関係なく、ID が back という共通の Google サービスアカウントにマッピングされます。Google サービスアカウント back は、Cloud Storage から Cloud SQL まで、任意の数の Google Cloud APIs で認証できます。

ID の同一性により、Workload Identity プール内のすべてのクラスタが高い信頼性を付与され、適切に管理されていることが重要です。前の例をもう一度見てみましょう。クラスタ C が別の信頼できないチームによって所有されている場合、backend 名前空間を作成し、クラスタ A またはクラスタ B に存在する backend であるかのように Google Cloud APIs にアクセスできます。

Workload Identity プール内の ID の同一性を示す図 — Workload Identity を使用して Google Cloud APIs にアクセスする際の ID の同一性

クラスタが権限を共有しないようにするには、クラスタを個別のプロジェクトにするか、別の Kubernetes 名前空間名を使用する必要があります。具体的な例として、寛容な「dev」クラスタとロックダウンされた「prod」クラスタを使用するユーザーは、これらのクラスタを別々のプロジェクトに分離して別々の Workload Identity プールを使用させることを考慮すべきです。

制限事項

現在のところ、Google Cloud プロジェクトごとに自動的に Workload Identity プール PROJECT_ID.svc.id.goog が 1 つだけ作成され、固定されます。
現在、Workload Identity は、Anthos clusters on VMware でワークロードが実行されている場合はサポートされません。
Workload Identity は、メタデータ隠蔽機能に代わるもので、この 2 つに互換性はありません。メタデータ隠蔽機能で保護された機密メタデータは Workload Identity でも保護されます。
ノードプールで GKE メタデータサーバーが有効にされると、Pod は Compute Engine のメタデータサーバーにアクセスできなくなります。代わりに、これらの Pod からメタデータ API に送信されたリクエストは、GKE メタデータサーバーにルーティングされます。ただし、ホストネットワークで実行されている Pod は例外です（次をご覧ください）。
ホストネットワークで実行されている Pod で Workload Identity を使用することはできません。これらの Pod からメタデータ API に送信されたリクエストは、Compute Engine のメタデータサーバーにルーティングされます。
GKE メタデータサーバーが新しく作成された Pod でリクエストの受信を開始できるようになるまでに数秒かかります。したがって、Pod の有効期間の最初の数秒以内に Workload Identity を使用して認証を試みると、失敗する可能性があります。この問題は、呼び出しを再試行することで解決します。詳細については、トラブルシューティングのセクションをご覧ください。
GKE の組み込みの Logging エージェントと Monitoring エージェントは、引き続きノードのサービスアカウントを使用します。
Workload Identity では Cloud Run for Anthos on Google Cloud がリクエスト指標を引き続きリリースするための手動設定が必要です。
Workload Identity は、クラスタが --disable-default-snat フラグなしで作成された場合に ip-masq-agent をインストールします。

始める前に

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

Google Kubernetes Engine API が有効になっていることを確認します。

Google Kubernetes Engine API を有効にする

Cloud SDK がインストール済みであることを確認します。

次のいずれかの方法で gcloud のデフォルトの設定を指定します。

gcloud init。デフォルトの設定全般を確認する場合に使用します。
gcloud config。プロジェクト ID、ゾーン、リージョンを個別に設定する場合に使用します。

gcloud init の使用

エラー One of [--zone, --region] must be supplied: Please specify location を受信した場合は、このセクションの内容を実施します。

gcloud init を実行して、次の操作を行います。
```
gcloud init
```
リモートサーバーで SSH を使用している場合は、--console-only フラグを指定して、コマンドがブラウザを起動しないようにします。
```
gcloud init --console-only
```
手順に従って gcloud を承認し、Google Cloud アカウントを使用します。
新しい構成を作成するか、既存の構成を選択します。
Google Cloud プロジェクトを選択します。
ゾーンクラスタの場合はデフォルトの Compute Engine ゾーン、リージョンクラスタまたは Autopilot クラスタの場合はデフォルトの Compute Engine リージョンを選択します。

注: これらのデフォルト設定は、gcloud コマンドで --project、--zone、--region フラグを使用することでオーバーライドできます。

gcloud config の使用

デフォルトのプロジェクト ID を設定します。
```
gcloud config set project PROJECT_ID
```
ゾーンクラスタを使用する場合は、デフォルトのコンピューティングゾーンを設定します。
```
gcloud config set compute/zone COMPUTE_ZONE
```
Autopilot クラスタまたはリージョンクラスタを使用する場合は、デフォルトのコンピューティングリージョンを設定します。
```
gcloud config set compute/region COMPUTE_REGION
```
gcloud を最新バージョンに更新します。
```
gcloud components update
```

注: これらのデフォルト設定は、gcloud コマンドで --project、--zone、--region フラグを使用するとオーバーライドできます。

クラスタで Workload Identity を有効にする

新規または既存の GKE Standard クラスタで Workload Identity を有効にするには、gcloud ツールを使用します。GKE Autopilot クラスタでは、Workload Identity がデフォルトで有効になっています。

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

IAM Credentials API を有効にする
Workload Identity を有効にして新しいクラスタを作成するには、次のコマンドを使用します。
```
gcloud container clusters create CLUSTER_NAME \
  --workload-pool=PROJECT_ID.svc.id.goog
```
次のように置き換えます。
- CLUSTER_NAME: クラスタの名前。
- PROJECT_ID: Google Cloud プロジェクトの ID。
この操作を行うには、プロジェクトに対する container.clusters.create 権限が必要です。
既存のクラスタで Workload Identity を有効にするには、次のコマンドを使用してクラスタを変更します。
```
gcloud container clusters update CLUSTER_NAME \
  --workload-pool=PROJECT_ID.svc.id.goog
```
既存のノードプールは影響を受けません。新しいノードプールはデフォルトで --workload-metadata=GKE_METADATA になります。

この操作を行うには、クラスタに対する container.clusters.update 権限が必要です。

アプリケーションを Workload Identity に移行する

ご使用の環境に適した移行方法を選択します。ノードプールを移行するか、新しいノードプールを作成して Workload Identity を有効にすることもできます。この機能に対応するようにアプリケーションを変更する必要がある場合は、新しいノードプールの作成をおすすめします。

オプション 1: Workload Identity を使用したノードプールの作成（推奨）

新しいノードプールをクラスタに追加して Workload Identity を有効にし、そのプールにワークロードを手動で移行します。この操作が成功するのは、Workload Identity がクラスタで有効になっている場合のみです。

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

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

オプション 2: ノードプールの変更

既存のノードプールを変更して、GKE_METADATA を有効にします。Workload Identity がクラスタで有効になっている場合のみ、この更新が成功します。更新が成功すると、ノードプールにデプロイされたワークロードの Workload Identity がすぐに有効になります。この変更により、ワークロードは Compute Engine サービスアカウントを使用できなくなるので、慎重にロールアウトする必要があります。

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

この操作を行うには、プロジェクトに対する container.nodes.update 権限が必要です。

Google Cloud の認証

このセクションでは、Workload Identity を使用してアプリケーションが Google Cloud で認証を行う方法について説明します。これを行うため、アプリケーションに Kubernetes サービスアカウントを割り当て、Google サービスアカウントとして機能するように構成します。

クラスタと通信を行うように kubectl を構成します。
```
gcloud container clusters get-credentials CLUSTER_NAME
```
CLUSTER_NAME は、前のステップで作成したクラスタの名前に置き換えます。

この操作を行うには、プロジェクトに対する container.clusters.get 権限が必要です。
他のほとんどのリソースと同様に、Kubernetes サービスアカウントは名前空間に存在します。Kubernetes サービスアカウントに使用する名前空間を作成します。
```
kubectl create namespace K8S_NAMESPACE
```
この操作を行うには、クラスタ内に名前空間の RBAC を作成する権限が必要です。
アプリケーションで使用する Kubernetes サービスアカウントを作成します。
```
kubectl create serviceaccount --namespace K8S_NAMESPACE KSA_NAME
```
次のように置き換えます。
- K8S_NAMESPACE: 前のステップで作成した Kubernetes の名前空間の名前。
- KSA_NAME: Kubernetes サービスアカウントに使用する名前。
この操作を行うには、名前空間内でサービスアカウントの RBAC を作成する権限が必要です。

また、デフォルトの名前空間または他の既存の名前空間でデフォルトの Kubernetes サービスアカウントを使用することもできます。
Kubernetes サービスアカウントを使用するようにアプリケーションを構成します。

注: デフォルトの Kubernetes サービスアカウントを使用している場合は、この手順を省略できます。
```
spec:
  serviceAccountName: KSA_NAME
```
アプリケーションに Google サービスアカウントを作成するか、既存の Google サービスアカウントを使用します。組織内の任意のプロジェクトで、任意の Google サービスアカウントを使用できます。Config Connector の場合は、選択したサービスアカウントに IAMServiceAccount オブジェクトを適用します。
gcloud
gcloud ツールを使用して新しい Google サービスアカウントを作成するには、次のコマンドを実行します。

注: gcloud ツールで既存の Google サービスアカウントを使用している場合は、この手順をスキップします。
```
gcloud iam service-accounts create GSA_NAME
```
GSA_NAME は、新しい Google Cloud サービスアカウントの名前に置き換えます。
Config Connector
Config Connector で新規または既存の Google サービスアカウントを使用するには、次の構成ファイルを適用します。

注: 既存の Google サービスアカウントを使用している場合でも、kubectl を使用してクラスタに IAMServiceAccount オブジェクトを適用する必要があります。構成ファイルの GSA_NAME は、使用するサービスアカウントの名前に置き換えます。
注: この手順には Config Connector が必要です。Config Connector をクラスタにインストールするには、インストール手順を実施してください。

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

kubectl を使用してマニフェストを適用します。
```
kubectl apply -f service-account.yaml
```
この操作を行うには、プロジェクトに対する iam.serviceAccounts.create 権限が必要です。

Google サービスアカウントから Google Cloud APIs へのアクセスを承認する方法については、サービスアカウントについてをご覧ください。
Kubernetes サービスアカウントが Google サービスアカウントの権限を借用できるように、この 2 つの間の IAM ポリシーバインディングを作成します。このバインドでは、Kubernetes サービスアカウントが Google サービスアカウントとして機能します。
gcloud
```
gcloud iam service-accounts add-iam-policy-binding \
  --role roles/iam.workloadIdentityUser \
  --member "serviceAccount:PROJECT_ID.svc.id.goog[K8S_NAMESPACE/KSA_NAME]" \
  GSA_NAME@PROJECT_ID.iam.gserviceaccount.com
```
Config Connector
注: この手順には Config Connector が必要です。Config Connector をクラスタにインストールするには、インストール手順を実施してください。

GitHub で表示
```
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_NAME、PROJECT_ID、K8S_NAMESPACE、KSA_NAME を、実際の環境での値に置き換えます。次のコマンドを実行します。
```
kubectl apply -f policy-binding.yaml
```
この操作を行うには、プロジェクトに対する iam.serviceAccounts.setIamPolicy 権限が必要です。
Google サービスアカウントのメールアドレスを使用して、iam.gke.io/gcp-service-account=GSA_NAME@PROJECT_ID アノテーションを Kubernetes サービスアカウントに追加します。
kubectl
```
kubectl annotate serviceaccount \
  --namespace K8S_NAMESPACE \
  KSA_NAME \
  iam.gke.io/gcp-service-account=GSA_NAME@PROJECT_ID.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: K8S_NAMESPACE
```
この操作を行うには、Kubernetes サービスアカウントに RBAC を編集する権限が必要です。

注: このアノテーションだけでは、Google サービスアカウントになり代わるためのアクセス権は付与されません。IAM バインディングが存在しない場合、Pod は Google サービスアカウントを使用できません。

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

Linux ノードの場合

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

次の構成を wi-test.yaml として保存します。
```
  apiVersion: v1
  kind: Pod
  metadata:
    name: workload-identity-test
    namespace: K8S_NAMESPACE
  spec:
    containers:
    - image: google/cloud-sdk:slim
      name: workload-identity-test
      command: ["sleep","infinity"]
    serviceAccountName: KSA_NAME
```
Pod を作成します。
```
  kubectl apply -f wi-test.yaml
```
Pod でインタラクティブセッションを開きます。
```
  kubectl exec -it workload-identity-test \
    --namespace K8S_NAMESPACE \
    -- /bin/bash
```
google/cloud-sdk イメージには gcloud コマンドラインツールが含まれています。このツールを使用すると、Google Cloud APIs を簡単に利用できます。イメージのダウンロードに時間がかかる場合があります。

この操作を行うには、名前空間内で Pod 作成の RBAC 権限が必要です。
これで、作成した Pod 内でインタラクティブシェルに接続できました。Pod 内で次のコマンドを実行します。
```
  gcloud auth list
```
サービスアカウントが正しく構成されている場合、Google サービスアカウントのメールアドレスがアクティブな唯一の ID になります。デフォルトでは、Google Cloud APIs を呼び出すときに Google サービスアカウントの権限が使用されます。

Windows Server ノードの場合

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

  apiVersion: v1
  kind: Pod
  metadata:
    name: workload-identity-test
    namespace: K8S_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

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` を指定します。

この操作を行うには、名前空間内で Pod 作成の RBAC 権限が必要です。

Pod でインタラクティブセッションを開きます。

  kubectl exec -it workload-identity-test \
    --namespace K8S_NAMESPACE \
    -- powershell

これで、作成した Pod 内でインタラクティブシェルに接続できました。Pod 内で次の powershell コマンドを実行します。
```
Invoke-WebRequest  -Headers @{"Metadata-Flavor"="Google"} -Uri  http://169.254.169.254/computeMetadata/v1/instance/service-accounts/default/email  -UseBasicParsing
```
サービスアカウントが正しく構成されている場合、Google サービスアカウントのメールアドレスがアクティブな唯一の ID になります。デフォルトでは、Google Cloud APIs を呼び出すときに Google サービスアカウントの権限が使用されます。

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

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

GKE メタデータサーバーについて

GKE メタデータサーバーは、Kubernetes で使用するために設計された新しいメタデータサーバーです。クラスタノードごとに 1 つの Pod を使用して、daemonset として実行されます。メタデータサーバーは、Pod がその役割を果たすように構成された Google サービスアカウントのトークンを取得するための GET /computeMetadata/v1/instance/service-accounts/default/token などのリクエストも含め、http://metadata.google.internal（169.254.169.254:80）への HTTP リクエストをインターセプトします。メタデータサーバーへのトラフィックは必ず、Pod をホストする VM インスタンスに向かいます。

GKE メタデータサーバーは、Kubernetes ワークロードとの関連性があり、安全な Compute Engine メタデータサーバーエンドポイントのサブセットのみを実装します。

/computeMetadata/v1/instance/attributes/cluster-location
/computeMetadata/v1/instance/attributes/cluster-name
/computeMetadata/v1/instance/attributes/cluster-uid
/computeMetadata/v1/instance/hostname
/computeMetadata/v1/instance/id
/computeMetadata/v1/project/numeric-project-id
/computeMetadata/v1/project/project-id
/computeMetadata/v1/instance/service-accounts
/computeMetadata/v1/instance/service-accounts/default
/computeMetadata/v1/instance/service-accounts/default/aliases
/computeMetadata/v1/instance/service-accounts/default/email
/computeMetadata/v1/instance/service-accounts/default/identity
/computeMetadata/v1/instance/service-accounts/default/identity?audience=audience
/computeMetadata/v1/instance/service-accounts/default/scopes
/computeMetadata/v1/instance/service-accounts/default/token
/computeMetadata/v1/instance/service-accounts/default/token?scopes=comma-separated-list-of-scopes

アクセス権の取り消し

IAM を使用して Google サービスアカウントへのアクセス権を取り消します。
gcloud
```
gcloud iam service-accounts remove-iam-policy-binding \
  --role roles/iam.workloadIdentityUser \
  --member "serviceAccount:PROJECT_ID.svc.id.goog[K8S_NAMESPACE/KSA_NAME]" \
  GSA_NAME@GSA_PROJECT_ID.iam.gserviceaccount.com
```
次のように置き換えます。
- PROJECT_ID: GKE クラスタのプロジェクト ID コンテナ。
- K8S_NAMESPACE: Kubernetes サービスアカウントが配置されている Kubernetes 名前空間の名前。
- KSA_NAME: アクセス権が取り消される Kubernetes サービスアカウントの名前。
- GSA_NAME: Google サービスアカウントの名前。
- GSA_PROJECT_ID: Google サービスアカウントを含むプロジェクト ID。
Config Connector
Config Connector を使用してサービスアカウントを作成した場合は、kubectl を使用してサービスアカウントを削除します。
```
kubectl delete -f service-account.yaml
```
この操作を実行するには、サービスアカウントに対する iam.serviceAccounts.setIamPolicy 権限が必要です。

キャッシュ内のトークンの有効期限は 30 分です。キャッシュ内のトークンが期限切れになっているかどうかは、次のコマンドで確認できます。
```
gcloud auth list
```
このコマンドの出力に GSA_NAME@PROJECT_ID.iam.gserviceaccount.com が含まれない場合は、キャッシュ内のトークンはすでに期限切れです。
Kubernetes サービスアカウントからアノテーションを削除します。IAM によってアクセス権が取り消されたため、このステップは省略可能です。
```
kubectl annotate serviceaccount KSA_NAME \
  --namespace K8S_NAMESPACE \
  iam.gke.io/gcp-service-account-
```

トラブルシューティング

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

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

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

IAM Credentials API を有効にする
Workload Identity がクラスタで有効になっていることを確かにするには、ワークロード ID プールが設定されていることを確認します。
```
gcloud container clusters describe CLUSTER_NAME \
  --format="value(workloadIdentityConfig.workloadPool)"
```
GKE メタデータサーバー（GKE_METADATA）が、アプリケーションが実行されているノードプールで構成されていることを確認します。
```
gcloud container node-pools describe NODEPOOL_NAME \
  --cluster=CLUSTER_NAME \
  --format="value(config.workloadMetadataConfig.mode)"
```
Kubernetes サービスアカウントに正しくアノテーションが付けられていることを確認します。
```
kubectl describe serviceaccount \
  --namespace K8S_NAMESPACE \
  KSA_NAME
```
アノテーションの形式は次のとおりです。
```
iam.gke.io/gcp-service-account: GSA_NAME@PROJECT_ID.iam.gserviceaccount.com
```

Google サービスアカウントが正しく構成されていることを確認します。

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

次の形式のバインディングがあることを確認します。

- members:
  - serviceAccount:PROJECT_ID.svc.id.goog[K8S_NAMESPACE/KSA_NAME]
  role: roles/iam.workloadIdentityUser

クラスタネットワークポリシーを導入している場合は、ポート 988 で 127.0.0.1/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://169.254.169.254/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 が失敗する

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

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

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

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

クラスタでの Workload Identity の無効化

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

各ノードプールで Workload Identity を無効にします。
```
gcloud container node-pools update NODEPOOL_NAME \
  --cluster=CLUSTER_NAME \
  --workload-metadata=GCE_METADATA
```
クラスタ内の各ノードプールに対してこのコマンドを繰り返します。
クラスタで Workload Identity を無効にします。
```
gcloud container clusters update CLUSTER_NAME \
  --disable-workload-identity
```
この操作を行うには、クラスタに対する container.clusters.update 権限が必要です。

組織内での Workload Identity の無効化

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

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

Workload Identity に代わる方法

GKE から Cloud APIs にアクセスするには、2 つの方法があります。Workload Identity のリリースに伴い、調整が必要になるため、これらのアプローチはおすすめしません。

サービスアカウントキーをエクスポートして Kubernetes Secret として保存します。Google サービスアカウントキーには有効期限がないため、手動でローテーションする必要があります。サービスアカウントキーをエクスポートすると、セキュリティ侵害を受けた場合、それが検出されなければ侵害の範囲が拡大する可能性があります。
ノードの Compute Engine サービスアカウントを使用します。プロジェクト内の任意の IAM サービスアカウントとしてノードプールを実行できます。ノードプールの作成時にサービスアカウントを指定しなければ、GKE はプロジェクトのデフォルトの Compute Engine サービスアカウントを使用します。デフォルトの Compute Engine サービスアカウントは、そのノードにデプロイされているすべてのワークロードで共有されます。そのため、権限が過剰にプロビジョニングされることがあります。

次のステップ

GKE セキュリティの概要を確認する。
Pod について学習する。
クラスタメタデータの保護について確認する。
Google サービスアカウントについて学習する。

Workload Identity の使用

概要

用語

コンセプト

クラスタ間での ID の同一性

制限事項

始める前に

gcloud init の使用

gcloud config の使用

クラスタで Workload Identity を有効にする

アプリケーションを Workload Identity に移行する

オプション 1: Workload Identity を使用したノードプールの作成（推奨）

オプション 2: ノードプールの変更

Google Cloud の認証

gcloud

Config Connector

gcloud

Config Connector

kubectl

yaml

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

GKE メタデータ サーバーについて

アクセス権の取り消し

gcloud

Config Connector

トラブルシューティング

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

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

Workload Identity が失敗する

クラスタでの Workload Identity の無効化

組織内での Workload Identity の無効化

Workload Identity に代わる方法

次のステップ

GKE メタデータサーバーについて

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