KI-Agenten-Gateway mit VPC-Verbindung einrichten

In diesem Dokument wird beschrieben, wie Sie die VPC-Konnektivität beim Bereitstellen eines Agent Gateways konfigurieren, damit es privat mit einem VPC-Netzwerk in Ihrer Organisation kommunizieren kann.

Wenn Sie eine VPC-Verbindung einrichten, können Sie Folgendes tun:

  • Ausgehenden VPC-Traffic erzwingen: Leiten Sie Traffic, der von Ihren Agents stammt, über Ihren Private Service Connect-Netzwerkanhang im Modus PRIVATE_RANGES_ONLY oder ALL_TRAFFIC in Ihr VPC-Netzwerk weiter.
  • Statischer Quell-IP-Adressbereich: Ausgehender Traffic verwendet den privaten IP-Adressbereich des Subnetzes Ihres Private Service Connect-Netzwerkanhangs als Quell-IP-Adresse. Mit diesem statischen Quell-IP-Bereich können Sie Firewallrichtlinien für Ihr VPC-Netzwerk konfigurieren, um den Traffic vom Gateway zu steuern.
  • Benutzerdefinierte DNS-Auflösung: Interne private Domainnamen und externe Domainnamen können direkt von Ihren Agents mithilfe von Cloud DNS-Peering aufgelöst werden.
  • Perimetersicherheit: Schützen Sie die Agent-Kommunikation mit VPC Service Controls-Dienstperimetern.
  • Validierung privater oder selbst signierter Zertifikate: Verbindungen zu Zielen herstellen, die private Zertifizierungsstellen oder selbst signierte Zertifikate verwenden.

Zum Konfigurieren der VPC-Konnektivität erstellen Sie eine Konnektivitätsvorlage für das Agent Gateway (AgentConnectivityTemplate), in der Sie die Einstellungen für ausgehenden Netzwerktraffic für Ihre Agent Gateway-Instanzen definieren und verwalten.

So funktioniert die VPC-Konnektivität

Wenn Sie ein Agent-Gateway mit einer Konnektivitätsvorlage bereitstellen, verwendet das Gateway eine Private Service Connect-Schnittstelle, um ausgehenden Agent-Traffic an Ihr designiertes VPC-Netzwerk weiterzuleiten.

Modi für ausgehenden VPC-Traffic

Mit der Einstellung vpcEgress in Ihrer Konnektivitätsvorlage konfigurieren Sie, wie das Gateway Traffic über Ihren Netzwerkanhang weiterleitet.

  • Traffic an private IP-Adressbereiche (PRIVATE_RANGES_ONLY): Leitet Traffic, der nur für private IP-Adressbereiche bestimmt ist, in Ihr VPC-Netzwerk weiter. Ausgehender Traffic wird nur dann in Ihr VPC-Netzwerk weitergeleitet, wenn die Ziel-IP-Adresse in einen der folgenden Bereiche fällt:

    • RFC 1918: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
    • RFC 6598: 100.64.0.0/10
    • Klasse E: 240.0.0.0/4
    • private.googleapis.com: 199.36.153.8/30
    • restricted.googleapis.com: 199.36.153.4/30
    • PSC-Endpunkte für Google APIs: Wenn Sie einen benutzerdefinierten Private Service Connect-Endpunkt für Google APIs mit einer internen privaten IP-Adresse in Ihrem VPC-Netzwerk bereitstellen, wird der Traffic zu diesem Endpunkt über Ihr VPC-Netzwerk weitergeleitet. Achten Sie darauf, dass Cloud DNS-Peering in der Verbindungsvorlage konfiguriert ist, damit das Agent Gateway Google API-Domains korrekt in die IP-Adresse Ihres internen PSC-Endpunkts auflöst.

    Anfragen an standardmäßige öffentliche Google APIs werden automatisch über den privater Google-Zugriff verarbeitet. Internetgebundener Traffic wird direkt über das Agent Gateway und nicht über Ihr VPC-Netzwerk weitergeleitet.

  • Traffic zu allen IP-Adressbereichen (ALL_TRAFFIC): Leitet den gesamten ausgehenden Traffic, der von Ihren Agenten stammt, über Ihr VPC-Netzwerk weiter, einschließlich öffentlichem Internet, externen SaaS-APIs und Nicht-RFC-1918-Adressen.

    • Routing und Sicherheit: Da mit dieser Einstellung der gesamte ausgehende Traffic in Ihre VPC geleitet wird, sind Sie für die Verwaltung des Routings und der Sicherheit verantwortlich. Ihr VPC-Netzwerk muss eine Standardroute (0.0.0.0/0) haben, um diesen Traffic an Ihre ausgehenden Gateways oder Sicherheits-Appliances (z. B. Firewalls für den nächsten Hop oder Cloud Interconnect-Schnittstellen) weiterzuleiten.
    • Ausgehender Traffic über das öffentliche Internet: Das Agent Gateway sendet ausgehenden Traffic an Ihr VPC-Netzwerk, von wo aus er über ein Cloud NAT-Gateway im Subnetz des Private Service Connect-Netzwerkanhangs an das öffentliche Internet weitergeleitet wird. Wenn Sie dem Cloud NAT-Gateway statische externe IP-Adressen zuweisen, können Remote-Dienste den ausgehenden Traffic Ihrer Agents basierend auf diesen Quell-IP-Adressen zulassen.
    • VPC Service Controls: Der Modus für ausgehenden Traffic muss auf ALL_TRAFFIC festgelegt sein, um VPC Service Controls-Dienstperimeter zu unterstützen.

DNS-Auflösung und Traffic-Routing

