Risoluzione dei problemi di Agent Gateway

Anteprima con accesso controllato per Agent Gateway su Cloud Run

Questa funzionalità è soggetta ai "Termini dell'offerta pre-GA" nella sezione dei Termini di servizio generali dei Termini specifici dei servizi. Le funzionalità pre-GA sono disponibili "così come sono" e potrebbero avere un supporto limitato. Per ulteriori informazioni, consulta le descrizioni della fase di lancio.

Questa funzionalità è in anteprima con accesso limitato ed è disponibile solo per i progetti inclusi in una lista consentita. Per richiedere l'accesso in anteprima, registrati qui per l'anteprima.

Quando una richiesta in uscita dall'agente Cloud Run non va a buon fine o bypassa Agent Gateway, traccia il percorso della richiesta utilizzando i seguenti controlli o consulta Problemi comuni e soluzioni. Per le istruzioni di configurazione, consulta Gestisci gli agenti con Agent Gateway.

Prima che il traffico raggiunga Agent Gateway, il sidecar Envoy di Cloud Run recupera la configurazione di routing e certificati dall'API Traffic Director. Il sidecar invia il traffico in uscita tramite un tunnel mTLS CONNECT a Secure Web Proxy.

Verifica il routing in uscita nei log di accesso del sidecar Envoy

Quando il sidecar Envoy di Cloud Run intercetta una connessione TCP in uscita, scrive una voce di log di accesso JSON in run.googleapis.com%2Fvar%2Flog%2Fenvoy_sidecar_log con il campo jsonPayload.upstream_host.

Attiva una richiesta in uscita dal tuo servizio Cloud Run ed esegui una query sui log di accesso del sidecar:

gcloud logging read \
    'resource.type="cloud_run_revision" AND resource.labels.service_name="SERVICE_NAME" AND logName=~"envoy_sidecar_log$" AND jsonPayload.upstream_host:*' \
    --project=PROJECT_ID \
    --freshness=7d \
    --limit=20 \
    --format="table(timestamp, jsonPayload.sni, jsonPayload.upstream_host, jsonPayload.response_flags, jsonPayload.bytes_sent, jsonPayload.bytes_received, jsonPayload.duration)"

Sostituisci quanto segue:

• SERVICE_NAME: il nome del tuo servizio agente Cloud Run.
• PROJECT_ID: il tuo ID progetto Google Cloud .

Una connessione integra tramite il gateway restituisce un output simile al seguente:

TIMESTAMP                     SNI          UPSTREAM_HOST                      RESPONSE_FLAGS  BYTES_SENT  BYTES_RECEIVED  DURATION
2026-10-09T05:07:48.340693Z   example.com  envoy://tunnel_internal_listener/  -               4101        2899            489

Controlla i valori UPSTREAM_HOST e RESPONSE_FLAGS:

• Se UPSTREAM_HOST è envoy://tunnel_internal_listener/ e RESPONSE_FLAGS è -, la connessione è integra. Il proxy sidecar Envoy ha trovato una corrispondenza con la tua policy EgressRouting e ha inoltrato la connessione ad Agent Gateway.
• Se UPSTREAM_HOST è un indirizzo IP e una porta di destinazione, ad esempio 93.184.216.34:443, l'API Traffic Director non è riuscita a trovare una corrispondenza con la policy EgressRouting o a risolvere il gateway di destinazione. Envoy ha utilizzato il passthrough ORIGINAL_DST e ha bypassato Agent Gateway. Consulta URI delle risorse Audit EgressRouting e AgentGateway.
• Se UPSTREAM_HOST è envoy://tunnel_internal_listener/ e RESPONSE_FLAGS è UF o UH oppure BYTES_RECEIVED è 0, Envoy non ha potuto aprire il tunnel CONNECT verso Secure Web Proxy. Controlla la connettività della subnet Virtual Private Cloud (VPC) o consulta L'aggiornamento del gateway Secure Web Proxy interrompe il tunneling Envoy.
• Se non vengono visualizzate righe, controlla run.googleapis.com%2Frequests per verificare che la richiesta abbia raggiunto il container Cloud Run. Verifica che la revisione attiva abiliti --ambient-networking. Se le righe non vengono ancora visualizzate, consulta Controlla i log di connessione e xDS del sidecar Envoy.

Controlla i log xDS e di connessione del sidecar Envoy

Se i log di accesso del sidecar Envoy non restituiscono voci o mostrano un errore di connessione, controlla i log di connessione xDS e upstream del sidecar:

