Accedere ad Apigee in modalità privata da Gemini Enterprise Agent Platform

Questa pagina si applica ad Apigee, ma non ad Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Questo documento descrive come configurare la connettività privata da un agente di cui è stato eseguito il deployment su Gemini Enterprise Agent Platform Agent Runtime alle API e agli strumenti Model Context Protocol (MCP) pubblicati su Apigee, utilizzando Private Service Connect. Con questo pattern, il traffico dall'agente ad Apigee rimane completamente privato e non attraversa la rete internet pubblica.

Panoramica

Agent Runtime esegue il deployment dell'agente in una rete sicura e gestita da Google senza accesso alla rete Virtual Private Cloud (VPC). Apigee viene eseguito in modo simile in una rete sicura gestita da Google. Quando vuoi che le chiamate di un agente a un modello linguistico di grandi dimensioni (LLM) o agli strumenti MCP esposti tramite Apigee vengano trasmesse privatamente, devi trovare un modo per collegare queste due reti gestite da Google tramite una rete VPC che controlli.

Questo documento descrive il seguente pattern per questo bridge:

Con questa configurazione, quando l'agente chiama https://APIGEE_HOSTNAME/..., la richiesta viene risolta nell'IP dell'endpoint Private Service Connect nel tuo VPC, viene inoltrata tramite il collegamento del servizio all'istanza Apigee ed è elaborata dal proxy API che corrisponde al percorso della richiesta.

Prima di iniziare

Questo documento utilizza i seguenti segnaposto nei comandi. Sostituiscili con i valori del tuo ambiente.

  • APIGEE_PROJECT_ID: l'ID progetto Google Cloud che contiene la tua organizzazione Apigee.
  • SERVICE_PROJECT_ID: l' Google Cloud ID progetto in cui esegui il deployment dell'agente su Agent Runtime. Può essere lo stesso di APIGEE_PROJECT_ID o un progetto diverso, a seconda di come organizzi le risorse Google Cloud.
  • SERVICE_PROJECT_NUMBER: il numero di progetto numerico per SERVICE_PROJECT_ID. Puoi recuperarlo con gcloud projects describe SERVICE_PROJECT_ID --format="value(projectNumber)".
  • HOST_PROJECT_ID: l'ID progetto Google Cloud che contiene la rete VPC consumer, la subnet e la zona privata Cloud DNS. Questo è uguale a SERVICE_PROJECT_ID, a meno che tu non utilizzi VPC condiviso, nel qual caso si tratta del progetto host a cui si collega il progetto di servizio.
  • REGION: la regione dell'istanza Apigee (ad esempio us-west1).
  • VPC_NAME: il nome della rete VPC consumer in HOST_PROJECT_ID.
  • SUBNET_NAME: il nome di una subnet in VPC_NAME che si trova in REGION.
  • APIGEE_HOSTNAME: il nome host che hai configurato nel gruppo di ambienti Apigee (ad esempio, api.internal.example.com).
  • BASE_PATH: il percorso di base del proxy API di cui è stato eseguito il deployment su Apigee (ad esempio, /mcp o /orders).
  • PARENT_DNS_NAME: il dominio DNS principale di APIGEE_HOSTNAME che vuoi pubblicare dalla zona privata (ad esempio, internal.example.com.). Il valore deve terminare con un punto.
  • APIGEE_INSTANCE_NAME: il nome dell'istanza Apigee in REGION.

Ti serviranno:

  • Uno o più progetti Google Cloud (come descritto nella nota precedente) con la fatturazione abilitata.
  • Un'organizzazione Apigee esistente in APIGEE_PROJECT_ID con almeno un'istanza. Questo documento crea tutte le risorse di networking consumer (collegamento di rete, endpoint Private Service Connect, deployment di Agent Runtime) nella stessa regione dell'istanza Apigee, che è la configurazione più semplice.
  • Un gruppo di ambienti i cui ambienti vengono implementati in quell'istanza Apigee e che include il nome host che vuoi che l'agente chiami. Questo documento si riferisce a questo nome host come APIGEE_HOSTNAME.
  • Almeno un proxy API di cui è stato eseguito il deployment in un ambiente del gruppo di ambienti. Tutti i proxy che vuoi che l'agente chiami devono essere raggiungibili all'indirizzo https://APIGEE_HOSTNAME/BASE_PATH.
  • Una rete VPC e una subnet in HOST_PROJECT_ID, nella stessa regione dell'istanza Apigee. Questo documento si riferisce a questi come VPC_NAME e SUBNET_NAME. Agent Runtime richiede una subnet minima di /28 e impone ulteriori limitazioni di intervallo. Per maggiori dettagli, vedi Requisiti dell'intervallo IP della subnet nella documentazione di Agent Platform.
  • Le seguenti API abilitate nel progetto appropriato:
    • Apigee (apigee.googleapis.com) in APIGEE_PROJECT_ID.
    • Compute Engine (compute.googleapis.com) e Cloud DNS (dns.googleapis.com) in HOST_PROJECT_ID.
    • Agent Platform (aiplatform.googleapis.com) in SERVICE_PROJECT_ID.
  • Autorizzazioni IAM sufficienti per creare zone e record Cloud DNS, indirizzi Compute Engine, collegamenti di rete e regole di forwarding Private Service Connect in HOST_PROJECT_ID e per aggiornare la configurazione dell'istanza e del gruppo di ambienti Apigee in APIGEE_PROJECT_ID. Per informazioni dettagliate sui ruoli richiesti, consulta Ruoli Apigee, Controllo dell'accesso a Cloud DNS e Ruoli IAM di Compute Engine.

