VPC 接続を使用して Agent Gateway を設定する

このドキュメントでは、Agent Gateway をデプロイするときに VPC 接続を構成して、組織内の VPC ネットワークと非公開で通信できるようにする方法について説明します。

VPC 接続を設定すると、次のことができます。

  • トラフィックに VPC 下り(外向き)を適用する: PRIVATE_RANGES_ONLY モードまたは ALL_TRAFFIC モードを使用して、エージェントから発信されたトラフィックを Private Service Connect ネットワーク アタッチメントを介して VPC ネットワークにルーティングします。
  • 静的送信元 IP アドレス範囲: 下り(外向き)トラフィックは、Private Service Connect ネットワーク アタッチメント サブネットのプライベート IP アドレス範囲を送信元 IP アドレスとして使用します。この静的送信元 IP 範囲を使用すると、VPC ネットワークのファイアウォール ポリシーを構成して、ゲートウェイからのトラフィックを管理できます。
  • カスタム DNS の解決: Cloud DNS ピアリングを使用して、エージェントから内部プライベート ドメイン名と外部ドメイン名を直接解決します。
  • 境界セキュリティ: VPC Service Controls のサービス境界を使用してエージェント通信を保護します。
  • プライベート証明書または自己署名証明書の検証: プライベート CA または自己署名証明書を使用する宛先に接続します。

VPC 接続を構成するには、Agent Gateway 接続テンプレート(AgentConnectivityTemplate)を作成します。ここで、Agent Gateway インスタンスの下り(外向き)ネットワーク設定を定義して管理します。

VPC 接続の仕組み

接続テンプレートを使用して Agent Gateway をデプロイすると、ゲートウェイは Private Service Connect インターフェースを使用して、アウトバウンド エージェント トラフィックを指定された VPC ネットワークにルーティングします。

VPC 下り(外向き)モード

ゲートウェイがネットワーク アタッチメントを介してトラフィックをルーティングする方法は、接続テンプレートの vpcEgress 設定を使用して構成します。

  • プライベート IP アドレス範囲(PRIVATE_RANGES_ONLY)へのトラフィック: プライベート IP アドレス範囲のみを宛先とするトラフィックを VPC ネットワークにルーティングします。アウトバウンド トラフィックは、宛先 IP アドレスが次のいずれかの範囲内にある場合にのみ、VPC ネットワークにルーティングされます。

    • RFC 1918: 10.0.0.0/8、172.16.0.0/12、192.168.0.0/16
    • RFC 6598: 100.64.0.0/10
    • クラス E: 240.0.0.0/4
    • private.googleapis.com: 199.36.153.8/30
    • restricted.googleapis.com: 199.36.153.4/30
    • Google API 用の PSC エンドポイント: VPC ネットワーク内の内部プライベート IP アドレスを使用して Google API 用のカスタム Private Service Connect エンドポイントをデプロイすると、このエンドポイントへのトラフィックは VPC ネットワークを介してルーティングされます。Agent Gateway が Google API ドメインを内部 PSC エンドポイント IP アドレスに正しく解決するように、接続テンプレートで Cloud DNS ピアリングが構成されていることを確認します。

    標準の一般公開 Google API へのリクエストは、プライベート Google アクセスを使用して自動的に処理されます。インターネット宛てのトラフィックは、VPC ネットワークではなく Agent Gateway を介して直接ルーティングされます。

  • すべての IP アドレス範囲(ALL_TRAFFIC)へのトラフィック: エージェントから発信されるすべてのアウトバウンド トラフィック(パブリック インターネット、外部 SaaS API、RFC 1918 以外のアドレスなど)を VPC ネットワーク経由でルーティングします。

    • ルーティングとセキュリティ: この設定では、すべてのアウトバウンド トラフィックが VPC にルーティングされるため、ルーティングとセキュリティの管理はお客様の責任となります。VPC ネットワークにデフォルト ルート(0.0.0.0/0)があり、このトラフィックをアウトバウンド ゲートウェイまたはセキュリティ アプライアンス(ネクストホップ ファイアウォールや Cloud Interconnect インターフェースなど)に転送することを確認します。
    • パブリック インターネットの下り(外向き): Agent Gateway は、アウトバウンド トラフィックを VPC ネットワークに送信します。このトラフィックは、Private Service Connect ネットワーク アタッチメント サブネットの Cloud NAT ゲートウェイを介してパブリック インターネットに送信されます。Cloud NAT ゲートウェイに静的外部 IP アドレスを割り当てると、リモート サービスは、これらの送信元 IP アドレスに基づいてエージェントの下り(外向き)トラフィックを許可リストに登録できます。
    • VPC Service Controls: VPC Service Controls のサービス境界をサポートするには、下り(外向き)モードを ALL_TRAFFIC に設定する必要があります。

DNS の解決とトラフィック ルーティング

デフォルトでは、Agent Gateway はパブリック再帰 DNS を使用してドメイン名を解決します。エージェントが VPC ネットワーク内のプライベート ドメイン名(corp.internal. や PSC エンドポイントなど)でホストされている内部ワークロード、プライベート ツール、Google API にアクセスする必要がある場合は、Cloud DNS ピアリングを構成して、DNS クエリをネットワークのプライベート Cloud DNS マネージド ゾーンに転送できます。

次の表は、VPC 接続が ALL_TRAFFIC モードで構成されている場合の、さまざまな宛先に対する Cloud DNS ピアリングの要件とトラフィック ルーティングの動作をまとめたものです。

