エージェントの Google Cloud API へのアクセスを管理する

アプリケーション デベロッパーは、Google Kubernetes Engine（GKE）で実行される AI エージェントのエージェント ID をリクエストできます。エージェント ID は、ワークロード内の各 Pod に暗号的にバインドできる Pod ごとの ID です。エージェントは、エージェント ID を使用して Google Cloud API に対して認証できます。エージェントがアクセスできるリソースを制御するには、Identity and Access Management（IAM）ポリシーでエージェントをプリンシパルとして指定します。このドキュメントでは、エージェント ID を使用するエージェントの Google Cloud API とサービスへのアクセスを管理する方法について説明します。

このドキュメントは、デベロッパーが GKE クラスタにデプロイするエージェントの認可を管理するセキュリティ管理者とプラットフォーム管理者を対象としています。次のトピックについて理解しておく必要があります。

始める前に

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

  • Google Kubernetes Engine API を有効にする。
    • Google Kubernetes Engine API を有効化
  • このタスクに Google Cloud CLI を使用する場合は、gcloud CLI をインストールして初期化します。gcloud CLI をインストール済みの場合は、gcloud components update コマンドを実行して最新のバージョンを取得します。以前のバージョンの gcloud CLI では、このドキュメントのコマンドを実行できない場合があります。
  • Workload Identity Federation for GKE が有効になっており、GKE バージョン 1.37.0-gke.3503000 以降を実行している既存の Autopilot クラスタまたは Standard クラスタがあることを確認します。

必要なロール

エージェントの Google Cloud API へのアクセスを管理するために必要な権限を取得するには、 Google Cloud プロジェクトに対する次の IAM ロールを付与するよう管理者に依頼してください。

ロールの付与については、プロジェクト、フォルダ、組織へのアクセス権の管理をご覧ください。

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

エージェントのプリンシパル ID を確認する

このセクションでは、エージェントのプリンシパル識別子を構築する方法について説明します。この識別子は、IAM ポリシーで使用して、エージェントがアクセスできるリソースを制御できます。

エージェント ID をリクエストするエージェント ワークロードには、そのワークロードに固有の SPIFFE ID 文字列が返されます。アプリケーションが Google Cloud APIs を呼び出すと、エージェント ID アクセス トークンを使用して呼び出しが認証されます。このトークンは、ワークロードにエージェント ID があることを検証します。このアクセス トークンには、エージェント ワークロードの IAM プリンシパル ID が含まれています。この ID を IAM ポリシーに含めて、エージェントがアクセスできるリソースを制御できます。

IAM ポリシーを設計する際は、次の情報を使用してエージェントのプリンシパル ID を作成できます。

  • プロジェクトのリソース階層。
  • クラスタ名。
  • Kubernetes Namespace と、その Namespace 内の Kubernetes ServiceAccount。

デベロッパーがプリンシパル ID と一致するエージェント ID を取得するエージェントをデプロイすると、エージェントはポリシーで指定したアクセス権を継承します。

ポリシーで使用するプリンシパル ID を確認する手順は次のとおりです。

  1. ID の信頼ドメインを特定します。信頼ドメインは、プロジェクトが組織内にあるかどうかによって次のように異なります。

    • 組織内のプロジェクト:

      agents.global.org-ORGANIZATION_ID.system.id.goog

      ORGANIZATION_ID は、組織 ID に置き換えます。

    • 組織に属していないプロジェクト:

      agents.global.proj-PROJECT_NUMBER.system.id.goog

      PROJECT_NUMBER は、鍵プロジェクトのプロジェクト番号に置き換えます。

  2. クラスタに関する次の情報を特定します。

    • GKE クラスタの名前。
    • クラスタ コントロール プレーンのロケーション（us-central1 など）。
    • デベロッパーがワークロードをデプロイする Kubernetes Namespace。
    • デベロッパーがエージェント ワークロードに使用する必要がある Kubernetes ServiceAccount の名前。

    この情報がわからない場合は、プラットフォーム チームにお問い合わせください。プラットフォーム チームは、アクセス要件が異なるエージェントが異なる ID を取得するように、クラスタに Namespace、ServiceAccount、RBAC ポリシーを設定する必要があります。

  3. プリンシパル ID を作成します。

    principal://TRUST_DOMAIN/resources/container/projects/PROJECT_NUMBER/locations/CONTROL_PLANE_LOCATION/clusters/CLUSTER_NAME/ns/KUBERNETES_NAMESPACE/sa/KUBERNETES_SERVICEACCOUNT

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

    • TRUST_DOMAIN: エージェント ID の信頼ドメイン。
    • PROJECT_NUMBER: クラスタ プロジェクトのプロジェクト番号。
    • CONTROL_PLANE_LOCATION: クラスタ コントロール プレーンのリージョンまたはゾーン。
    • CLUSTER_NAME: クラスタの名前。
    • KUBERNETES_NAMESPACE: Kubernetes Namespace の名前。
    • KUBERNETES_SERVICEACCOUNT: Kubernetes ServiceAccount の名前。

ポリシーを使用してアクセスを制御する

このセクションでは、エージェントのプリンシパル ID を使用して、エージェントがアクセスできる Google Cloud API とサービスを制御する方法について説明します。アクセスを制御するには、次のいずれかの IAM ポリシーにプリンシパル ID を含めます。

ポリシーを作成または更新すると、エージェント ID をリクエストし、その Namespace で実行され、その ServiceAccount を使用するエージェントは、ポリシーで指定したアクセス権を持ちます。

認証マネージャーにアクセスする権限をエージェントに付与する

Agent Identity Auth Manager は、エージェントが外部ツールやサービスにアクセスするための認証情報を取得するために使用する認証ブローカーと認証情報保管庫です。エージェント自身の ID として、またはエンドユーザーに代わって認証情報を取得できます。認証マネージャーには 1 つ以上の認証プロバイダを設定できます。各認証プロバイダは、特定のサービスの特定の認証フローと認証情報取得フローを処理します。GKE エージェントに特定の認証プロバイダへのアクセス権を付与する手順は次のとおりです。

  1. エージェントのプリンシパル ID を確認する。
  2. エージェントがアクセスする必要がある認証プロバイダの名前を取得します。

  3. 認証プロバイダでエージェント プリンシパルに Agent Identity ユーザー（roles/agentidentity.user）ロールを付与します。

    gcloud agent-identity auth-providers add-iam-policy-binding AUTH_PROVIDER_NAME \
    --location=AUTH_PROVIDER_LOCATION \
    --member=PRINCIPAL_IDENTIFIER \
    --role=roles/agentidentity.user

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

    • AUTH_PROVIDER_NAME: 認証プロバイダの名前。
    • AUTH_PROVIDER_LOCATION: 認証プロバイダのリージョン。
    • PRINCIPAL_IDENTIFIER: エージェントのプリンシパル ID。

    または、エージェント レジストリに登録されているエージェントの場合は、認証プロバイダ バインディングを作成して、認証プロバイダへのアクセスを管理できます。

次のステップ