Resolver problemas do Gateway de Agente

Quando uma solicitação de saída do agente do Cloud Run falha ou ignora o Gateway de Agente, rastreie o caminho da solicitação usando as verificações a seguir ou consulte Problemas comuns e soluções. Para instruções de configuração, consulte Controlar agentes com o Gateway de Agente.

Antes que o tráfego chegue ao Gateway de Agente, o sidecar do Envoy do Cloud Run busca a configuração de roteamento e certificado na API Traffic Director. O arquivo secundário envia o tráfego de saída por um túnel mTLS CONNECT para o Secure Web Proxy.

Verificar o roteamento de saída nos registros de acesso do arquivo secundário do Envoy

Quando o sidecar do Envoy do Cloud Run intercepta uma conexão TCP de saída, ele grava uma entrada de registro de acesso JSON em run.googleapis.com%2Fvar%2Flog%2Fenvoy_sidecar_log com o campo jsonPayload.upstream_host.

Acione uma solicitação de saída do serviço do Cloud Run e consulte os registros de acesso do arquivo secundário:

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)"

Substitua:

  • SERVICE_NAME: o nome do serviço do agente do Cloud Run.
  • PROJECT_ID: o ID do projeto Google Cloud .

Uma conexão íntegra pelo gateway retorna uma saída semelhante a esta:

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

Verifique os valores UPSTREAM_HOST e RESPONSE_FLAGS:

  • Se UPSTREAM_HOST for envoy://tunnel_internal_listener/ e RESPONSE_FLAGS for -, a conexão estará íntegra. O arquivo secundário do Envoy correspondeu à política EgressRouting e encaminhou a conexão para o Gateway de Agente.
  • Se UPSTREAM_HOST for um endereço IP de destino e uma porta, como 93.184.216.34:443, a API Traffic Director não poderá corresponder à política EgressRouting ou resolver o gateway de destino. O Envoy usou a passagem ORIGINAL_DST e ignorou o Gateway de Agente. Consulte Auditar URIs de recursos EgressRouting e AgentGateway.
  • Se UPSTREAM_HOST for envoy://tunnel_internal_listener/ e RESPONSE_FLAGS for UF ou UH, ou BYTES_RECEIVED for 0, o Envoy não poderá abrir o túnel CONNECT para o Secure Web Proxy. Verifique a conectividade da sub-rede da nuvem privada virtual (VPC) ou consulte A atualização do gateway do Secure Web Proxy interrompe o tunelamento do Envoy.
  • Se nenhuma linha aparecer, verifique run.googleapis.com%2Frequests para confirmar se a solicitação chegou ao contêiner do Cloud Run. Verifique se a revisão ativa ativa --ambient-networking. Se as linhas ainda não aparecerem, consulte Verificar os registros de conexão e xDS do sidecar do Envoy.

Verificar os registros de conexão e xDS do sidecar do Envoy

Se os registros de acesso do arquivo secundário do Envoy não retornarem entradas ou mostrarem uma falha de conexão, inspecione os registros de conexão upstream e xDS do arquivo secundário:

  1. Verifique se há erros de stream xDS da API Traffic Director ou o status de inicialização:

    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. Verifique as tentativas de conexão do túnel upstream com 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)"

    Substitua:

    • SERVICE_NAME: o nome do serviço do agente do Cloud Run.
    • PROJECT_ID: o ID do projeto Google Cloud .

Verifique as mensagens de registro:

  • Se os registros contiverem DeltaAggregatedResources gRPC config stream e The caller does not have permission, a identidade de serviço não terá roles/trafficdirector.client. Consulte O sidecar do Envoy não pode receber a configuração do xDS.
  • Se os registros contiverem Creating connection to cluster ambient-swp-connect-cluster, o Envoy recebeu a configuração EgressRouting e tentou se conectar ao Secure Web Proxy.

Auditar URIs de recursos EgressRouting e AgentGateway

Quando você executa gcloud alpha network-services egress-routings create ou gcloud beta network-services agent-gateways import, a API valida a sintaxe do URI sem verificar se os recursos de destino existem. Um erro de digitação em um nome de recurso ou região faz com que a API Traffic Director pule a tradução de EgressRouting, e o Envoy use o roteamento de passagem.

Inspecione os URIs armazenados e compare-os com os recursos implantados:

  1. Inspecione o recurso EgressRouting. A saída normaliza os IDs do projeto para números do projeto:

    gcloud alpha network-services egress-routings describe EGRESS_ROUTING_NAME \
       --location=REGION \
       --project=PROJECT_ID
  2. Liste todos os recursos EgressRouting na região para confirmar que nenhuma política duplicada segmenta o mesmo serviço:

    gcloud alpha network-services egress-routings list \
       --location=REGION \
       --project=PROJECT_ID
  3. Verifique se o gateway de destino do Secure Web Proxy corresponde ao URI em EgressRouting.gateway e AgentGateway.selfManaged.resourceUris:

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

    Substitua:

    • EGRESS_ROUTING_NAME: o nome do recurso EgressRouting.
    • REGION: a região da implantação.
    • PROJECT_ID: o ID do projeto Google Cloud .
    • SWP_NAME: o nome do gateway do Secure Web Proxy.