Standardmäßig löst Agent Gateway Domainnamen mithilfe von öffentlichem rekursivem DNS auf. Wenn Ihre Agenten auf interne Arbeitslasten, private Tools oder Google APIs zugreifen müssen, die auf privaten Domainnamen in Ihrem VPC-Netzwerk gehostet werden (z. B. corp.internal. oder PSC-Endpunkte), können Sie Cloud DNS-Peering konfigurieren, um DNS-Abfragen an die privaten von Cloud DNS verwalteten Zonen Ihres Netzwerks weiterzuleiten.

In der folgenden Tabelle sind die Cloud DNS-Peering-Anforderungen und das Traffic-Routing-Verhalten für verschiedene Ziele zusammengefasst, wenn die VPC-Konnektivität im Modus ALL_TRAFFIC konfiguriert ist:

Tabelle: DNS-Auflösung und Traffic-Routing im Modus ALL_TRAFFIC
Traffic-Ziel Cloud DNS-Peering erforderlich? DNS-Auflösung Pfad für ausgehenden Traffic
Private IP-Dienste
(RFC 1918 / intern)		 Ja (z. B. corp.internal.) Wird mithilfe von Cloud DNS-Peering mit der privaten, von Cloud DNS verwalteten Zone Ihres Ziel-VPC-Netzwerk aufgelöst. Der Traffic gelangt über den Netzwerkanhang in Ihr VPC-Netzwerk, um eine Verbindung zu internen Arbeitslasten herzustellen.
Öffentliche Hostnamen mit privaten IP-Adressen
(Split-Horizon-DNS)		 Nein Die Auflösung erfolgt über das standardmäßige öffentliche rekursive DNS am Gateway-Proxy, ohne dass ein Cloud DNS-Peering erforderlich ist. Der Traffic gelangt über den Netzwerkanhang in Ihr VPC-Netzwerk, um eine Verbindung zu internen Arbeitslasten herzustellen.
Öffentliches Internet und SaaS-APIs
(Externe Domains)		 Nein Die Auflösung erfolgt über das standardmäßige öffentliche rekursive DNS am Gateway-Proxy, ohne dass ein Cloud DNS-Peering erforderlich ist. Der Traffic gelangt über den Netzwerkanhang in Ihr VPC-Netzwerk und wird über Cloud NAT, das im Subnetz konfiguriert ist, an das öffentliche Internet weitergeleitet.
Google Cloud APIs
(Standard, ohne VPC Service Controls)		 Nein Die Auflösung erfolgt über das standardmäßige öffentliche rekursive DNS am Gateway-Proxy, ohne dass ein Cloud DNS-Peering erforderlich ist. Der Traffic gelangt über den Netzwerkanhang in Ihr VPC-Netzwerk und wird privat über den im Subnetz aktivierten privater Google-Zugriff weitergeleitet, ohne Cloud NAT oder DNS-Peering zu verwenden.
Google Cloud APIs
(mit VPC Service Controls)		 Ja (für googleapis.com.) Wird über eine private Cloud DNS-Zone in den eingeschränkten Google API-Bereich (199.36.153.4/30) oder interne Private Service Connect-Endpunkte aufgelöst. Der Traffic gelangt über den Netzwerkanhang in Ihr VPC-Netzwerk, um die Sicherheitsregeln des VPC Service Controls-Perimeters durchzusetzen1.

1 Wenn Anfragen aufgrund von VPC Service Controls-Verstößen wie NETWORK_NOT_IN_SAME_SERVICE_PERIMETER oder SECURITY_POLICY_VIOLATED für compute.googleapis.com oder dns.googleapis.com, die auf das Hostprojekt verweisen, fehlschlagen, prüfen Sie, ob sich das Hostprojekt im selben Perimeter wie das Gateway-Projekt befindet.

Anforderungen an TLS-Zertifikate

Wenn ausgehender Traffic über HTTPS weitergeleitet wird, validiert das Agent-Gateway die TLS-Zertifikatskette des Zielservers während des TLS-Handshakes. Die Zertifikatsanforderungen für HTTPS-Verbindungen hängen davon ab, ob Ihre Zielendpunkte öffentlich vertrauenswürdige Zertifizierungsstellen (CAs) oder private/selbst signierte CAs verwenden.

  • Öffentliche Zertifizierungsstellen: Standardmäßig vertraut Agent Gateway Zertifikaten, die von öffentlich vertrauenswürdigen Zertifizierungsstellen ausgestellt wurden, die die standardmäßigen Anforderungen an Serverzertifikate erfüllen (einschließlich eines Subject Alternative Name (SAN), der mit dem Zielhostnamen übereinstimmt).

  • Private Zertifizierungsstellen und selbst signierte Zertifikate: Wenn Ihr Ziel (Agenten, Tools oder MCP-Server in Ihrem VPC-Netzwerk) eine private Zertifizierungsstelle oder eine interne PKI verwendet, können Sie benutzerdefinierte Trust-Anker mit der Einstellung tlsConfig in Ihrer Konnektivitätsvorlage konfigurieren.

    Wenn Sie auf eine Zertifikatmanager-TrustConfig-Ressource verweisen, können Sie Agent Gateway so konfigurieren, dass nur bestimmten privaten Zertifizierungsstellen vertraut wird, oder private Stammzertifizierungsstellen mit öffentlich vertrauenswürdigen Zertifizierungsstellen (PUBLICLY_TRUSTED_ROOTS) kombinieren. Dadurch wird eine Vertrauensstellung sowohl für öffentliche als auch für private Endpunkte hergestellt.

    Wenn Ihre Agents eine Verbindung zu Google Cloud -APIs (*.googleapis.com) oder anderen öffentlichen HTTPS-Endpunkten herstellen, müssen Sie additionalRoots auf PUBLICLY_TRUSTED_ROOTS setzen. Ohne diese Einstellung vertraut Agent Gateway von Google signierten Zertifikaten für googleapis.com nicht.

    Beachten Sie bei der Verwendung von tlsConfig die folgenden Einschränkungen:

    • Wenn Sie trustConfigs verwenden, um Traffic an Ziele weiterzuleiten, die private Zertifizierungsstellen verwenden, müssen Sie die PEM-Dateien manuell rotieren. Die automatische Rotation von PEM-Dateien mit Secret-Managern wie dem Secret Manager vonGoogle Cloud wird nicht unterstützt.
    • Das Feld trustConfig ist unveränderlich, sobald es in einer Konnektivitätsvorlage konfiguriert wurde. Agent Gateway übernimmt Änderungen an tlsConfig (z. B. Aktualisierungen von additionalRoots) in einer angehängten Konnektivitätsvorlage nicht automatisch. Eine Anleitung zum Aktualisieren der TLS-Einstellungen finden Sie unter Einstellungen für ausgehenden VPC-Traffic aktualisieren.