1. Controlla se sono presenti errori dello stream xDS dell'API Traffic Director o lo stato di avvio:

   gcloud logging read \
      'resource.type="cloud_run_revision" AND resource.labels.service_name="SERVICE_NAME" AND logName=~"envoy_sidecar_log$" AND (severity>=INFO OR textPayload:"DeltaAggregatedResources")' \
      --project=PROJECT_ID \
      --freshness=7d \
      --limit=30 \
      --format="table(timestamp, severity, textPayload, jsonPayload.message)"

2. Controlla i tentativi di connessione del tunnel upstream a ambient-swp-connect-cluster:

   gcloud logging read \
      'resource.type="cloud_run_revision" AND resource.labels.service_name="SERVICE_NAME" AND logName=~"envoy_sidecar_log$" AND (textPayload:"ambient-swp-connect-cluster" OR jsonPayload.message:"ambient-swp-connect-cluster" OR jsonPayload.message:"tunnel_internal_listener")' \
      --project=PROJECT_ID \
      --freshness=7d \
      --limit=30 \
      --format="table(timestamp, severity, textPayload, jsonPayload.message)"

   Sostituisci quanto segue:

   • SERVICE_NAME: il nome del tuo servizio agente Cloud Run.
   • PROJECT_ID: il tuo ID progetto Google Cloud .

Controlla i messaggi di log:

• Se i log contengono DeltaAggregatedResources gRPC config stream e The caller does not have permission, all'identità di servizio manca roles/trafficdirector.client. Consulta Il sidecar Envoy non può ricevere la configurazione xDS.
• Se i log contengono Creating connection to cluster ambient-swp-connect-cluster, Envoy ha ricevuto la configurazione EgressRouting e ha provato a connettersi a Secure Web Proxy.

Controlla gli URI delle risorse EgressRouting e AgentGateway

Quando esegui gcloud alpha network-services egress-routings create o gcloud beta network-services agent-gateways import, l'API convalida la sintassi dell'URI senza verificare se le risorse di destinazione esistono. Un errore di battitura nel nome o nella regione di una risorsa fa sì che l'API Traffic Director salti la traduzione di EgressRouting ed Envoy utilizzi il routing passthrough.

Esamina gli URI archiviati e confrontali con le risorse di cui hai eseguito il deployment:

1. Esamina la risorsa EgressRouting. L'output normalizza gli ID progetto in numeri di progetto:

   gcloud alpha network-services egress-routings describe EGRESS_ROUTING_NAME \
      --location=REGION \
      --project=PROJECT_ID

2. Elenca tutte le risorse EgressRouting nella regione per verificare che nessuna policy duplicata abbia come target lo stesso servizio:

   gcloud alpha network-services egress-routings list \
      --location=REGION \
      --project=PROJECT_ID

3. Verifica che il gateway Secure Web Proxy di destinazione corrisponda all'URI in EgressRouting.gateway e AgentGateway.selfManaged.resourceUris:

   gcloud network-services gateways describe SWP_NAME \
      --location=REGION \
      --project=PROJECT_ID

   Sostituisci quanto segue:

   • EGRESS_ROUTING_NAME: il nome della tua risorsa EgressRouting.
   • REGION: la regione del deployment.
   • PROJECT_ID: il tuo ID progetto Google Cloud .
   • SWP_NAME: il nome del gateway Secure Web Proxy.

Verifica che tutti e tre gli URI corrispondano all'ID progetto o al numero, alla regione e al nome della risorsa:

• EgressRouting.sources[].workloadUri:
  • Con ambito del servizio: //run.googleapis.com/projects/PROJECT_ID/locations/REGION/services/SERVICE_NAME
  • Con ambito a livello di progetto: //run.googleapis.com/projects/PROJECT_ID o //run.googleapis.com/projects/PROJECT_NUMBER
• EgressRouting.gateway: //networkservices.googleapis.com/projects/PROJECT_ID/locations/REGION/gateways/SWP_NAME
• AgentGateway.selfManaged.resourceUris[]: projects/PROJECT_ID/locations/REGION/gateways/SWP_NAME

Controlla i log delle transazioni di Secure Web Proxy

Se il proxy sidecar Envoy inoltra il traffico a Secure Web Proxy, ma le richieste non vanno a buon fine, controlla i log del proxy come descritto in Visualizza i log delle transazioni del proxy:

• Se nei log del proxy non viene visualizzato alcun traffico, significa che le richieste non raggiungono Secure Web Proxy. Controlla la configurazione di EgressRouting in Controlla gli URI delle risorse EgressRouting e AgentGateway e Problemi comuni e soluzioni.
• Se vedi decisioni DENY o ALLOW impreviste, controlla jsonPayload.authzPolicyInfo e jsonPayload.agentGatewayInfo nella voce di log per esaminare i metadati AuthzPolicy e di destinazione corrispondenti e verifica le regole ExtensionBinding associate alla risorsa Agent Gateway. Dopo aver creato o aggiornato una risorsa ExtensionBinding, la propagazione delle modifiche alla configurazione nel gateway può richiedere fino a cinque minuti.