Verifique se os três URIs correspondem ao ID ou número do projeto, à região e ao nome do recurso:

  • EgressRouting.sources[].workloadUri:
    • Com escopo de serviço: //run.googleapis.com/projects/PROJECT_ID/locations/REGION/services/SERVICE_NAME
    • Com escopo de projeto: //run.googleapis.com/projects/PROJECT_ID ou //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

Verificar os registros de transações do Secure Web Proxy

Se o sidecar do Envoy encaminhar o tráfego para o Secure Web Proxy, mas as solicitações falharem, inspecione os registros do proxy, conforme descrito em Ver registros de transações do proxy:

  • Se nenhum tráfego aparecer nos registros do proxy, as solicitações não estão chegando ao Secure Web Proxy. Verifique a configuração de EgressRouting em Auditar URIs de recursos EgressRouting e AgentGateway e Problemas comuns e soluções.
  • Se você encontrar decisões inesperadas de DENY ou ALLOW, verifique jsonPayload.authzPolicyInfo e jsonPayload.agentGatewayInfo na entrada de registro para inspecionar os metadados de destino e AuthzPolicy correspondentes e verifique todas as regras de ExtensionBinding anexadas ao seu recurso do Gateway de Agente. Depois de criar ou atualizar um recurso ExtensionBinding, as alterações de configuração podem levar até cinco minutos para serem propagadas para o gateway.

Problemas comuns e soluções

As seções a seguir descrevem problemas comuns e como resolvê-los.

O tráfego de saída ignora o Gateway de Agente devido a um URI de recurso incompatível

O tráfego de saída do Cloud Run ignora o Gateway de Agente ou expira após o sucesso de egress-routings create. Em envoy_sidecar_log, jsonPayload.upstream_host mostra o endereço IP e a porta de destino em vez de envoy://tunnel_internal_listener/.

Um dos URIs de recurso EgressRouting ou AgentGateway faz referência a um nome de recurso inexistente ou a uma região incompatível. Quando a API Traffic Director não consegue resolver a cadeia do serviço do Cloud Run para o Secure Web Proxy, ela ignora a conversão do túnel e exibe ORIGINAL_DST.

Execute os comandos em Auditar URIs de recursos EgressRouting e AgentGateway para encontrar o URI incompatível. Atualize a configuração com o nome e a região do recurso correspondente e recrie o recurso AgentGateway ou EgressRouting.

O arquivo secundário do Envoy não pode receber a configuração do xDS

As solicitações de saída do contêiner do Cloud Run expiram ou falham, e envoy_sidecar_log contém o seguinte erro:

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

A identidade de serviço do ambiente de execução do Cloud Run não tem roles/trafficdirector.client. Por padrão, implantar um serviço com --functional-type=agent e --identity-type=agent-identity concede roles/run.agentDefaultAccess, que inclui roles/trafficdirector.client e roles/cloudtrace.agent. Se a identidade de serviço não tiver essas permissões, conceda os papéis:

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"

Substitua:

  • PROJECT_ID: o ID do projeto Google Cloud .
  • ORGANIZATION_ID: o ID da organização do Google Cloud .
  • PROJECT_NUMBER: o número do projeto do Google Cloud .
  • REGION: a região do serviço.
  • SERVICE_NAME: o nome do serviço do agente do Cloud Run. Se o serviço usar uma conta de serviço em vez da identidade do agente, defina --member como serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com.

Confirme se o agente de serviço do Cloud Run pode acessar sua rede VPC. Por padrão, roles/run.serviceAgent inclui estas permissões. Se você modificou as permissões do agente de serviço, conceda roles/compute.networkUser:

gcloud projects add-iam-policy-binding PROJECT_ID \
    --member="serviceAccount:service-PROJECT_NUMBER@serverless-robot-prod.iam.gserviceaccount.com" \
    --role="roles/compute.networkUser"

A atualização do gateway do Secure Web Proxy interrompe o tunelamento do Envoy

Depois de atualizar o ServerTlsPolicy, o certificado, o endereço IP ou a porta de um gateway do Secure Web Proxy, as solicitações de saída falham com erros 502, 503 ou 504, ou o envoy_sidecar_log informa RESPONSE_FLAGS: UF.

Não é possível alterar addresses ou ports depois de criar um gateway do Secure Web Proxy. Além disso, as atualizações de serverTlsPolicy ou certificateUrls em um gateway do Secure Web Proxy não são propagadas para endpoints EgressRouting na API Traffic Director.

