このガイドでは、標準の Kubernetes クラスタにクロス クラウド用の Agent Gateway をデプロイして、Gemini Enterprise Agent Platform のガバナンスを環境に拡張する方法について説明します。3 プレーン アーキテクチャの概要については、クロスクラウド用 Agent Gateway の概要をご覧ください。
始める前に
始める前に、次の準備をしてください。
- Cloud Native Computing Foundation(CNCF)に準拠した Kubernetes クラスタ。
- クラスタに構成されている既存のサービス メッシュまたはネットワーク スタック。
- クラスタから Google Cloud API への HTTPS(TCP ポート
443)経由のアウトバウンド ネットワーク接続。 - Google Cloud CLI バージョン 591.0.0 以降がインストールされている。最新バージョンに更新するには、
gcloud components updateを実行します。 - API の有効化、Workload Identity プールとプロバイダの作成、IAM ロールの付与に必要な Google Cloud プロジェクトの Identity and Access Management(IAM)ロール。
API を有効にしてクラスタを登録する
必要な Google Cloud API を有効にしてから、外部クラスタを登録します。
必要な API を有効にする
クロスクラウド用 Agent Gateway に必要な API を有効にするには、次のコマンドを実行します。
gcloud services enable \
agentregistry.googleapis.com \
apphubendpoint.googleapis.com \
cloudresourcemanager.googleapis.com \
cloudtrace.googleapis.com \
iam.googleapis.com \
iamcredentials.googleapis.com \
iap.googleapis.com \
logging.googleapis.com \
modelarmor.googleapis.com \
monitoring.googleapis.com \
networkservices.googleapis.com \
serviceextensions.googleapis.com \
sts.googleapis.com \
telemetry.googleapis.com \
trafficdirector.googleapis.com \
--project=PROJECT_ID
PROJECT_ID は、Google Cloud プロジェクトの ID に置き換えます。
Kubernetes API サーバーの公開鍵を抽出する
クラスタを登録するには、クラスタがサービス アカウント トークンの署名に使用する公開鍵が必要です。公開鍵を抽出するには、次の操作を行います。
現在の
kubectlコンテキストを、登録するクラスタに設定します。クラスタの JSON Web Key Set(JWKS)を取得し、最初の RSA 鍵を
pubkey.pemという名前の公開鍵ファイルに変換します。kubectl get --raw /openid/v1/jwks > cluster-jwks.json N_HEX=$(jq -r '[.keys[] | select((.kty // "" | ascii_upcase) == "RSA" and (.n // "") != "" and (.e // "") != "")][0].n | gsub("-";"+") | gsub("_";"/") | . + ("==="[:(4 - length % 4) % 4])' cluster-jwks.json | base64 -d | od -An -tx1 | tr -d ' \n') E_HEX=$(jq -r '[.keys[] | select((.kty // "" | ascii_upcase) == "RSA" and (.n // "") != "" and (.e // "") != "")][0].e | gsub("-";"+") | gsub("_";"/") | . + ("==="[:(4 - length % 4) % 4])' cluster-jwks.json | base64 -d | od -An -tx1 | tr -d ' \n') openssl asn1parse -genconf <(printf "asn1=SEQUENCE:rsa_key\n[rsa_key]\nmodulus=INTEGER:0x%s\nexponent=INTEGER:0x%s\n" "$N_HEX" "$E_HEX") -noout -out /dev/stdout \ | openssl rsa -RSAPublicKey_in -inform DER -pubout -out pubkey.pemこれらのコマンドには、Bash シェルと
jqユーティリティ、opensslユーティリティが必要です。
クラスタを登録する
クラスタを登録するには、次の操作を行います。
クラスタの OpenID Connect(OIDC)発行者 URL を取得します。
kubectl get --raw /.well-known/openid-configuration | jq -r '.issuer'
出力は、クラスタの Kubernetes API サーバーの
--service-account-issuerフラグの値です。この値は、Kubernetes API サーバーの外部 URL とは異なる場合があります。出力をそのままコピーします。末尾のスラッシュを追加または削除しないでください。クラスタを登録します。
gcloud alpha network-services registered-clusters create CLUSTER_NAME \ --project=PROJECT_ID \ --location=LOCATION \ --oidc-issuer-url=OIDC_ISSUER_URL \ --api-server-public-key="$(cat pubkey.pem)"次のように置き換えます。
CLUSTER_NAME: 登録済みクラスタの名前。PROJECT_ID: 実際の Google Cloudプロジェクトの ID。LOCATION: 登録済みクラスタの Google Cloud リージョン(例:us-central1)。OIDC_ISSUER_URL: 前の手順で取得した正確な発行元 URL。先頭はhttps://でなければなりません。
リソースの誤削除を防止する
クロスクラウド ワークロードがアクティブなときに Google Cloud プロジェクトを削除するか、登録済みのクラスタの登録を解除すると、クラスタ内コントローラが切断され、ポリシーの適用が中断されます。 Google Cloud リソースを誤って削除しないように保護するには、次の安全対策を適用します。
- リーエンで Google Cloud プロジェクトを保護する: 登録済みクラスタ、Agent Registry、フェデレーション ID プールをホストするGoogle Cloud プロジェクトにプロジェクト リーエンを適用して、すべてのクロスクラウド クラスタがデコミッションされるまで、プロジェクトが誤って削除されないようにします。
- 破壊的な IAM 権限を制限する: 登録済みクラスタまたはゲートウェイ リソース(
networkservices.registeredClusters.deleteやnetworkservices.agentGateways.deleteなど)を削除できる権限を、専用のプラットフォーム管理者ロールに制限します。 - Kubernetes リソースのファイナライザを保持する:
agent-governance-cross-cloud-controllerコントローラによって管理されているクラスタ内カスタム リソースのファイナライザを削除しないでください。ファイナライザにより、ローカル クラスタ リソースが削除される前に、対応する Google Cloud コントロール プレーンの登録がクリーンにプロビジョニング解除されます。 - コントローラを削除する前にカスタム リソースを削除する:
agent-governance-cross-cloudHelm チャートをアンインストールするか、Kubernetes クラスタを削除する前に、すべてのGCPExtensionBindingカスタム リソースとGCPAgentGatewayカスタム リソースを削除し、削除が完了するまで待ちます。最初にコントローラを削除すると、対応する Agent Gateway リソースが Network Services で孤立したままになります。孤立したゲートウェイにより、エージェント接続テンプレートと登録済みクラスタの削除がブロックされます。
Workload Identity 連携を構成する
クロスクラウド用 Agent Gateway のクラスタ内コンポーネント(agent-governance-cross-cloud-controller コントローラ、テレメトリー コレクタ、プロキシ)は、Workload Identity 連携を使用してGoogle Cloud API に対する認証を行います。各コンポーネントは、Kubernetes サービス アカウント(KSA)トークンを連携アクセス トークンと交換します。IAM ロールはこれらのフェデレーション ID に直接付与されるため、Google Cloud サービス アカウントを作成したり、サービス アカウント キーをクラスタに保存したりする必要はありません。
各プロキシで実行される Agent Identity Runtime(AIR)サイドカーは、Workload Identity プールを使用して、エージェント ワークロードに SPIFFE ID を提供します。これらの ID は、エージェントのエージェント ID です。Model Armor と IAP のポリシーは、クラスタ内コンポーネントのフェデレーション ID ではなく、エージェント ID によってエージェントを識別します。プリンシパルの形式については、エージェント プリンシパルを特定するをご覧ください。
Workload Identity プールとプロバイダを作成する
クラスタの Workload Identity プールと OIDC プロバイダを作成するには、次の操作を行います。
クラスタの OIDC 発行元 URL が一般公開されていない場合は、クラスタの JSON Web Key Set(JWKS)をファイルに保存します。
kubectl get --raw /openid/v1/jwks > cluster-jwks.json
JWKS をプロバイダに提供すると、 Google Cloud はクラスタの OIDC 発行者に接続せずに KSA トークンを検証できます。
Workload Identity プールを作成します。
gcloud iam workload-identity-pools create POOL_ID \ --project=PROJECT_ID \ --location=global \ --display-name="POOL_DISPLAY_NAME"プールに OIDC プロバイダを作成します。
gcloud iam workload-identity-pools providers create-oidc PROVIDER_ID \ --project=PROJECT_ID \ --location=global \ --workload-identity-pool=POOL_ID \ --issuer-uri=OIDC_ISSUER_URL \ --jwk-json-path=cluster-jwks.json \ --attribute-mapping="google.subject=assertion.sub,attribute.namespace=assertion['kubernetes.io']['namespace'],attribute.service_account=assertion['kubernetes.io']['serviceaccount']['name']"--allowed-audiencesフラグは指定しないでください。クロスクラウド コンポーネントは、デフォルトのオーディエンス(プロバイダの完全なリソース名//iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/PROVIDER_ID)のトークンをリクエストします。
次のように置き換えます。
POOL_ID: Workload Identity プールの ID。PROJECT_ID: 実際の Google Cloud プロジェクト ID。POOL_DISPLAY_NAME: プールの表示名。PROVIDER_ID: OIDC プロバイダの ID。OIDC_ISSUER_URL: クラスタを登録したときに取得した正確な OIDC 発行者 URL。この値は、末尾のスラッシュの有無を含め、--oidc-issuer-urlに渡した値と一致する必要があります。
コントロール プレーンをデプロイする
提供されている Helm チャートを使用して、クラスタ内コントローラ、agent-governance-cross-cloud-controller、テレメトリー コレクタを geap-system Namespace にデプロイします。
コントローラの接続を確認する
クラスタのファイアウォール、プロキシ、下り(外向き)ルール、ネットワーク ポリシーで、次の接続が許可されていることを確認します。
- Google Cloud API:
agent-governance-cross-cloud-controllerコントローラ Pod とテレメトリー コレクタには、TCP ポート443で*.googleapis.comへのアウトバウンド HTTPS 接続と gRPC 接続が必要です。 - Kubernetes API サーバー: コントローラ Pod は、Kubernetes サービス、ワークロード、カスタム リソースを監視するために、Kubernetes API サーバーにアクセスできる必要があります。
- すべての Namespace のエージェント ワークロード: コントローラ Pod は、クラスタ内の任意の Namespace のエージェント Pod と MCP サーバー Pod を呼び出すことができる必要があります。コントローラは、各エージェント ワークロードからエージェント カードを取得して、エージェントを Agent Registry に登録します。
コントローラとテレメトリー コレクタに IAM ロールを付与する
geap-system 名前空間で実行される agent-governance-cross-cloud-controller コントローラとテレメトリー コレクタのフェデレーション ID に IAM ロールを付与します。
- 衛星オペレーター(
roles/networkservices.satelliteOperator) - Cloud テレメトリー書き込み(
roles/telemetry.writer)
ロールを付与するには、次のコマンドを実行します。
for ROLE in \
roles/networkservices.satelliteOperator \
roles/telemetry.writer; do
gcloud projects add-iam-policy-binding PROJECT_ID \
--role="${ROLE}" \
--member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.namespace/geap-system"
done
次のように置き換えます。
PROJECT_ID: 実際の Google Cloud プロジェクト ID。PROJECT_NUMBER: Google Cloud プロジェクト番号。POOL_ID: Workload Identity プールの ID。
コントロール プレーンの Helm チャートをインストールする
コントロール プレーンをインストールする手順は次のとおりです。
geap-systemNamespace にagent-governance-cross-cloudHelm チャートをインストールします。helm upgrade --install agent-governance-cross-cloud \ oci://gcr.io/gke-release/agent-governance-cross-cloud \ --version 0.1.1-preview \ --namespace geap-system \ --create-namespace \ --set gcp.projectId=PROJECT_ID \ --set-string gcp.projectNumber=PROJECT_NUMBER \ --set-string gcp.orgId=ORGANIZATION_ID \ --set gcp.location=LOCATION \ --set gcp.registeredCluster=CLUSTER_NAME \ --set gcp.workloadIdentityPool=POOL_ID \ --set gcp.identityProvider=PROVIDER_ID次のように置き換えます。
PROJECT_ID: 実際の Google Cloud プロジェクト ID。PROJECT_NUMBER: Google Cloud プロジェクト番号。ORGANIZATION_ID:Google Cloud 組織の ID。プロジェクトが組織に関連付けられていない場合は、--set-string gcp.orgIdフラグを省略します。LOCATION: クラスタを登録したリージョン(例:us-central1)。CLUSTER_NAME: 登録済みクラスタの名前。POOL_ID: Workload Identity プールの ID。PROVIDER_ID: Workload Identity プール プロバイダの ID。
クラスタのノードに taint がある場合( Google Cloud、AWS、Azure などのほとんどのクラウド プロバイダの arm64 ノードなど)、
k8s.tolerationsHelm 値に Pod の toleration を設定します。toleration は、コントローラ、OpenTelemetry(OTel)コレクタ、コントローラが作成するゲートウェイ デプロイに適用されます。たとえば、次をtolerations-values.yamlとして保存し、前のコマンドに--values tolerations-values.yamlを追加します。k8s: tolerations: - key: "kubernetes.io/arch" operator: "Equal" value: "arm64" effect: "NoSchedule"コントローラのデプロイの準備が整うまで待ちます。
kubectl rollout status deployment/agent-governance-cross-cloud-controller \ --namespace geap-system --timeout=180s
データプレーンをデプロイする
GCPAgentGateway カスタム リソースを作成して、クロス クラウド プロキシ(Envoy プロキシ)用の Agent Gateway をデプロイします。プロキシは、トラフィックを検査し、管理するエージェント ワークロードにポリシーを適用します。各プロキシは、Workload Identity、Secret Discovery Service(SDS)証明書、プロキシのローカル トークン交換を仲介する Agent Identity Runtime(AIR)サイドカーとともに実行されます。
クロスクラウド用の Agent Gateway は、エージェント ワークロード、MCP サーバー、その他のアプリケーション Pod を含まない専用の Namespace(agent-gateway-system など)にデプロイする必要があります。この専用 Namespace 内の単一の Gateway は、クラスタ全体のエージェント ワークロードからのアウトバウンド トラフィックを管理できます。
ゲートウェイに IAM ロールを付与する
クロスクラウド プロキシの Agent Gateway のフェデレーション ID に IAM ロールを付与します。このバインディングは、ゲートウェイ Namespace 内のすべての KSA に適用されるため、ゲートウェイ Namespace ごとに次のロールを付与します。
- Traffic Director クライアント(
roles/trafficdirector.client) - App Hub エンドポイント閲覧者(
roles/apphubendpoint.viewer) - Agent Registry 閲覧者(
roles/agentregistry.viewer) - Service Extensions 編集者(
roles/serviceextensions.editor)。プロキシが Service Extensions ポリシーのコールアウトを呼び出せるようにします。
ロールを付与するには、次のコマンドを実行します。
for ROLE in \
roles/trafficdirector.client \
roles/apphubendpoint.viewer \
roles/agentregistry.viewer \
roles/serviceextensions.editor; do
gcloud projects add-iam-policy-binding PROJECT_ID \
--role="${ROLE}" \
--member="principalSet://iam.googleapis.com/projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/attribute.namespace/GATEWAY_NAMESPACE"
done
次のように置き換えます。
PROJECT_ID: 実際の Google Cloud プロジェクト ID。PROJECT_NUMBER: Google Cloud プロジェクト番号。POOL_ID: Workload Identity プールの ID。GATEWAY_NAMESPACE: ゲートウェイ専用の名前空間。この Namespace にはエージェント ワークロードを含めないでください。
エージェント接続テンプレートを作成する
各ゲートウェイは、エージェント接続テンプレートを参照します。これは、登録済みクラスタを参照するGoogle Cloud リソースです。ゲートウェイごとに個別のテンプレートを作成する必要はありません。複数のゲートウェイを 1 つのテンプレートにマッピングできます。同じクラスタに複数のテンプレートを作成することもできます。
使用するクラスタのエージェント接続テンプレートがすでにある場合は、ゲートウェイを作成するに進みます。
エージェント接続テンプレートを作成する手順は次のとおりです。
次のテンプレート定義を
act.yamlとして保存します。description: "Agent connectivity template for CLUSTER_NAME" agentCompute: K8S registeredCluster: "projects/PROJECT_ID/locations/LOCATION/registeredClusters/CLUSTER_NAME"
テンプレートをインポートします。
gcloud alpha network-services agent-connectivity-templates import ACT_NAME \ --project=PROJECT_ID \ --location=LOCATION \ --source=act.yaml
次のように置き換えます。
CLUSTER_NAME: 登録済みクラスタの名前。PROJECT_ID: 実際の Google Cloud プロジェクト ID。LOCATION: クラスタを登録したリージョン。ACT_NAME: エージェント接続テンプレートの名前。
ゲートウェイを作成する
ゲートウェイを作成する手順は次のとおりです。
ゲートウェイの Namespace がまだ存在しない場合は、作成します。
kubectl create namespace GATEWAY_NAMESPACE
GATEWAY_NAMESPACEは、ゲートウェイにロールを付与したときに使用したゲートウェイの専用名前空間に置き換えます。次のマニフェストを
agent-gateway.yamlとして保存します。apiVersion: networkservices.googleapis.com/v1alpha1 kind: GCPAgentGateway metadata: name: GATEWAY_NAME namespace: GATEWAY_NAMESPACE spec: agentConnectivityTemplateUri: "projects/PROJECT_ID/locations/LOCATION/agentConnectivityTemplates/ACT_NAME"
次のように置き換えます。
GATEWAY_NAME: ゲートウェイの名前。GATEWAY_NAMESPACE: ゲートウェイにロールを付与したときに使用したゲートウェイの専用 Namespace。PROJECT_ID: 実際の Google Cloud プロジェクト ID。LOCATION: エージェント接続テンプレートのリージョン。このリージョンは、クラスタを登録したリージョンと一致する必要があります。ACT_NAME: エージェント接続テンプレートの名前。
次のようにマニフェストを適用します。
kubectl apply -f agent-gateway.yaml
ゲートウェイがデプロイされ、準備が整うまで待ちます。
kubectl wait --for=condition=Reconciled=True \ gcpagentgateway/GATEWAY_NAME \ -n GATEWAY_NAMESPACE \ --timeout=300sゲートウェイの準備が整うと、コマンドは
gcpagentgateway.networkservices.googleapis.com/GATEWAY_NAME condition metを返します。大規模言語モデル(LLM)、Model Context Protocol(MCP)、Agent-to-Agent(A2A)リクエストなどのアウトバウンド エージェント トラフィックをゲートウェイ経由で転送するようにサービス メッシュを構成します。
既存のゲートウェイに toleration を追加する
GCPAgentGateway リソースの作成後に k8s.tolerations Helm 値を追加する場合は、次の操作を行い、コントローラが新しい toleration でゲートウェイ デプロイを再作成するようにします。
--values tolerations-values.yamlを指定して、コントロール プレーンの Helm チャートをインストールするからhelm upgrade --installコマンドを実行します。既存のゲートウェイ デプロイを削除します。
kubectl delete deployment GATEWAY_NAME \ --namespace GATEWAY_NAMESPACEクラスタ内の各ゲートウェイに対してこの手順を繰り返します。
コントローラを再起動して、ゲートウェイ Deployment を再作成します。
kubectl rollout restart deployment/agent-governance-cross-cloud-controller \ --namespace geap-system
この手順は、 Google Cloud AgentGateway リソースや、アタッチされている GCPExtensionBinding リソースには影響しません。コントローラがゲートウェイのデプロイを再作成するまで、ゲートウェイを通過するアウトバウンド トラフィックは中断されます。
Google API へのアウトバウンド接続を許可する
クロスクラウド プロキシ Pod の Agent Gateway に、TCP ポート 443 で *.googleapis.com へのアウトバウンド HTTPS 接続と gRPC 接続があることを確認します。
TLS インスペクションを構成する
クロスクラウド用の Agent Gateway がアウトバウンド トラフィックを検査して管理できるように、Transport Layer Security(TLS)インスペクションを構成します。
TLS インスペクション CA シークレットを保護する
クロスクラウド用 Agent Gateway は、ルート認証局(CA)を使用して、送信 TLS トラフィックを検査するときに提示する証明書を発行します。コントローラは、起動時にこの CA を作成します。CA(秘密鍵を含む)は、2 つの Namespace(コントローラ Namespace(geap-system)と、クロスクラウド プロキシと AIR サイドカーの Agent Gateway がデプロイされているゲートウェイ Namespace)の Kubernetes Secret リソースに保存されます。これらの Secret リソースを読み取ることができるユーザーは、エージェント ワークロードの外部エンドポイントになりすますことができます。CA を保護するには、次の安全対策を適用します。
Secretへの RBAC アクセスを制限する:geap-system名前空間とゲートウェイ名前空間のSecretリソースに対するget、list、watch権限を、クロス クラウド サービス アカウントと専用プラットフォーム管理者用の Agent Gateway に制限します。list権限とwatch権限でもSecretのコンテンツが公開されます。- コントローラとゲートウェイの Namespace を分離する: Namespace に Pod を作成できるユーザーは、その Namespace に任意の
Secretをマウントできます。geap-system名前空間とゲートウェイ名前空間のクロス クラウド コンポーネント用の Agent Gateway のみを実行します。これらの Namespace にエージェント ワークロードや他の Pod をデプロイしないでください。これらの Namespace で Pod、Deployment、その他のワークロード リソースを作成または変更する権限を、信頼できる管理者に制限します。 Secretの保存データを暗号化する: クラスタの etcd データストア内のSecretリソースに対して保存データの暗号化を有効にします。可能な場合は、KMS プロバイダを使用して暗号鍵を管理します。Secretへのアクセスを監査する: Kubernetes 監査ロギングを有効にして、CASecretへの読み取りアクセスをモニタリングします。