表: ALL_TRAFFIC モードでの DNS の解決とトラフィック ルーティング
トラフィックの宛先 Cloud DNS ピアリングが必要かどうか DNS の解決 下り(外向き)パス
プライベート IP サービス
(RFC 1918 / 内部)
はい(例: corp.internal.) ターゲット VPC ネットワークのプライベート Cloud DNS マネージド ゾーンとの Cloud DNS ピアリングを使用して解決します。 トラフィックは、ネットワーク アタッチメントを介して VPC ネットワークに入り、内部ワークロードに接続します。
プライベート IP を持つパブリック ホスト名
(スプリット ホライズン DNS)
いいえ Cloud DNS ピアリングを必要とせずに、ゲートウェイ プロキシで標準のパブリック再帰 DNS を使用して解決します。 トラフィックは、ネットワーク アタッチメントを介して VPC ネットワークに入り、内部ワークロードに接続します。
公共のインターネットと SaaS API
(外部ドメイン)
いいえ Cloud DNS ピアリングを必要とせずに、ゲートウェイ プロキシで標準のパブリック再帰 DNS を使用して解決します。 トラフィックはネットワーク アタッチメントを介して VPC ネットワークに入り、サブネットに構成された Cloud NAT を使用して公共のインターネットに送信されます。
Google Cloud API
(標準、VPC Service Controls なし)
いいえ Cloud DNS ピアリングを必要とせずに、ゲートウェイ プロキシで標準のパブリック再帰 DNS を使用して解決します。 トラフィックはネットワーク アタッチメントを介して VPC ネットワークに入り、サブネットで有効になっている限定公開の Google アクセスを使用して、Cloud NAT や DNS ピアリングを使用せずにプライベートにルーティングされます。
Google Cloud API
(VPC Service Controls を使用)
はい(googleapis.com. の場合) 限定公開の Cloud DNS ゾーンを使用して、制限付き Google API 範囲(199.36.153.4/30)または内部 Private Service Connect エンドポイントに解決されます。 トラフィックは、ネットワーク アタッチメントを介して VPC ネットワークに入り、VPC Service Controls の境界セキュリティ ルールを適用します1。

1 リクエストが VPC Service Controls 違反(compute.googleapis.com の NETWORK_NOT_IN_SAME_SERVICE_PERIMETER や SECURITY_POLICY_VIOLATED、ホスト プロジェクトを参照する dns.googleapis.com など)で失敗する場合は、ホスト プロジェクトがゲートウェイ プロジェクトと同じ境界内にあることを確認します。

TLS 証明書の要件

HTTPS 経由で下り(外向き)トラフィックをルーティングする場合、Agent Gateway は TLS handshake 中に宛先サーバーの TLS 証明書チェーンを検証します。HTTPS 接続の証明書要件は、ターゲット エンドポイントが公的に信頼できる認証局(CA)を使用しているか、プライベート / 自己署名 CA を使用しているかによって異なります。

  • パブリック CA: デフォルトでは、Agent Gateway は、標準のサーバー証明書の要件(ターゲット ホスト名に一致するサブジェクト代替名(SAN)を含む)を満たす公的に信頼されている認証局(CA)によって発行された証明書を信頼します。

  • プライベート CA と自己署名証明書: ターゲットの宛先(VPC ネットワーク内のエージェント、ツール、MCP サーバー)がプライベート CA または内部 PKI を使用している場合は、接続テンプレートの tlsConfig 設定を使用してカスタム トラスト アンカーを構成できます。

    Certificate Manager の TrustConfig リソースを参照することで、特定のプライベート CA のみを信頼するように Agent Gateway を構成したり、プライベート ルート CA と公的に信頼されている CA(PUBLICLY_TRUSTED_ROOTS)を組み合わせたりできます。これにより、パブリック エンドポイントとプライベート エンドポイントの両方に対する信頼が確立されます。

    エージェントが Google Cloud API(*.googleapis.com)または他のパブリック HTTPS エンドポイントに接続する場合は、additionalRoots を PUBLICLY_TRUSTED_ROOTS に設定する必要があります。この設定がないと、Agent Gateway は googleapis.com の Google 署名付き証明書を信頼しません。

    tlsConfig を使用する場合は、次の制限事項に注意してください。

    • trustConfig を使用して、プライベート CA を使用する宛先にトラフィックをルーティングする場合は、PEM ファイルを手動でローテーションする必要があります。Google Cloudの Secret Manager などのシークレット マネージャーを使用した PEM ファイルの自動ローテーションはサポートされていません。
    • trustConfig フィールドは、接続テンプレートで構成されると変更できません。Agent Gateway は、接続された接続テンプレートの tlsConfig に加えられた変更(additionalRoots の更新など)を自動的に取得しません。TLS 設定の更新手順については、VPC 下り(外向き)設定の更新をご覧ください。

Agent Gateway が証明書チェーンを検証できない場合、接続は失敗します。

必要なロールと権限

Agent Gateway の VPC 接続性を構成するには、プロビジョニングに使用される ID とゲートウェイ サービス エージェントに必要なロールが付与されていることを確認します。

スタンドアロン プロジェクトのデプロイ

ゲートウェイ、ネットワーク アタッチメント、VPC ネットワークが同じプロジェクトに存在するスタンドアロン プロジェクトでは、標準の Agent Gateway 権限が適用されます。詳細については、必要な権限をご覧ください。