Architettura

I seguenti passaggi descrivono il flusso di traffico tra un agente di cui è stato eseguito il deployment in Agent Runtime e un proxy API ospitato su Apigee, utilizzando un endpoint Private Service Connect in un VPC consumer come bridge.

  1. L'agente, in esecuzione su Agent Runtime, effettua una richiesta HTTPS a APIGEE_HOSTNAME.
  2. Il peering DNS configurato sull'interfaccia PSC di Agent Runtime inoltra la ricerca alla zona privata Cloud DNS nel tuo VPC consumer, che restituisce l'indirizzo IP dell'endpoint Private Service Connect.
  3. La richiesta dell'agente esce tramite l'interfaccia PSC nel tuo VPC consumer e raggiunge l'endpoint Private Service Connect su quell'indirizzo IP.
  4. L'endpoint Private Service Connect inoltra la richiesta tramite la connessione di servizio al collegamento di servizio dell'istanza Apigee.
  5. L'istanza Apigee termina TLS, associa il nome host della richiesta al gruppo di ambienti e indirizza al proxy API corretto.

Passaggio 1: configura il networking nel VPC consumer

Questa sezione configura le risorse in due progetti. Ogni comando include un flag --project esplicito, in modo da poter eseguire i comandi da qualsiasi configurazione gcloud attiva:

  • Le risorse Cloud DNS (zona privata e record) vengono create in HOST_PROJECT_ID, perché la zona privata è collegata alla rete VPC consumer.
  • Le risorse endpoint Private Service Connect (indirizzo IP interno statico e regola di forwarding) e il collegamento di rete vengono create in SERVICE_PROJECT_ID. Ciascuno di questi comandi utilizza un riferimento tra progetti alla subnet condivisa o alla rete VPC in HOST_PROJECT_ID. In un deployment a progetto singolo, SERVICE_PROJECT_ID e HOST_PROJECT_ID sono uguali, quindi non ci sono modifiche alla proprietà nei vari passaggi. Per saperne di più sul modello VPC condiviso per gli endpoint Private Service Connect, consulta Creare un endpoint in un progetto di servizio VPC condiviso.

Crea una zona privata Cloud DNS

Crea una zona privata Cloud DNS visibile solo al tuo VPC consumer. L'agente utilizza questa zona (tramite peering DNS) per risolvere APIGEE_HOSTNAME in un indirizzo IP privato. 

gcloud dns managed-zones create apigee-private \
  --project=HOST_PROJECT_ID \
  --dns-name="PARENT_DNS_NAME" \
  --description="Private zone for Apigee PSC access" \
  --visibility=private \
  --networks=VPC_NAME

Per saperne di più sulle zone private Cloud DNS, consulta Zone private.

Crea un collegamento di rete

Crea un collegamento di rete nella stessa regione e subnet in cui vuoi che venga visualizzata l'interfaccia PSC di Agent Runtime. Agent Runtime associa la propria interfaccia PSC a questo collegamento quando l'agente viene implementato.

In un deployment a progetto singolo, crea il collegamento di rete in SERVICE_PROJECT_ID (che è anche HOST_PROJECT_ID). In un deployment VPC condiviso, puoi creare il collegamento di rete nel progetto di servizio o nel progetto host; Agent Platform consiglia il progetto di servizio per semplificare le autorizzazioni. Per indicazioni sulla scelta e sui ruoli IAM corrispondenti, consulta Utilizzo dell'interfaccia Private Service Connect con VPC condiviso.

Il seguente comando crea il collegamento di rete in SERVICE_PROJECT_ID. In un deployment VPC condiviso, il riferimento alla subnet deve includere l'ID progetto host. 

