GKE エージェントのエージェント ID をリクエストする

Autopilot Standard

プレビュー - GKE 用エージェント ID

この機能は、サービス固有規約の「一般サービス規約」セクションの「一般提供前のサービス規約」の対象となります。pre-GA の機能は「現状のまま」で提供されるものであり、サポートが制限されることがあります。 詳細については、リリース ステージの説明をご覧ください。

Google Kubernetes Engine（GKE）クラスタにデプロイするエージェント ワークロードは、エージェント自身の ID として、またはエンドユーザーに代わって、外部ツールやサービスにアクセスする必要があることがよくあります。セキュリティ管理者とプラットフォーム管理者は、デプロイされたエージェントが Google Cloudサービス全体で何を行っているかを知りたいと考えています。このドキュメントでは、Pod の エージェント ID をリクエストして、エージェント ワークロードの認証を構成する方法について説明します。このエージェント ID を使用すると、さまざまなワークフローの認証情報を手動で管理することなく認証を構成し、GKE エージェントを Gemini Enterprise Agent Platform と統合できます。このドキュメントは、GKE クラスタでエージェント ワークロードをビルドして実行するアプリケーション デベロッパーを対象としています。

次のトピックについて理解しておく必要があります。

• GKE 用エージェント ID について
• Kubernetes オブジェクトの宣言型管理

料金

エージェント ID は、GKE で追加料金なしで提供されます。

制限事項

• Agent Registry に自動的に登録できるのは、Deployment のみです。他のワークロード コントローラと静的 Pod は自動登録をサポートしていません。すべてのワークロード タイプのエージェント ID をリクエストできますが、Agent Registry に登録すると、これらの ID を Agent Platform と統合できます。
• バインドされたエージェント ID アクセス トークンは、https://www.googleapis.com/auth/cloud-platform OAuth スコープのみを使用します。バインドされたアクセス トークンに別のスコープを指定することはできません。

始める前に

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

• Google Kubernetes Engine API を有効にする。
Google Kubernetes Engine API を有効化
• このタスクに Google Cloud CLI を使用する場合は、gcloud CLI をインストールして初期化します。gcloud CLI をインストール済みの場合は、gcloud components update コマンドを実行して最新のバージョンを取得します。以前のバージョンの gcloud CLI では、このドキュメントのコマンドを実行できない場合があります。
  注: gcloud CLI がすでにインストールされている場合には、必ず compute/region プロパティを設定してください。主にゾーンクラスタを使用する場合は、代わりに compute/zone を設定します。デフォルトのロケーションを設定することで、gcloud CLI のエラー（One of [--zone, --region] must be supplied: Please specify location など）を防止できます。クラスタのロケーションが設定したデフォルトと異なる場合は、特定のコマンドでロケーションの指定が必要になることがあります。

• Agent Registry API を有効にします（有効になっていない場合）。

  API を有効にするために必要なロール

  API を有効にするには、serviceusage.services.enable 権限が必要です。プロジェクトを作成した場合は、オーナーロール（roles/owner）を通じてこの権限がすでに付与されている可能性があります。それ以外の場合は、Service Usage 管理者ロール（roles/serviceusage.serviceUsageAdmin）を通じてこの権限を取得できます。ロールを付与する方法を確認する。

  gcloud services enable agentregistry.googleapis.com

• Workload Identity Federation for GKE が有効になっており、GKE バージョン 1.37.0-gke.3503000 以降を実行している既存の Autopilot クラスタまたは Standard クラスタがあることを確認します。

• トークン交換オペレーションに十分な割り当てがあることを確認します。この割り当ての名前は、リージョンごとの 1 分あたりの Workload Identity トークン交換リクエスト数です。詳細については、割り当てと上限をご覧ください。

必要なロール

エージェント ID をリクエストしてワークロードをデプロイするために必要な権限を取得するには、 Google Cloud プロジェクトに対する Kubernetes Engine デベロッパー （roles/container.developer）IAM ロールを付与するよう管理者に依頼してください。ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