Para alterar esses campos do Secure Web Proxy sem inatividade da carga de trabalho, siga estas etapas:

  1. Crie um gateway de substituição do Secure Web Proxy com um nome de recurso diferente e a configuração atualizada.
  2. Atualize selfManaged.resourceUris no recurso AgentGateway para fazer referência ao URI do gateway do Secure Web Proxy de substituição.
  3. Recrie o recurso EgressRouting para apontar para o gateway de substituição do Secure Web Proxy.
  4. Depois que o gateway de substituição rotear o tráfego, remova o gateway antigo do Secure Web Proxy do recurso AgentGateway e exclua o gateway antigo do Secure Web Proxy.

As solicitações de saída falham com erros 403

As solicitações de saída do agente do Cloud Run, incluindo chamadas para endpoints de modelo, como a Vertex AI em REGION-aiplatform.googleapis.com ou aiplatform.googleapis.com, falham com erros 403 Forbidden depois que você configura políticas no Gateway de Agente.

Como o --vpc-egress=all encaminha todo o tráfego de saída do contêiner pelo Secure Web Proxy, as solicitações falham por um dos seguintes motivos:

  • O Identity-Aware Proxy (IAP) ExtensionBinding omite matchConditions (ou corresponde a hosts fora dos servidores do Protocolo de Contexto de Modelo (MCP)) sem uma regra de permissão para o destino na Política de Acesso Unificado do Identity and Access Management (IAM).
  • Um AuthzPolicy de ALLOW está anexado ao recurso do Gateway de Agente (ou ao Secure Web Proxy Gateway subjacente), e as solicitações de saída não correspondem às regras de ALLOW.

Para resolver o problema:

  • Defina o escopo de matchConditions no ExtensionBinding do IAP como prefix: "urn:mcp" para servidores MCP (e, opcionalmente, prefix: "urn:agent" para tráfego entre agentes) para que as chamadas de modelo e outros destinos que não sejam MCP ignorem a avaliação do IAP ou adicione uma regra de permissão destination.unregistered.host para seu destino (como REGION-aiplatform.googleapis.com ou aiplatform.googleapis.com) na política de acesso unificado do IAM. Para instruções, consulte Configurar políticas de saída do IAP.
  • Se você anexou um AuthzPolicy de ALLOW, adicione regras de ALLOW para os destinos necessários ou remova o AuthzPolicy se você controlar o tráfego apenas com recursos de ExtensionBinding.

O Secure Web Proxy ignora GatewaySecurityPolicyRules

Você criou recursos GatewaySecurityPolicyRule no Secure Web Proxy Gateway, mas eles não têm efeito no tráfego de saída do agente.

Quando o Secure Web Proxy está associado a um recurso AgentGateway, ele ignora todos os recursos GatewaySecurityPolicyRule no Gateway subjacente (o TlsInspectionPolicy permanece ativo).

Em vez disso, anexe recursos ExtensionBinding ao recurso do Gateway de Agente. Se você usar recursos AuthzPolicy, anexe-os apenas ao recurso Gateway de Agente. Anexar recursos AuthzPolicy ao AgentGateway e ao Secure Web Proxy Gateway subjacente causa um conflito de configuração. Para instruções, consulte Configurar políticas no Gateway de Agente.

As solicitações de saída falham na inspeção de TLS

As solicitações de saída do agente do Cloud Run falham com erros de TLS em todas as conexões.

A conta de serviço do Secure Web Proxy não tem roles/privateca.certificateManager no pool do Certificate Authority Service.

Conceda roles/privateca.certificateManager no pool de CAs à sua conta de serviço do Secure Web Proxy. Para mais instruções, consulte Criar uma conta de serviço.

As conexões de saída inspecionadas por TLS falham com SSLV3_ALERT_HANDSHAKE_FAILURE ou RemoteDisconnected

As solicitações de saída do agente falham na primeira conexão com um host de destino com SSLV3_ALERT_HANDSHAKE_FAILURE ou falham com RemoteDisconnected.

Na primeira conexão inspecionada por TLS com um host de destino, o Secure Web Proxy emite e armazena em cache um certificado de folha do CA Service, o que pode causar um erro de handshake temporário. Os clientes HTTP que enviam Connection: close por padrão, como urllib.request.urlopen, podem falhar com RemoteDisconnected durante a interceptação de TLS.

Para evitar esses erros no código do agente:

  • Use clientes HTTP que reutilizam conexões persistentes, como httpx.AsyncClient ou requests.Session().
  • Configure novas tentativas de conexão e handshake no cliente HTTP, como httpx.AsyncHTTPTransport(retries=2) ou urllib3.util.Retry.

A seguir