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

Autopilot Standard

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

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

始める前に

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

Google Kubernetes Engine API を有効にする。

Google Kubernetes Engine API の有効化

このタスクに Google Cloud CLI を使用する場合は、gcloud CLI をインストールして初期化する。すでに gcloud CLI をインストールしている場合は、gcloud components update を実行して最新のバージョンを取得する。
注: gcloud CLI がすでにインストールされている場合には、必ず compute/region と compute/zone のプロパティを設定してください。デフォルトのロケーションを設定することで、gcloud CLI のエラー（One of [--zone, --region] must be supplied: Please specify location など）を防止できます。

アクセスする 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 コンソールを使用します。

gcloud

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
新しいクラスタで GKE 用 Workload Identity 連携を有効にするには、次のコマンドを実行します。
```
gcloud container clusters create CLUSTER_NAME \
    --location=LOCATION \
    --workload-pool=PROJECT_ID.svc.id.goog
```
次のように置き換えます。
- CLUSTER_NAME: 新しいクラスタの名前。
- LOCATION: クラスタの Compute Engine のロケーション。
- PROJECT_ID: Google Cloud プロジェクト ID。

コンソール

新しいクラスタで GKE 用 Workload Identity 連携を有効にするには、次の操作を行います。

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

Google Kubernetes Engine に移動
[ 作成] をクリックします。
[クラスタを作成] ダイアログで、GKE Standard の [構成] をクリックします。
ナビゲーションメニューの [クラスタ] セクションで、[セキュリティ] をクリックします。
[Workload Identity を有効にする] チェックボックスをオンにします。
クラスタの構成を続行し、[作成] をクリックします。

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

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

gcloud

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
既存のクラスタで GKE 用 Workload Identity 連携を有効にするには、次のコマンドを実行します。
```
gcloud container clusters update CLUSTER_NAME \
    --location=LOCATION \
    --workload-pool=PROJECT_ID.svc.id.goog
```
次のように置き換えます。
- CLUSTER_NAME: 既存のクラスタの名前。
- LOCATION: クラスタの Compute Engine のロケーション。
- PROJECT_ID: Google Cloud プロジェクト ID。

コンソール

既存のクラスタで GKE 用 Workload Identity 連携を有効にするには、次の操作を行います。

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

