Esegui il deployment di un agente e di Agent Gateway con i Controlli di servizio VPC

1. Introduzione

Questo codelab ti guida nella configurazione di un ambiente Google Cloud per configurare un agente e un Agent Gateway con perimetri dei Controlli di servizio VPC. Stabilisci un perimetro dei Controlli di servizio VPC, configura la rete e il DNS, implementa un Agent Gateway con l'autorizzazione delle richieste di Identity-Aware Proxy (IAP) e testa l'agente in modo sicuro.

Cosa creerai

In questo codelab, crei un'architettura Google Cloud sicura per Gemini Enterprise Agent Platform e Agent Gateway che esegue le seguenti operazioni:

Cosa imparerai a fare

  • Come abilitare le API Google Cloud richieste per Agent Platform e la sicurezza.
  • Come configurare un perimetro dei Controlli di servizio VPC e regole di accesso in entrata.
  • Come configurare la connettività di rete privata e i record DNS privati.
  • Come creare un Agent Gateway e modelli di connettività dell'agente.
  • Come configurare le estensioni e le policy di autorizzazione delle richieste IAP.
  • Come eseguire il deployment e testare in modo sicuro un agente Agent Engine.

Che cosa ti serve

  • Google Cloud CLI installato e aggiornato all'ultima versione.
  • Python 3 installato sulla workstation.
  • Git installato sulla workstation.
  • Un'organizzazione Google Cloud attiva e autorizzazioni per l'account di fatturazione.

2. Prerequisiti

Questa sezione descrive i requisiti di base degli strumenti a riga di comando e la configurazione dell'ambiente necessaria prima di eseguire gli script di configurazione.

  1. Verifica che Google Cloud CLI sia installata e aggiornata all'ultima versione, quindi esegui l'autenticazione con il tuo Account Google. Aggiorna i componenti di Google Cloud CLI per assicurarti di avere il supporto delle funzionalità più recenti per i servizi di rete e i controlli di servizio VPC.
gcloud components update
gcloud auth login
gcloud config set account USER_EMAIL
  1. Verifica che Python 3 sia installato per configurare e implementare il framework dell'agente personalizzato. Per istruzioni, vedi Installazione di moduli Python:
python3 --version
  1. Assicurati che Git sia installato per clonare il repository di esempio contenente il codice di configurazione e i modelli di configurazione. Per istruzioni, vedi Installazione di Git.

3. Configurare un progetto Google Cloud

La creazione di un progetto isolato all'interno della tua organizzazione garantisce che tutte le risorse, le reti e le autorizzazioni utilizzate in questo codelab rimangano incapsulate e gestibili. Scopri di più su Creare e gestire progetti.

Inizializza un nuovo progetto cloud Google Cloud nella tua organizzazione per ospitare le risorse per questa configurazione. Puoi anche utilizzare il tuo progetto:

export PROJ_ID="YOUR_PROJECT_ID"
gcloud projects create ${PROJ_ID} --organization=YOUR_ORG_ID
gcloud config set project $PROJ_ID
gcloud auth application-default set-quota-project $PROJ_ID

Ottieni le credenziali predefinite dell'applicazione accedendo:

gcloud auth application-default login

Verifica la configurazione:

gcloud config list

Abilita fatturazione

Collega un account di fatturazione attivo al progetto appena creato per attivare l'utilizzo del servizio.

L'attivazione della fatturazione è un prerequisito per utilizzare la quota API e il provisioning dell'infrastruttura cloud di Google Cloud, come i gateway agent, i cloud privati virtuali e i nodi di calcolo. Per informazioni dettagliate sulle configurazioni di fatturazione, consulta la documentazione sulla fatturazione di Google Cloud.

gcloud billing accounts list
# Copy the billing account to assign to your GCP project
gcloud billing projects link $PROJ_ID --billing-account=BILLING_ACCOUNT_ID

4. Attiva i servizi

Abilita tutte le API Google Cloud richieste per le funzionalità di agente, gateway dell'agente, networking, sicurezza e osservabilità.