ネットワーク アタッチメントを構成する場合、ゲートウェイまたはエージェント接続テンプレートを作成または更新する ID(ユーザー アカウントまたはデプロイ サービス アカウント)には、ネットワーク アタッチメントに対する compute.networkAttachments.use 権限も必要です。たとえば、ネットワーク アタッチメントを含むプロジェクトに対する Compute ネットワーク管理者ロール(roles/compute.networkAdmin)を介して付与されます。Compute ネットワーク ユーザーでは不十分です。この権限がないと、リクエストは失敗し、ネットワーク アタッチメントの名前を示す PERMISSION_DENIED エラーが発生します。

また、DNS ピアリングを構成すると、Agent Gateway は Agent Gateway サービス エージェント(service-AGENT_GATEWAY_PROJECT_NUMBER@gcp-sa-agentgateway.iam.gserviceaccount.com)を使用して DNS ピアリング構成(およびネットワーク アタッチメントとそのサブネットワーク)を検証します。ターゲット VPC ネットワーク、ネットワーク アタッチメント、プライベート DNS ゾーンを含むプロジェクト(スタンドアロン デプロイの独自のプロジェクト)で、サービス エージェントに次のロールを付与します。

  • Compute ネットワーク閲覧者(roles/compute.networkViewer)
  • DNS 読み取り(roles/dns.reader)

これらのロールは自動的には付与されません。DNS ピアリングを使用しないネットワーク アタッチメントのみの場合は、これらは必要ありません。

これらのロールがない場合、DNS ピアリングを構成するゲートウェイまたはエージェント接続テンプレートを作成または更新すると、サービス エージェントと不足しているロールを示す INVALID_ARGUMENT エラーで検証が失敗します。

共有 VPC またはプロジェクト間のデプロイ

共有 VPC のデプロイでは、サービス プロジェクトまたはホスト プロジェクトのいずれかに Agent Gateway をプロビジョニングできます。ホスト プロジェクト(共有 VPC ネットワーク、サブネット、ネットワーク アタッチメントも存在する)でゲートウェイをプロビジョニングする場合は、スタンドアロン プロジェクトの権限が適用されます。

ターゲット VPC ネットワーク、ネットワーク アタッチメント、またはプライベート DNS ゾーンがホスト プロジェクト(TARGET_VPC_PROJECT_ID)に存在する間に、サービス プロジェクトで Agent Gateway をプロビジョニングすると、サービス プロジェクトの ID には、ホスト プロジェクトのネットワーク リソースと DNS リソースの検証、接続、ピアリングを行う権限が自動的に付与されません。標準の Agent Gateway 権限に加えて、ホスト プロジェクトに次のロールを付与します。

表: 共有 VPC とプロジェクト間のデプロイに必要な権限
プリンシパルまたは ID プロジェクトに付与する 必要な IAM ロール 目的
プロビジョニング ID1
(ユーザー アカウントまたはデプロイ サービス アカウント)
ホスト プロジェクト(TARGET_VPC_PROJECT_ID)
  • Compute ネットワーク閲覧者(roles/compute.networkViewer)
  • DNS 読み取り(roles/dns.reader)
  • ネットワーク接続リージョン エンドポイント管理者(roles/networkconnectivity.regionalEndpointAdmin)
  • ネットワーク接続コンシューマー ネットワーク管理者(roles/networkconnectivity.consumerNetworkAdmin)
  • ネットワーク アタッチメントを含むプロジェクトに対する Compute ネットワーク管理者(roles/compute.networkAdmin)(compute.networkAttachments.use 権限用)
プロビジョニング ID が、ホスト プロジェクト ネットワークとプライベート DNS リソース( Google Cloud コンソールなど)を表示し、リージョン エンドポイントを管理して、ネットワーク アタッチメントを使用できるようにします。ゲートウェイの作成または更新時に、プロビジョニング ID ではなく、Agent Gateway サービス エージェントがターゲット VPC ネットワーク、サブネット、ネットワーク アタッチメント、プライベート DNS ゾーンを検証します。
ネットワーク アタッチメント作成者
(PSC アタッチメントを作成する管理者)
ホスト プロジェクト(TARGET_VPC_PROJECT_ID)
  • Compute ネットワーク ユーザー(roles/compute.networkUser)
ホスト プロジェクトで共有 VPC サブネットを使用して、Private Service Connect ネットワーク アタッチメントを作成できます。
サービス プロジェクトのネットワーク アタッチメント(推奨)
Agent Gateway サービス エージェント2 ホスト プロジェクト(TARGET_VPC_PROJECT_ID)
  • Compute ネットワーク ユーザー(roles/compute.networkUser)
  • Compute ネットワーク閲覧者(roles/compute.networkViewer)
  • DNS 読み取り(roles/dns.reader)
  • DNS ピアリング(roles/dns.peer)
Agent Gateway サービス エージェントが、ネットワーク アタッチメントにホスト プロジェクトのサブネットを使用し、Private Service Connect インターフェースを接続して下り(外向き)トラフィックをルーティングし、ホスト プロジェクトのプライベート Cloud DNS ゾーンとピアリングできるようにします。また、サービス エージェントが、ゲートウェイの作成または更新時に、ターゲット VPC ネットワーク、サブネット、プライベート DNS ゾーンを検証できるようにします。
Agent Gateway サービス エージェント2 サービス プロジェクト(AGENT_GATEWAY_PROJECT_ID)
  • Compute ネットワーク閲覧者(roles/compute.networkViewer)