Wenn das Agent Gateway die Zertifikatskette nicht validieren kann, schlägt die Verbindung fehl.

Erforderliche Rollen und Berechtigungen

Wenn Sie die VPC-Konnektivität für das Agent Gateway konfigurieren möchten, müssen die für die Bereitstellung verwendete Identität und der Gateway-Dienst-Agent die erforderlichen Rollen haben.

Bereitstellungen in eigenständigen Projekten

In einem eigenständigen Projekt, in dem sich das Gateway, der Netzwerkanhang und das VPC-Netzwerk im selben Projekt befinden, gelten die Standardberechtigungen für das Agent-Gateway. Weitere Informationen finden Sie unter Erforderliche Berechtigungen.

Freigegebene VPC oder projektübergreifende Bereitstellungen

In einer Bereitstellung mit gemeinsam genutzter VPC können Sie das Agent-Gateway entweder in einem Dienstprojekt oder im Hostprojekt bereitstellen. Wenn Sie das Gateway im Hostprojekt bereitstellen, in dem sich auch das freigegebene VPC-Netzwerk, das Subnetz und der Netzwerkanhang befinden, gelten die Berechtigungen für eigenständige Projekte.

Wenn Sie das Agent-Gateway in einem Dienstprojekt bereitstellen, während sich das Ziel-VPC-Netzwerk, der Netzwerkanhang oder die privaten DNS-Zonen im Hostprojekt (TARGET_VPC_PROJECT_ID) befinden, haben Identitäten im Dienstprojekt nicht automatisch Berechtigungen zum Validieren, Anhängen oder Peering mit Netzwerk- und DNS-Ressourcen im Hostprojekt. Weisen Sie dem Hostprojekt zusätzlich zu den Standardberechtigungen für das Agent-Gateway die folgenden Rollen zu:

Tabelle: Erforderliche Berechtigungen für freigegebene VPC und projektübergreifende Bereitstellungen
Hauptkonto oder Identität Für Projekt gewähren Erforderliche IAM-Rolle Zweck
Bereitstellungsidentität1
(Nutzerkonto oder Dienstkonto für die Bereitstellung)		 Hostprojekt (TARGET_VPC_PROJECT_ID)
  • Compute-Netzwerkbetrachter (roles/compute.networkViewer)
  • DNS-Leser (roles/dns.reader)
  • Network Connectivity Regional Endpoint Admin (roles/networkconnectivity.regionalEndpointAdmin)
  • Network Connectivity Consumer Network Admin (roles/networkconnectivity.consumerNetworkAdmin)
 Ermöglicht die Backend-Validierung des Ziel-VPC-Netzwerk, der Subnetze, des Netzwerkanhangs und der privaten DNS-Zonen beim Erstellen oder Aktualisieren des Gateways.
Netzwerkanhang-Ersteller
(Administrator, der den PSC-Anhang erstellt)		 Hostprojekt (TARGET_VPC_PROJECT_ID)
  • Compute Netzwerknutzer (roles/compute.networkUser)
 Ermöglicht die Verwendung eines freigegebene VPC-Subnetzes im Hostprojekt, um einen Private Service Connect-Netzwerkanhang zu erstellen.
Netzwerkanhang im Dienstprojekt (empfohlen)
Agent Gateway Service Agent2 Hostprojekt (TARGET_VPC_PROJECT_ID)
  • Compute Netzwerknutzer (roles/compute.networkUser)
  • DNS-Peer (roles/dns.peer)
 Ermöglicht dem Agent Gateway-Dienst-Agent, das Subnetz des Hostprojekts für den Netzwerkanhang zu verwenden, die Private Service Connect-Schnittstelle zum Weiterleiten von ausgehendem Traffic zu verbinden und ein Peering mit privaten Cloud DNS-Zonen im Hostprojekt durchzuführen.
Netzwerkanhang im Hostprojekt
Agent Gateway Service Agent2 Hostprojekt (TARGET_VPC_PROJECT_ID)
  • Compute-Netzwerkadministrator (roles/compute.networkAdmin) oder eine benutzerdefinierte Rolle mit:
    • compute.networkAttachments.get
    • compute.networkAttachments.update
    • compute.regionOperations.get
  • DNS-Peer (roles/dns.peer)
 Ermöglicht dem Agent Gateway-Dienst-Agent, den Netzwerk-Anhang des Hostprojekts zu aktualisieren, um die Verbindung vom Agent Gateway-Mandantenprojekt zuzulassen, ausgehenden Traffic weiterzuleiten und Peering mit privaten Cloud DNS-Zonen im Hostprojekt durchzuführen.