Problemi comuni e soluzioni

Le sezioni seguenti descrivono i problemi comuni e come risolverli.

Il traffico in uscita bypassa l'Agent Gateway a causa di un URI della risorsa non corrispondente

Il traffico in uscita da Cloud Run bypassa l'Agent Gateway o scade dopo che egress-routings create ha esito positivo. In envoy_sidecar_log, jsonPayload.upstream_host mostra l'indirizzo IP e la porta di destinazione anziché envoy://tunnel_internal_listener/.

Uno degli URI delle risorse EgressRouting o AgentGateway fa riferimento a un nome di risorsa inesistente o a una regione non corrispondente. Quando l'API Traffic Director non riesce a risolvere la catena dal servizio Cloud Run a Secure Web Proxy, ignora la traduzione del tunnel e pubblica ORIGINAL_DST.

Esegui i comandi in Controlla gli URI delle risorse EgressRouting e AgentGateway per trovare l'URI non corrispondente. Aggiorna la configurazione con il nome e la regione della risorsa corrispondenti e ricrea la risorsa AgentGateway o EgressRouting.

Il sidecar Envoy non può ricevere la configurazione xDS

Le richieste in uscita dal container Cloud Run scadono o non vanno a buon fine e envoy_sidecar_log contiene il seguente errore:

DeltaAggregatedResources gRPC config stream to trafficdirector.REGION.rep.googleapis.com:443 closed: 7, The caller does not have permission

L'identità del service account di runtime di Cloud Run non ha roles/trafficdirector.client. Per impostazione predefinita, il deployment di un servizio con --functional-type=agent e --identity-type=agent-identity concede roles/run.agentDefaultAccess, che include roles/trafficdirector.client e roles/cloudtrace.agent. Se l'identità del servizio non dispone di queste autorizzazioni, concedi i ruoli:

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAME" \
    --role="roles/trafficdirector.client"

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="principal://agents.global.org-ORGANIZATION_ID.system.id.goog/resources/run/projects/PROJECT_NUMBER/locations/REGION/services/SERVICE_NAME" \
    --role="roles/cloudtrace.agent"

Sostituisci quanto segue:

• PROJECT_ID: il tuo ID progetto Google Cloud .
• ORGANIZATION_ID: l'ID della tua organizzazione Google Cloud .
• PROJECT_NUMBER: il tuo numero di progetto Google Cloud .
• REGION: la regione del servizio.
• SERVICE_NAME: il nome del tuo servizio agente Cloud Run. Se il tuo servizio utilizza un service account anziché l'identità dell'agente, imposta --member su serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com.

Verifica che l'agente di servizio Cloud Run possa accedere alla tua rete VPC. Per impostazione predefinita, roles/run.serviceAgent include queste autorizzazioni. Se hai modificato le autorizzazioni dell'agente di servizio, concedi roles/compute.networkUser:

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:[e-mail]" \
    --role="roles/compute.networkUser"

L'aggiornamento del gateway Secure Web Proxy interrompe il tunneling di Envoy

Dopo aver aggiornato il ServerTlsPolicy, il certificato, l'indirizzo IP o la porta di un gateway Secure Web Proxy esistente, le richieste in uscita non vanno a buon fine con errori 502, 503 o 504 oppure envoy_sidecar_log segnala RESPONSE_FLAGS: UF.

Non puoi modificare addresses o ports dopo aver creato un gateway Secure Web Proxy. Inoltre, gli aggiornamenti a serverTlsPolicy o certificateUrls su un gateway Secure Web Proxy esistente non vengono propagati agli endpoint EgressRouting nell'API Traffic Director.

Per modificare questi campi di Secure Web Proxy senza tempi di inattività del workload, completa i seguenti passaggi:

1. Crea un gateway Secure Web Proxy sostitutivo con un nome risorsa diverso e la configurazione aggiornata.
2. Aggiorna selfManaged.resourceUris nella risorsa AgentGateway per fare riferimento all'URI del gateway Secure Web Proxy sostitutivo.
3. Ricrea la risorsa EgressRouting in modo che rimandi al gateway Secure Web Proxy sostitutivo.
4. Dopo che il gateway sostitutivo ha instradato il traffico, rimuovi il vecchio gateway Secure Web Proxy dalla risorsa AgentGateway ed eliminalo.