ゲートウェイの作成または更新時に DNS ピアリング構成を検証するときに、サービス プロジェクトにあるネットワーク アタッチメントをサービス エージェントが読み取れるようにします。サービス エージェントのデフォルト ロールに compute.networkAttachments.get が含まれていません。
ホスト プロジェクトのネットワーク アタッチメント
Agent Gateway サービス エージェント2 ホスト プロジェクト(TARGET_VPC_PROJECT_ID)
  • Compute ネットワーク管理者(roles/compute.networkAdmin)、または次の権限を持つカスタムロール。
    • compute.networkAttachments.get
    • compute.networkAttachments.update
    • compute.regionOperations.get
  • Compute ネットワーク閲覧者(roles/compute.networkViewer)
  • DNS 読み取り(roles/dns.reader)
  • DNS ピアリング(roles/dns.peer)
Agent Gateway サービス エージェントがホスト プロジェクトのネットワーク アタッチメントを更新して、Agent Gateway テナント プロジェクトからの接続を許可し、下り(外向き)トラフィックをルーティングして、ホスト プロジェクトのプライベート Cloud DNS ゾーンとピアリングできるようにします。また、サービス エージェントがゲートウェイの作成または更新時に、ターゲット VPC ネットワーク、サブネット、ネットワーク アタッチメント、プライベート DNS ゾーンを検証できるようにします。

1 プロビジョニング ID の場合、ホスト プロジェクトの閲覧者(roles/viewer)や編集者(roles/editor)などの基本的なプロジェクト レベルのロールでも十分です。

2 Agent Gateway サービス エージェントの形式は service-AGENT_GATEWAY_PROJECT_NUMBER@gcp-sa-agentgateway.iam.gserviceaccount.com です。ここで、AGENT_GATEWAY_PROJECT_NUMBER は Agent Gateway をプロビジョニングするプロジェクトのプロジェクト番号です。共有 VPC デプロイの場合、このプロジェクトはサービス プロジェクトまたはホスト プロジェクトのいずれかになります。

複数の Agent Runtime サービス プロジェクトを Agent Gateway ホスト プロジェクトに接続する場合は、各 Agent Runtime サービス エージェントにゲートウェイ プロジェクトへのクロス プロジェクト アクセス権も付与する必要があります。大規模なデプロイについては、Google グループを使用して Agent Runtime サービス プロジェクトをスケーリングするをご覧ください。

VPC 接続を構成する

接続テンプレートを使用して Agent Gateway をデプロイするには、次のセクションの手順を完了します。

Private Service Connect ネットワーク アタッチメントを作成する

ターゲット VPC ネットワークに Private Service Connect ネットワーク アタッチメントを作成します。

ネットワーク アタッチメントが次の要件を満たしていることを確認します。

  • 接続の設定: 接続を自動的に受け入れる(--connection-preference=ACCEPT_AUTOMATIC)ようにネットワーク アタッチメントを構成します。
  • 同じ VPC ネットワークの要件: ネットワーク アタッチメント サブネットと DNS ピアリング(targetNetwork)用に構成されたターゲット ネットワークは、まったく同じ VPC ネットワーク内にある必要があります。ネットワーク アタッチメントのサブネットが DNS ピアリング ターゲット ネットワークとは異なるネットワークに属している場合、構成の検証は失敗します。
  • VPC ネットワーク MTU のサポート: Agent Gateway は、ネットワーク アタッチメントのサブネットを含む VPC ネットワークに対して、最大 1,500 バイトの最大伝送単位(MTU)をサポートしています。その VPC ネットワークでジャンボ フレームなどのより大きな MTU が使用されている場合は、Cloud カスタマーケアに連絡して、Agent Gateway プロデューサー サービスをカスタム VPC MTU に合わせてください。
  • サブネットの要件: ネットワーク アタッチメント サブネットの次の要件に注意してください。
    • サブネット範囲: ネットワーク アタッチメント サブネットは、すべての有効な範囲をサポートしています。
    • サブネット サイズ: Agent Gateway には、ネットワーク アタッチメントに最小 /28 サブネットが必要です。/28 サブネットには 12 個の使用可能な IP アドレスがあり、1 つの Agent Gateway インスタンスには十分です。複数のゲートウェイを同じネットワーク アタッチメントまたはサブネットに接続する場合は、IP アドレスの枯渇を回避するために、より大きなサブネット(/26 や /24 など)を使用します。
    • プライベート Google アクセスの要件: ネットワーク アタッチメントをホストするサブネットでプライベート Google アクセス(private_ip_google_access = true)を有効にする必要があります。
  • 共有 VPC のデプロイ: 共有 VPC のデプロイについては、共有 VPC のデプロイ トポロジをご覧ください。

ネットワーク アタッチメントの完全なリソース URI(projects/NETWORK_ATTACHMENT_PROJECT_NUMBER/regions/NETWORK_ATTACHMENT_REGION/networkAttachments/NETWORK_ATTACHMENT_NAME など)をメモします。これは、後の手順で接続テンプレート リソースを作成するときに必要になります。

省略可: DNS ピアリングを設定する

DNS ピアリングにより、Agent Gateway は VPC ネットワークの Cloud DNS 限定公開マネージド ゾーンのレコードを使用して DNS 名を解決できます。DNS ピアリングは、エージェントがプライベート内部ドメイン名(corp.internal. など)を解決する必要がある場合、または Google API(googleapis.com.)に VPC Service Controls を適用する必要がある場合にのみ必要です。パブリック インターネット ドメインや、VPC Service Controls を使用しない標準の Google API には必要ありません。

