Configura Agent Gateway con la connettività VPC

Questo documento ti guida nel processo di configurazione della connettività VPC durante il deployment di un Agent Gateway in modo che possa comunicare privatamente con una rete VPC nella tua organizzazione.

La configurazione della connettività VPC ti consente di:

  • Forza il traffico in uscita VPC: instrada il traffico proveniente dai tuoi agenti tramite il collegamento di rete Private Service Connect alla tua rete VPC utilizzando la modalità PRIVATE_RANGES_ONLY o ALL_TRAFFIC.
  • Intervallo di indirizzi IP di origine statico: il traffico in uscita utilizza l'intervallo di indirizzi IP privati della subnet del collegamento di rete Private Service Connect come indirizzo IP di origine. Questo intervallo IP di origine statico ti consente di configurare le policy del firewall per la tua rete VPC in modo da gestire il traffico proveniente dal gateway.
  • Risoluzione DNS personalizzata: risolvi i nomi di dominio privati interni e i nomi di dominio esterni direttamente dai tuoi agenti utilizzando il peering DNS di Cloud DNS.
  • Sicurezza del perimetro: proteggi le comunicazioni degli agenti utilizzando i perimetri di servizio dei Controlli di servizio VPC.
  • Convalida dei certificati privati o autofirmati: connettiti alle destinazioni che utilizzano CA private o certificati autofirmati.

Per configurare la connettività VPC, devi creare un modello di connettività di Agent Gateway (AgentConnectivityTemplate) in cui definisci e gestisci le impostazioni di rete in uscita per le tue istanze di Agent Gateway.

Come funziona la connettività VPC

Quando esegui il deployment di un Agent Gateway con un modello di connettività, il gateway utilizza un'interfaccia Private Service Connect per instradare il traffico degli agenti in uscita verso la rete VPC designata.

Modalità traffico in uscita VPC

Puoi configurare il modo in cui il gateway instrada il traffico attraverso il collegamento di rete utilizzando l'impostazione vpcEgress nel modello di connettività.

  • Traffico verso intervalli di indirizzi IP privati (PRIVATE_RANGES_ONLY): instrada il traffico destinato solo a intervalli di indirizzi IP privati nella tua rete VPC. Il traffico in uscita viene instradato alla rete VPC solo se l'indirizzo IP di destinazione rientra in uno dei seguenti intervalli:

    • RFC 1918: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
    • RFC 6598: 100.64.0.0/10
    • Classe E: 240.0.0.0/4
    • private.googleapis.com: 199.36.153.8/30
    • restricted.googleapis.com: 199.36.153.4/30
    • Endpoint PSC per le API di Google: se esegui il deployment di un endpoint Private Service Connect personalizzato per le API di Google utilizzando un indirizzo IP privato interno nella tua rete VPC, il traffico verso questo endpoint viene instradato attraverso la tua rete VPC. Assicurati che il peering DNS di Cloud DNS sia configurato nel template di connettività in modo che Agent Gateway risolva correttamente i domini delle API di Google nell'indirizzo IP dell'endpoint PSC interno.

    Le richieste alle API di Google pubbliche standard vengono gestite automaticamente utilizzando l'accesso privato Google e il traffico verso internet viene instradato direttamente tramite Agent Gateway anziché tramite la tua rete VPC.

  • Traffico verso tutti gli intervalli di indirizzi IP (ALL_TRAFFIC): instrada tutto il traffico in uscita proveniente dai tuoi agenti attraverso la tua rete VPC, inclusi internet pubblico, API SaaS esterne e indirizzi non RFC 1918.

    • Routing e sicurezza: poiché questa impostazione instrada tutto il traffico in uscita nel VPC, sei responsabile della gestione del routing e della sicurezza. Assicurati che la tua rete VPC abbia una route predefinita (0.0.0.0/0) per inoltrare questo traffico ai gateway in uscita o alle appliance di sicurezza (come i firewall di hop successivo o le interfacce Cloud Interconnect).
    • Traffico in uscita verso internet pubblico: l'Agent Gateway invia il traffico in uscita alla tua rete VPC, da cui esce verso internet pubblico tramite un gateway Cloud NAT sulla subnet del collegamento di rete Private Service Connect. Se assegni indirizzi IP esterni statici al gateway Cloud NAT, i servizi remoti possono inserire nella lista consentita il traffico in uscita degli agenti in base a questi indirizzi IP di origine.
    • Controlli di servizio VPC: la modalità in uscita deve essere impostata su ALL_TRAFFIC per supportare i perimetri di servizio dei Controlli di servizio VPC.