必要な権限は、カスタムロールや他の事前定義ロールから取得することもできます。

ワークロードのエージェント ID をリクエストする

Pod のエージェント ID を取得するには、Pod 仕様にアノテーションを追加して、ワークロードの SPIFFE ID をリクエストし、X.509 証明書バンドルを各 Pod に挿入します。Deployment によって管理される Pod の場合は、アノテーションとラベルを追加して、Agent Registry にエージェントを登録する必要があります。登録は任意ですが、登録されたエージェントのみが Agent Gateway などの Agent Platform サービスを使用できます。特定のアノテーションとラベルの詳細については、ワークロード レベルの構成をご覧ください。

次の手順では、エージェント ID をリクエストする Deployment の例を作成する方法について説明します。

1. 組織 ID を確認します。プロジェクトが組織に属していない場合は、この手順をスキップして、代わりにプロジェクト番号を確認してください。

   gcloud projects get-ancestors PROJECT_ID
   

   PROJECT_ID は、クラスタ プロジェクト ID に置き換えます。

   出力は次のようになります。

   ID: my-project
   TYPE: project
   ID: 811159889184
   TYPE: folder
   ID: 301928500920
   TYPE: organization
   

   organization リソースの ID フィールドの値をメモします。

2. クラスタに接続します。

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

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

   • CLUSTER_NAME: クラスタの名前。
   • CONTROL_PLANE_LOCATION: クラスタのコントロール プレーンのリージョンまたはゾーン。

3. サンプル Deployment を実行する Namespace を作成します。

   kubectl create namespace NAMESPACE_NAME
   

   NAMESPACE_NAME は、Namespace の名前に置き換えます。

4. Deployment の Kubernetes ServiceAccount を作成します。

   kubectl create serviceaccount SERVICEACCOUNT_NAME \
       --namespace=NAMESPACE_NAME
   

   SERVICEACCOUNT_NAME は、サービス アカウントの名前に置き換えます。

5. 次の Deployment マニフェストを agent-identity-deployment.yaml として保存します。

   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: agent-identity-deployment
     namespace: NAMESPACE_NAME
     # Add the agent to Agent Registry
     labels:
       registry.gke.io/functional-type: "AGENT"
     annotations:
       # A2A protocol metadata annotation for automated Agent Card discovery
       a2a-protocol.org/agent-card: |
         card:
           endpoint: /.well-known/agent-card.json
           protocol: HTTP
           port: 8080
   spec:
     replicas: 2
     selector:
       matchLabels:
         workload-type: agent
     template:
       metadata:
         name: agent-identity-pod
         annotations:
           iam.gke.io/identity: "spiffe://TRUST_DOMAIN/*" # The trust domain from which to assign SPIFFE IDs.
           iam.gke.io/inject-podcertificates: "true" # Inject X.509 certificates and per-Pod private key into each Pod.
           iam.gke.io/spiffe-identity-type: "agent-identity" # Required for Agent Registry registration.
         labels:
           workload-type: agent
       spec:
         serviceAccountName: SERVICEACCOUNT_NAME
         containers:
         - name: agent
           image: python:3.11-slim
           command: ["sleep","infinity"]
   

   TRUST_DOMAIN は、プロジェクト内のエージェントの ID を発行する信頼ドメインに置き換えます。この値は、プロジェクトが組織内にあるかどうかに応じて、次のいずれかの構文を使用する必要があります。

   • 組織内のプロジェクト: agents.global.org-ORGANIZATION_ID.system.id.goog。ここで、ORGANIZATION_ID は組織の ID です。
   • 組織に属していないプロジェクト: agents.global.proj-PROJECT_NUMBER.system.id.goog。ここで、PROJECT_NUMBER はクラスタ プロジェクトのプロジェクト番号です。

   この Deployment は、ワークロードのエージェント ID をリクエストし、Pod ごとの X.509 証明書を Pod に追加して、エージェントをエージェント レジストリに登録します。