Secure Web Proxy nega tutto il traffico in uscita

Tutte le richieste in uscita dall'agente Cloud Run non vanno a buon fine con errori 403 dopo aver creato una policy EgressRouting o aver collegato un ExtensionBinding.

Per impostazione predefinita, Secure Web Proxy nega tutto il traffico finché una AuthzPolicy ALLOW sulla risorsa Agent Gateway non lo consente. Il collegamento di un ExtensionBinding non consente il traffico senza un ALLOW AuthzPolicy e le policy collegate alla risorsa Gateway Secure Web Proxy sottostante vengono ignorate.

Per consentire il traffico autorizzato, collega un AuthzPolicy ALLOW che ha come target la risorsa Agent Gateway. Per istruzioni, consulta Consenti il traffico in uscita di base e MCP.

Le richieste di modelli in uscita non vanno a buon fine con errori 403

Le chiamate in uscita dall'agente Cloud Run agli endpoint del modello, come Vertex AI, all'indirizzo REGION-aiplatform.googleapis.com non vanno a buon fine con errori 403 Forbidden dopo la configurazione delle policy su Agent Gateway.

Poiché --vpc-egress=all instrada tutto il traffico dei container in uscita tramite Secure Web Proxy, le richieste del modello non vanno a buon fine se ALLOW AuthzPolicy corrisponde solo ai metodi Model Context Protocol (MCP) o se ExtensionBinding di Identity-Aware Proxy (IAP) corrisponde a host non MCP senza una regola di autorizzazione nelle Unified Access Policies di Identity and Access Management (IAM).

Per consentire le chiamate ai modelli in uscita, consenti gli endpoint dei modelli in un ALLOW AuthzPolicy nella risorsa Agent Gateway. Inoltre, imposta l'ambito matchConditions in IAP ExtensionBinding su prefix: "urn:mcp" o aggiungi una regola di autorizzazione destination.unregistered.host nella policy di accesso unificato IAM. Per istruzioni, consulta Consenti il traffico in uscita di base e il traffico MCP e Configura le policy in uscita di IAP.

Secure Web Proxy ignora GatewaySecurityPolicyRules

Hai creato GatewaySecurityPolicyRules o collegato un AuthzPolicy alla risorsa Secure Web Proxy Gateway, ma non hanno alcun effetto sul traffico degli agenti in uscita.

Quando Secure Web Proxy è associato a una risorsa AgentGateway, Secure Web Proxy applica solo le policy di autorizzazione e le associazioni di estensioni collegate alla risorsa AgentGateway. Qualsiasi risorsa GatewaySecurityPolicyRules o AuthzPolicy collegata al Secure Web Proxy Gateway sottostante viene ignorata.

Collega invece le risorse AuthzPolicy e ExtensionBinding alla risorsa Agent Gateway. Per istruzioni, consulta Configura le policy su Agent Gateway.

Le richieste in uscita non superano l'ispezione TLS

Le richieste in uscita dall'agente Cloud Run non vanno a buon fine con errori TLS su ogni connessione.

Il account di servizio Secure Web Proxy non dispone di roles/privateca.certificateManager nel pool di Certificate Authority Service.

Concedi roles/privateca.certificateManager sul pool di CA al tuo account di servizio Secure Web Proxy. Per le istruzioni, vedi Crea un service account.

Le connessioni in uscita ispezionate con TLS non vanno a buon fine con SSLV3_ALERT_HANDSHAKE_FAILURE o RemoteDisconnected

Le richieste in uscita dall'agente non vanno a buon fine alla prima connessione a un host di destinazione con SSLV3_ALERT_HANDSHAKE_FAILURE o non vanno a buon fine con RemoteDisconnected.

Alla prima connessione con ispezione TLS a un host di destinazione, Secure Web Proxy genera e memorizza nella cache un certificato foglia di Certificate Authority Service, il che può causare un errore di handshake temporaneo. I client HTTP che inviano Connection: close per impostazione predefinita, come urllib.request.urlopen, possono non riuscire con RemoteDisconnected durante l'intercettazione TLS.

Per evitare questi errori nel codice dell'agente:

• Utilizza client HTTP che riutilizzano connessioni permanenti, come httpx.AsyncClient o requests.Session().
• Configura i nuovi tentativi di connessione e handshake sul client HTTP, ad esempio httpx.AsyncHTTPTransport(retries=2) o urllib3.util.Retry.

Passaggi successivi

• Gestisci gli agenti con Agent Gateway
• Configura Ambient Networking per Cloud Run
• Risolvi i problemi di Cloud Run