Agent Gateway は、単一の推移的ホップ(最大 3 つの VPC ネットワーク)まで推移的 DNS ピアリングをサポートします。たとえば、vpc-net-a( Agent Gateway テナント ネットワーク)は vpc-net-b(接続された ネットワーク)とピアリングできます。は vpc-net-c(リモート ネットワーク)とピアリングして、チェーン全体で DNS クエリを解決します。

DNS ピアリングを設定する手順は次のとおりです。

  1. ターゲット VPC ネットワークでプライベート DNS ゾーンを設定します。プライベート DNS ゾーンに DNS レコードを追加するには、リソース レコードセットを追加するをご覧ください。

  2. ピアリングを有効にする接続テンプレートを構成するために、次の情報を収集します。

    • ターゲット ネットワーク URI(targetNetwork): ターゲット VPC ネットワークの完全なリソース URI を projects/TARGET_VPC_PROJECT_ID/global/networks/TARGET_VPC_NETWORK_NAME の形式でメモします。ターゲット ネットワークは常に、ネットワーク アタッチメントによって参照されるサブネットを含む VPC ネットワークです。ターゲット ネットワークが共有 VPC ネットワークの場合は、対応する共有 VPC ホスト プロジェクト ID を使用してください。

    • ドメイン名: DNS ピアリングの 1 つ以上のドメイン サフィックス。各ドメインの末尾はドット(.)にする必要があります(例: corp.internal.、googleapis.com.)。

      domains フィールドの構成方法に関するその他のガイダンスについては、DNS ピアリング ドメインのパターンをご覧ください。共有 VPC などのプロジェクト間のデプロイについては、プロジェクト間の DNS ゾーンとピアリングの要件をご覧ください。

省略可: TLS 信頼構成を設定する

ターゲットの宛先がプライベート CA または自己署名証明書を使用している場合は、Certificate Manager で TrustConfig リソースを作成する必要があります。TrustConfig リソースは、Agent Gateway が TLS 接続の検証に使用するトラスト アンカーと証明書を定義します。

  1. PEM 形式の証明書ファイルを準備します。

    • トラストストア: PEM 形式のルート CA 証明書または中間 CA 証明書。Agent Gateway は、信頼チェーンがこれらの CA 証明書のいずれかにつながるサーバー証明書を信頼します。トラストストアには、少なくとも 1 つのルート CA 証明書または中間 CA 証明書が含まれている必要があります。
    • 許可リストに登録済みの証明書(省略可): 明示的に信頼する PEM 形式のサーバー証明書(自己署名証明書など)。
  2. 次のコマンドを実行して TrustConfig リソースを作成します。TrustConfig は、Agent Gateway と接続テンプレートと同じプロジェクトとリージョンに作成する必要があります。

    gcloud certificate-manager trust-configs create TRUST_CONFIG_NAME \
        --location=LOCATION \
        --trust-store="trust-anchors=ROOT_CERT_FILE" \
        --allowlisted-certificates=ALLOWLISTED_CERT_FILE
    

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

    • TRUST_CONFIG_NAME: TrustConfig リソースの名前。
    • LOCATION: 信頼構成のリージョン(例: europe-west1)。これは、Agent Gateway および接続テンプレートと同じリージョンにする必要があります。
    • ROOT_CERT_FILE: PEM エンコードされたルートまたは中間 CA 証明書のパス。
    • ALLOWLISTED_CERT_FILE:(省略可)明示的に信頼する PEM エンコード証明書のパス。許可リストに登録済みの証明書を使用していない場合は、このフラグを省略します。

    信頼構成の管理の詳細については、信頼構成を作成して管理するをご覧ください。