gcloud compute network-attachments create agent-network-attachment \
  --project=SERVICE_PROJECT_ID \
  --region=REGION \
  --subnets=projects/HOST_PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME \
  --connection-preference=ACCEPT_AUTOMATIC

Prenota un indirizzo IP interno statico

Riserva un indirizzo IP interno da utilizzare come IP dell'endpoint Private Service Connect a cui si connette l'agente. Crea la risorsa indirizzo in SERVICE_PROJECT_ID e fai riferimento alla subnet condivisa in HOST_PROJECT_ID in modo che il valore dell'indirizzo venga allocato dall'intervallo di questa subnet. Ciò corrisponde alle indicazioni per VPC condiviso in Utilizzare un indirizzo IP interno statico con VPC condiviso. 

gcloud compute addresses create apigee-psc-endpoint-ip \
  --project=SERVICE_PROJECT_ID \
  --region=REGION \
  --subnet=projects/HOST_PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME

Recupera l'indirizzo riservato, che utilizzerai nei passaggi successivi: 

gcloud compute addresses describe apigee-psc-endpoint-ip \
  --project=SERVICE_PROJECT_ID \
  --region=REGION \
  --format="value(address)"

Questo documento fa riferimento a questo indirizzo come PSC_ENDPOINT_IP.

Recupera il collegamento al servizio per l'istanza Apigee

Recupera l'URI del collegamento al servizio per la tua istanza Apigee utilizzando il metodo organizations.instances.get dell'API Apigee. Utilizzi questo URI come destinazione per l'endpoint Private Service Connect. 

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://apigee.googleapis.com/v1/organizations/APIGEE_PROJECT_ID/instances/APIGEE_INSTANCE_NAME"

La risposta include un campo serviceAttachment. Questo documento si riferisce a questo valore come APIGEE_SERVICE_ATTACHMENT. Per saperne di più su come Apigee espone un collegamento al servizio su ogni istanza, consulta Gestione delle istanze.

Crea l'endpoint Private Service Connect

Crea una regola di forwarding che funge da endpoint Private Service Connect. Ha come target l'allegato del servizio Apigee e utilizza l'IP statico che hai prenotato. Crea la regola di forwarding in SERVICE_PROJECT_ID e fai riferimento alla rete VPC condivisa in HOST_PROJECT_ID e all'indirizzo in SERVICE_PROJECT_ID. 

gcloud compute forwarding-rules create apigee-psc-endpoint \
  --project=SERVICE_PROJECT_ID \
  --region=REGION \
  --network=projects/HOST_PROJECT_ID/global/networks/VPC_NAME \
  --address=projects/SERVICE_PROJECT_ID/regions/REGION/addresses/apigee-psc-endpoint-ip \
  --target-service-attachment=APIGEE_SERVICE_ATTACHMENT

Verifica che il servizio Apigee abbia accettato la connessione: 

gcloud compute forwarding-rules describe apigee-psc-endpoint \
  --project=SERVICE_PROJECT_ID \
  --region=REGION \
  --format="value(pscConnectionStatus)"

Lo stato deve essere ACCEPTED prima che l'endpoint possa inoltrare il traffico. Per ulteriori informazioni sugli endpoint Private Service Connect, consulta Informazioni sull'accesso ai servizi pubblicati tramite endpoint.

Aggiungi un record DNS per il nome host

Nella zona privata, crea un record A che risolve APIGEE_HOSTNAME in PSC_ENDPOINT_IP. Questo record è visibile solo all'interno di VPC_NAME, quindi i client esterni continuano a risolvere il nome host tramite il DNS pubblico. 

gcloud dns record-sets create APIGEE_HOSTNAME. \
  --project=HOST_PROJECT_ID \
  --zone=apigee-private \
  --type=A \
  --ttl=60 \
  --rrdatas=PSC_ENDPOINT_IP

Passaggio 2: configura Apigee

Aggiungi il progetto di servizio all'elenco di accettazione dei consumer dell'istanza

L'istanza Apigee accetta solo connessioni Private Service Connect dai progetti consumer che si trovano nel suo consumerAcceptList. Il lato consumer della connessione è associato a SERVICE_PROJECT_ID, perché è il progetto in cui è stato eseguito il deployment dell'agente.

Per impostazione predefinita, il progetto associato all'organizzazione Apigee (APIGEE_PROJECT_ID) è già nell'elenco. Se SERVICE_PROJECT_ID è uguale a APIGEE_PROJECT_ID, non è necessaria alcuna modifica e puoi saltare questa sezione. In caso contrario, aggiungi SERVICE_PROJECT_ID all'elenco.

Per prima cosa, controlla il valore attuale di consumerAcceptList utilizzando il metodo organizations.instances.get: 

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://apigee.googleapis.com/v1/organizations/APIGEE_PROJECT_ID/instances/APIGEE_INSTANCE_NAME"