1 Für die Bereitstellungsidentität reichen auch einfache Rollen auf Projektebene wie „Betrachter“ (roles/viewer) oder „Bearbeiter“ (roles/editor) im Hostprojekt aus.

2 Der Agent Gateway Service Agent hat das Format service-AGENT_GATEWAY_PROJECT_NUMBER@gcp-sa-agentgateway.iam.gserviceaccount.com, wobei AGENT_GATEWAY_PROJECT_NUMBER die Projektnummer des Projekts ist, in dem Sie das Agent Gateway bereitstellen. Bei Bereitstellungen mit freigegebene VPC kann dieses Projekt entweder ein Dienstprojekt oder das Hostprojekt sein.

Wenn Sie mehrere Agent Runtime-Dienstprojekte mit einem Agent Gateway-Hostprojekt verbinden, müssen Sie jedem Agent Runtime-Dienst-Agent auch projektübergreifenden Zugriff auf das Gateway-Projekt gewähren. Informationen zu umfangreichen Bereitstellungen finden Sie unter Agent Runtime-Dienstprojekte mit einer Google-Gruppe skalieren.

VPC-Konnektivität konfigurieren

Führen Sie die Schritte in den folgenden Abschnitten aus, um ein Agent-Gateway mit einer Konnektivitätsvorlage bereitzustellen.

Private Service Connect-Netzwerkanhang erstellen

Erstellen Sie einen Private Service Connect-Netzwerkanhang in Ihrem Ziel-VPC-Netzwerk.

Ihr Netzwerkanhang muss die folgenden Anforderungen erfüllen:

  • Verbindungseinstellung: Konfigurieren Sie den Netzwerkanhang so, dass Verbindungen automatisch akzeptiert werden (--connection-preference=ACCEPT_AUTOMATIC).
  • Anforderung für dasselbe VPC-Netzwerk: Das Subnetz des Netzwerkanhangs und das für DNS-Peering konfigurierte Zielnetzwerk (targetNetwork) müssen sich im genau selben VPC-Netzwerk befinden. Wenn das Subnetz des Netzwerkanhangs zu einem anderen Netzwerk als dem DNS-Peering-Zielnetzwerk gehört, schlägt die Konfigurationsvalidierung fehl.
  • Anforderungen an Subnetze: Beachten Sie die folgenden Anforderungen für das Subnetz des Netzwerkanhangs:
    • Subnetzbereich: Das Subnetz des Netzwerkanhangs unterstützt alle gültigen Bereiche.
    • Subnetzgröße: Agent Gateway erfordert ein Subnetz mit mindestens /28 für den Netzwerkanhang. Ein /28-Subnetz stellt 12 verwendbare IP-Adressen bereit, was für eine einzelne Agent Gateway-Instanz ausreicht. Wenn Sie mehrere Gateways mit demselben Netzwerkanhang oder Subnetz verbinden möchten, verwenden Sie ein größeres Subnetz (z. B. /26 oder /24), um eine Erschöpfung der IP-Adressen zu vermeiden.
    • Anforderung für privaten Google-Zugriff: Sie müssen den privaten Google-Zugriff (private_ip_google_access = true) für das Subnetz aktivieren, in dem der Netzwerkanhang gehostet wird.
  • Bereitstellungen gemeinsam genutzter VPCs: Informationen zu Bereitstellungen gemeinsam genutzter VPCs finden Sie unter Bereitstellungstopologien für gemeinsam genutzte VPCs.

Notieren Sie sich den vollständigen Ressourcen-URI des Netzwerkanhangs (z. B. projects/NETWORK_ATTACHMENT_PROJECT_NUMBER/regions/NETWORK_ATTACHMENT_REGION/networkAttachments/NETWORK_ATTACHMENT_NAME). Sie benötigen ihn, wenn Sie in einem späteren Schritt die Konnektivitätsvorlagen-Ressource erstellen.

Optional: DNS-Peering einrichten

Mit DNS-Peering kann das Agent Gateway DNS-Namen mithilfe von Einträgen aus einer privaten verwalteten Cloud DNS-Zone in Ihrem VPC-Netzwerk auflösen. DNS-Peering ist nur erforderlich, wenn Ihre Agents private interne Domainnamen (z. B. corp.internal.) auflösen oder VPC Service Controls für Google APIs (googleapis.com.) erzwingen müssen. Es ist nicht für öffentliche Internetdomains oder Standard-Google APIs ohne VPC Service Controls erforderlich.

Agent Gateway unterstützt transitives DNS-Peering nur bis zu einem einzigen transitiven Hop, also maximal drei VPC-Netzwerke. Beispiel: vpc-net-a (das Agent Gateway-Mandantennetzwerk) kann ein Peering mit vpc-net-b (angehängtes Netzwerk) durchführen, das wiederum ein Peering mit vpc-net-c (Remote-Netzwerk) durchführt, um DNS-Abfragen über die Kette aufzulösen.