L'attivazione dell'API espone i servizi cloud di backend per la gestione delle risorse, l'osservabilità e le funzionalità di networking necessarie per la connettività sicura degli agenti. Scopri di più nella documentazione dell'API Service Usage.

gcloud services enable \
  agentregistry.googleapis.com \
  aiplatform.googleapis.com \
  apphub.googleapis.com \
  apptopology.googleapis.com \
  cloudapiregistry.googleapis.com \
  cloudtrace.googleapis.com \
  compute.googleapis.com \
  dataform.googleapis.com \
  iam.googleapis.com \
  iap.googleapis.com \
  logging.googleapis.com \
  modelarmor.googleapis.com \
  monitoring.googleapis.com \
  networksecurity.googleapis.com \
  networkservices.googleapis.com \
  notebooks.googleapis.com \
  observability.googleapis.com \
  securitycenter.googleapis.com
gcloud services enable \
  saasservicemgmt.googleapis.com \
  storage.googleapis.com \
  telemetry.googleapis.com \
  texttospeech.googleapis.com \
  run.googleapis.com \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  dns.googleapis.com \
  accesscontextmanager.googleapis.com \
  discoveryengine.googleapis.com \
  agentidentity.googleapis.com \
  agentidentitycredentials.googleapis.com

5. Esporta variabili di ambiente

Definisci variabili di ambiente riutilizzabili per regione, ID progetto, numero di progetto, ID organizzazione e identità utente. L'impostazione delle variabili shell standardizza i comandi di configurazione delle risorse nei vari passaggi, riducendo al minimo gli errori di sostituzione manuale durante l'esecuzione dello script.

export REGION="us-central1"
export PROJ_ID=$(gcloud config list --format="value(core.project)")
export PROJ_NO=$(gcloud projects describe ${PROJ_ID} --format="value(projectNumber)")
export ORG_ID=$(gcloud projects get-ancestors ${PROJ_ID} --format="value(id)" | tail -n 1)
export USER_IDENTITY=$(gcloud config get-value account)

6. Crea un perimetro dei Controlli di servizio VPC

Crea un perimetro dei Controlli di servizio VPC per isolare le risorse del progetto e contribuire a impedire l'esfiltrazione di dati. Per saperne di più, consulta la panoramica dei Controlli di servizio VPC.

Recupera la policy di accesso

Recupera l'ID policy Gestore contesto accesso associato alla tua organizzazione. Le policy di Gestore contesto accesso definiscono il limite organizzativo a cui sono collegati e applicati i perimetri dei Controlli di servizio VPC.

gcloud access-context-manager policies list --organization=$ORG_ID

Esportare la policy di accesso

Imposta la policy di accesso nella configurazione di gcloud CLI e raccogli l'elenco dei servizi limitati supportati. La raccolta di tutti i servizi supportati ti consente di creare un insieme di regole perimetrali con restrizioni che impediscono l'accesso non autorizzato agli endpoint API Google Cloud.

export ACCESS_POLICY=ACCESS_POLICY_ID
gcloud config set access_context_manager/policy $ACCESS_POLICY
SUPPORTED_SERVICES=$(gcloud access-context-manager supported-services list --format="value(name)" | paste -sd, -)

Creare un perimetro

Definisci il nome del perimetro di servizio e applica le limitazioni ai servizi Google Cloud supportati all'interno del progetto. Il perimetro funge da confine che circonda le risorse del progetto, limitando il traffico in entrata e in uscita diretto, a meno che non sia esplicitamente consentito dalle regole di ingresso/uscita.

export PERIMETER_NAME="perimeter_${PROJ_NO}"
gcloud access-context-manager perimeters create accessPolicies/${ACCESS_POLICY}/servicePerimeters/${PERIMETER_NAME} \
--title="${PERIMETER_NAME}" \
--perimeter-type=regular \
--resources=projects/${PROJ_NO} \
--restricted-services=${SUPPORTED_SERVICES}

Crea una policy in entrata

