このドキュメントでは、Google Kubernetes Engine(GKE)クラスタで Workload Identity を有効にして構成する方法を説明します。Workload Identity を使用すると、GKE クラスタ内のワークロードが Identity and Access Management(IAM)サービス アカウントに代わって Google Cloud サービスにアクセスできます。Workload Identity の仕組みと制限事項の詳細については、Workload Identity をご覧ください。
始める前に
作業を始める前に、次のことを確認してください。
- Google Kubernetes Engine API を有効にします。 Google Kubernetes Engine API の有効化
- このタスクに Google Cloud CLI を使用する場合は、gcloud CLI をインストールして初期化します。 すでに gcloud CLI をインストールしている場合は、
gcloud components update
を実行して最新バージョンを取得します。
IAM Service Account Credentials API が有効になっているかを確認します。
次の IAM ロールがあることを確認します。
roles/container.admin
roles/iam.serviceAccountAdmin
Workload Identity の制限事項を理解していることを確認します。
Workload Identity を有効にする
Workload Identity は、Google Cloud CLI または Google Cloud コンソールを使用して、クラスタとノードプールで有効にできます。Workload Identity をノードプールで有効にするには、クラスタレベルで Workload Identity を有効にする必要があります。
Autopilot クラスタは、デフォルトで Workload Identity を有効にします。Workload Identity を使用するように Autopilot Pod を構成するには、Workload Identity を使用するようにアプリケーションを構成するに進んでください。
新しいクラスタの作成
Workload Identity は、gcloud CLI または Google Cloud コンソールを使用して新しい標準クラスタで有効にできます。
gcloud
-
Google Cloud コンソールで、「Cloud Shell をアクティブにする」をクリックします。
Google Cloud コンソールの下部で Cloud Shell セッションが開始し、コマンドライン プロンプトが表示されます。Cloud Shell はシェル環境です。Google Cloud CLI がすでにインストールされており、現在のプロジェクトの値もすでに設定されています。セッションが初期化されるまで数秒かかることがあります。
新しいクラスタで 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 を有効にする手順は、次のとおりです。
Google Cloud コンソールで [Google Kubernetes Engine] ページに移動します。
[add_box 作成] をクリックします。
[クラスタを作成] ダイアログで、GKE Standard の [構成] をクリックします。
ナビゲーション メニューの [クラスタ] セクションで、[セキュリティ] をクリックします。
[Workload Identity を有効にする] チェックボックスをオンにします。
クラスタの構成を続行して、[作成] をクリックします。
既存のクラスタを更新する
既存の標準クラスタでは、gcloud CLI または Google Cloud コンソールを使用して Workload Identity を有効にできます。既存のノードプールは影響を受けませんが、クラスタ内の新しいノードプールすべてでは Workload Identity が使用されます。
gcloud
-
Google Cloud コンソールで、「Cloud Shell をアクティブにする」をクリックします。
Google Cloud コンソールの下部で Cloud Shell セッションが開始し、コマンドライン プロンプトが表示されます。Cloud Shell はシェル環境です。Google Cloud CLI がすでにインストールされており、現在のプロジェクトの値もすでに設定されています。セッションが初期化されるまで数秒かかることがあります。
既存のクラスタで 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 を有効にする手順は、次のとおりです。
Google Cloud コンソールで Google Kubernetes Engine のページに移動します。
クラスタのリストで、変更するクラスタの名前をクリックします。
クラスタの詳細ページの [セキュリティ] セクションで、
[Workload Identity の編集] をクリックします。[Workload Identity の編集] ダイアログで、[Workload Identity を有効にする] チェックボックスをオンにします。
[保存] をクリックします。
既存のワークロードを 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 \
--region=COMPUTE_REGION \
--workload-metadata=GKE_METADATA
次のように置き換えます。
NODEPOOL_NAME
: 新しいノードプールの名前。CLUSTER_NAME
: Workload Identity が有効になっている既存のクラスタの名前。
--workload-metadata=GKE_METADATA
フラグにより、GKE メタデータ サーバーを使用するようにノードプールが構成されます。Workload Identity がクラスタで有効になっていない場合は、ノードプールの作成が失敗するようにこのフラグを含めることをおすすめします。
既存のノードプールを更新する
Workload Identity は、クラスタで Workload Identity を有効にした後、既存のノードプールで手動で有効にできます。
gcloud
-
Google Cloud コンソールで、「Cloud Shell をアクティブにする」をクリックします。
Google Cloud コンソールの下部で Cloud Shell セッションが開始し、コマンドライン プロンプトが表示されます。Cloud Shell はシェル環境です。Google Cloud CLI がすでにインストールされており、現在のプロジェクトの値もすでに設定されています。セッションが初期化されるまで数秒かかることがあります。
Workload Identity が使用されるように既存のノードプールを変更するには、次のコマンドを実行します。
gcloud container node-pools update NODEPOOL_NAME \ --cluster=CLUSTER_NAME \ --region=COMPUTE_REGION \ --workload-metadata=GKE_METADATA
クラスタで Workload Identity が有効になっている場合、
--workload-metadata=GCE_METADATA
を明示的に指定することで特定のノードプールで選択的に無効にできます。詳しくは、クラスタ メタデータの保護をご覧ください。
Console
Workload Identity を使用するように既存のノードプールを変更する手順は、次のとおりです。
Google Cloud コンソールで Google Kubernetes Engine のページに移動します。
クラスタのリストで、変更するクラスタの名前をクリックします。
[ノード] タブをクリックします。
[ノードプール] セクションで、変更するノードプールの名前をクリックします。
[ノードプールの詳細] ページで、[
編集] をクリックします。[ノードプールの編集] ページの [セキュリティ] セクションで、[GKE メタデータ サーバーを有効にする] チェックボックスをオンにします。
[保存] をクリックします。
Workload Identity を使用するようにアプリケーションを構成する
Workload Identity を有効にしたら、アプリケーションを新しいノードプールに移行する前に、Workload Identity を使用して Google Cloud への認証を行うようにアプリケーションを構成する必要があります。
Kubernetes サービス アカウントをアプリケーションに割り当て、その Kubernetes サービス アカウントが IAM サービス アカウントとして機能するように構成する必要があります。
次の手順は、クラスタで Workload Identity が有効になっている場合に、Workload Identity を使用するようにアプリケーションを構成する方法を示したものです。
クラスタの認証情報を取得します。
gcloud container clusters get-credentials CLUSTER_NAME \ --region=COMPUTE_REGION
以下を置き換えます。
CLUSTER_NAME
: Workload Identity が有効になっているクラスタの名前。COMPUTE_REGION
: クラスタの Compute Engine のリージョン。
Kubernetes サービス アカウントに使用する Namespace を作成します。デフォルトの Namespace を使用することも、既存の Namespace を使用することもできます。
kubectl create namespace NAMESPACE
アプリケーションで使用する Kubernetes サービス アカウントを作成します。また、
default
サービス アカウントを含むすべての Namespace の既存の Kubernetes サービス アカウントを使用することもできます。kubectl create serviceaccount KSA_NAME \ --namespace NAMESPACE
以下を置き換えます。
KSA_NAME
: 新しい Kubernetes サービス アカウントの名前。NAMESPACE
: サービス アカウントの Kubernetes Namespace の名前。
アプリケーションに IAM サービス アカウントを作成するか、既存の IAM サービス アカウントを使用します。組織内の任意のプロジェクトで、任意の IAM サービス アカウントを使用できます。Config Connector の場合は、選択したサービス アカウントに
IAMServiceAccount
オブジェクトを適用します。gcloud
-
Google Cloud コンソールで、「Cloud Shell をアクティブにする」をクリックします。
Google Cloud コンソールの下部で Cloud Shell セッションが開始し、コマンドライン プロンプトが表示されます。Cloud Shell はシェル環境です。Google Cloud CLI がすでにインストールされており、現在のプロジェクトの値もすでに設定されています。セッションが初期化されるまで数秒かかることがあります。
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 をクラスタにインストールするには、インストール手順を実施してください。
このマニフェストをデプロイするには、service-account.yaml
という名前でマシンにダウンロードします。kubectl
を使用してマニフェストを適用します。kubectl apply -f service-account.yaml
IAM サービス アカウントから Google Cloud APIs へのアクセスを承認する方法については、サービス アカウントについてをご覧ください。
-
必要なロールが IAM サービス アカウントにあることを確認します。次のコマンドを使用して、追加のロールを付与できます。
gcloud projects add-iam-policy-binding GSA_PROJECT \ --member "serviceAccount:GSA_NAME@GSA_PROJECT.iam.gserviceaccount.com" \ --role "ROLE_NAME"
以下を置き換えます。
GSA_PROJECT
: IAM サービス アカウントの Google Cloud プロジェクトのプロジェクト ID。GSA_NAME
: IAM サービス アカウントの名前。ROLE_NAME
:roles/spanner.viewer
など、サービス アカウントに割り当てる IAM ロール。
2 つのサービス アカウントの間に IAM ポリシー バインディングを追加して、Kubernetes サービス アカウントが IAM サービス アカウントの権限の借用できるようにします。このバインドでは、Kubernetes サービス アカウントが IAM サービス アカウントとして機能します。
gcloud
-
Google Cloud コンソールで、「Cloud Shell をアクティブにする」をクリックします。
Google Cloud コンソールの下部で Cloud Shell セッションが開始し、コマンドライン プロンプトが表示されます。Cloud Shell はシェル環境です。Google Cloud CLI がすでにインストールされており、現在のプロジェクトの値もすでに設定されています。セッションが初期化されるまで数秒かかることがあります。
開発環境で、次のコマンドを実行します。
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 をクラスタにインストールするには、インストール手順を実施してください。
このマニフェストをデプロイするには、policy-binding.yaml
という名前でマシンにダウンロードします。GSA_NAME
、PROJECT_ID
、NAMESPACE
、KSA_NAME
を、実際の環境での値に置き換えます。次のコマンドを実行します。kubectl apply -f policy-binding.yaml
-
IAM サービス アカウントのメールアドレスで Kubernetes サービス アカウントにアノテーションを付けます。
kubectl
-
Google Cloud コンソールで、「Cloud Shell をアクティブにする」をクリックします。
Google Cloud コンソールの下部で Cloud Shell セッションが開始し、コマンドライン プロンプトが表示されます。Cloud Shell はシェル環境です。Google Cloud CLI がすでにインストールされており、現在のプロジェクトの値もすでに設定されています。セッションが初期化されるまで数秒かかることがあります。
開発環境で、次のコマンドを実行します。
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
-
Workload Identity を使用するノード上のワークロードをスケジュール設定して、アノテーション付きの Kubernetes サービス アカウントを使用するように、Pod の仕様を更新します。
spec: serviceAccountName: KSA_NAME nodeSelector: iam.gke.io/gke-metadata-server-enabled: "true"
更新された構成をクラスタに適用します。
kubectl apply -f DEPLOYMENT_FILE
DEPLOYMENT_FILE
は、更新された Pod 仕様へのパスに置き換えます。
Workload Identity の設定を確認する
サービス アカウントが正しく構成されていることを確認します。Kubernetes サービス アカウントを使用して、OS 固有のコンテナ イメージを実行する Pod を作成し、インタラクティブなセッションで Pod に接続します。
Linux
アノテーション付きの Kubernetes サービス アカウントを使用し、service-accounts
エンドポイントを curl
する Pod を作成します。
次の構成を
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 を簡単に利用できます。イメージのダウンロードに時間がかかる場合があります。Pod を作成します。
kubectl apply -f wi-test.yaml
Pod でインタラクティブ セッションを開きます。
kubectl exec -it workload-identity-test \ --namespace NAMESPACE \ -- /bin/bash
Pod 内で次のコマンドを実行します。
curl -H "Metadata-Flavor: Google" http://169.254.169.254/computeMetadata/v1/instance/service-accounts/default/email
サービス アカウントが正しく構成されている場合、IAM サービス アカウントのメールアドレスがアクティブな唯一の ID になります。デフォルトでは、Google Cloud APIs を呼び出すときに Pod が IAM サービス アカウントの権限として動作します。
Windows
servercore
コンテナ イメージを実行する Kubernetes サービス アカウントを使用して Pod を作成します。
次のマニフェストを保存します。
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
を指定します。Pod でインタラクティブ セッションを開きます。
kubectl exec -it workload-identity-test \ --namespace NAMESPACE -- powershell
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 で別のプロジェクトから割り当てを使用する
GKE バージョン 1.24 以降を実行しているクラスタでは、IAM Service Account Credentials API の GenerateAccessToken
メソッドと GenerateIdToken
メソッドの呼び出し時に、別の Google Cloud プロジェクトの割り当てを使用するように、Kubernetes サービス アカウントを必要に応じて構成できます。これにより、メイン プロジェクトで割り当てのすべてを使用することを避け、クラスタ内のこれらのサービスに他のプロジェクトの割り当てを使用できます。
Workload Identity を使用して割り当てプロジェクトを構成するには、次の手順に従います。
割り当てプロジェクトの
serviceusage.services.use
権限を Kubernetes サービス アカウントに付与します。gcloud projects add-iam-policy-binding \ --role=roles/serviceusage.serviceUsageConsumer \ --member=serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE/KSA_NAME] \ QUOTA_PROJECT_ID
QUOTA_PROJECT_ID
は、割り当てプロジェクトのプロジェクト ID に置き換えます。割り当てプロジェクトで Kubernetes サービス アカウントにアノテーションを付けます。
kubectl annotate serviceaccount KSA_NAME \ --namespace NAMESPACE \ iam.gke.io/credential-quota-project=QUOTA_PROJECT_ID
構成が正しく機能することを確認するには、次の手順に従います。
Workload Identity の設定を確認するの手順に沿って、Pod を作成してシェル セッションを開始します。
サービス アカウント トークン リクエストを作成します。
curl -H "Metadata-Flavor: Google" http://169.254.169.254/computeMetadata/v1/instance/service-accounts/default/token
Google Cloud Console で、割り当てプロジェクトの IAM Service Accounts Credentials API ページに移動します。
トラフィックの変化を確認します。
クリーンアップ
Workload Identity の使用を停止するには、IAM サービス アカウントへのアクセス権を取り消して、クラスタの Workload Identity を無効にします。
アクセスの取り消し
IAM サービス アカウントへのアクセス権を取り消します。
gcloud
-
Google Cloud コンソールで、「Cloud Shell をアクティブにする」をクリックします。
Google Cloud コンソールの下部で Cloud Shell セッションが開始し、コマンドライン プロンプトが表示されます。Cloud Shell はシェル環境です。Google Cloud CLI がすでにインストールされており、現在のプロジェクトの値もすでに設定されています。セッションが初期化されるまで数秒かかることがあります。
開発環境で、次のコマンドを実行します。
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
が含まれない場合は、キャッシュ内のトークンはすでに期限切れです。-
Kubernetes サービス アカウントからアノテーションを削除します。IAM によってアクセス権が取り消されたため、このステップは省略可能です。
kubectl annotate serviceaccount KSA_NAME \ --namespace NAMESPACE iam.gke.io/gcp-service-account-
Workload Identity を無効にする
Workload Identity は GKE Standard クラスタでのみ無効にできます。
gcloud
-
Google Cloud コンソールで、「Cloud Shell をアクティブにする」をクリックします。
Google Cloud コンソールの下部で Cloud Shell セッションが開始し、コマンドライン プロンプトが表示されます。Cloud Shell はシェル環境です。Google Cloud CLI がすでにインストールされており、現在のプロジェクトの値もすでに設定されています。セッションが初期化されるまで数秒かかることがあります。
各ノードプールで 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
Console
Google Cloud コンソールで Google Kubernetes Engine のページに移動します。
クラスタのリストで、変更するクラスタの名前をクリックします。
[ノード] タブをクリックします。
各ノードプールの Workload Identity を無効にするには、[ノードプール] セクションで各ノードプールに対して次の操作を行います。
- 変更するノードプールの名前をクリックします。
- [ノードプールの詳細] ページで、[ 編集] をクリックします。
- [ノードプールの編集] ページの [セキュリティ] セクションで、[GKE メタデータ サーバーを有効にする] チェックボックスをオフにします。
- [保存] をクリックします。
クラスタの Workload Identity を無効にする手順は、次のとおりです。
- [詳細] タブをクリックします。
- [セキュリティ] セクションで、[Workload Identity] の横にある [ 編集] をクリックします。
- [Workload Identity の編集] ダイアログで、[Workload Identity を有効にする] チェックボックスをオフにします。
- [保存] をクリックします。
組織内で Workload Identity を無効にする
セキュリティの観点から、Workload Identity では GKE が、Kubernetes サービス アカウント ID を Google Cloud リソースに対して認証、認可できるものとして表明できるようになっています。サービス アカウント作成の無効化やサービス アカウント キーの作成の無効化など、ワークロードを Google Cloud リソースから分離するための措置を講じた管理者は、組織の Workload Identity を無効にする場合もあります。
組織の Workload Identity を無効にする手順をご覧ください。
トラブルシューティング
トラブルシューティング情報については、Workload Identity のトラブルシューティングをご覧ください。
次のステップ
- Workload Identity の詳細を確認する。
- GKE セキュリティの概要を確認する。
- クラスタ メタデータの保護について確認する。
- IAM サービス アカウントについて学習する。