Agent Gateway をデプロイする

  1. 接続テンプレートの構成ファイルを作成します。

    agw-connectivity-template.yaml という名前の YAML ファイルを作成します。

    name: projects/AGENT_GATEWAY_PROJECT_NUMBER/locations/LOCATION/agentConnectivityTemplates/CONNECTIVITY_TEMPLATE_NAME
    accessPath: AGENT_TO_ANYWHERE
    deploymentModel: CENTRALIZED
    egressNetworkConfig:
      networkAttachment: projects/NETWORK_ATTACHMENT_PROJECT_NUMBER/regions/NETWORK_ATTACHMENT_REGION/networkAttachments/NETWORK_ATTACHMENT_NAME
      dnsPeeringConfig:
        domains:
          - DOMAIN_NAME
        targetNetwork: projects/TARGET_VPC_PROJECT_ID/global/networks/TARGET_VPC_NETWORK_NAME
      vpcEgress: VPC_EGRESS_MODE
      tlsConfig:
        trustConfig: projects/AGENT_GATEWAY_PROJECT_NUMBER/locations/LOCATION/trustConfigs/TRUST_CONFIG_NAME
        additionalRoots: ADDITIONAL_ROOTS_OPTION
    

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

    • AGENT_GATEWAY_PROJECT_NUMBER: Agent Gateway をプロビジョニングする Google Cloud プロジェクトのプロジェクト番号。プロジェクト番号を取得するには、gcloud projects describe PROJECT_ID --format="value(projectNumber)" を実行します。

    • LOCATION: 接続テンプレートのリージョン(例: europe-west1)。

    • CONNECTIVITY_TEMPLATE_NAME: 接続テンプレート リソースの名前。

    • accessPath: 接続テンプレートの管理されたアクセスパス。AGENT_TO_ANYWHERE に設定します(接続テンプレートは、下り(外向き)ゲートウェイでのみサポートされます)。

    • deploymentModel: ゲートウェイのデプロイモデル。CENTRALIZED に設定します。

    • networkAttachment: Private Service Connect ネットワーク アタッチメントの完全なリソース URI。

      • NETWORK_ATTACHMENT_PROJECT_NUMBER: ネットワーク アタッチメントを作成したプロジェクトのプロジェクト番号。このプロジェクトは、Agent Gateway プロジェクトと同じにすることも、共有 VPC サービス プロジェクトに Agent Gateway をプロビジョニングして共有 VPC ホスト プロジェクトにネットワーク アタッチメントを作成する場合は、別のプロジェクトにすることもできます。
      • NETWORK_ATTACHMENT_REGION: ネットワーク アタッチメントを含むリージョン。
      • NETWORK_ATTACHMENT_NAME: ネットワーク アタッチメント名。
    • DOMAIN_NAME: (省略可)DNS ピアリングの 1 つ以上のドメイン サフィックス(例: corp.internal.、googleapis.com.、.)。ピアリングするドメイン サフィックスごとに、domains の下にリスト項目を追加します。各値の末尾はドット(.)にする必要があります。また、ターゲット ネットワークに対して承認された、対応する Cloud DNS 限定公開マネージド ゾーンが必要です。

      domains フィールドの構成方法に関するその他のガイダンスについては、DNS ピアリング ドメインのパターンをご覧ください。

    • targetNetwork:(省略可)DNS ピアリングのターゲット VPC ネットワークの完全なリソース URI。ターゲット ネットワークは、常にネットワーク アタッチメントによって参照されるサブネットを含む VPC ネットワークです。

      • TARGET_VPC_PROJECT_ID: ターゲット VPC ネットワークを所有するプロジェクトのプロジェクト ID。ネットワーク アタッチメントによって参照されるサブネットを含むネットワークが共有 VPC ネットワークの場合、TARGET_VPC_PROJECT_ID は共有 VPC ホスト プロジェクト ID です。targetNetwork は、プロジェクト番号ではなくプロジェクト ID を使用して指定してください。
      • TARGET_VPC_NETWORK_NAME: ターゲット VPC ネットワークの名前。
    • VPC_EGRESS_MODE: 下り(外向き)ルーティング モードを設定します。PRIVATE_RANGES_ONLY または ALL_TRAFFIC のいずれかに設定します。

    • tlsConfig:(省略可)HTTPS 経由でプライベート エンドポイントに接続するときにサーバー証明書を検証するための TLS 構成。

      • TRUST_CONFIG_NAME: プライベート CA 証明書またはトラスト アンカーを含む Certificate Manager TrustConfig リソースの名前。
      • ADDITIONAL_ROOTS_OPTION: カスタム信頼構成に加えて、一般に信頼されている CA ルートを信頼するかどうかを指定します。
      • PUBLICLY_TRUSTED_ROOTS(デフォルト)に設定すると、trustConfig パラメータによって検証された証明書と、公的に信頼されているすべての CA の両方が信頼されます。エージェントがGoogle Cloud API(*.googleapis.com)または他のパブリック HTTPS エンドポイントにも接続する場合は、additionalRoots を PUBLICLY_TRUSTED_ROOTS に設定する必要があります。この設定を行わないと、Agent Gateway は googleapis.com の Google 署名付き証明書を信頼しません。
      • trustConfig パラメータで検証された証明書のみを信頼するには、NO_ADDITIONAL_ROOTS に設定します。
  2. 接続テンプレートを作成する:

    次のコマンドを実行して、接続テンプレートを作成します。

    gcloud network-services agent-connectivity-templates import CONNECTIVITY_TEMPLATE_NAME \
        --source="agw-connectivity-template.yaml" \
        --location=LOCATION
    

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

    • CONNECTIVITY_TEMPLATE_NAME: 接続テンプレート リソースの名前。
    • LOCATION: 接続テンプレート リソースを作成するロケーション。例: europe-west1
  3. Agent Gateway リソースを定義する:

    接続テンプレートを参照するゲートウェイ YAML 構成ファイル(my-agent-gateway-vpc-egress.yaml など)を作成して、AGENT_TO_ANYWHERE モードで新しい Agent Gateway リソースを定義します。

    name: AGENT_GATEWAY_NAME
    protocols:
      - MCP
    googleManaged:
      governedAccessPath: AGENT_TO_ANYWHERE
    agentConnectivityTemplate: projects/AGENT_GATEWAY_PROJECT_NUMBER/locations/LOCATION/agentConnectivityTemplates/CONNECTIVITY_TEMPLATE_NAME
    registries:
      - AGENT_REGISTRY_PATH
    

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

    • AGENT_GATEWAY_NAME: Agent Gateway リソースの名前。

    • AGENT_GATEWAY_PROJECT_NUMBER: Agent Gateway と接続テンプレートをプロビジョニングする Google Cloud プロジェクトのプロジェクト番号。共有 VPC デプロイの場合、このプロジェクトはサービス プロジェクトまたはホスト プロジェクトのいずれかになります。プロジェクト番号を取得するには、gcloud projects describe PROJECT_ID --format="value(projectNumber)" を実行します。

    • LOCATION: 接続テンプレートのロケーション(例: europe-west1)。

    • CONNECTIVITY_TEMPLATE_NAME: 接続テンプレート リソースの名前。

      • AGENT_REGISTRY_PATH: ゲートウェイと同じプロジェクトとリージョンにあるリージョン Agent Registry インスタンスへのパス。//agentregistry.googleapis.com/projects/PROJECT_ID/locations/LOCATION の形式で指定します。ガイダンスについては、Agent Gateway のデプロイを計画するをご覧ください。
  4. Agent Gateway をインポートしてデプロイする:

    次のコマンドを実行して、YAML 仕様に基づいて Agent Gateway リソースを作成します。

    gcloud network-services agent-gateways import AGENT_GATEWAY_NAME \
        --source="my-agent-gateway-vpc-egress.yaml" \
        --location=LOCATION
    

    LOCATION は、Agent Gateway リソースを作成するロケーションに置き換えます。例: europe-west1