Le policy in entrata definiscono condizioni esplicite, come identità utente o livelli di accesso specifici, in base alle quali il traffico ha origine all'esterno del perimetro e può raggiungere le risorse con limitazioni all'interno.

Crea un file YAML che consenta l'accesso esplicito per l'identità utente in tutti i servizi:

cat > ingress-policy.yaml << EOF
- ingressFrom:
    identities:
      - user:${USER_IDENTITY}
    sources:
      - accessLevel: '*'
  ingressTo:
    operations:
      - serviceName: '*'
    resources:
      - '*'
EOF
gcloud access-context-manager perimeters update $PERIMETER_NAME --set-ingress-policies="ingress-policy.yaml"

Questo codelab configura l'ambiente in modo da evitare i rifiuti di accesso dei Controlli di servizio VPC per impostazione predefinita. Tuttavia, per aiutarti a risolvere i problemi durante i test, Controlli di servizio VPC fornisce log di rifiuto dettagliati e strumenti di intelligence delle policy.

Risoluzione dei problemi relativi ai rifiuti dei Controlli di servizio VPC

Durante il test, fai riferimento ai seguenti suggerimenti per la risoluzione dei problemi:

  1. Attiva la dashboard delle violazioni per monitorare le violazioni più recenti nel tuo ambiente.
  2. Monitora Cloud Audit Logs per i log di negazione dell'accesso (403) dei Controlli di servizio VPC.
  3. Diagnostica le violazioni utilizzando l'ID univoco o il token della violazione nello strumento di analisi delle violazioni.
  4. Guarda il video sulla risoluzione dei problemi relativi ai Controlli di servizio VPC per una procedura dettagliata.

7. Configurare la rete

Configura le impostazioni della rete VPC per supportare la comunicazione privata con le API di Google e i servizi Google. La corretta configurazione di rete garantisce che il traffico di rete tra agent, gateway e API Google Cloud rimanga sulle reti interne private. Per pattern di networking dettagliati, consulta la documentazione di Google Cloud VPC.

Abilitare l'accesso privato Google

Abilita l'accesso privato Google sulla subnet predefinita in modo che le istanze VM e i carichi di lavoro interni possano raggiungere le API di Google utilizzando indirizzi IP interni anziché indirizzi IP pubblici.

export NETWORK_NAME="default"
export SUBNET_NAME="default"
gcloud compute networks subnets update $SUBNET_NAME --region=$REGION --enable-private-ip-google-access

Crea un collegamento di rete PSC

Crea un collegamento di rete Private Service Connect (PSC) per la connettività di Agent Gateway. I collegamenti di rete forniscono interfacce Private Service Connect (PSC), facilitando la comunicazione sicura tra VPC incrociati tra il servizio Agent Gateway e la tua subnet interna.

gcloud compute network-attachments create psc-agw-${REGION} \
  --region=${REGION} \
  --subnets=${SUBNET_NAME} \
  --connection-preference=ACCEPT_AUTOMATIC

Verifica

Recupera e ispeziona l'URI della risorsa self-link del collegamento di rete appena creato. La convalida dell'URI della risorsa garantisce che il collegamento di rete sia stato istanziato correttamente e che sia possibile farvi riferimento nei modelli di connettività.

export PSC_NA_URI=$(gcloud compute network-attachments describe psc-agw-${REGION} \
  --region=${REGION} \
  --format="value(selfLink.scope(v1))")
echo ${PSC_NA_URI}

Crea una zona privata Cloud DNS

Configura una zona privata Cloud DNS per instradare il traffico googleapis.com tramite intervalli IP privati. Le zone DNS private sostituiscono le ricerche di domini pubblici per googleapis.com, indirizzando tutto il traffico in uscita a IP virtuali (VIP) interni privati all'interno della tua rete VPC. Per ulteriori dettagli, consulta Zone private Cloud DNS.

export ZONE_NAME="gapis"
gcloud dns managed-zones create ${ZONE_NAME} \
--visibility=private \
--networks=https://www.googleapis.com/compute/v1/projects/${PROJ_ID}/global/networks/${NETWORK_NAME} \
  --description="Privately reach Google APIs" \
  --dns-name=googleapis.com