So richten Sie DNS-Peering ein:

  1. Richten Sie Ihre private DNS-Zone in Ihrem Ziel-VPC-Netzwerk ein. Informationen zum Hinzufügen von DNS-Einträgen zu Ihrer privaten DNS-Zone finden Sie unter Ressourceneintragssatz hinzufügen.

  2. Erfassen Sie die folgenden Informationen, um die Konnektivitätsvorlage für das Peering zu konfigurieren:

    • Zielnetzwerk-URI (targetNetwork): Notieren Sie sich den vollständigen Ressourcen-URI des Ziel-VPC-Netzwerk im folgenden Format: projects/TARGET_VPC_PROJECT_ID/global/networks/TARGET_VPC_NETWORK_NAME. Das Zielnetzwerk ist immer das VPC-Netzwerk, das das Subnetz enthält, auf das der Netzwerkanhang verweist. Wenn das Zielnetzwerk ein freigegebene VPC-Netzwerk ist, müssen Sie die entsprechende Hostprojekt-ID der freigegebene VPC verwenden.

    • Domainnamen: Ein oder mehrere Domainsuffixe für das DNS-Peering. Jede Domain muss mit einem Punkt (.) enden, z. B. corp.internal. oder googleapis.com..

      Weitere Informationen zum Konfigurieren des Felds domains finden Sie unter DNS-Peering-Domainmuster. Informationen zu projektübergreifenden Bereitstellungen wie freigegebene VPC finden Sie unter Anforderungen für projektübergreifende DNS-Zonen und Peering.

Optional: TLS-Vertrauenskonfiguration einrichten

Wenn Ihr Ziel eine private Zertifizierungsstelle oder ein selbst signiertes Zertifikat verwendet, müssen Sie im Zertifikatmanager eine TrustConfig-Ressource erstellen. Die TrustConfig-Ressource definiert die Trust-Anker und Zertifikate, die Agent Gateway zum Validieren von TLS-Verbindungen verwendet.

  1. Bereiten Sie Ihre Zertifikatsdateien im PEM-Format vor:

    • Trust Store: Root- oder Zwischen-CA-Zertifikate im PEM-Format. Agent Gateway vertraut jedem Serverzertifikat, dessen Vertrauenskette zu einem dieser CA-Zertifikate führt. Der Trust Store muss mindestens ein Root- oder Zwischen-CA-Zertifikat enthalten.
    • Zertifikate auf der Zulassungsliste (optional): Serverzertifikate im PEM-Format, denen Sie explizit vertrauen möchten, z. B. ein selbst signiertes Zertifikat.

  2. Führen Sie den folgenden Befehl aus, um die TrustConfig-Ressource zu erstellen. Der TrustConfig muss im selben Projekt und in derselben Region wie das Agent-Gateway und die Konnektivitätsvorlage erstellt werden.

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

    Ersetzen Sie Folgendes:

    • TRUST_CONFIG_NAME: Ein Name für die TrustConfig-Ressource.
    • LOCATION: Die Region für die Vertrauenskonfiguration (z. B. europe-west1). Dies muss dieselbe Region wie das Agent-Gateway und die Konnektivitätsvorlage sein.
    • ROOT_CERT_FILE: Der Pfad zu Ihrem PEM-codierten Stamm- oder Zwischen-CA-Zertifikat.
    • ALLOWLISTED_CERT_FILE: (Optional) Der Pfad zu einem PEM-codierten Zertifikat, dem Sie explizit vertrauen möchten. Wenn Sie keine Zertifikate auf der Zulassungsliste verwenden, lassen Sie dieses Flag weg.

    Weitere Informationen zum Verwalten von Vertrauenskonfigurationen finden Sie unter Vertrauenskonfigurationen erstellen und verwalten.