6. Deployment を作成します。

   kubectl apply -f agent-identity-deployment.yaml
   

7. Pod が実行されていることを確認します。

   kubectl get pods -l workload-type=agent -n NAMESPACE_NAME
   

割り当てられたエージェント ID を確認する

エージェント ID をリクエストするワークロードをデプロイしたら、X.509 証明書を確認して ID を検証できます。証明書の挿入を無効にすると、 Google Cloud API に対する認証で説明されているように、GKE メタデータ サーバーからバインドされていない ID トークンを取得して、サブジェクト フィールドを確認できます。

Pod の X.509 証明書を読み取るには、次の操作を行います。

1. Pod が X.509 証明書と秘密鍵にアクセスできるかどうかを確認します。

   kubectl get pod POD_NAME -n NAMESPACE_NAME \
       -o=jsonpath='{range .spec.volumes[*]}{.name}{"\n"}{end}'
   

   POD_NAME は、エージェント ID を使用する Pod の名前に置き換えます。

   出力は次のようになります。

   kube-api-access-bx86g
   gke-workload-spiffe-credentials
   

   この出力では、gke-workload-spiffe-credentials ボリュームは挿入された証明書の場所です。このボリュームが表示されない場合は、Pod 仕様で iam.gke.io/inject-podcertificates アノテーションの値が true に設定されていることを確認します。

2. Pod でインタラクティブ シェル セッションを作成します。

   kubectl exec -n NAMESPACE_NAME -it POD_NAME -- /bin/bash
   

3. シェル セッションで、gke-workload-spiffe-credentials ボリュームの認証情報を一覧表示します。

   ls -1 /var/run/secrets/workload-spiffe-credentials/
   

   出力は次のようになります。

   x509.credential-bundle.private-key.pem
   TRUST_DOMAIN.spiffe-trust-bundle.pem
   

   出力には次のファイルが表示されます。

   • x509.credential-bundle.private-key.pem: エージェント ID 認証情報バンドル。これには、X.509 証明書チェーンと Pod に固有の秘密鍵が含まれます。この認証情報バンドルは、アクセス トークンと ID トークンをリクエストし、mTLS を使用して Google CloudAPI を認証するために使用されます。
   • TRUST_DOMAIN.spiffe-trust-bundle.pem: エージェント ID 認証情報のトラスト アンカーを形成する自己署名証明書を含むルート CA トラスト バンドル。この信頼バンドルは、主に mTLS handshake 中に他のワークロードからの TLS 証明書を検証するために使用されます。

4. Pod に関連付けられている SPIFFE ID を取得するには、X.509 証明書を読み取ります。

   openssl x509 -in /var/run/secrets/workload-spiffe-credentials/x509.credential-bundle.private-key.pem -text -noout
   

   出力は次のようになります。

   Certificate:
       Data:
       # Multiple lines are omitted here
           X509v3 extensions:
               # Multiple lines are omitted here
               X509v3 Subject Alternative Name: critical
                   URI:spiffe://agents.global.org-301928500920.system.id.goog/resources/container/projects/729788050015/locations/us-central1/clusters/cluster-2/ns/agent-identity-ns/sa/agent-identity-sa
       # Multiple lines are omitted here
   

   この出力では、X509v3 Subject Alternative Name フィールドの URI フィールドの値は、エージェントの SPIFFE ID です。

エージェント Pod に SPIFFE ID が割り当てられている場合、エージェント ID のリクエストは成功しています。割り当てられた ID を使用して、さまざまなツールやサービスに対して認証を行うことができます。

次のステップ

• GKE でエージェント ID を使用して認証する
• エージェントのトレースを設定する
• エージェントのロギングを設定する
• エージェントのモニタリングを設定する