gcloud dns record-sets transaction start --zone=${ZONE_NAME}

Scegli una delle seguenti opzioni di dominio per il routing privato (esegui solo i comandi in Opzione 1 o Opzione 2 prima di eseguire la transazione). Scopri di più nelle opzioni di configurazione dell'accesso privato Google:

Opzione 1: VIP privato [consigliato]

gcloud dns record-sets transaction add --name="*.googleapis.com." \
    --type=CNAME private.googleapis.com. \
    --zone=${ZONE_NAME} \
    --ttl=300
gcloud dns record-sets transaction add --name=private.googleapis.com. \
    --type=A 199.36.153.8 199.36.153.9 199.36.153.10 199.36.153.11 \
    --zone=${ZONE_NAME} \
    --ttl=300

Opzione 2: VIP con limitazioni

gcloud dns record-sets transaction add --name="*.googleapis.com." \
    --type=CNAME restricted.googleapis.com. \
    --zone=${ZONE_NAME} \
    --ttl=300
gcloud dns record-sets transaction add --name=restricted.googleapis.com. \
    --type=A 199.36.153.4 199.36.153.5 199.36.153.6 199.36.153.7 \
    --zone=${ZONE_NAME} \
    --ttl=300

Esegui il commit delle transazioni DNS:

gcloud dns record-sets transaction execute --zone=${ZONE_NAME}

8. Crea Agent Gateway

Esegui il provisioning dell'Agent Gateway e definisci i relativi modelli di connettività e regole di routing. Agent Gateway funge da proxy centralizzato per la gestione del traffico degli agenti, delle policy in uscita, della gestione dei protocolli e di Service Discovery sicuro. Per i riferimenti all'architettura, consulta la Panoramica di Agent Gateway.

Diagramma dell'architettura che mostra un agente che instrada le richieste tramite Agent Gateway, l'autorizzazione delle richieste IAP e un collegamento di rete PSC all'interno di un perimetro dei Controlli di servizio VPC.

export AGW_NAME="gateway-${USER_IDENTITY}"
export AGW_CONNECTIVITY_TEMPLATE="agw-connectivity-template-${USER_IDENTITY}"

Crea un modello di connettività dell'agente

I modelli di connettività specificano la configurazione di rete, le policy di routing in uscita, le impostazioni di peering DNS e gli URI di collegamento di rete richiesti dal gateway per gestire le richieste in uscita.

cat > ${AGW_CONNECTIVITY_TEMPLATE}.yaml << EOF
name: projects/${PROJ_NO}/locations/${REGION}/agentConnectivityTemplates/${AGW_CONNECTIVITY_TEMPLATE}
accessPath: AGENT_TO_ANYWHERE
deploymentModel: CENTRALIZED
egressNetworkConfig:
  networkAttachment: ${PSC_NA_URI}
  dnsPeeringConfig:
    domain: googleapis.com.
    targetNetwork: projects/${PROJ_ID}/global/networks/${NETWORK_NAME}
  vpcEgress: ALL_TRAFFIC
EOF
gcloud network-services agent-connectivity-templates import ${AGW_CONNECTIVITY_TEMPLATE} \
    --source="${AGW_CONNECTIVITY_TEMPLATE}.yaml" \
    --location=${REGION}

Crea Agent Gateway

cat > ${AGW_NAME}-config.yaml << EOF
name: ${AGW_NAME}
protocols:
  - MCP
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
agentConnectivityTemplate: projects/${PROJ_NO}/locations/${REGION}/agentConnectivityTemplates/${AGW_CONNECTIVITY_TEMPLATE}
registries:
  - //agentregistry.googleapis.com/projects/${PROJ_NO}/locations/global
EOF
gcloud network-services agent-gateways import ${AGW_NAME} \
    --source="${AGW_NAME}-config.yaml" \
    --location=${REGION}

Verifica della creazione