KI-Agenten-Gateway bereitstellen

  1. Konfigurationsdatei für die Konnektivitätsvorlage erstellen:

    Erstellen Sie eine YAML-Datei mit dem Namen agw-connectivity-template.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

    Ersetzen Sie Folgendes:

    • AGENT_GATEWAY_PROJECT_NUMBER: Die Projektnummer des Google Cloud -Projekts, in dem Sie das Agent-Gateway bereitstellen. Führen Sie den folgenden Befehl aus, um die Projektnummer abzurufen: gcloud projects describe PROJECT_ID --format="value(projectNumber)".

    • LOCATION: Die Region für die Konnektivitätsvorlage (z. B. europe-west1).

    • CONNECTIVITY_TEMPLATE_NAME: Der Name der Konnektivitätsvorlagenressource.

    • accessPath: Der verwaltete Zugriffspfad für die Konnektivitätsvorlage. Legen Sie AGENT_TO_ANYWHERE fest (Konnektivitätsvorlagen werden nur für Ausgangsgateways unterstützt).

    • deploymentModel: Das Bereitstellungsmodell für das Gateway. Legen Sie CENTRALIZED fest.

    • networkAttachment: Der vollständige Ressourcen-URI des Private Service Connect-Netzwerkanhangs:

      • NETWORK_ATTACHMENT_PROJECT_NUMBER: Die Projektnummer des Projekts, in dem Sie den Netzwerkanhang erstellt haben. Dieses Projekt kann mit dem Agent-Gateway-Projekt identisch sein oder ein anderes Projekt sein, wenn Sie das Agent-Gateway in einem freigegebene VPC-Dienstprojekt bereitstellen und den Netzwerkanhang im freigegebene VPC-Hostprojekt erstellen.
      • NETWORK_ATTACHMENT_REGION: Die Region, die den Netzwerkanhang enthält.
      • NETWORK_ATTACHMENT_NAME: Der Name des Netzwerkanhangs.

    • DOMAIN_NAME: (Optional) Ein oder mehrere Domain-Suffixe für das DNS-Peering (z. B. corp.internal., googleapis.com. oder .). Fügen Sie unter domains für jedes Domain-Suffix, das Sie peeren möchten, ein Listenelement hinzu. Jeder Wert muss mit einem Punkt (.) enden und eine entsprechende private verwaltete Cloud DNS-Zone haben, die für das Zielnetzwerk autorisiert ist.

      Weitere Informationen zum Konfigurieren des Felds domains finden Sie unter DNS-Peering-Domainmuster.

    • targetNetwork: (Optional) Der vollständige Ressourcen-URI des Ziel-VPC-Netzwerk für das DNS-Peering. Das Zielnetzwerk ist immer das VPC-Netzwerk, das das Subnetz enthält, auf das der Netzwerkanhang verweist:

      • TARGET_VPC_PROJECT_ID: Die Projekt-ID des Projekts, zu dem das Ziel-VPC-Netzwerk gehört. Wenn das Netzwerk, das das vom Netzwerkanhang referenzierte Subnetz enthält, ein freigegebene VPC-Netzwerk ist, ist TARGET_VPC_PROJECT_ID die Hostprojekt-ID der freigegebene VPC. Geben Sie targetNetwork immer mit der Projekt-ID und nicht mit der Projektnummer an.
      • TARGET_VPC_NETWORK_NAME: Der Name des Ziel-VPC-Netzwerk.

    • VPC_EGRESS_MODE: Legen Sie den Routingmodus für ausgehenden Traffic fest. Legen Sie entweder PRIVATE_RANGES_ONLY oder ALL_TRAFFIC fest.

    • tlsConfig: (Optional) Die TLS-Konfiguration für die Serverzertifikatsvalidierung beim Herstellen einer Verbindung zu privaten Endpunkten über HTTPS:

      • TRUST_CONFIG_NAME: Der Name der TrustConfig-Ressource des Zertifikatmanagers, die Ihre privaten CA-Zertifikate oder Trust-Anchor enthält.
      • ADDITIONAL_ROOTS_OPTION: Gibt an, ob zusätzlich zu Ihrer benutzerdefinierten Vertrauenskonfiguration öffentlich vertrauenswürdigen Stammzertifizierungsstellen vertraut werden soll:
      • Legen Sie PUBLICLY_TRUSTED_ROOTS (Standard) fest, um sowohl Zertifikaten, die durch den Parameter trustConfig validiert wurden, als auch allen öffentlich vertrauenswürdigen Zertifizierungsstellen zu vertrauen. Sie müssen additionalRoots auf PUBLICLY_TRUSTED_ROOTS setzen, wenn Ihre Agents auch eine Verbindung zuGoogle Cloud -APIs (*.googleapis.com) oder anderen öffentlichen HTTPS-Endpunkten herstellen. Ohne diese Einstellung vertraut das Agent-Gateway von Google signierten Zertifikaten für googleapis.com nicht.
      • Legen Sie NO_ADDITIONAL_ROOTS fest, um nur den Zertifikaten zu vertrauen, die durch den Parameter trustConfig validiert wurden.

  2. Konnektivitätsvorlage erstellen:

    Führen Sie den folgenden Befehl aus, um die Konnektivitätsvorlage zu erstellen:

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

    Ersetzen Sie Folgendes:

    • CONNECTIVITY_TEMPLATE_NAME: Der Name der Konnektivitätsvorlagenressource.
    • LOCATION: Der Standort, an dem Sie die Konnektivitätsvorlagen-Ressource erstellen möchten. Beispiel: europe-west1.

  3. Agent Gateway-Ressource definieren:

    Definieren Sie eine neue Agent Gateway-Ressource im AGENT_TO_ANYWHERE-Modus. Erstellen Sie dazu eine YAML-Konfigurationsdatei für das Gateway (z. B. my-agent-gateway-vpc-egress.yaml), die auf die Konnektivitätsvorlage verweist:

    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

    Ersetzen Sie Folgendes:

    • AGENT_GATEWAY_NAME: Der Name der Agent-Gateway-Ressource.

    • AGENT_GATEWAY_PROJECT_NUMBER: Die Projektnummer des Projekts in Google Cloud , in dem Sie das Agent Gateway und die Konnektivitätsvorlage bereitstellen. Bei freigegebene VPC-Bereitstellungen kann dieses Projekt entweder ein Dienstprojekt oder das Hostprojekt sein. Führen Sie den folgenden Befehl aus, um die Projektnummer abzurufen: gcloud projects describe PROJECT_ID --format="value(projectNumber)".

    • LOCATION: Der Standort der Konnektivitätsvorlage (z. B. europe-west1).

    • CONNECTIVITY_TEMPLATE_NAME: Der Name der Konnektivitätsvorlagenressource.

      • AGENT_REGISTRY_PATH: Der Pfad zur regionalen Agent Registry-Instanz im selben Projekt und in derselben Region wie das Gateway, formatiert als //agentregistry.googleapis.com/projects/PROJECT_ID/locations/LOCATION. Eine Anleitung finden Sie unter Agent-Gateway-Bereitstellung planen.

  4. Agent Gateway importieren und bereitstellen:

    Führen Sie den folgenden Befehl aus, um die Agent-Gateway-Ressource basierend auf der YAML-Spezifikation zu erstellen:

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

    Ersetzen Sie LOCATION durch den Standort, an dem Sie die Agent-Gateway-Ressource erstellen möchten. Beispiel: europe-west1

Überlegungen zu Architektur und Netzwerk

In diesem Abschnitt finden Sie Architekturhinweise und erweiterte Netzwerkmuster für die Bereitstellung von Agent Gateway mit VPC-Konnektivität.

Einstellungen für ausgehenden VPC-Traffic aktualisieren