Risoluzione DNS e routing del traffico

Per impostazione predefinita, Agent Gateway risolve i nomi di dominio utilizzando il DNS ricorsivo pubblico. Se i tuoi agenti devono accedere a workload interni, strumenti privati o API di Google ospitate su nomi di dominio privati nella tua rete VPC (come corp.internal. o endpoint PSC), puoi configurare il peering Cloud DNS per inoltrare le query DNS alle zone gestite di Cloud DNS private della tua rete.

La tabella seguente riassume i requisiti di peering Cloud DNS e il comportamento di routing del traffico per diverse destinazioni quando la connettività VPC è configurata in modalità ALL_TRAFFIC:

Tabella: risoluzione DNS e routing del traffico in modalità ALL_TRAFFIC
Destinazione traffico È richiesto il peering Cloud DNS? Risoluzione DNS Percorso in uscita
Servizi con IP privato
(RFC 1918 / interno)		 Sì (ad esempio corp.internal.) Risolve utilizzando il peering Cloud DNS con la zona gestita Cloud DNS privata della rete VPC di destinazione. Il traffico entra nella rete VPC tramite il collegamento di rete per connettersi ai workload interni.
Nomi host pubblici con IP privati
(DNS split horizon)		 No Risolve utilizzando il DNS ricorsivo pubblico standard nel proxy gateway senza richiedere il peering DNS di Cloud DNS. Il traffico entra nella rete VPC tramite il collegamento di rete per connettersi ai workload interni.
Internet pubblico e API SaaS
(domini esterni)		 No Risolve utilizzando il DNS ricorsivo pubblico standard nel proxy gateway senza richiedere il peering DNS di Cloud DNS. Il traffico entra nella rete VPC tramite il collegamento di rete ed esce verso la rete internet pubblica utilizzando Cloud NAT configurato sulla subnet.
APIGoogle Cloud
(standard, senza Controlli di servizio VPC)		 No Risolve utilizzando il DNS ricorsivo pubblico standard nel proxy gateway senza richiedere il peering DNS di Cloud DNS. Il traffico entra nella rete VPC tramite il collegamento di rete e viene instradato privatamente utilizzando l'accesso privato Google abilitato sulla subnet, senza utilizzare Cloud NAT o il peering DNS.
APIGoogle Cloud
(con i Controlli di servizio VPC)		 Sì (per googleapis.com.) Risolve nell'intervallo di API di Google limitato (199.36.153.4/30) o negli endpoint Private Service Connect interni utilizzando una zona Cloud DNS privata. Il traffico entra nella rete VPC tramite il collegamento di rete per applicare le regole di sicurezza del perimetro dei Controlli di servizio VPC1.

1 Se le richieste non vanno a buon fine con violazioni dei Controlli di servizio VPC come NETWORK_NOT_IN_SAME_SERVICE_PERIMETER o SECURITY_POLICY_VIOLATED su compute.googleapis.com o dns.googleapis.com che fanno riferimento al progetto host, verifica che il progetto host si trovi nello stesso perimetro del progetto gateway.

Requisiti per i certificati TLS