Verifica che la risorsa Agent Gateway sia stata implementata e configurata correttamente. La descrizione del gateway dell'agente di cui è stato eseguito il deployment conferma che il suo stato operativo è attivo e verifica che i modelli e i registri di connettività associati siano collegati correttamente.

gcloud network-services agent-gateways describe ${AGW_NAME} \
  --location=${REGION}

9. Crea l'autorizzazione tramite IAP

Configura le policy di autorizzazione delle richieste e le estensioni del servizio Identity-Aware Proxy (IAP) per verificare le credenziali delle richieste prima di concedere l'accesso ad Agent Gateway. Per saperne di più, consulta la documentazione di IAP.

Diagramma di flusso che mostra come Agent Gateway delega l'autorizzazione delle richieste a Identity-Aware Proxy (IAP) utilizzando una policy di autorizzazione di Network Security e un'estensione del servizio di autorizzazione.

export AUTHZ_EXT="iap-authz-extension-${USER_IDENTITY}"
export AUTHZ_POLICY="iap-authz-policy-${USER_IDENTITY}"

Crea estensione di autorizzazione

cat > ${AUTHZ_EXT}.yaml << EOF
name: ${AUTHZ_EXT}
service: iap.googleapis.com
failOpen: false
timeout: 1s
metadata:
  iapPolicyVersion: "V2"
EOF
gcloud service-extensions authz-extensions import ${AUTHZ_EXT} \
    --source=${AUTHZ_EXT}.yaml \
    --location=${REGION}

Crea una policy AuthZ e associala all'Agent Gateway

cat > ${AUTHZ_POLICY}.yaml << EOF
name: ${AUTHZ_POLICY}
target:
  resources:
    - "projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
policyProfile: REQUEST_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
      - "projects/${PROJ_ID}/locations/${REGION}/authzExtensions/${AUTHZ_EXT}"
EOF
gcloud network-security authz-policies import ${AUTHZ_POLICY} \
    --source=${AUTHZ_POLICY}.yaml \
    --location=${REGION}

Questo codelab assicura che per impostazione predefinita non ti venga negato l'accesso agli acquisti in-app. Tuttavia, per facilitare i test, Agent Gateway fornisce un'osservabilità dettagliata per i rifiuti di accesso.

Risolvi i problemi e monitora i rifiuti di autorizzazione IAP

  1. Abilita Analisi dei log nel bucket di logging predefinito:
gcloud logging buckets update _Default --location=global --enable-analytics --async
  1. Apri la dashboard di osservabilità di Agent Gateway:
  2. Nella console Google Cloud, vai alla pagina Agent Gateway.
  3. Fai clic sul nome del gateway (ad esempio gateway-xyz).
  4. Fai clic sulla scheda Osservabilità.
  5. Esamina le dashboard Errore di autorizzazione e Negazioni 403.

10. Crea agente motore agente

Crea bucket di staging

Crea un bucket Cloud Storage nella regione di destinazione per archiviare artefatti di staging temporanei, dipendenze e configurazioni di deployment durante l'inizializzazione del runtime.

#Staging bucket name needs to be globally unique
export STAGING_BUCKET="agent-temp-bucket-${PROJ_NO}-${USER_IDENTITY}"
gcloud storage buckets create gs://${STAGING_BUCKET} --location=${REGION}

Attiva l'ambiente virtuale Python

python3 -m venv .venv
source .venv/bin/activate

Scarica il codice dell'agente

git clone https://github.com/gpratikab/gcp-vpcsc-agent.git
cd gcp-vpcsc-agent

Installa le dipendenze

python3 -m pip install --upgrade -r requirements.txt

Concedi ruoli IAM al service agent della piattaforma dell'agente

gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:service-${PROJ_NO}@gcp-sa-aiplatform.iam.gserviceaccount.com" \
  --role="roles/agentgateway.serviceAgent"
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:service-${PROJ_NO}@gcp-sa-aiplatform.iam.gserviceaccount.com" \
  --role="roles/ml.serviceAgent"