Eine Konnektivitätsvorlage kann nicht direkt geändert werden, während sie von einem Agent Gateway referenziert wird. Außerdem übernimmt das Agent Gateway Änderungen an einer angehängten Konnektivitätsvorlage nicht automatisch:

  • DNS-Peering, VPC-Ausgangsmodus oder TLS-Einstellungen (tlsConfig) aktualisieren: In einer Konnektivitätsvorlage ist das Feld tlsConfig.trustConfig nach der Konfiguration unveränderlich. Direktaktualisierungen von tlsConfig (z. B. Hinzufügen oder Ändern von additionalRoots) werden von einem angehängten Agent-Gateway nicht übernommen. Wenn Sie die DNS-Peering-Konfiguration, den VPC-Ausgangsmodus oder die tlsConfig-Einstellungen für ein vorhandenes Gateway aktualisieren möchten, erstellen Sie eine neue Konnektivitätsvorlage, die dieselbe networkAttachment mit den aktualisierten Einstellungen verwendet, und aktualisieren Sie das Agent-Gateway, sodass es auf die neue Vorlage verweist (oder heben Sie die Bindung der Konnektivitätsvorlage auf und binden Sie sie neu).

  • Netzwerkanhang ändern: Der networkAttachment selbst ist unveränderlich, sobald er sowohl in der Konnektivitätsvorlage als auch im Agent Gateway konfiguriert wurde. Wenn Sie zu einem anderen Netzwerkanhang (oder Ziel-VPC-Netzwerk) wechseln möchten, müssen Sie eine neue Konnektivitätsvorlage und ein neues Agent Gateway erstellen.

Topologien für die Bereitstellung von freigegebene VPC

In einer gemeinsam genutzten VPC-Architektur können Sie das Agent-Gateway entweder in einem Dienstprojekt oder im Hostprojekt bereitstellen. Wenn Sie das Agent Gateway in einem Dienstprojekt bereitstellen, können Sie den Netzwerkanhang entweder im Dienstprojekt (empfohlen) oder im Hostprojekt erstellen:

Compliance mit VPC Service Controls

Wenn Sie VPC Service Controls-Perimeter für die Agentenkommunikation erzwingen möchten, müssen Sie Folgendes tun:

  • Legen Sie in Ihrer Konnektivitätsvorlage vpcEgress auf ALL_TRAFFIC fest.

  • Leiten Sie Google API-Anfragen entweder an den restricted.googleapis.com-IP-Bereich (199.36.153.4/30) oder an einen internen Private Service Connect-Endpunkt für Google APIs weiter.

  • Konfigurieren Sie die DNS-Auflösung für googleapis.com. Erstellen Sie eine private Cloud DNS-Zone in Ihrem VPC-Netzwerk, die *.googleapis.com zu restricted.googleapis.com zuordnet, und fügen Sie googleapis.com. in das Feld domains Ihrer Konnektivitätsvorlage ein.

    Weitere Informationen zur DNS-Konfiguration finden Sie in der Dokumentation zum privater Google-Zugriff unter DNS für googleapis.com konfigurieren.

  • Bei gemeinsam genutzten VPC-Bereitstellungen müssen sich das Hostprojekt, zu dem das Subnetz des Netzwerkanhangs gehört, und der dnsPeeringConfig.targetNetwork im selben Dienstperimeter befinden wie das Projekt, in dem Sie das Agent-Gateway bereitstellen. Dies gilt auch, wenn Sie den Netzwerkanhang im Dienstprojekt erstellen, da das Subnetz und das VPC-Netzwerk weiterhin zum Hostprojekt gehören. Wenn Ihre privaten DNS-Zonen in einem separaten DNS-Projekt gehostet werden, nehmen Sie dieses Projekt ebenfalls in den Perimeter auf.

DNS-Peering-Domainmuster

In diesem Abschnitt werden Muster für die Domainauflösung und Optionen zum Konfigurieren des Felds domains in einer Konnektivitätsvorlage beschrieben.

Domainnamenkonfiguration: Konfigurieren Sie das Feld domains in der Konnektivitätsvorlage anhand der folgenden Überlegungen:

  • Private interne Domains: Wenn Sie private interne Dienste auflösen möchten, die in Ihrem VPC-Netzwerk gehostet werden (z. B. service.corp.internal), geben Sie Ihr internes Domain-Suffix an (z. B. corp.internal.). Für das Ziel-VPC-Netzwerk muss eine genau übereinstimmende private verwaltete Cloud DNS-Zone für diese Domain autorisiert sein.

  • Split-Horizon-DNS (öffentliche Domain mit RFC 1918-IP): Wenn Sie eine öffentliche DNS-Zone verwenden, um Einträge zu hosten, die auf interne private IP-Adressen verweisen (z. B. mcp.example.com, die für öffentliche Zertifikate des Zertifikatmanagers in eine RFC 1918-Adresse aufgelöst wird), löst das Gateway diese Einträge automatisch mithilfe von öffentlichem rekursivem DNS auf, ohne dass DNS-Peering erforderlich ist.

  • Google Cloud APIs mit VPC Service Controls: Wenn ALL_TRAFFIC für die Erzwingung von VPC Service Controls konfiguriert ist, müssen Google API-Anfragen in den IP-Bereich restricted.googleapis.com (199.36.153.4/30) oder in interne PSC-Endpunkte aufgelöst werden. Erstellen Sie in Ihrem VPC-Netzwerk eine private Cloud DNS-Zone, die *.googleapis.com restricted.googleapis.com zuordnet, und fügen Sie googleapis.com. in das Feld domains Ihrer Konnektivitätsvorlage ein.

  • Muster für die Auflösung mehrerer Domains: Wenn für Ihre Bereitstellung mehrere private Domainsuffixe aufgelöst werden müssen, wählen Sie eines der folgenden Muster aus:

    • Peering mehrerer einzelner Domains: Geben Sie eine Liste von Domainsuffixen im Feld domains von dnsPeeringConfig an (z. B. corp.internal., prod.internal. und googleapis.com.). Jede Domain in der Liste muss mit einem abschließenden Punkt (.) enden und eine entsprechende private Cloud DNS-verwaltete Zone haben, die für das Ziel-VPC-Netzwerk autorisiert ist.
    • Konsolidiertes übergeordnetes Suffix (empfohlen): Konsolidieren Sie interne Dienste unter einem gemeinsamen übergeordneten Domain-Suffix (z. B. *.internal. oder *.corp.internal.) und fügen Sie diese übergeordnete Domain der domains-Liste hinzu.

    • Catch-all-Root-Peering mit einer privaten Weiterleitungszone: Fügen Sie "." in das Feld domains der Konnektivitätsvorlage ein und konfigurieren Sie eine private Cloud DNS-Weiterleitungszone für die Stammdomain (.) in Ihrem VPC-Netzwerk, die auf einen vorgelagerten rekursiven Resolver verweist (z. B. 8.8.8.8 oder einen internen Unternehmens-Resolver). Spezifischere private Zonen in Ihrer VPC werden zuerst nach der längsten Suffixübereinstimmung abgeglichen, während nicht übereinstimmende öffentliche Abfragen über die vorgelagerte Weiterleitung aufgelöst werden.