アーキテクチャとネットワーキングに関する考慮事項

このセクションでは、VPC 接続を使用して Agent Gateway をデプロイするためのアーキテクチャ ガイダンスと高度なネットワーキング パターンについて説明します。

VPC 下り(外向き)設定を更新する

接続テンプレートは、Agent Gateway によって参照されている間はインプレースで変更できません。また、Agent Gateway は、アタッチされた接続テンプレートに加えられた変更を自動的に取得しません。

  • DNS ピアリング、VPC 下り(外向き)モード、TLS 設定(tlsConfig)の更新: 接続テンプレートでは、tlsConfig.trustConfig フィールドは構成後に変更できません。tlsConfig のインプレース更新(additionalRoots の追加や変更など)は、接続された Agent Gateway によって取得されません。既存のゲートウェイで DNS ピアリング構成、VPC 下り(外向き)モード、または tlsConfig 設定を更新するには、更新された設定で同じ networkAttachment を使用する新しい接続テンプレートを作成し、新しいテンプレートを参照するように Agent Gateway を更新します(または、接続テンプレートのバインドを解除して再バインドします)。

  • ネットワーク アタッチメントの変更: networkAttachment 自体は、接続テンプレートと Agent Gateway の両方で構成されると変更できません。別のネットワーク アタッチメント(またはターゲット VPC ネットワーク)に切り替えるには、新しい接続テンプレートと新しい Agent Gateway を作成する必要があります。

共有 VPC のデプロイ トポロジ

共有 VPC アーキテクチャでは、サービス プロジェクトまたはホスト プロジェクトのいずれかに Agent Gateway をプロビジョニングできます。サービス プロジェクトで Agent Gateway をプロビジョニングする場合は、サービス プロジェクト(推奨)またはホスト プロジェクトのいずれかでネットワーク アタッチメントを作成できます。

VPC Service Controls 準拠

エージェント通信に VPC Service Controls の境界を適用するには、次のことを確認します。

  • 接続テンプレートで vpcEgress を ALL_TRAFFIC に設定します。

  • Google API リクエストを restricted.googleapis.com IP 範囲(199.36.153.4/30)または Google API の内部 Private Service Connect エンドポイントに転送します。

  • googleapis.com の DNS の解決を構成します。*.googleapis.com を restricted.googleapis.com にマッピングするプライベート Cloud DNS ゾーンを VPC ネットワークに作成し、接続テンプレートの domains フィールドに googleapis.com. を含めます。

    DNS 構成の詳細については、限定公開の Google アクセスのドキュメントの googleapis.com の DNS を構成するをご覧ください。

  • 共有 VPC デプロイの場合、ネットワーク アタッチメントのサブネットと dnsPeeringConfig.targetNetwork を所有するホスト プロジェクトは、Agent Gateway をデプロイするプロジェクトと同じサービス境界に存在する必要があります。これは、サービス プロジェクトにネットワーク アタッチメントを作成する場合にも当てはまります。サブネットと VPC ネットワークはホスト プロジェクトに属しているためです。プライベート DNS ゾーンが別の DNS プロジェクトでホストされている場合は、そのプロジェクトも境界に含めます。

DNS ピアリング ドメインのパターン

このセクションでは、接続テンプレートで domains フィールドを構成するためのドメイン解決パターンとオプションについて説明します。