Google Kubernetes Engine に移動
クラスタのリストで、変更するクラスタの名前をクリックします。
クラスタの詳細ページの [セキュリティ] セクションで、 [Workload Identity の編集] をクリックします。
[Workload Identity の編集] ダイアログで、[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 連携を手動で有効にできます。

gcloud

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
Workload Identity Federation for GKE を使用するように既存のノードプールを変更するには、次のコマンドを実行します。
```
gcloud container node-pools update NODEPOOL_NAME \
    --cluster=CLUSTER_NAME \
    --region=COMPUTE_REGION \
    --workload-metadata=GKE_METADATA
```
クラスタで GKE 用 Workload Identity 連携が有効になっている場合、--workload-metadata=GCE_METADATA を明示的に指定することで、この機能を特定のノードプールで選択的に無効にできます。詳しくは、クラスタメタデータの保護をご覧ください。

コンソール

Workload Identity Federation for GKE を使用するように既存のノードプールを変更するには、次の操作を行います。

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

Google Kubernetes Engine に移動
クラスタのリストで、変更するクラスタの名前をクリックします。
[ノード] タブをクリックします。
[ノードプール] セクションで、変更するノードプールの名前をクリックします。
[ノードプールの詳細] ページで、[ 編集] をクリックします。
[ノードプールの編集] ページの [セキュリティ] セクションで、[GKE メタデータサーバーを有効にする] チェックボックスをオンにします。
[保存] をクリックします。

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

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

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

クラスタの認証情報を取得します。
```
gcloud container clusters get-credentials CLUSTER_NAME \
    --location=LOCATION
```
次のように置き換えます。
- CLUSTER_NAME: GKE 用 Workload Identity 連携が有効になっているクラスタの名前。
- LOCATION: クラスタのロケーション。
Kubernetes サービスアカウントに使用する Namespace を作成します。default Namespace を使用することも、既存の Namespace を使用することもできます。
```
kubectl create namespace NAMESPACE
```
アプリケーションで使用する 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 の名前。
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 のリストについては、GKE 用 Workload Identity 連携のプリンシパル ID をご覧ください。

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

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

空の Cloud Storage バケットを作成します。
```
gcloud storage buckets create gs://BUCKET
```
BUCKET は、新しいバケットの名前に置き換えます。
作成した 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 の名前。

次のマニフェストを 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

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

すべてのノードが GKE 用 Workload Identity 連携を使用するので、Autopilot クラスタではこの手順をスキップします。Autopilot クラスタではこの nodeSelector が拒否されます。
```
spec:
  nodeSelector:
    iam.gke.io/gke-metadata-server-enabled: "true"
```
クラスタに構成ファイルを適用します。
```
kubectl apply -f test-app.yaml
```
Pod の準備ができるまで待ちます。Pod のステータスを確認するには、次のコマンドを実行します。
```
kubectl get pods --namespace=NAMESPACE
```
Pod の準備が整うと、出力は次のようになります。
```
NAME       READY   STATUS    RESTARTS   AGE
test-pod   1/1     Running   0          5m27s
```

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

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

バケット内のオブジェクトのリストを取得します。
```
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 にリンクする

IAM プリンシパル ID を使用して、GKE 用 Workload Identity 連携を構成することをおすすめします。ただし、この連携 ID には、サポートされている Google Cloud API ごとに固有の制限があります。制限の一覧については、サポートされているプロダクトと制限事項をご覧ください。

これらの制限が適用される場合は、次の手順で GKE ワークロードからこれらの API へのアクセスを構成します。

Kubernetes Namespace を作成します。
```
kubectl create namespace NAMESPACE
```

Kubernetes ServiceAccount を作成します。

kubectl create serviceaccount KSA_NAME \
    --namespace=NAMESPACE

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 へのアクセスを承認する方法については、サービスアカウントについてをご覧ください。
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 など）に置き換えます。
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]
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 連携を使用して割り当てプロジェクトを構成するには、次の操作を行います。

割り当てプロジェクトの 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 に置き換えます。

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

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

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

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

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

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

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

[API] に移動
トラフィックの変化を確認します。

クリーンアップ

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 クラスタでのみ無効にできます。

gcloud

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
各ノードプールで GKE 用 Workload Identity 連携を無効にします。
```
gcloud container node-pools update NODEPOOL_NAME \
    --cluster=CLUSTER_NAME \
    --workload-metadata=GCE_METADATA
```
クラスタ内の各ノードプールに対してこのコマンドを繰り返します。

クラスタで Workload Identity Federation for GKE を無効にします。

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

コンソール

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

Google Kubernetes Engine に移動
クラスタのリストで、変更するクラスタの名前をクリックします。
[ノード] タブをクリックします。
各ノードプールで GKE 用 Workload Identity 連携を無効にするには、[ノードプール] セクションで、ノードプールごとに次の操作を行います。
1. 変更するノードプールの名前をクリックします。
2. [ノードプールの詳細] ページで、[ 編集] をクリックします。
3. [ノードプールの編集] ページの [セキュリティ] セクションで、[GKE メタデータサーバーを有効にする] チェックボックスをオフにします。
4. [保存] をクリックします。
クラスタで GKE 用 Workload Identity 連携を無効にするには、次の操作を行います。
1. [詳細] タブをクリックします。
2. [セキュリティ] セクションで、[Workload Identity] の横にある [ 編集] をクリックします。
3. [Workload Identity の編集] ダイアログで、[Workload Identity を有効にする] チェックボックスをオフにします。
4. [保存] をクリックします。

組織で 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 サービスアカウントについて学習する。