Cerca il campo consumerAcceptList nella risposta.

Poi aggiorna l'elenco chiamando il metodo organizations.instances.patch con una maschera di aggiornamento su consumerAcceptList. Poiché il campo sostituisce l'elenco esistente, includi ogni ID progetto che deve mantenere l'accesso, inclusi APIGEE_PROJECT_ID e tutti i progetti di servizio aggiuntivi che eseguono il deployment degli agenti: 

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{"consumerAcceptList": ["APIGEE_PROJECT_ID", "SERVICE_PROJECT_ID"]}' \
  "https://apigee.googleapis.com/v1/organizations/APIGEE_PROJECT_ID/instances/APIGEE_INSTANCE_NAME?updateMask=consumerAcceptList"

Conferma l'aggiornamento eseguendo di nuovo il comando get e verificando che SERVICE_PROJECT_ID sia ora incluso in consumerAcceptList.

Verifica il nome host del gruppo di ambienti

Verifica che APIGEE_HOSTNAME sia elencato nel gruppo di ambienti che ospita i tuoi proxy API. In caso contrario, aggiungilo.

Per istruzioni, vedi Utilizzo dei gruppi di ambienti.

Passaggio 3: esegui il deployment dell'agente con un'interfaccia PSC e il peering DNS

Quando esegui il deployment dell'agente in Agent Runtime, configuralo con un'interfaccia PSC che fa riferimento al collegamento di rete che hai creato e configura il peering DNS alla tua zona privata. Per la procedura di deployment completa e i framework supportati, consulta Utilizzo dell'interfaccia Private Service Connect con Agent Runtime e Deploy di agenti nella documentazione di Agent Platform.

Configura i seguenti due campi nella configurazione dell'interfaccia PSC dell'agente (vedi il riferimento PscInterfaceConfig):

  • networkAttachment: imposta questo valore sul nome completo della risorsa del collegamento di rete creato nel passaggio 1, nel formato projects/SERVICE_PROJECT_ID/regions/REGION/networkAttachments/agent-network-attachment. Se hai creato il collegamento di rete nel progetto host, utilizza HOST_PROJECT_ID in questo percorso.
  • dnsPeeringConfigs: aggiungi una voce con i seguenti campi, in modo che Agent Runtime risolva APIGEE_HOSTNAME tramite la tua zona privata:
    • domain: PARENT_DNS_NAME. Il valore deve terminare con un punto.
    • targetProject: HOST_PROJECT_ID. Questo è il progetto che contiene il VPC consumer e la zona privata.
    • targetNetwork: VPC_NAME.

Il service agent Agent Platform Service per SERVICE_PROJECT_ID (service-SERVICE_PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com) deve disporre dell'autorizzazione per configurare il peering DNS e aggiornare l'allegato di rete. Concedi i ruoli richiesti come descritto in Ruolo richiesto per il service agent della piattaforma dell'agente. In un deployment VPC condiviso, vengono applicati ruoli aggiuntivi al progetto host. Per maggiori dettagli, consulta Utilizzo dell'interfaccia Private Service Connect con il VPC condiviso.

Dal codice dell'agente, chiama il proxy API all'indirizzo https://APIGEE_HOSTNAME/BASE_PATH. All'interno dell'ambiente Agent Runtime, questo nome host viene risolto tramite peering DNS in PSC_ENDPOINT_IP e la richiesta attraversa l'endpoint Private Service Connect nella tua rete VPC e in Apigee.

Verifica il percorso privato

Dopo aver eseguito il deployment dell'agente, verifica che le richieste raggiungano Apigee tramite il percorso privato:

  • Verifica che lo stato della regola di forwarding sia ACCEPTED utilizzando il comando in Crea l'endpoint Private Service Connect.
  • Da una VM Compute Engine collegata a VPC_NAME in REGION (in un deployment VPC condiviso, questa VM può trovarsi nel progetto host o in un progetto di servizio collegato al VPC condiviso), esegui dig +short APIGEE_HOSTNAME. Il risultato deve essere PSC_ENDPOINT_IP. Ciò conferma che la zona privata risolve correttamente il nome host all'interno del VPC.
  • Dalla stessa VM, invia una richiesta a un proxy API di cui è stato eseguito il deployment all'indirizzo https://APIGEE_HOSTNAME/BASE_PATH e verifica di ricevere la risposta prevista.
  • Richiama l'agente di cui è stato eseguito il deployment e conferma che la richiesta sia stata gestita. Poi utilizza Apigee Analytics o Debug per verificare che la richiesta sia arrivata al proxy API previsto sul nome host del gruppo di ambienti.

Passaggi successivi