Quando esegue il routing del traffico in uscita tramite HTTPS, Agent Gateway convalida la catena di certificati TLS del server di destinazione durante il TLS handshake. I requisiti dei certificati per le connessioni HTTPS dipendono dal fatto che gli endpoint di destinazione utilizzino autorità di certificazione (CA) attendibili pubblicamente o CA private/autofirmate.

  • CA pubbliche: per impostazione predefinita, Agent Gateway considera attendibili i certificati emessi da autorità di certificazione (CA) attendibili pubblicamente che soddisfano i requisiti standard dei certificati server (incluso un nome alternativo del soggetto (SAN) corrispondente al nome host di destinazione).

  • CA private e certificati autofirmati: se la destinazione target (agenti, strumenti o server MCP nella tua rete VPC) utilizza una CA privata o una PKI interna, puoi configurare trust anchor personalizzati utilizzando l'impostazione tlsConfig nel template di connettività.

    Facendo riferimento a una risorsa Certificate Manager TrustConfig, puoi configurare Agent Gateway in modo che consideri attendibili solo CA private specifiche o combinare CA root private con CA attendibili pubblicamente (PUBLICLY_TRUSTED_ROOTS). In questo modo, viene stabilita l'attendibilità sia per gli endpoint pubblici sia per quelli privati.

    Se i tuoi agenti si connettono alle API Google Cloud (*.googleapis.com) o ad altri endpoint HTTPS pubblici, devi impostare additionalRoots suPUBLICLY_TRUSTED_ROOTS. Senza questa impostazione, Agent Gateway non considera attendibili i certificati firmati da Google per googleapis.com.

    Tieni presente le seguenti limitazioni quando utilizzi tlsConfig:

    • Quando utilizzi trustConfig per instradare il traffico verso destinazioni che utilizzano CA private, devi ruotare i file PEM manualmente. La rotazione automatica dei file PEM tramite gestori di secret, come Secret Manager diGoogle Cloud, non è supportata.
    • Il campo trustConfig è immutabile una volta configurato in un template di connettività e Agent Gateway non rileva automaticamente le modifiche apportate a tlsConfig (ad esempio l'aggiornamento di additionalRoots) in un template di connettività collegato. Per istruzioni sull'aggiornamento delle impostazioni TLS, consulta Aggiornamento delle impostazioni VPC in uscita.

Se Agent Gateway non riesce a convalidare la catena di certificati, la connessione non va a buon fine.

Ruoli e autorizzazioni richiesti

Per configurare la connettività VPC per Agent Gateway, assicurati che l'identità utilizzata per il provisioning e l'agente di servizio del gateway dispongano dei ruoli richiesti.

Deployment di progetti autonomi

In un progetto autonomo in cui il gateway, il collegamento di rete e la rete VPC risiedono nello stesso progetto, si applicano le autorizzazioni standard di Agent Gateway. Per maggiori dettagli, consulta Autorizzazioni richieste.

Deployment VPC condiviso o tra progetti

In un deployment VPC condiviso, puoi eseguire il provisioning dell'Agent Gateway in un progetto di servizio o nel progetto host. Se esegui il provisioning del gateway nel progetto host (dove si trovano anche la rete VPC condiviso, la subnet e il collegamento di rete), si applicano le autorizzazioni del progetto autonomo.

Se esegui il provisioning di Agent Gateway in un progetto di servizio mentre la rete VPC di destinazione, il collegamento di rete o le zone DNS private si trovano nel progetto host (TARGET_VPC_PROJECT_ID), le identità nel progetto di servizio non dispongono automaticamente delle autorizzazioni per convalidare, collegare o eseguire il peering con le risorse di networking e DNS nel progetto host. Concedi i seguenti ruoli nel progetto host oltre alle autorizzazioni standard di Agent Gateway:

Tabella: autorizzazioni necessarie per VPC condiviso e deployment tra progetti
Entità o identità Concedi sul progetto Ruolo IAM richiesto Finalità
Identità di provisioning1
(Account utente o account di servizio di deployment)		 Progetto host (TARGET_VPC_PROJECT_ID)
  • Compute Network Viewer (roles/compute.networkViewer)
  • DNS Reader (roles/dns.reader)
  • Network Connectivity Regional Endpoint Admin (roles/networkconnectivity.regionalEndpointAdmin)
  • Network Connectivity Consumer Network Admin (roles/networkconnectivity.consumerNetworkAdmin)
 Consente la convalida del backend della rete VPC di destinazione, delle subnet, del collegamento di rete e delle zone DNS private durante la creazione o l'aggiornamento del gateway.
Creatore di collegamento di rete
(Amministratore che crea il collegamento PSC)		 Progetto host (TARGET_VPC_PROJECT_ID)
  • Compute Network User (roles/compute.networkUser)
 Consente di utilizzare una subnet VPC condiviso nel progetto host per creare un collegamento di rete Private Service Connect.
Collegamento di rete nel progetto di servizio (consigliato)
Agent Gateway Service Agent2 Progetto host (TARGET_VPC_PROJECT_ID)
  • Compute Network User (roles/compute.networkUser)
  • Peering DNS (roles/dns.peer)
 Consente all'agente di servizio Agent Gateway di utilizzare la subnet del progetto host per il collegamento di rete, di connettere l'interfaccia Private Service Connect per instradare il traffico in uscita e di eseguire il peering con le zone Cloud DNS private nel progetto host.
Collegamento di rete nel progetto host
Agent Gateway Service Agent2 Progetto host (TARGET_VPC_PROJECT_ID)
  • Compute Network Admin (roles/compute.networkAdmin) o un ruolo personalizzato con:
    • compute.networkAttachments.get
    • compute.networkAttachments.update
    • compute.regionOperations.get
  • Peering DNS (roles/dns.peer)
 Consente all'agente di servizio Agent Gateway di aggiornare il collegamento di rete del progetto host per consentire la connessione dal progetto tenant Agent Gateway, instradare il traffico in uscita ed eseguire il peering con le zone Cloud DNS private nel progetto host.

1 Per l'identità di provisioning, sono sufficienti anche i ruoli di base a livello di progetto, come Visualizzatore (roles/viewer) o Editor (roles/editor) nel progetto host.

2 L'agente di servizio Agent Gateway è formattato come: service-AGENT_GATEWAY_PROJECT_NUMBER@gcp-sa-agentgateway.iam.gserviceaccount.com, dove AGENT_GATEWAY_PROJECT_NUMBER è il numero del progetto in cui esegui il provisioning di Agent Gateway. Per i deployment di VPC condiviso, questo progetto può essere un progetto di servizio o il progetto host.

Se colleghi più progetti di servizio Agent Runtime a un progetto host Agent Gateway, devi anche concedere l'accesso tra progetti nel progetto gateway a ogni agente di servizio Agent Runtime. Per i deployment su larga scala, consulta Scala i progetti di servizio Agent Runtime con un gruppo Google.

Configura la connettività VPC

Per eseguire il deployment di un Agent Gateway con un template di connettività, completa i passaggi descritti nelle sezioni seguenti.

Crea un collegamento di rete Private Service Connect

Crea un collegamento di rete Private Service Connect nella rete VPC di destinazione.

Assicurati che il collegamento di rete soddisfi i seguenti requisiti:

  • Preferenza di connessione: configura il collegamento di rete in modo da accettare automaticamente le connessioni (--connection-preference=ACCEPT_AUTOMATIC).
  • Requisito della stessa rete VPC: la subnet del collegamento di rete e la rete di destinazione configurata per il peering DNS (targetNetwork) devono trovarsi esattamente nella stessa rete VPC. Se la subnet del collegamento di rete appartiene a una rete diversa da quella di destinazione del peering DNS, la convalida della configurazione non va a buon fine.
  • Requisiti delle subnet: tieni presente i seguenti requisiti per la subnet del collegamento di rete:
    • Intervallo di subnet: la subnet del collegamento di rete supporta tutti gli intervalli validi.
    • Dimensioni della subnet: Agent Gateway richiede una subnet minima /28 per il collegamento di rete. Una subnet /28 fornisce 12 indirizzi IP utilizzabili, sufficienti per una singola istanza di Agent Gateway. Se prevedi di connettere più gateway allo stesso collegamento di rete o alla stessa subnet, utilizza una subnet più grande (ad esempio /26 o /24) per evitare l'esaurimento degli indirizzi IP.
    • Requisito per l'accesso privato Google: devi abilitare l'accesso privato Google (private_ip_google_access = true) sulla subnet che ospita il collegamento di rete.
  • Deployment VPC condiviso: per i deployment VPC condiviso, consulta Topologie di deployment VPC condiviso.

Prendi nota dell'URI completo della risorsa del collegamento di rete (ad esempio, projects/NETWORK_ATTACHMENT_PROJECT_NUMBER/regions/NETWORK_ATTACHMENT_REGION/networkAttachments/NETWORK_ATTACHMENT_NAME). Ti servirà quando creerai la risorsa del template di connettività in un passaggio successivo.

(Facoltativo) Configura il peering DNS

Il peering DNS consente ad Agent Gateway di risolvere i nomi DNS utilizzando i record di una zona Cloud DNS privata gestita nella tua rete VPC. Il peering DNS è richiesto solo quando gli agenti devono risolvere nomi di dominio interni privati (come corp.internal.) o applicare i Controlli di servizio VPC per le API di Google (googleapis.com.). Non è richiesto per i domini internet pubblici o per le API di Google standard senza Controlli di servizio VPC.

Agent Gateway supporta il peering DNS transitivo solo fino a un singolo hop transitivo, il che significa un massimo di tre reti VPC. Ad esempio, vpc-net-a (la rete tenant di Agent Gateway) può eseguire il peering con vpc-net-b (rete collegata), che a sua volta esegue il peering con vpc-net-c (rete remota) per risolvere le query DNS nella catena.

Per configurare il peering DNS, segui questi passaggi:

  1. Configura la zona DNS privata nella rete VPC di destinazione. Per aggiungere record DNS alla tua zona DNS privata, consulta Aggiungi un set di record di risorse.

  2. Raccogli le seguenti informazioni per configurare il template di connettività per abilitare il peering:

    • URI della rete di destinazione (targetNetwork): prendi nota dell'URI completo della risorsa della rete VPC di destinazione nel seguente formato: projects/TARGET_VPC_PROJECT_ID/global/networks/TARGET_VPC_NETWORK_NAME. La rete di destinazione è sempre la rete VPC che contiene la subnet a cui fa riferimento il collegamento di rete. Se la rete di destinazione è una rete VPC condivisa, assicurati di utilizzare l'ID progetto host del VPC condiviso corrispondente.

    • Nomi di dominio: uno o più suffissi di dominio per il peering DNS. Ogni dominio deve terminare con un punto finale (.) (ad esempio, corp.internal. o googleapis.com.).

      Per ulteriori indicazioni su come configurare il campo domains, consulta Pattern di dominio di peering DNS. Per i deployment tra progetti, come il VPC condiviso, consulta Requisiti per le zone DNS e il peering tra progetti.

(Facoltativo) Configura la configurazione di attendibilità TLS

Se la destinazione di destinazione utilizza una CA privata o un certificato autofirmato, devi creare una risorsa TrustConfig in Certificate Manager. La risorsa TrustConfig definisce i trust anchor e i certificati che Agent Gateway utilizza per convalidare le connessioni TLS.

  1. Prepara i file dei certificati in formato PEM:

    • Archivio di attendibilità: certificati CA radice o intermedi in formato PEM. Agent Gateway considera attendibile qualsiasi certificato del server la cui catena di attendibilità rimanda a uno di questi certificati CA. L'archivio di attendibilità deve contenere almeno un certificato CA radice o intermedio.
    • Certificati inclusi nella lista consentita (facoltativo): certificati server in formato PEM che vuoi considerare esplicitamente attendibili, ad esempio un certificato autofirmato.

  2. Esegui il comando seguente per creare la risorsa TrustConfig. TrustConfig deve essere creato nello stesso progetto e nella stessa regione dell'Agent Gateway e del template di connettività.

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

    Sostituisci quanto segue:

    • TRUST_CONFIG_NAME: un nome per la risorsa TrustConfig.
    • LOCATION: la regione per la configurazione di attendibilità (ad esempio europe-west1). Deve essere la stessa regione dell'Agent Gateway e del template di connettività.
    • ROOT_CERT_FILE: il percorso del certificato CA radice o intermedio con codifica PEM.
    • ALLOWLISTED_CERT_FILE: (facoltativo) il percorso di un certificato con codifica PEM che vuoi considerare attendibile in modo esplicito. Se non utilizzi certificati inclusi nella lista consentita, ometti questo flag.

    Per ulteriori informazioni sulla gestione delle configurazioni di attendibilità, consulta Crea e gestisci le configurazioni di attendibilità.

Esegui il deployment di Agent Gateway

  1. Crea il file di configurazione del template di connettività:

    Crea un file YAML denominato 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

    Sostituisci quanto segue:

    • AGENT_GATEWAY_PROJECT_NUMBER: il numero di progetto del progetto Google Cloud in cui esegui il provisioning dell'Agent Gateway. Per recuperare il numero del progetto, esegui: gcloud projects describe PROJECT_ID --format="value(projectNumber)".

    • LOCATION: la regione del template di connettività (ad esempio europe-west1).

    • CONNECTIVITY_TEMPLATE_NAME: il nome della risorsa del template di connettività.

    • accessPath: Il percorso di accesso governato per il modello di connettività. Imposta su AGENT_TO_ANYWHERE (i template di connettività sono supportati solo per i gateway in uscita).

    • deploymentModel: il modello di deployment del gateway. Impostalo su CENTRALIZED.

    • networkAttachment: l'URI completo della risorsa del collegamento di rete Private Service Connect:

      • NETWORK_ATTACHMENT_PROJECT_NUMBER: il numero del progetto in cui hai creato il collegamento di rete. Questo progetto potrebbe essere lo stesso del progetto Agent Gateway o un progetto diverso se esegui il provisioning di Agent Gateway in un progetto di servizio VPC condiviso e crei il collegamento di rete nel progetto host del VPC condiviso.
      • NETWORK_ATTACHMENT_REGION: la regione che contiene il collegamento di rete.
      • NETWORK_ATTACHMENT_NAME: il nome del collegamento di rete.

    • DOMAIN_NAME: (facoltativo) uno o più suffissi di dominio per il peering DNS (ad esempio corp.internal., googleapis.com. o .). Aggiungi una voce dell'elenco in domains per ogni suffisso di dominio per cui vuoi eseguire il peering. Ogni valore deve terminare con un punto (.) e avere una zona gestita Cloud DNS privata corrispondente autorizzata per la rete di destinazione.

      Per ulteriori indicazioni su come configurare il campo domains, consulta Pattern di dominio di peering DNS.

    • targetNetwork: (facoltativo) l'URI completo della risorsa della rete VPC di destinazione per il peering DNS. La rete di destinazione è sempre la rete VPC che contiene la subnet a cui fa riferimento il collegamento di rete:

      • TARGET_VPC_PROJECT_ID: l'ID progetto del progetto proprietario della rete VPC di destinazione. Se la rete che contiene la subnet a cui fa riferimento il collegamento di rete è una rete VPC condivisa, TARGET_VPC_PROJECT_ID è l'ID progetto host del VPC condiviso. Specifica sempre targetNetwork utilizzando l'ID progetto anziché il numero di progetto.
      • TARGET_VPC_NETWORK_NAME: il nome della rete VPC di destinazione.

    • VPC_EGRESS_MODE: imposta la modalità di routing in uscita. Imposta su PRIVATE_RANGES_ONLY o ALL_TRAFFIC.

    • tlsConfig: (facoltativo) la configurazione TLS per la convalida del certificato del server durante la connessione agli endpoint privati tramite HTTPS:

      • TRUST_CONFIG_NAME: Il nome della risorsa Certificate Manager TrustConfig contenente i certificati CA privati ​​o i trust anchor.
      • ADDITIONAL_ROOTS_OPTION: specifica se considerare attendibili le radici delle CA attendibili pubblicamente oltre alla configurazione di attendibilità personalizzata:
      • Imposta su PUBLICLY_TRUSTED_ROOTS (predefinito) per considerare attendibili sia i certificati convalidati dal parametro trustConfig sia tutte le CA pubblicamente attendibili. Devi impostare additionalRoots su PUBLICLY_TRUSTED_ROOTS se i tuoi agenti si connettono anche alle APIGoogle Cloud (*.googleapis.com) o ad altri endpoint HTTPS pubblici; senza questa impostazione, Agent Gateway non considererà attendibili i certificati firmati da Google per googleapis.com.
      • Imposta su NO_ADDITIONAL_ROOTS per considerare attendibili solo i certificati convalidati dal parametro trustConfig.

  2. Crea il template di connettività:

    Esegui questo comando per creare il template di connettività:

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

    Sostituisci quanto segue:

    • CONNECTIVITY_TEMPLATE_NAME: il nome della risorsa del template di connettività.
    • LOCATION: la località in cui vuoi creare la risorsa del template di connettività. Ad esempio, europe-west1.

  3. Definisci la risorsa Agent Gateway:

    Definisci una nuova risorsa Agent Gateway in modalità AGENT_TO_ANYWHERE creando un file di configurazione YAML del gateway (ad esempio my-agent-gateway-vpc-egress.yaml) che fa riferimento al template di connettività:

    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

    Sostituisci quanto segue:

    • AGENT_GATEWAY_NAME: il nome della risorsa Agent Gateway.

    • AGENT_GATEWAY_PROJECT_NUMBER: il numero di progetto del progetto Google Cloud in cui esegui il provisioning di Agent Gateway e del template di connettività. Per i deployment VPC condiviso, questo progetto può essere un progetto di servizio o il progetto host. Per recuperare il numero del progetto, esegui: gcloud projects describe PROJECT_ID --format="value(projectNumber)".

    • LOCATION: la località del template di connettività (ad esempio europe-west1).

    • CONNECTIVITY_TEMPLATE_NAME: il nome della risorsa del template di connettività.

      • AGENT_REGISTRY_PATH: il percorso dell'istanza di Agent Registry regionale nello stesso progetto e nella stessa regione del gateway, formattato come //agentregistry.googleapis.com/projects/PROJECT_ID/locations/LOCATION. Per indicazioni, consulta Pianifica il deployment di Agent Gateway.

  4. Importa ed esegui il deployment di Agent Gateway:

    Esegui questo comando per creare la risorsa Agent Gateway in base alla specifica YAML:

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

    Sostituisci LOCATION con la località in cui vuoi creare la risorsa Agent Gateway. Ad esempio, europe-west1.

Considerazioni su architettura e networking

Questa sezione fornisce indicazioni sull'architettura e pattern di networking avanzati per il deployment di Agent Gateway con connettività VPC.

Aggiornamento delle impostazioni del traffico VPC in uscita

Un template di connettività non può essere modificato in loco mentre è referenziato da un Agent Gateway e l'Agent Gateway non rileva automaticamente le modifiche apportate a un template di connettività collegato:

  • Aggiornamento delle impostazioni di peering DNS, modalità di uscita VPC o TLS (tlsConfig): in un template di connettività, il campo tlsConfig.trustConfig non è modificabile una volta configurato e gli aggiornamenti in loco di tlsConfig (come l'aggiunta o la modifica di additionalRoots) non vengono rilevati da un Agent Gateway collegato. Per aggiornare la configurazione del peering DNS, la modalità di traffico in uscita VPC o le impostazioni tlsConfig su un gateway esistente, crea un nuovo template di connettività che utilizzi lo stesso networkAttachment con le impostazioni aggiornate e aggiorna l'Agent Gateway in modo che faccia riferimento al nuovo template (o scollega e ricollega il template di connettività).

  • Modifica del collegamento di rete: networkAttachment stesso è immutabile una volta configurato sia sul template di connettività sia su Agent Gateway. Per passare a un altro collegamento di rete (o a una rete VPC di destinazione), devi creare un nuovo template di connettività e un nuovo Agent Gateway.

Topologie di deployment del VPC condiviso

In un'architettura VPC condiviso, puoi eseguire il provisioning di Agent Gateway in un progetto di servizio o nel progetto host. Quando esegui il provisioning di Agent Gateway in un progetto di servizio, puoi creare il collegamento di rete nel progetto di servizio (consigliato) o nel progetto host:

Conformità ai Controlli di servizio VPC

Per applicare i perimetri dei Controlli di servizio VPC per le comunicazioni degli agenti, assicurati di quanto segue:

  • Imposta vpcEgress su ALL_TRAFFIC nel tuo template di connettività.

  • Indirizza le richieste API di Google all'intervallo IP restricted.googleapis.com (199.36.153.4/30) o a un endpoint Private Service Connect interno per le API di Google.

  • Configura la risoluzione DNS per googleapis.com. Crea una zona Cloud DNS privata nella rete VPC mappando *.googleapis.com a restricted.googleapis.com e includi googleapis.com. nel campo domains del template di connettività.

    Per maggiori dettagli sulla configurazione del DNS, consulta Configura il DNS per googleapis.com nella documentazione sull'accesso privato Google.

  • Per i deployment di VPC condiviso, il progetto host proprietario della subnet del collegamento di rete e l'dnsPeeringConfig.targetNetwork devono trovarsi nello stesso perimetro di servizio del progetto in cui esegui il deployment di Agent Gateway. Questo vale anche se crei il collegamento di rete nel progetto di servizio, perché la subnet e la rete VPC appartengono comunque al progetto host. Se le tue zone DNS private sono ospitate in un progetto DNS separato, includi anche questo progetto nel perimetro.

Pattern dei domini di peering DNS

Questa sezione descrive i pattern di risoluzione dei domini e le opzioni per configurare il campo domains in un template di connettività.

Configurazione del nome di dominio: configura il campo domains nel template di connettività in base alle seguenti considerazioni:

  • Domini interni privati: per risolvere i servizi interni privati ospitati nella tua rete VPC (ad esempio service.corp.internal), specifica il suffisso del dominio interno (ad esempio corp.internal.). Una zona Cloud DNS gestita privata con corrispondenza esatta per questo dominio deve essere autorizzata per la rete VPC di destinazione.

  • DNS split-horizon (dominio pubblico con IP RFC 1918): se utilizzi una zona DNS pubblica per ospitare record che puntano a IP privati interni (ad esempio mcp.example.com che si risolve in un indirizzo RFC 1918 per i certificati pubblici di Certificate Manager), il gateway risolve questi record automaticamente utilizzando il DNS ricorsivo pubblico senza richiedere il peering DNS.

  • APIGoogle Cloud con Controlli di servizio VPC: quando ALL_TRAFFIC è configurato per applicare i Controlli di servizio VPC, le richieste API di Google devono essere risolte nell'intervallo IP restricted.googleapis.com (199.36.153.4/30) o negli endpoint PSC interni. Crea una zona Cloud DNS privata nella rete VPC mappando *.googleapis.com a restricted.googleapis.com e includi googleapis.com. nel campo domains del modello di connettività.

  • Pattern di risoluzione multidominio: se il tuo deployment richiede la risoluzione di più suffissi di dominio privato, scegli uno dei seguenti pattern:

    • Esegui il peering di più domini singoli: specifica un elenco di suffissi di dominio nel campo domains di dnsPeeringConfig (ad esempio, corp.internal., prod.internal. e googleapis.com.). Ogni dominio nell'elenco deve terminare con un punto finale (.) e avere una zona Cloud DNS privata gestita corrispondente autorizzata per la rete VPC di destinazione.
    • Suffisso principale consolidato (consigliato): consolida i servizi interni in un suffisso di dominio principale condiviso (ad esempio *.internal. o *.corp.internal.) e includi il dominio principale nell'elenco domains.

    • Peering root catch-all con una zona di forwarding privato: includi "." nel campo domains del template di connettività e configura una zona di forwarding privato Cloud DNS per il dominio principale (.) nella tua rete VPC che punta a un resolver ricorsivo upstream (come 8.8.8.8 o un resolver aziendale interno). Le zone private più specifiche nella tua rete VPC vengono abbinate per prime in base alla corrispondenza del suffisso più lungo, mentre le query pubbliche senza corrispondenza vengono risolte tramite l'agente di inoltro upstream.

Requisiti per le zone DNS e il peering tra progetti

L'impostazione dnsPeeringConfig del template di connettività non supporta il peering Cloud DNS diretto tra progetti. Quando importi il template di connettività, la convalida non va a buon fine se la subnet a cui fa riferimento networkAttachment appartiene a una rete VPC diversa da targetNetwork o se utilizzi l'associazione di zone DNS tra progetti da un servizio o un progetto esterno.

La zona gestita per il dominio deve essere creata nel progetto host proprietario di targetNetwork. La zona gestita può essere uno dei seguenti tipi di zona:

  • Zona privata autorevole
  • Zona di forwarding
  • Zona di peering Cloud DNS: deve essere associata alla rete VPC del progetto host e avere come target una rete VPC di destinazione. Il VPC di destinazione deve risolvere la query direttamente utilizzando una zona privata autoritativa. Il forwarding della query a un'altra zona di peering DNS (concatenamento) non è supportato e genera un errore NXDOMAIN.

Scala i progetti di servizio Agent Runtime con un gruppo Google

Se colleghi più progetti di servizio Agent Runtime a un progetto host Agent Gateway e concedi l'accesso tra progetti a ogni agente di servizio singolarmente, devi aggiornare la policy IAM del progetto host ogni volta che aggiungi un progetto. In deployment su larga scala, potresti anche raggiungere i limiti delle policy IAM man mano che aggiungi associazioni di ruoli.

Per evitare di aggiornare la policy IAM del progetto host per ogni nuovo progetto di servizio, puoi gestire l'accesso tramite un unico gruppo di sicurezza Google:

  1. Crea un gruppo di sicurezza: crea un gruppo di sicurezza nella Console di amministrazione Google o eseguendo il comando gcloud identity groups create.

  2. Concedi al gruppo l'accesso al progetto host di Agent Gateway: associa il gruppo al ruolo Network Services Viewer (roles/networkservices.viewer) su AGENT_GATEWAY_PROJECT_ID:

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

    Sostituisci quanto segue:

    • AGENT_GATEWAY_PROJECT_ID: l'ID progetto del progetto host di Agent Gateway.
    • GROUP_EMAIL: l'indirizzo email del tuo gruppo di sicurezza (ad esempio agw-cross-project-runtime@example.com).

  3. Aggiungi l'agente di servizio Agent Runtime di ogni progetto di servizio al gruppo: per ogni progetto di servizio Agent Runtime, aggiungi il relativo agente di servizio al gruppo di sicurezza eseguendo il comando gcloud identity groups memberships add come segue:

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

    Sostituisci AGENT_RUNTIME_PROJECT_NUMBER con il numero di progetto del progetto di servizio Agent Runtime.

Passaggi successivi

Guida

Scopri come instradare il traffico di Agent Runtime tramite Agent Gateway per una connettività sicura e controllata.

Codelab

Scopri come gestire i workload degli agenti con Agent Gateway su Gemini Enterprise Agent Platform.

Codelab

Scopri di più sulla governance del traffico in uscita di Agent Gateway per gli agenti AI che accedono alle destinazioni in una rete VPC.

Guida

Scopri come delegare l'autorizzazione per Agent Gateway a IAP, Model Armor o al tuo servizio di autorizzazione personalizzato.

Guida

Scopri come monitorare Agent Gateway.

Guida

Scopri come instradare il traffico di Gemini Enterprise tramite Agent Gateway.