ドメイン名の構成: 次の考慮事項に基づいて、接続テンプレートの domains フィールドを構成します。

  • プライベート内部ドメイン: VPC ネットワークでホストされているプライベート内部サービス(service.corp.internal など)を解決するには、内部ドメインのサフィックス(corp.internal. など)を指定します。このドメインの完全一致のプライベート Cloud DNS マネージド ゾーンは、ターゲット VPC ネットワークに対して認可されている必要があります。

  • スプリット ホライズン DNS(RFC 1918 IP を使用するパブリック ドメイン): パブリック DNS ゾーンを使用して、内部プライベート IP を指すレコード(Certificate Manager のパブリック証明書の RFC 1918 アドレスに解決される mcp.example.com など)をホストする場合、ゲートウェイは DNS ピアリングを必要とせずに、パブリック再帰 DNS を使用してこれらのレコードを自動的に解決します。

  • Google Cloud VPC Service Controls を使用する API: VPC Service Controls を適用するように ALL_TRAFFIC が構成されている場合、Google API リクエストは restricted.googleapis.com IP 範囲(199.36.153.4/30)または内部 PSC エンドポイントに解決される必要があります。*.googleapis.com を restricted.googleapis.com にマッピングするプライベート Cloud DNS ゾーンを VPC ネットワークに作成し、接続テンプレートの domains フィールドに googleapis.com. を含めます。

  • マルチドメイン解決パターン: デプロイで複数のプライベート ドメイン サフィックスを解決する必要がある場合は、次のいずれかのパターンを選択します。

    • 複数の個別のドメインをピアリングする: dnsPeeringConfig の domains フィールドにドメイン サフィックスのリストを指定します(例: corp.internal.、prod.internal.、googleapis.com.)。リスト内の各ドメインは、末尾のドット(.)で終わり、ターゲット VPC ネットワークに対して承認された対応する限定公開 Cloud DNS マネージド ゾーンが必要です。
    • 統合された親サフィックス(推奨): 内部サービスを共有の親ドメイン サフィックス(*.internal. や *.corp.internal. など)に統合し、その親ドメインを domains リストに含めます。
    • 限定公開転送ゾーンを使用したキャッチオール ルート ピアリング: 接続テンプレートの domains フィールドに "." を含め、アップストリームの再帰リゾルバ(8.8.8.8 や内部エンタープライズ リゾルバなど)を指す VPC ネットワーク内のルートドメイン(.)に Cloud DNS の限定公開転送ゾーンを構成します。VPC 内のより限定的な限定公開ゾーンは、最長サフィックス マッチングによって最初に一致しますが、一致しない一般公開クエリはアップストリーム フォワーダーを介して解決されます。

プロジェクト間の DNS ゾーンとピアリングの要件

接続テンプレートの dnsPeeringConfig 設定は、プロジェクト間の直接 Cloud DNS ピアリングをサポートしていません。接続テンプレートをインポートするときに、networkAttachment で参照されているサブネットが targetNetwork とは異なる VPC ネットワークに属している場合、またはサービス プロジェクトまたは外部プロジェクトからのプロジェクト間の DNS ゾーン バインディングに依存している場合、検証は失敗します。

ドメインのマネージド ゾーンは、targetNetwork を所有するホスト プロジェクトに作成する必要があります。マネージド ゾーンは、次のいずれかのゾーンタイプにできます。

  • 権威限定公開ゾーン
  • 転送ゾーン
  • Cloud DNS ピアリング ゾーン: ホスト プロジェクトの VPC ネットワークに関連付け、宛先 VPC ネットワークをターゲットにする必要があります。宛先 VPC は、権威限定公開ゾーンを使用してクエリを直接解決する必要があります。クエリを別の DNS ピアリング ゾーンに転送する(チェーンする)ことはサポートされていません。転送すると、NXDOMAIN エラーが発生します。

Google グループを使用して Agent Runtime サービス プロジェクトをスケーリングする

複数の Agent Runtime サービス プロジェクトを Agent Gateway ホスト プロジェクトに接続し、各サービス エージェントにプロジェクト間のアクセス権を個別に付与する場合は、プロジェクトを追加するたびにホスト プロジェクトの IAM ポリシーを更新する必要があります。大規模なデプロイでは、ロール バインディングを追加すると IAM ポリシーの上限に達する可能性もあります。

新しいサービス プロジェクトごとにホスト プロジェクトの IAM ポリシーを更新する代わりに、1 つの Google セキュリティ グループを介してアクセスを管理できます。

  1. セキュリティ グループを作成する: Google 管理コンソールで、または gcloud identity groups create コマンドを実行して、セキュリティ グループを作成します。

  2. グループに Agent Gateway ホスト プロジェクトへのアクセス権を付与する: グループを AGENT_GATEWAY_PROJECT_ID のネットワーク サービス閲覧者ロール(roles/networkservices.viewer)にバインドします。

    gcloud projects add-iam-policy-binding AGENT_GATEWAY_PROJECT_ID \
        --member="group:GROUP_EMAIL" \
        --role="roles/networkservices.viewer"
    

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

    • AGENT_GATEWAY_PROJECT_ID: Agent Gateway ホスト プロジェクトのプロジェクト ID。
    • GROUP_EMAIL: セキュリティ グループのメールアドレス(例: agw-cross-project-runtime@example.com)。
  3. 各サービス プロジェクトの Agent Runtime サービス エージェントをグループに追加する: 各 Agent Runtime サービス プロジェクトで、次のように gcloud identity groups memberships add コマンドを実行して、サービス エージェントをセキュリティ グループに追加します。

    gcloud identity groups memberships add \
        --group-email="GROUP_EMAIL" \
        --member-email="service-AGENT_RUNTIME_PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com"
    

    AGENT_RUNTIME_PROJECT_NUMBER は、Agent Runtime サービス プロジェクトのプロジェクト番号に置き換えます。

次のステップ

ガイド

Agent Gateway を介して Agent Runtime トラフィックをルーティングし、安全で管理された接続を実現する方法について説明します。

Codelab

Gemini Enterprise Agent Platform の Agent Gateway でエージェント ワークロードを管理する方法について説明します。

Codelab

VPC ネットワーク内の宛先にアクセスする AI エージェントの Agent Gateway 下り(外向き)ガバナンスについて説明します。

ガイド

Agent Gateway の認可を IAP、Model Armor、または独自のカスタム認可サービスに委任する方法について説明します。

ガイド

Agent Gateway リソースを表示、更新、関連付け解除、削除する方法について説明します。

ガイド

Agent Gateway をモニタリングする方法について説明します。

ガイド

Gemini Enterprise トラフィックを Agent Gateway 経由でルーティングする方法について説明します。