gcloud projects add-iam-policy-binding ${PROJ_ID} \
  --member="serviceAccount:service-${PROJ_NO}@gcp-sa-aiplatform.iam.gserviceaccount.com" \
  --role="roles/networkservices.viewer"

Esegui il deployment dell'agente

python3 deploy_gcp_agent.py create

Esporta l'identità dell'agente stampata nell'output del comando precedente come variabile di ambiente:

#Paste identity of your Agent, it will be printed as the output of the previous command
export AGENT_IDENTITY="principal://PRINCIPAL_ID"
echo $AGENT_IDENTITY

11. Consenti l'uscita dell'agente tramite il gateway

Consenti all'agente appena creato di inviare traffico in uscita a googleapis.com.

Nota:puoi inserire selettivamente gli endpoint nella lista consentita utilizzando l'osservabilità di Agent Gateway. Per semplicità, questo codelab consente l'accesso a tutte le API.

La configurazione di regole esplicite per le policy in uscita IAM concede all'agente l'autorizzazione a instradare le chiamate API tramite l'Agent Gateway e il proxy IAP per raggiungere i servizi Google Cloud esterni.

Crea policy IAM

cat > agent-access-rules.json << EOF
{
  "conditions": {
    "iap.googleapis.com": {
      "description": "Allow access to agent",
      "expression": "(destination.agent_registry.location == 'global') || (destination.unregistered.host.endsWith('googleapis.com'))",
      "title": "agenttogapis"
    }
  },
  "description": "agenttogapis",
  "effect": "ALLOW",
  "excludedPrincipals": [],
  "operation": {
    "excludedPermissions": [],
    "permissions": [
      "iap.googleapis.com/resources.egressViaIAP"
    ]
  },
  "principals": [
    "${AGENT_IDENTITY}"
  ]
}
EOF

Aggiorna policy di accesso

Controlla se hai una policy di accesso esistente:

gcloud iam access-policies list --project=${PROJ_ID} --location=global

Imposta il nome della policy di accesso:

export IAM_ACCESS_POLICY="agent-access-policy"

Per creare una nuova norma:

gcloud iam access-policies create ${IAM_ACCESS_POLICY} \
  --details-rules=agent-access-rules.json \
  --project=${PROJ_ID} \
  --location=global

In alternativa, aggiorna una policy esistente:

gcloud iam access-policies update ${IAM_ACCESS_POLICY} \
  --add-details-rules=agent-access-rules.json \
  --project=${PROJ_ID} \
  --location=global

12. Testare l'agente

La convalida dell'operazione dell'agente nella console Google Cloud verifica che la comunicazione end-to-end, i criteri IAM e i limiti dei Controlli di servizio VPC funzionino correttamente. Ora puoi testare l'agente:

  1. Nella console Google Cloud, vai alla pagina Deployment degli agenti.
  2. Seleziona l'agente di cui è stato eseguito il deployment (gcp_agent_...).
  3. Apri la scheda Playground.
  4. Nel campo del prompt, inserisci: List storage buckets in the current project.
  5. Verifica che l'agente restituisca correttamente l'elenco dei bucket tramite l'Agent Gateway privato.
  6. Verifica che l'agente non possa recuperare bucket da un altro progetto a causa di un rifiuto di accesso. Puoi esaminare il rifiuto in Cloud Audit Logs o nella dashboard delle violazioni dei Controlli di servizio VPC.

13. Esegui la pulizia

Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questo codelab, elimina il progetto che hai creato:

gcloud projects delete ${PROJ_ID}

14. Complimenti

Complimenti! Hai configurato correttamente un agente e un Agent Gateway all'interno di un perimetro dei Controlli di servizio VPC sicuro su Google Cloud.

Passaggi successivi

  • Esplora le regole granulari in entrata e in uscita nei Controlli di servizio VPC.
  • Configura le policy di accesso e semantiche utilizzando Agent Gateway.
  • Integra Model Armor per un filtraggio avanzato di sicurezza e protezione.

Documentazione di riferimento