Anforderungen für projektübergreifende DNS-Zonen und Peering

Die Einstellung dnsPeeringConfig der Konnektivitätsvorlage unterstützt kein direktes projektübergreifendes Cloud DNS-Peering. Wenn Sie die Konnektivitätsvorlage importieren, schlägt die Validierung fehl, wenn das von networkAttachment referenzierte Subnetz zu einem anderen VPC-Netzwerk als targetNetwork gehört oder wenn Sie die projektübergreifende DNS-Zonenbindung von einem Dienst- oder externen Projekt verwenden.

Die verwaltete Zone für die Domain muss im Hostprojekt erstellt werden, zu dem targetNetwork gehört. Die verwaltete Zone kann einer der folgenden Zonentyps sein:

  • Autoritative private Zone
  • Weiterleitungszone
  • Cloud DNS-Peering-Zone: Muss mit dem VPC-Netzwerk des Hostprojekts verknüpft sein und auf ein Ziel-VPC-Netzwerk verweisen. Die Ziel-VPC muss die Abfrage direkt mithilfe einer autoritativen privaten Zone auflösen. Das Weiterleiten der Abfrage an eine andere DNS-Peering-Zone (Verkettung) wird nicht unterstützt und führt zu einem NXDOMAIN-Fehler.

Agent Runtime-Dienstprojekte mit einer Google-Gruppe skalieren

Wenn Sie mehrere Agent Runtime-Dienstprojekte mit einem Agent Gateway-Hostprojekt verbinden und jedem Dienst-Agent einzeln projektübergreifenden Zugriff gewähren, müssen Sie die IAM-Richtlinie des Hostprojekts jedes Mal aktualisieren, wenn Sie ein Projekt hinzufügen. Bei umfangreichen Bereitstellungen können Sie beim Hinzufügen von Rollenbindungen auch die IAM-Richtlinienlimits erreichen.

Wenn Sie die IAM-Richtlinie des Hostprojekts nicht für jedes neue Dienstprojekt aktualisieren möchten, können Sie den Zugriff stattdessen über eine einzelne Google-Sicherheitsgruppe verwalten:

  1. Sicherheitsgruppe erstellen: Erstellen Sie eine Sicherheitsgruppe entweder in der Google Admin-Konsole oder durch Ausführen des Befehls gcloud identity groups create.

  2. Gewähren Sie der Gruppe Zugriff auf das Hostprojekt des Agent-Gateways: Binden Sie die Gruppe an die Rolle „Network Services Viewer“ (roles/networkservices.viewer) in AGENT_GATEWAY_PROJECT_ID:

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

    Ersetzen Sie Folgendes:

    • AGENT_GATEWAY_PROJECT_ID: Die Projekt-ID des Hostprojekts des Agent-Gateways.
    • GROUP_EMAIL: Die E-Mail-Adresse Ihrer Sicherheitsgruppe (z. B. agw-cross-project-runtime@example.com).

  3. Agent Runtime-Dienst-Agent jedes Dienstprojekts zur Gruppe hinzufügen: Fügen Sie für jedes Agent Runtime-Dienstprojekt den Dienst-Agent zur Sicherheitsgruppe hinzu. Führen Sie dazu den Befehl gcloud identity groups memberships add so aus:

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

    Ersetzen Sie AGENT_RUNTIME_PROJECT_NUMBER durch die Projektnummer des Agent Runtime-Dienstprojekts.

Nächste Schritte

Anleitung

Hier erfahren Sie, wie Sie Agent Runtime-Traffic über Agent Gateway weiterleiten, um eine sichere und verwaltete Verbindung zu ermöglichen.

Codelab

Hier erfahren Sie, wie Sie agentische Arbeitslasten mit Agent Gateway auf der Gemini Enterprise Agent Platform verwalten.

Codelab

Informationen zur Governance für ausgehenden Traffic über Agent Gateway für KI-Agenten, die auf Ziele in einem VPC-Netzwerk zugreifen.

Anleitung

Hier erfahren Sie, wie Sie die Autorisierung für Agent Gateway an IAP, Model Armor oder Ihren eigenen benutzerdefinierten Autorisierungsdienst delegieren.

Anleitung

Informationen zum Ansehen, Aktualisieren, Aufheben der Verknüpfung und Löschen von Agent Gateway-Ressourcen.

Anleitung

Informationen zum Monitoring des KI-Agenten-Gateways

Anleitung

Informationen zum Weiterleiten von Gemini Enterprise-Traffic über Agent Gateway.