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_HOSTforenvoy://tunnel_internal_listener/eRESPONSE_FLAGSfor-, a conexão estará íntegra. O arquivo secundário do Envoy correspondeu à políticaEgressRoutinge encaminhou a conexão para o Gateway de Agente. - Se
UPSTREAM_HOSTfor um endereço IP de destino e uma porta, como93.184.216.34:443, a API Traffic Director não poderá corresponder à políticaEgressRoutingou resolver o gateway de destino. O Envoy usou a passagemORIGINAL_DSTe ignorou o Gateway de Agente. Consulte Auditar URIs de recursos EgressRouting e AgentGateway. - Se
UPSTREAM_HOSTforenvoy://tunnel_internal_listener/eRESPONSE_FLAGSforUFouUH, ouBYTES_RECEIVEDfor0, o Envoy não poderá abrir o túnelCONNECTpara 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%2Frequestspara 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:
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)"
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 streameThe 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çãoEgressRoutinge 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:
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
Liste todos os recursos
EgressRoutingna 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
Verifique se o gateway de destino do Secure Web Proxy corresponde ao URI em
EgressRouting.gatewayeAgentGateway.selfManaged.resourceUris:gcloud network-services gateways describe SWP_NAME \ --location=REGION \ --project=PROJECT_ID
Substitua:
EGRESS_ROUTING_NAME: o nome do recursoEgressRouting.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_IDou//run.googleapis.com/projects/PROJECT_NUMBER
- Com escopo de serviço:
EgressRouting.gateway://networkservices.googleapis.com/projects/PROJECT_ID/locations/REGION/gateways/SWP_NAMEAgentGateway.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
EgressRoutingem Auditar URIs de recursos EgressRouting e AgentGateway e Problemas comuns e soluções. - Se você encontrar decisões inesperadas de
DENYouALLOW, verifiquejsonPayload.authzPolicyInfoejsonPayload.agentGatewayInfona entrada de registro para inspecionar os metadados de destino eAuthzPolicycorrespondentes e verifique todas as regras deExtensionBindinganexadas ao seu recurso do Gateway de Agente. Depois de criar ou atualizar um recursoExtensionBinding, 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--membercomoserviceAccount: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:
- Crie um gateway de substituição do Secure Web Proxy com um nome de recurso diferente e a configuração atualizada.
- Atualize
selfManaged.resourceUrisno recursoAgentGatewaypara fazer referência ao URI do gateway do Secure Web Proxy de substituição. - Recrie o recurso
EgressRoutingpara apontar para o gateway de substituição do Secure Web Proxy. - Depois que o gateway de substituição rotear o tráfego, remova o gateway antigo do Secure Web Proxy do recurso
AgentGatewaye 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)
ExtensionBindingomitematchConditions(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
AuthzPolicydeALLOWestá anexado ao recurso do Gateway de Agente (ou ao Secure Web ProxyGatewaysubjacente), e as solicitações de saída não correspondem às regras deALLOW.
Para resolver o problema:
- Defina o escopo de
matchConditionsnoExtensionBindingdo IAP comoprefix: "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ãodestination.unregistered.hostpara seu destino (comoREGION-aiplatform.googleapis.comouaiplatform.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
AuthzPolicydeALLOW, adicione regras deALLOWpara os destinos necessários ou remova oAuthzPolicyse você controlar o tráfego apenas com recursos deExtensionBinding.
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.AsyncClientourequests.Session(). - Configure novas tentativas de conexão e handshake no cliente HTTP, como
httpx.AsyncHTTPTransport(retries=2)ouurllib3.util.Retry.
A seguir
- Gerenciar agentes com o Gateway de Agente
- Configurar a rede de ambiente para o Cloud Run
- Resolver problemas do Cloud Run