Cloud Run 에이전트의 아웃바운드 요청이 실패하거나 Agent Gateway를 우회하는 경우 다음 검사를 사용하여 요청 경로를 추적하거나 일반적인 문제 및 해결 방법을 참조하세요. 설정 안내는 Agent Gateway로 에이전트 제어를 참조하세요.
트래픽이 Agent Gateway에 도달하기 전에 Cloud Run Envoy 사이드카가 Traffic Director API에서 라우팅 및 인증서 구성을 가져옵니다. 사이드카는 mTLS CONNECT 터널을 통해 아웃바운드 트래픽을 Secure Web Proxy로 전송합니다.
Envoy 사이드카 액세스 로그에서 아웃바운드 라우팅 확인
Cloud Run Envoy 사이드카가 아웃바운드 TCP 연결을 가로채면 jsonPayload.upstream_host 필드를 사용하여 JSON 액세스 로그 항목을 run.googleapis.com%2Fvar%2Flog%2Fenvoy_sidecar_log에 작성합니다.
Cloud Run 서비스에서 아웃바운드 요청을 트리거하고 사이드카 액세스 로그를 쿼리합니다.
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)"
다음을 바꿉니다.
SERVICE_NAME: Cloud Run 에이전트 서비스의 이름입니다.PROJECT_ID: Google Cloud 프로젝트 ID입니다.
게이트웨이를 통한 정상적인 연결은 다음과 비슷한 출력을 반환합니다.
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
UPSTREAM_HOST 및 RESPONSE_FLAGS 값을 확인합니다.
UPSTREAM_HOST가envoy://tunnel_internal_listener/이고RESPONSE_FLAGS가-이면 연결이 정상입니다. Envoy 사이드카가EgressRouting정책과 일치하고 연결을 Agent Gateway로 전달했습니다.UPSTREAM_HOST가93.184.216.34:443와 같은 대상 IP 주소 및 포트인 경우 Traffic Director API가EgressRouting정책과 일치하거나 대상 게이트웨이를 확인할 수 없습니다. Envoy가ORIGINAL_DST패스 스루를 사용하고 Agent Gateway를 우회했습니다. EgressRouting 및 AgentGateway 리소스 URI 감사를 참조하세요.UPSTREAM_HOST가envoy://tunnel_internal_listener/이고RESPONSE_FLAGS가UF또는UH이거나BYTES_RECEIVED가0인 경우 Envoy가 Secure Web Proxy에 대한CONNECT터널을 열 수 없습니다. 가상 프라이빗 클라우드(VPC) 서브넷 연결을 확인하거나 Secure Web Proxy 게이트웨이를 업데이트하면 Envoy 터널링이 중단됨을 참조하세요.- 행이 표시되지 않으면
run.googleapis.com%2Frequests를 확인하여 요청이 Cloud Run 컨테이너에 도달했는지 확인합니다. 활성 버전에서--ambient-networking가 사용 설정되어 있는지 확인합니다. 그래도 행이 표시되지 않으면 Envoy 사이드카 xDS 및 연결 로그 확인을 참조하세요.
Envoy 사이드카 xDS 및 연결 로그 확인
Envoy 사이드카 액세스 로그가 항목을 반환하지 않거나 연결 실패를 표시하는 경우 사이드카 xDS 및 업스트림 연결 로그를 검사합니다.
Traffic Director API xDS 스트림 오류 또는 시작 상태를 확인합니다.
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)"
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)"
다음을 바꿉니다.
SERVICE_NAME: Cloud Run 에이전트 서비스의 이름입니다.PROJECT_ID: Google Cloud 프로젝트 ID입니다.
로그 메시지를 확인합니다.
- 로그에
DeltaAggregatedResources gRPC config stream및The caller does not have permission가 포함된 경우 서비스 ID에roles/trafficdirector.client가 누락된 것입니다. Envoy 사이드카가 xDS 구성을 수신할 수 없음을 참조하세요. - 로그에
Creating connection to cluster ambient-swp-connect-cluster가 포함되어 있으면 Envoy가EgressRouting구성을 수신하고 Secure Web Proxy에 연결하려고 시도한 것입니다.
EgressRouting 및 AgentGateway 리소스 URI 감사
gcloud alpha network-services egress-routings create 또는 gcloud beta network-services agent-gateways import를 실행하면 API는 대상 리소스가 있는지 확인하지 않고 URI 문법을 검증합니다. 리소스 이름 또는 리전의 오타로 인해 Traffic Director API가 EgressRouting 변환을 건너뛰고 Envoy가 패스 스루 라우팅을 사용합니다.
저장된 URI를 검사하고 배포된 리소스와 비교합니다.
EgressRouting리소스를 검사합니다. 출력은 프로젝트 ID를 프로젝트 번호로 정규화합니다.gcloud alpha network-services egress-routings describe EGRESS_ROUTING_NAME \ --location=REGION \ --project=PROJECT_ID
리전의 모든
EgressRouting리소스를 나열하여 동일한 서비스를 타겟팅하는 중복 정책이 없는지 확인합니다.gcloud alpha network-services egress-routings list \ --location=REGION \ --project=PROJECT_ID
대상 Secure Web Proxy 게이트웨이가
EgressRouting.gateway및AgentGateway.selfManaged.resourceUris의 URI와 일치하는지 확인합니다.gcloud network-services gateways describe SWP_NAME \ --location=REGION \ --project=PROJECT_ID
다음을 바꿉니다.
EGRESS_ROUTING_NAME:EgressRouting리소스 이름입니다.REGION: 배포의 리전입니다.PROJECT_ID: Google Cloud 프로젝트 ID입니다.SWP_NAME: Secure Web Proxy 게이트웨이의 이름입니다.
세 URI가 모두 프로젝트 ID 또는 번호, 리전, 리소스 이름과 일치하는지 확인합니다.
EgressRouting.sources[].workloadUri:- 서비스 범위:
//run.googleapis.com/projects/PROJECT_ID/locations/REGION/services/SERVICE_NAME - 프로젝트 범위:
//run.googleapis.com/projects/PROJECT_ID또는//run.googleapis.com/projects/PROJECT_NUMBER
- 서비스 범위:
EgressRouting.gateway://networkservices.googleapis.com/projects/PROJECT_ID/locations/REGION/gateways/SWP_NAMEAgentGateway.selfManaged.resourceUris[]:projects/PROJECT_ID/locations/REGION/gateways/SWP_NAME
Secure Web Proxy 트랜잭션 로그 확인
Envoy 사이드카가 트래픽을 Secure Web Proxy로 전달하지만 요청이 실패하는 경우 프록시 트랜잭션 로그 보기에 설명된 대로 프록시 로그를 검사합니다.
- 프록시 로그에 트래픽이 표시되지 않으면 요청이 Secure Web Proxy에 도달하지 않는 것입니다. EgressRouting 및 AgentGateway 리소스 URI 감사 및 일반적인 문제 및 해결 방법에서
EgressRouting구성을 확인합니다. - 예상치 못한
DENY또는ALLOW결정이 표시되면 로그 항목에서jsonPayload.authzPolicyInfo및jsonPayload.agentGatewayInfo를 확인하여 일치하는AuthzPolicy및 대상 메타데이터를 검사하고 Agent Gateway 리소스에 연결된ExtensionBinding규칙을 확인합니다.ExtensionBinding리소스를 만들거나 업데이트한 후 구성 변경사항이 게이트웨이에 전파되는 데 최대 5분이 걸릴 수 있습니다.
일반적인 문제 및 해결 방법
다음 섹션에서는 일반적인 문제와 해결 방법을 설명합니다.
리소스 URI 불일치로 인해 아웃바운드 트래픽이 Agent Gateway를 우회함
Cloud Run의 아웃바운드 트래픽이 Agent Gateway를 우회하거나 egress-routings create가 성공한 후 타임아웃됩니다. envoy_sidecar_log에서 jsonPayload.upstream_host는 envoy://tunnel_internal_listener/ 대신 대상 IP 주소와 포트를 표시합니다.
EgressRouting 또는 AgentGateway 리소스 URI 중 하나가 존재하지 않는 리소스 이름 또는 일치하지 않는 리전을 참조합니다. Traffic Director API가 Cloud Run 서비스에서 Secure Web Proxy로의 체인을 확인할 수 없는 경우 터널 변환을 건너뛰고 ORIGINAL_DST를 제공합니다.
EgressRouting 및 AgentGateway 리소스 URI 감사의 명령어를 실행하여 일치하지 않는 URI를 찾습니다. 일치하는 리소스 이름과 리전으로 구성을 업데이트하고 AgentGateway 또는 EgressRouting 리소스를 다시 만듭니다.
Envoy 사이드카가 xDS 구성을 수신할 수 없음
Cloud Run 컨테이너의 아웃바운드 요청이 타임아웃되거나 실패하고 envoy_sidecar_log에 다음 오류가 포함됩니다.
DeltaAggregatedResources gRPC config stream to trafficdirector.REGION.rep.googleapis.com:443 closed: 7, The caller does not have permission
Cloud Run 런타임 서비스 ID에 roles/trafficdirector.client가 없습니다. 기본적으로 --functional-type=agent 및 --identity-type=agent-identity를 사용하여 서비스를 배포하면 roles/run.agentDefaultAccess가 부여되며, 여기에는 roles/trafficdirector.client 및 roles/cloudtrace.agent가 포함됩니다. 서비스 ID에 이러한 권한이 없으면 역할을 부여합니다.
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"
다음을 바꿉니다.
PROJECT_ID: Google Cloud 프로젝트 ID입니다.ORGANIZATION_ID: Google Cloud 조직 ID입니다.PROJECT_NUMBER: Google Cloud 프로젝트 번호REGION: 서비스의 리전SERVICE_NAME: Cloud Run 에이전트 서비스의 이름입니다. 서비스에서 에이전트 ID 대신 서비스 계정을 사용하는 경우--member를serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com로 설정합니다.
Cloud Run 서비스 에이전트가 VPC 네트워크에 액세스할 수 있는지 확인합니다. 기본적으로 roles/run.serviceAgent에는 이러한 권한이 포함됩니다. 서비스 에이전트 권한을 수정한 경우 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"
Secure Web Proxy 게이트웨이를 업데이트하면 Envoy 터널링이 중단됨
기존 Secure Web Proxy 게이트웨이의 ServerTlsPolicy, 인증서, IP 주소 또는 포트를 업데이트한 후 아웃바운드 요청이 502, 503 또는 504 오류로 실패하거나 envoy_sidecar_log에서 RESPONSE_FLAGS: UF를 보고합니다.
보안 웹 프록시 게이트웨이를 만든 후에는 addresses 또는 ports를 변경할 수 없습니다. 또한 기존 Secure Web Proxy 게이트웨이에서 serverTlsPolicy 또는 certificateUrls에 대한 업데이트는 Traffic Director API의 EgressRouting 엔드포인트로 전파되지 않습니다.
워크로드 다운타임 없이 이러한 Secure Web Proxy 필드를 변경하려면 다음 단계를 완료합니다.
- 다른 리소스 이름과 업데이트된 구성으로 대체 Secure Web Proxy 게이트웨이를 만듭니다.
- 대체 Secure Web Proxy 게이트웨이 URI를 참조하도록
AgentGateway리소스의selfManaged.resourceUris를 업데이트합니다. - 대체 Secure Web Proxy 게이트웨이를 가리키도록
EgressRouting리소스를 다시 만듭니다. - 대체 Secure Web Proxy 게이트웨이가 트래픽을 라우팅한 후
AgentGateway리소스에서 이전 Secure Web Proxy 게이트웨이를 삭제하고 이전 Secure Web Proxy 게이트웨이를 삭제합니다.
Secure Web Proxy가 모든 아웃바운드 트래픽을 거부함
EgressRouting 정책을 만들거나 ExtensionBinding를 연결한 후 Cloud Run 에이전트의 모든 아웃바운드 요청이 403 오류와 함께 실패합니다.
Secure Web Proxy는 Agent Gateway 리소스의 ALLOW AuthzPolicy에서 허용할 때까지 기본적으로 모든 트래픽을 거부합니다. ExtensionBinding를 연결해도 ALLOW AuthzPolicy가 없는 트래픽은 허용되지 않으며 기본 Secure Web Proxy Gateway 리소스에 연결된 정책은 무시됩니다.
승인된 트래픽을 허용하려면 Agent Gateway 리소스를 타겟팅하는 ALLOW AuthzPolicy를 연결합니다. 자세한 내용은 기준 이그레스 및 MCP 트래픽 허용을 참조하세요.
아웃바운드 모델 요청이 403 오류와 함께 실패함
Agent Gateway에서 정책을 구성한 후 Cloud Run 에이전트에서 REGION-aiplatform.googleapis.com의 Vertex AI와 같은 모델 엔드포인트로의 아웃바운드 호출이 403 Forbidden 오류와 함께 실패합니다.
--vpc-egress=all는 모든 아웃바운드 컨테이너 트래픽을 Secure Web Proxy를 통해 라우팅하므로 ALLOW AuthzPolicy가 모델 컨텍스트 프로토콜(MCP) 메서드만 일치하거나 Identity-Aware Proxy(IAP) ExtensionBinding가 Identity and Access Management(IAM) 통합 액세스 정책에 허용 규칙이 없는 비MCP 호스트와 일치하면 모델 요청이 실패합니다.
아웃바운드 모델 호출을 허용하려면 Agent Gateway 리소스의 ALLOW AuthzPolicy에서 모델 엔드포인트를 허용합니다. 또한 IAP matchConditionsExtensionBinding의 범위를 prefix: "urn:mcp"로 지정하거나 IAM 통합 액세스 정책에 destination.unregistered.host 허용 규칙을 추가합니다. 자세한 내용은 기준 이그레스 및 MCP 트래픽 허용 및 IAP 이그레스 정책 구성을 참조하세요.
Secure Web Proxy에서 GatewaySecurityPolicyRules를 무시함
GatewaySecurityPolicyRules를 만들었거나 Secure Web Proxy Gateway 리소스에 AuthzPolicy를 연결했지만 아웃바운드 에이전트 트래픽에 영향을 미치지 않습니다.
Secure Web Proxy가 AgentGateway 리소스와 연결된 경우 Secure Web Proxy는 AgentGateway 리소스에 연결된 승인 정책 및 확장 프로그램 바인딩만 적용합니다. 기본 Secure Web Proxy Gateway에 연결된 GatewaySecurityPolicyRules 또는 AuthzPolicy 리소스는 무시됩니다.
대신 AuthzPolicy 및 ExtensionBinding 리소스를 Agent Gateway 리소스에 연결하세요. 자세한 내용은 Agent Gateway에서 정책 구성을 참조하세요.
아웃바운드 요청이 TLS 검사에 실패함
Cloud Run 에이전트의 아웃바운드 요청이 모든 연결에서 TLS 오류로 인해 실패합니다.
Certificate Authority Service 풀에 보안 웹 프록시 서비스 계정 roles/privateca.certificateManager이 없습니다.
CA 풀에 대한 roles/privateca.certificateManager을 보안 웹 프록시 서비스 계정에 부여합니다. 자세한 내용은 서비스 계정 만들기를 참조하세요.
아웃바운드 TLS 검사 연결이 SSLV3_ALERT_HANDSHAKE_FAILURE 또는 RemoteDisconnected로 실패함
에이전트의 아웃바운드 요청이 SSLV3_ALERT_HANDSHAKE_FAILURE을 사용하여 대상 호스트에 처음 연결할 때 실패하거나 RemoteDisconnected로 실패합니다.
대상 호스트에 대한 첫 번째 TLS 검사 연결에서 Secure Web Proxy는 CA 서비스에서 리프 인증서를 생성하고 캐시하므로 일시적인 핸드셰이크 오류가 발생할 수 있습니다. 기본적으로 Connection: close를 전송하는 HTTP 클라이언트(예: urllib.request.urlopen)는 TLS 가로채기 중에 RemoteDisconnected로 인해 실패할 수 있습니다.
에이전트 코드에서 이러한 오류를 방지하려면 다음 안내를 따르세요.
httpx.AsyncClient또는requests.Session()와 같이 영구 연결을 재사용하는 HTTP 클라이언트를 사용합니다.httpx.AsyncHTTPTransport(retries=2)또는urllib3.util.Retry와 같은 HTTP 클라이언트에서 연결 및 핸드셰이크 재시도를 구성합니다.