VPC 연결을 사용하여 Agent Gateway 설정

이 문서에서는 Agent Gateway를 배포할 때 조직의 VPC 네트워크와 비공개로 통신할 수 있도록 VPC 연결을 구성하는 과정을 안내합니다.

VPC 연결을 설정하면 다음을 수행할 수 있습니다.

  • 트래픽에 VPC 이그레스 적용: PRIVATE_RANGES_ONLY 또는 ALL_TRAFFIC 모드를 사용하여 Private Service Connect 네트워크 연결을 통해 에이전트에서 발생하는 트래픽을 VPC 네트워크로 라우팅합니다.
  • 고정 소스 IP 주소 범위: 이그레스 트래픽은 Private Service Connect 네트워크 연결 서브넷의 비공개 IP 주소 범위를 소스 IP 주소로 사용합니다. 이 고정 소스 IP 범위를 사용하면 게이트웨이에서 들어오는 트래픽을 제어하도록 VPC 네트워크의 방화벽 정책을 구성할 수 있습니다.
  • 커스텀 DNS 변환: Cloud DNS 피어링을 사용하여 에이전트에서 직접 내부 비공개 도메인 이름과 외부 도메인 이름을 변환합니다.
  • 경계 보안: VPC 서비스 제어 서비스 경계를 사용하여 에이전트 통신을 보호합니다.
  • 비공개 또는 자체 서명 인증서 검증: 비공개 CA 또는 자체 서명 인증서를 사용하는 대상에 연결합니다.

VPC 연결을 구성하려면 Agent Gateway 인스턴스의 이그레스 네트워킹 설정을 정의하고 관리하는 Agent Gateway 연결 템플릿(AgentConnectivityTemplate)을 만듭니다.

VPC 연결 작동 방식

연결 템플릿을 사용하여 Agent Gateway를 배포하면 게이트웨이는 Private Service Connect 인터페이스를 사용하여 아웃바운드 에이전트 트래픽을 지정된 VPC 네트워크로 라우팅합니다.

VPC 이그레스 모드

연결 템플릿의 vpcEgress 설정을 사용하여 게이트웨이가 네트워크 연결을 통해 트래픽을 라우팅하는 방법을 구성합니다.

  • 비공개 IP 주소 범위로의 트래픽(PRIVATE_RANGES_ONLY): 비공개 IP 주소 범위로만 향하는 트래픽을 VPC 네트워크로 라우팅합니다. 대상 IP 주소가 다음 범위 중 하나에 속하는 경우에만 아웃바운드 트래픽이 VPC 네트워크로 라우팅됩니다.

    • RFC 1918: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
    • RFC 6598: 100.64.0.0/10
    • E등급: 240.0.0.0/4
    • private.googleapis.com: 199.36.153.8/30
    • restricted.googleapis.com: 199.36.153.4/30
    • Google API용 PSC 엔드포인트: VPC 네트워크에서 내부 비공개 IP 주소를 사용하여 Google API용 커스텀 Private Service Connect 엔드포인트를 배포하는 경우 이 엔드포인트에 대한 트래픽이 VPC 네트워크를 통해 라우팅됩니다. Agent Gateway가 Google API 도메인을 내부 PSC 엔드포인트 IP 주소로 올바르게 변환하도록 연결 템플릿에 Cloud DNS 피어링이 구성되어 있는지 확인합니다.

    표준 공개 Google API에 대한 요청은 비공개 Google 액세스를 사용하여 자동으로 처리되며 인터넷으로 향하는 트래픽은 VPC 네트워크가 아닌 Agent Gateway를 통해 직접 라우팅됩니다.

  • 모든 IP 주소 범위로의 트래픽(ALL_TRAFFIC): 공개 인터넷, 외부 SaaS API, RFC 1918 이외의 주소를 포함하여 에이전트에서 발생하는 모든 아웃바운드 트래픽을 VPC 네트워크를 통해 라우팅합니다.

    • 라우팅 및 보안: 이 설정은 모든 아웃바운드 트래픽을 VPC로 라우팅하므로 라우팅 및 보안을 관리해야 합니다. VPC 네트워크에 이 트래픽을 아웃바운드 게이트웨이 또는 보안 어플라이언스 (예: 다음 홉 방화벽 또는 Cloud Interconnect 인터페이스)로 전달하는 기본 경로 (0.0.0.0/0)가 있는지 확인합니다.
    • 공개 인터넷 이그레스: Agent Gateway는 아웃바운드 트래픽을 VPC 네트워크로 전송하며, 이 트래픽은 Private Service Connect 네트워크 연결 서브넷의 Cloud NAT 게이트웨이를 통해 공개 인터넷으로 나갑니다. 고정 외부 IP 주소를 Cloud NAT 게이트웨이에 할당하면 원격 서비스에서 이러한 소스 IP 주소를 기반으로 에이전트의 이그레스 트래픽을 허용 목록에 추가할 수 있습니다.
    • VPC 서비스 제어: VPC 서비스 제어 서비스 경계를 지원하려면 이그레스 모드를 ALL_TRAFFIC로 설정해야 합니다.

DNS 변환 및 트래픽 라우팅

기본적으로 Agent Gateway는 공개 재귀 DNS를 사용하여 도메인 이름을 확인합니다. 에이전트가 VPC 네트워크의 비공개 도메인 이름에 호스팅된 내부 워크로드, 비공개 도구 또는 Google API(예: corp.internal. 또는 PSC 엔드포인트)에 액세스해야 하는 경우 DNS 쿼리를 네트워크의 비공개 Cloud DNS 관리형 영역으로 전달하도록 Cloud DNS 피어링을 구성할 수 있습니다.

다음 표에는 VPC 연결이 ALL_TRAFFIC 모드로 구성된 경우 다양한 대상에 대한 Cloud DNS 피어링 요구사항과 트래픽 라우팅 동작이 요약되어 있습니다.

표: ALL_TRAFFIC 모드의 DNS 변환 및 트래픽 라우팅
트래픽 대상 Cloud DNS 피어링이 필요한가요? DNS 확인 이그레스 경로
비공개 IP 서비스
(RFC 1918/내부)		 예(예: corp.internal.) 대상 VPC 네트워크의 비공개 Cloud DNS 관리형 영역과 Cloud DNS 피어링을 사용하여 확인합니다. 트래픽은 네트워크 연결을 통해 VPC 네트워크로 들어가 내부 워크로드에 연결됩니다.
비공개 IP가 있는 공개 호스트 이름
(분할된 범위의 DNS)		 아니요 Cloud DNS 피어링 없이 게이트웨이 프록시에서 표준 공개 재귀 DNS를 사용하여 확인합니다. 트래픽은 네트워크 연결을 통해 VPC 네트워크로 들어가 내부 워크로드에 연결됩니다.
공개 인터넷 및 SaaS API
(외부 도메인)		 아니요 Cloud DNS 피어링 없이 게이트웨이 프록시에서 표준 공개 재귀 DNS를 사용하여 확인합니다. 트래픽은 네트워크 연결을 통해 VPC 네트워크로 들어오고 서브넷에 구성된 Cloud NAT를 사용하여 공개 인터넷으로 나갑니다.
Google Cloud API
(표준, VPC 서비스 제어 없음)		 아니요 Cloud DNS 피어링 없이 게이트웨이 프록시에서 표준 공개 재귀 DNS를 사용하여 확인합니다. 트래픽은 네트워크 연결을 통해 VPC 네트워크로 들어오고 Cloud NAT 또는 DNS 피어링을 사용하지 않고 서브넷에서 사용 설정된 비공개 Google 액세스를 사용하여 비공개로 라우팅됩니다.
Google Cloud API
(VPC 서비스 제어 사용)		 예(googleapis.com.의 경우) 비공개 Cloud DNS 영역을 사용하여 제한된 Google API 범위 (199.36.153.4/30) 또는 내부 Private Service Connect 엔드포인트로 확인됩니다. 트래픽은 네트워크 연결을 통해 VPC 네트워크로 들어가 VPC 서비스 제어 경계 보안 규칙을 적용합니다1.

1 호스트 프로젝트를 참조하는 compute.googleapis.com 또는 dns.googleapis.com에서 NETWORK_NOT_IN_SAME_SERVICE_PERIMETER 또는 SECURITY_POLICY_VIOLATED와 같은 VPC 서비스 제어 위반으로 인해 요청이 실패하는 경우 호스트 프로젝트가 게이트웨이 프로젝트와 동일한 경계에 있는지 확인합니다.

TLS 인증서 요구사항

HTTPS를 통해 이그레스 트래픽을 라우팅할 때 Agent Gateway는 TLS 핸드셰이크 중에 대상 서버의 TLS 인증서 체인을 검증합니다. HTTPS 연결의 인증서 요구사항은 대상 엔드포인트가 공개적으로 신뢰할 수 있는 인증 기관 (CA)을 사용하는지 아니면 비공개/자체 서명 CA를 사용하는지에 따라 달라집니다.

  • 공개 CA: 기본적으로 Agent Gateway는 표준 서버 인증서 요구사항(대상 호스트 이름과 일치하는 주체 대체 이름(SAN) 포함)을 충족하는 공개적으로 신뢰할 수 있는 인증 기관(CA)에서 발급한 인증서를 신뢰합니다.

  • 비공개 CA 및 자체 서명 인증서: 대상 목적지(VPC 네트워크의 에이전트, 도구 또는 MCP 서버)에서 비공개 CA 또는 내부 PKI를 사용하는 경우 연결 템플릿의 tlsConfig 설정을 사용하여 커스텀 신뢰 앵커를 구성할 수 있습니다.

    인증서 관리자 TrustConfig 리소스를 참조하여 특정 비공개 CA만 신뢰하도록 Agent Gateway를 구성하거나 비공개 루트 CA를 공개적으로 신뢰할 수 있는 CA(PUBLICLY_TRUSTED_ROOTS)와 결합할 수 있습니다. 이렇게 하면 공개 및 비공개 엔드포인트 모두에 대한 신뢰가 설정됩니다.

    에이전트가 Google Cloud API (*.googleapis.com) 또는 기타 공개 HTTPS 엔드포인트에 연결하는 경우 additionalRoots를 PUBLICLY_TRUSTED_ROOTS로 설정해야 합니다. 이 설정이 없으면 Agent Gateway가 googleapis.com에 대해 Google에서 서명한 인증서를 신뢰하지 않습니다.

    tlsConfig를 사용할 때는 다음 제한사항에 유의하세요.

    • trustConfig를 사용하여 비공개 CA를 사용하는 대상으로 트래픽을 라우팅하는 경우 PEM 파일을 수동으로 순환해야 합니다. Google Cloud의 Secret Manager와 같은 보안 비밀 관리자를 사용한 PEM 파일의 자동 순환은 지원되지 않습니다.
    • trustConfig 필드는 연결 템플릿에서 구성된 후에는 변경할 수 없으며, Agent Gateway는 연결된 연결 템플릿에서 tlsConfig에 대한 변경사항 (예: additionalRoots 업데이트)을 자동으로 선택하지 않습니다. TLS 설정 업데이트에 대한 안내는 VPC 이그레스 설정 업데이트를 참조하세요.

Agent Gateway가 인증서 체인을 검증할 수 없으면 연결이 실패합니다.

필수 역할 및 권한

Agent Gateway의 VPC 연결을 구성하려면 프로비저닝에 사용되는 ID와 게이트웨이 서비스 에이전트에 필요한 역할이 있는지 확인합니다.

독립형 프로젝트 배포

게이트웨이, 네트워크 연결, VPC 네트워크가 동일한 프로젝트에 있는 독립형 프로젝트에서는 표준 Agent Gateway 권한이 적용됩니다. 자세한 내용은 필수 권한을 참조하세요.

공유 VPC 또는 프로젝트 간 배포

공유 VPC 배포에서는 서비스 프로젝트 또는 호스트 프로젝트에서 Agent Gateway를 프로비저닝할 수 있습니다. 호스트 프로젝트 (공유 VPC 네트워크, 서브넷, 네트워크 연결도 상주하는 프로젝트)에서 게이트웨이를 프로비저닝하는 경우 독립형 프로젝트 권한이 적용됩니다.

대상 VPC 네트워크, 네트워크 연결 또는 비공개 DNS 영역이 호스트 프로젝트 (TARGET_VPC_PROJECT_ID)에 있는 동안 서비스 프로젝트에서 Agent Gateway를 프로비저닝하는 경우 서비스 프로젝트의 ID에 호스트 프로젝트의 네트워킹 및 DNS 리소스를 검증, 연결 또는 피어링할 수 있는 권한이 자동으로 부여되지 않습니다. 표준 Agent Gateway 권한 외에도 호스트 프로젝트에 다음 역할을 부여합니다.

표: 공유 VPC 및 프로젝트 간 배포에 필요한 권한
주 구성원 또는 ID 프로젝트에 대한 권한 부여 필요한 IAM 역할 목적
프로비저닝 ID1
(사용자 계정 또는 배포 서비스 계정)		 호스트 프로젝트(TARGET_VPC_PROJECT_ID)
  • Compute 네트워크 뷰어(roles/compute.networkViewer)
  • DNS 리더(roles/dns.reader)
  • 네트워크 연결 리전 엔드포인트 관리자(roles/networkconnectivity.regionalEndpointAdmin)
  • 네트워크 연결 소비자 네트워크 관리자(roles/networkconnectivity.consumerNetworkAdmin)
 게이트웨이 생성 또는 업데이트 중에 대상 VPC 네트워크, 서브넷, 네트워크 연결, 비공개 DNS 영역의 백엔드 검증을 허용합니다.
네트워크 연결 생성자
(PSC 연결을 만드는 관리자)		 호스트 프로젝트(TARGET_VPC_PROJECT_ID)
  • Compute 네트워크 사용자(roles/compute.networkUser)
 호스트 프로젝트에서 공유 VPC 서브넷을 사용하여 Private Service Connect 네트워크 연결을 만들 수 있습니다.
서비스 프로젝트의 네트워크 연결(권장)
Agent Gateway 서비스 에이전트2 호스트 프로젝트(TARGET_VPC_PROJECT_ID)
  • Compute 네트워크 사용자(roles/compute.networkUser)
  • DNS 피어 (roles/dns.peer)
 Agent Gateway 서비스 에이전트가 네트워크 연결에 호스트 프로젝트 서브넷을 사용하고, Private Service Connect 인터페이스를 연결하여 이그레스 트래픽을 라우팅하고, 호스트 프로젝트의 비공개 Cloud DNS 영역과 피어링할 수 있도록 허용합니다.
호스트 프로젝트의 네트워크 연결
Agent Gateway 서비스 에이전트2 호스트 프로젝트(TARGET_VPC_PROJECT_ID)
  • Compute 네트워크 관리자(roles/compute.networkAdmin) 또는 다음 권한이 있는 커스텀 역할:
    • compute.networkAttachments.get
    • compute.networkAttachments.update
    • compute.regionOperations.get
  • DNS 피어 (roles/dns.peer)
 Agent Gateway 서비스 에이전트가 호스트 프로젝트 네트워크 연결을 업데이트하여 Agent Gateway 테넌트 프로젝트의 연결을 허용하고, 이그레스 트래픽을 라우팅하고, 호스트 프로젝트의 비공개 Cloud DNS 영역과 피어링할 수 있도록 허용합니다.

1 프로비저닝 ID의 경우 호스트 프로젝트의 뷰어 (roles/viewer) 또는 편집자 (roles/editor)와 같은 기본 프로젝트 수준 역할도 충분합니다.

2 Agent Gateway 서비스 에이전트의 형식은 service-AGENT_GATEWAY_PROJECT_NUMBER@gcp-sa-agentgateway.iam.gserviceaccount.com입니다. 여기서 AGENT_GATEWAY_PROJECT_NUMBER는 Agent Gateway를 프로비저닝하는 프로젝트의 프로젝트 번호입니다. 공유 VPC 배포의 경우 이 프로젝트는 서비스 프로젝트 또는 호스트 프로젝트일 수 있습니다.

여러 Agent Runtime 서비스 프로젝트를 Agent Gateway 호스트 프로젝트에 연결하는 경우 게이트웨이 프로젝트에 대한 프로젝트 간 액세스 권한을 각 Agent Runtime 서비스 에이전트에 부여해야 합니다. 대규모 배포의 경우 Google 그룹을 사용하여 Agent Runtime 서비스 프로젝트 확장을 참조하세요.

VPC 연결 구성

연결 템플릿을 사용하여 Agent Gateway를 배포하려면 다음 섹션의 단계를 완료하세요.

Private Service Connect 네트워크 연결 만들기

대상 VPC 네트워크에 Private Service Connect 네트워크 연결을 만듭니다.

네트워크 연결이 다음 요구사항을 충족하는지 확인합니다.

  • 연결 환경설정: 연결을 자동으로 수락하도록 네트워크 연결을 구성합니다(--connection-preference=ACCEPT_AUTOMATIC).
  • 동일한 VPC 네트워크 요구사항: 네트워크 연결 서브넷과 DNS 피어링 (targetNetwork)에 구성된 대상 네트워크는 정확히 동일한 VPC 네트워크에 있어야 합니다. 네트워크 연결의 서브넷이 DNS 피어링 대상 네트워크와 다른 네트워크에 속하는 경우 구성 검증이 실패합니다.
  • VPC 네트워크 MTU 지원: Agent Gateway는 네트워크 연결의 서브넷이 포함된 VPC 네트워크에 대해 최대 1,500바이트의 최대 전송 단위(MTU)를 지원합니다. 해당 VPC 네트워크에서 점보 프레임과 같은 더 큰 MTU를 사용하는 경우 Cloud Customer Care에 문의하여 Agent Gateway 프로듀서 서비스를 커스텀 VPC MTU에 맞추세요.
  • 서브넷 요구사항: 네트워크 연결 서브넷에 대한 다음 요구사항을 참고하세요.
    • 서브넷 범위: 네트워크 연결 서브넷은 모든 유효한 범위를 지원합니다.
    • 서브넷 크기: Agent Gateway에는 네트워크 연결을 위한 최소 /28 서브넷이 필요합니다. /28 서브넷은 사용 가능한 IP 주소 12개를 제공하며, 이는 단일 Agent Gateway 인스턴스에 충분합니다. 여러 게이트웨이를 동일한 네트워크 연결 또는 서브넷에 연결하려면 IP 주소 소진을 방지하기 위해 더 큰 서브넷 (예: /26 또는 /24)을 사용합니다.
    • 비공개 Google 액세스 요구사항: 네트워크 연결을 호스팅하는 서브넷에서 비공개 Google 액세스(private_ip_google_access = true)를 사용 설정해야 합니다.
  • 공유 VPC 배포: 공유 VPC 배포의 경우 공유 VPC 배포 토폴로지를 참조하세요.

네트워크 연결의 전체 리소스 URI를 기록해 둡니다 (예: projects/NETWORK_ATTACHMENT_PROJECT_NUMBER/regions/NETWORK_ATTACHMENT_REGION/networkAttachments/NETWORK_ATTACHMENT_NAME). 이후 단계에서 연결 템플릿 리소스를 만들 때 필요합니다.

선택사항: DNS 피어링 설정

DNS 피어링을 사용하면 Agent Gateway가 VPC 네트워크의 Cloud DNS 비공개 관리형 영역에 있는 레코드를 사용하여 DNS 이름을 확인할 수 있습니다. DNS 피어링은 에이전트가 비공개 내부 도메인 이름 (예: corp.internal.)을 확인하거나 Google API (googleapis.com.)에 VPC 서비스 제어를 적용해야 하는 경우에만 필요합니다. 공개 인터넷 도메인이나 VPC 서비스 제어가 없는 표준 Google API에는 필요하지 않습니다.

Agent Gateway는 단일 전환 홉까지만 전환 DNS 피어링을 지원합니다. 즉, 최대 3개의 VPC 네트워크를 지원합니다. 예를 들어 vpc-net-a (Agent Gateway 테넌트 네트워크)는 vpc-net-b (연결된 네트워크)에 피어링할 수 있으며, 이는 다시 vpc-net-c (원격 네트워크)에 피어링하여 체인 전체에서 DNS 쿼리를 확인합니다.

DNS 피어링을 설정하려면 다음 단계를 수행합니다.

  1. 대상 VPC 네트워크에서 비공개 DNS 영역을 설정합니다. 비공개 DNS 영역에 DNS 레코드를 추가하려면 리소스 레코드 세트 추가를 참조하세요.

  2. 피어링을 사용 설정하기 위해 연결 템플릿을 구성하려면 다음 정보를 수집합니다.

    • 대상 네트워크 URI (targetNetwork): 대상 VPC 네트워크의 전체 리소스 URI를 projects/TARGET_VPC_PROJECT_ID/global/networks/TARGET_VPC_NETWORK_NAME 형식으로 기록해 둡니다. 대상 네트워크는 항상 네트워크 연결에서 참조하는 서브넷이 포함된 VPC 네트워크입니다. 대상 네트워크가 공유 VPC 네트워크인 경우 해당 공유 VPC 호스트 프로젝트 ID를 사용해야 합니다.

    • 도메인 이름: DNS 피어링을 위한 하나 이상의 도메인 서픽스입니다. 각 도메인은 후행 점 (.)으로 끝나야 합니다(예: corp.internal. 또는 googleapis.com.).

      domains 필드를 구성하는 방법에 대한 추가 안내는 DNS 피어링 도메인 패턴을 참조하세요. 공유 VPC와 같은 프로젝트 간 배포의 경우 프로젝트 간 DNS 영역 및 피어링 요구사항을 참조하세요.

선택사항: TLS 트러스트 구성 설정

대상에서 비공개 CA 또는 자체 서명 인증서를 사용하는 경우 인증서 관리자에서 TrustConfig 리소스를 만들어야 합니다. TrustConfig 리소스는 Agent Gateway가 TLS 연결을 검증하는 데 사용하는 신뢰 앵커와 인증서를 정의합니다.

  1. PEM 형식으로 인증서 파일을 준비합니다.

    • 트러스트 저장소: PEM 형식의 루트 또는 중간 CA 인증서입니다. Agent Gateway는 신뢰 체인이 이러한 CA 인증서 중 하나로 이어지는 모든 서버 인증서를 신뢰합니다. 트러스트 저장소에는 루트 또는 중간 CA 인증서가 하나 이상 포함되어야 합니다.
    • 허용 목록에 추가된 인증서 (선택사항): 자체 서명 인증서와 같이 명시적으로 신뢰하려는 PEM 형식의 서버 인증서입니다.

  2. 다음 명령어를 실행하여 TrustConfig 리소스를 만듭니다. TrustConfig는 Agent Gateway 및 연결 템플릿과 동일한 프로젝트 및 리전에 만들어야 합니다.

    gcloud certificate-manager trust-configs create TRUST_CONFIG_NAME \
    --location=LOCATION \
    --trust-store="trust-anchors=ROOT_CERT_FILE" \
    --allowlisted-certificates=ALLOWLISTED_CERT_FILE

    다음을 바꿉니다.

    • TRUST_CONFIG_NAME: TrustConfig 리소스의 이름입니다.
    • LOCATION: 트러스트 구성의 리전입니다(예: europe-west1). Agent Gateway 및 연결 템플릿과 동일한 리전이어야 합니다.
    • ROOT_CERT_FILE: PEM으로 인코딩된 루트 또는 중간 CA 인증서의 경로입니다.
    • ALLOWLISTED_CERT_FILE: (선택사항) 명시적으로 신뢰하려는 PEM으로 인코딩된 인증서의 경로입니다. 허용 목록에 추가된 인증서를 사용하지 않는 경우 이 플래그를 생략합니다.

    트러스트 구성 관리에 대한 자세한 내용은 트러스트 구성 만들기 및 관리를 참조하세요.

Agent Gateway 배포

  1. 연결 템플릿 구성 파일을 만듭니다.

    agw-connectivity-template.yaml이라는 YAML 파일을 만듭니다.

    name: projects/AGENT_GATEWAY_PROJECT_NUMBER/locations/LOCATION/agentConnectivityTemplates/CONNECTIVITY_TEMPLATE_NAME
accessPath: AGENT_TO_ANYWHERE
deploymentModel: CENTRALIZED
egressNetworkConfig:
  networkAttachment: projects/NETWORK_ATTACHMENT_PROJECT_NUMBER/regions/NETWORK_ATTACHMENT_REGION/networkAttachments/NETWORK_ATTACHMENT_NAME
  dnsPeeringConfig:
    domains:
      - DOMAIN_NAME
    targetNetwork: projects/TARGET_VPC_PROJECT_ID/global/networks/TARGET_VPC_NETWORK_NAME
  vpcEgress: VPC_EGRESS_MODE
  tlsConfig:
    trustConfig: projects/AGENT_GATEWAY_PROJECT_NUMBER/locations/LOCATION/trustConfigs/TRUST_CONFIG_NAME
    additionalRoots: ADDITIONAL_ROOTS_OPTION

    다음을 바꿉니다.

    • AGENT_GATEWAY_PROJECT_NUMBER: Agent Gateway를 프로비저닝하는 Google Cloud 프로젝트의 프로젝트 번호입니다. 프로젝트 번호를 검색하려면 gcloud projects describe PROJECT_ID --format="value(projectNumber)"를 실행합니다.

    • LOCATION: 연결 템플릿의 리전(예: europe-west1)

    • CONNECTIVITY_TEMPLATE_NAME: 연결 템플릿 리소스의 이름입니다.

    • accessPath: 연결 템플릿의 관리형 액세스 경로입니다. AGENT_TO_ANYWHERE로 설정합니다(연결 템플릿은 이그레스 게이트웨이에만 지원됨).

    • deploymentModel: 게이트웨이의 배포 모델입니다. CENTRALIZED로 설정합니다.

    • networkAttachment: Private Service Connect 네트워크 연결의 전체 리소스 URI입니다.

      • NETWORK_ATTACHMENT_PROJECT_NUMBER: 네트워크 연결을 만든 프로젝트의 프로젝트 번호입니다. 이 프로젝트는 Agent Gateway 프로젝트와 동일할 수도 있고, 공유 VPC 서비스 프로젝트에서 Agent Gateway를 프로비저닝하고 공유 VPC 호스트 프로젝트에서 네트워크 연결을 만드는 경우 다른 프로젝트일 수도 있습니다.
      • NETWORK_ATTACHMENT_REGION: 네트워크 연결이 포함된 리전입니다.
      • NETWORK_ATTACHMENT_NAME: 네트워크 연결 이름입니다.

    • DOMAIN_NAME: (선택사항) DNS 피어링을 위한 하나 이상의 도메인 서픽스입니다(예: corp.internal., googleapis.com., .). 피어링할 각 도메인 서픽스의 domains 아래에 목록 항목을 추가합니다. 각 값은 후행 점 (.)으로 끝나야 하며 대상 네트워크에 대해 승인된 해당 비공개 Cloud DNS 관리형 영역이 있어야 합니다.

      domains 필드를 구성하는 방법에 대한 추가 안내는 DNS 피어링 도메인 패턴을 참조하세요.

    • targetNetwork: (선택사항) DNS 피어링의 대상 VPC 네트워크의 전체 리소스 URI입니다. 대상 네트워크는 항상 네트워크 연결에서 참조하는 서브넷이 포함된 VPC 네트워크입니다.

      • TARGET_VPC_PROJECT_ID: 대상 VPC 네트워크를 소유한 프로젝트의 프로젝트 ID입니다. 네트워크 연결에서 참조하는 서브넷이 포함된 네트워크가 공유 VPC 네트워크인 경우 TARGET_VPC_PROJECT_ID는 공유 VPC 호스트 프로젝트 ID입니다. 항상 프로젝트 번호가 아닌 프로젝트 ID를 사용하여 targetNetwork를 지정합니다.
      • TARGET_VPC_NETWORK_NAME: 대상 VPC 네트워크의 이름입니다.

    • VPC_EGRESS_MODE: 이그레스 라우팅 모드를 설정합니다. PRIVATE_RANGES_ONLY 또는 ALL_TRAFFIC로 설정합니다.

    • tlsConfig: (선택사항) HTTPS를 통해 비공개 엔드포인트에 연결할 때 서버 인증서 검증을 위한 TLS 구성입니다.

      • TRUST_CONFIG_NAME: 비공개 CA 인증서 또는 신뢰 앵커가 포함된 인증서 관리자 TrustConfig 리소스의 이름입니다.
      • ADDITIONAL_ROOTS_OPTION: 커스텀 트러스트 구성 외에 공개적으로 신뢰할 수 있는 CA 루트를 신뢰할지 여부를 지정합니다.
      • trustConfig 파라미터로 검증된 인증서와 공개적으로 신뢰할 수 있는 모든 CA를 모두 신뢰하려면 PUBLICLY_TRUSTED_ROOTS(기본값)로 설정합니다. 에이전트가Google Cloud API(*.googleapis.com) 또는 기타 공개 HTTPS 엔드포인트에도 연결하는 경우 additionalRoots를 PUBLICLY_TRUSTED_ROOTS로 설정해야 합니다. 이 설정이 없으면 Agent Gateway가 googleapis.com에 대해 Google에서 서명한 인증서를 신뢰하지 않습니다.
      • trustConfig 파라미터로 검증된 인증서만 신뢰하려면 NO_ADDITIONAL_ROOTS로 설정합니다.

  2. 연결 템플릿 만들기:

    다음 명령어를 실행하여 연결 템플릿을 만듭니다.

    gcloud network-services agent-connectivity-templates import CONNECTIVITY_TEMPLATE_NAME \
    --source="agw-connectivity-template.yaml" \
    --location=LOCATION

    다음을 바꿉니다.

    • CONNECTIVITY_TEMPLATE_NAME: 연결 템플릿 리소스의 이름입니다.
    • LOCATION: 연결 템플릿 리소스를 만들 위치입니다. 예를 들면 europe-west1입니다.

  3. Agent Gateway 리소스 정의:

    연결 템플릿을 참조하는 게이트웨이 YAML 구성 파일(예: my-agent-gateway-vpc-egress.yaml)을 만들어 AGENT_TO_ANYWHERE 모드에서 새 Agent Gateway 리소스를 정의합니다.

    name: AGENT_GATEWAY_NAME
protocols:
  - MCP
googleManaged:
  governedAccessPath: AGENT_TO_ANYWHERE
agentConnectivityTemplate: projects/AGENT_GATEWAY_PROJECT_NUMBER/locations/LOCATION/agentConnectivityTemplates/CONNECTIVITY_TEMPLATE_NAME
registries:
  - AGENT_REGISTRY_PATH

    다음을 바꿉니다.

    • AGENT_GATEWAY_NAME: Agent Gateway 리소스의 이름입니다.

    • AGENT_GATEWAY_PROJECT_NUMBER: Agent Gateway 및 연결 템플릿을 프로비저닝하는 Google Cloud 프로젝트의 프로젝트 번호입니다. 공유 VPC 배포의 경우 이 프로젝트는 서비스 프로젝트 또는 호스트 프로젝트일 수 있습니다. 프로젝트 번호를 검색하려면 gcloud projects describe PROJECT_ID --format="value(projectNumber)"를 실행합니다.

    • LOCATION: 연결 템플릿의 위치입니다(예: europe-west1).

    • CONNECTIVITY_TEMPLATE_NAME: 연결 템플릿 리소스의 이름입니다.

      • AGENT_REGISTRY_PATH: 게이트웨이와 동일한 프로젝트 및 리전에 있는 리전 에이전트 레지스트리 인스턴스의 경로입니다. 형식은 //agentregistry.googleapis.com/projects/PROJECT_ID/locations/LOCATION입니다. 자세한 내용은 Agent Gateway 배포 계획을 참조하세요.

  4. Agent Gateway 가져오기 및 배포:

    다음 명령어를 실행하여 YAML 사양을 기반으로 Agent Gateway 리소스를 만듭니다.

    gcloud network-services agent-gateways import AGENT_GATEWAY_NAME \
    --source="my-agent-gateway-vpc-egress.yaml" \
    --location=LOCATION

    LOCATION을 Agent Gateway 리소스를 만들려는 위치로 바꿉니다. 예를 들면 europe-west1입니다.

아키텍처 및 네트워킹 고려사항

이 섹션에서는 VPC 연결을 사용하여 Agent Gateway를 배포하기 위한 아키텍처 안내와 고급 네트워킹 패턴을 제공합니다.

VPC 이그레스 설정 업데이트

연결 템플릿은 Agent Gateway에서 참조되는 동안에는 수정할 수 없으며, Agent Gateway는 연결된 연결 템플릿에 적용된 변경사항을 자동으로 선택하지 않습니다.

  • DNS 피어링, VPC 이그레스 모드 또는 TLS 설정(tlsConfig) 업데이트: 연결 템플릿에서 tlsConfig.trustConfig 필드는 구성된 후 변경할 수 없으며, tlsConfig에 대한 인플레이스 업데이트(예: additionalRoots 추가 또는 변경)는 연결된 Agent Gateway에서 선택되지 않습니다. 기존 게이트웨이에서 DNS 피어링 구성, VPC 이그레스 모드 또는 tlsConfig 설정을 업데이트하려면 업데이트된 설정과 함께 동일한 networkAttachment를 사용하는 새 연결 템플릿을 만들고 새 템플릿을 참조하도록 Agent Gateway를 업데이트합니다(또는 연결 템플릿을 바인딩 해제하고 다시 바인딩).

  • 네트워크 연결 변경: networkAttachment 자체는 연결 템플릿과 Agent Gateway 모두에서 구성된 후에는 변경할 수 없습니다. 다른 네트워크 연결(또는 대상 VPC 네트워크)로 전환하려면 새 연결 템플릿과 새 Agent Gateway를 만들어야 합니다.

공유 VPC 배포 토폴로지

공유 VPC 아키텍처에서는 서비스 프로젝트 또는 호스트 프로젝트에서 Agent Gateway를 프로비저닝할 수 있습니다. 서비스 프로젝트에서 Agent Gateway를 프로비저닝할 때 서비스 프로젝트(권장) 또는 호스트 프로젝트에서 네트워크 연결을 만들 수 있습니다.

VPC 서비스 제어 규정 준수

에이전트 통신에 VPC 서비스 제어 경계를 적용하려면 다음을 확인하세요.

  • 연결 템플릿에서 vpcEgress를 ALL_TRAFFIC로 설정합니다.

  • Google API 요청을 restricted.googleapis.com IP 범위(199.36.153.4/30) 또는 Google API용 내부 Private Service Connect 엔드포인트로 전달합니다.

  • googleapis.com의 DNS 변환을 구성합니다. *.googleapis.com를 restricted.googleapis.com에 매핑하는 VPC 네트워크에 비공개 Cloud DNS 영역을 만들고 연결 템플릿의 domains 필드에 googleapis.com.를 포함합니다.

    DNS 구성에 대한 자세한 내용은 비공개 Google 액세스 문서의 googleapis.com의 DNS 구성을 참조하세요.

  • 공유 VPC 배포의 경우 네트워크 연결의 서브넷과 dnsPeeringConfig.targetNetwork를 소유하는 호스트 프로젝트가 Agent Gateway를 배포하는 프로젝트와 동일한 서비스 경계에 있어야 합니다. 이는 서비스 프로젝트에서 네트워크 연결을 만들 때도 적용됩니다. 서브넷과 VPC 네트워크가 여전히 호스트 프로젝트에 속하기 때문입니다. 비공개 DNS 영역이 별도의 DNS 프로젝트에서 호스팅되는 경우 해당 프로젝트도 경계에 포함합니다.

DNS 피어링 도메인 패턴

이 섹션에서는 연결 템플릿에서 domains 필드를 구성하기 위한 도메인 확인 패턴과 옵션을 설명합니다.

도메인 이름 구성: 다음 고려사항에 따라 연결 템플릿에서 domains 필드를 구성합니다.

  • 비공개 내부 도메인: VPC 네트워크에서 호스팅되는 비공개 내부 서비스(예: service.corp.internal)를 확인하려면 내부 도메인 서픽스(예: corp.internal.)를 지정합니다. 이 도메인의 정확히 일치하는 비공개 Cloud DNS 관리형 영역은 대상 VPC 네트워크에 대해 승인되어야 합니다.

  • 분할 수평 DNS(RFC 1918 IP가 있는 공개 도메인): 공개 DNS 영역을 사용하여 내부 비공개 IP를 가리키는 레코드를 호스팅하는 경우(예: Certificate Manager 공개 인증서의 RFC 1918 주소로 확인되는 mcp.example.com) 게이트웨이는 DNS 피어링 없이 공개 재귀 DNS를 사용하여 이러한 레코드를 자동으로 확인합니다.

  • Google Cloud VPC 서비스 제어가 적용된 API: ALL_TRAFFIC가 VPC 서비스 제어를 적용하도록 구성된 경우 Google API 요청은 restricted.googleapis.com IP 범위 (199.36.153.4/30) 또는 내부 PSC 엔드포인트로 확인되어야 합니다. *.googleapis.com를 restricted.googleapis.com에 매핑하는 VPC 네트워크에 비공개 Cloud DNS 영역을 만들고 연결 템플릿의 domains 필드에 googleapis.com.를 포함합니다.

  • 멀티 도메인 확인 패턴: 배포에 여러 비공개 도메인 서픽스를 확인해야 하는 경우 다음 패턴 중 하나를 선택합니다.

    • 여러 개별 도메인 피어링: dnsPeeringConfig의 domains 필드에 도메인 서픽스 목록을 지정합니다(예: corp.internal., prod.internal., googleapis.com.). 목록의 각 도메인은 후행 점(.)으로 끝나야 하며 대상 VPC 네트워크에 대해 승인된 해당 비공개 Cloud DNS 관리형 영역이 있어야 합니다.
    • 통합 상위 서픽스(권장): 공유 상위 도메인 서픽스(예: *.internal. 또는 *.corp.internal.) 아래에 내부 서비스를 통합하고 domains 목록에 해당 상위 도메인을 포함합니다.

    • 비공개 전달 영역을 사용한 포괄적 루트 피어링: 연결 템플릿의 domains 필드에 "."를 포함하고 업스트림 재귀 리졸버(예: 8.8.8.8 또는 내부 엔터프라이즈 리졸버)를 가리키는 VPC 네트워크의 루트 도메인(.)에 대해 Cloud DNS 비공개 전달 영역을 구성합니다. VPC의 더 구체적인 비공개 영역은 가장 긴 서픽스 일치로 먼저 일치하는 반면, 일치하지 않는 공개 쿼리는 업스트림 전달자를 통해 확인됩니다.

프로젝트 간 DNS 영역 및 피어링 요구사항

연결 템플릿의 dnsPeeringConfig 설정은 직접 프로젝트 간 Cloud DNS 피어링을 지원하지 않습니다. 연결 템플릿을 가져올 때 networkAttachment에서 참조하는 서브넷이 targetNetwork과 다른 VPC 네트워크에 속하거나 서비스 또는 외부 프로젝트의 프로젝트 간 DNS 영역 바인딩을 사용하는 경우 검증이 실패합니다.

도메인의 관리형 영역은 targetNetwork를 소유한 호스트 프로젝트에서 만들어야 합니다. 관리형 영역은 다음 영역 유형 중 하나일 수 있습니다.

  • 권한이 있는 비공개 영역
  • 전달 영역
  • Cloud DNS 피어링 영역: 호스트 프로젝트 VPC 네트워크와 연결되어야 하며 대상 VPC 네트워크를 타겟팅해야 합니다. 대상 VPC는 권한 있는 비공개 영역을 사용하여 쿼리를 직접 확인해야 합니다. 쿼리를 다른 DNS 피어링 영역으로 전달(체이닝)하는 것은 지원되지 않으며 NXDOMAIN 오류가 발생합니다.

Google 그룹을 사용하여 Agent Runtime 서비스 프로젝트 확장

여러 Agent Runtime 서비스 프로젝트를 Agent Gateway 호스트 프로젝트에 연결하고 각 서비스 에이전트에 프로젝트 간 액세스 권한을 개별적으로 부여하는 경우 프로젝트를 추가할 때마다 호스트 프로젝트의 IAM 정책을 업데이트해야 합니다. 대규모 배포에서는 역할 바인딩을 추가할 때 IAM 정책 한도에 도달할 수도 있습니다.

새 서비스 프로젝트마다 호스트 프로젝트의 IAM 정책을 업데이트하지 않으려면 단일 Google 보안 그룹을 통해 액세스를 관리하면 됩니다.

  1. 보안 그룹 만들기: Google 관리 콘솔에서 또는 gcloud identity groups create 명령어를 실행하여 보안 그룹을 만듭니다.

  2. Agent Gateway 호스트 프로젝트에 대한 그룹 액세스 권한 부여: AGENT_GATEWAY_PROJECT_ID에서 그룹을 네트워크 서비스 뷰어 역할 (roles/networkservices.viewer)에 바인딩합니다.

    gcloud projects add-iam-policy-binding AGENT_GATEWAY_PROJECT_ID \
    --member="group:GROUP_EMAIL" \
    --role="roles/networkservices.viewer"

    다음을 바꿉니다.

    • AGENT_GATEWAY_PROJECT_ID: Agent Gateway 호스트 프로젝트의 프로젝트 ID입니다.
    • GROUP_EMAIL: 보안 그룹의 이메일 주소 (예: agw-cross-project-runtime@example.com)

  3. 각 서비스 프로젝트의 Agent Runtime 서비스 에이전트를 그룹에 추가: 각 Agent Runtime 서비스 프로젝트에 대해 다음과 같이 gcloud identity groups memberships add 명령어를 실행하여 서비스 에이전트를 보안 그룹에 추가합니다.

    gcloud identity groups memberships add \
    --group-email="GROUP_EMAIL" \
    --member-email="service-AGENT_RUNTIME_PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com"

    AGENT_RUNTIME_PROJECT_NUMBER를 Agent Runtime 서비스 프로젝트의 프로젝트 번호로 바꿉니다.

다음 단계

가이드

안전하고 제어되는 연결을 위해 Agent Gateway를 통해 Agent Runtime 트래픽을 라우팅하는 방법을 알아봅니다.

Codelab

Gemini Enterprise Agent Platform에서 Agent Gateway를 사용하여 에이전트형 워크로드를 제어하는 방법을 알아봅니다.

Codelab

VPC 네트워크의 대상에 액세스하는 AI 에이전트의 Agent Gateway 이그레스 거버넌스에 대해 알아봅니다.

가이드

Agent Gateway의 승인을 IAP, Model Armor 또는 자체 커스텀 승인 서비스에 위임하는 방법을 알아봅니다.

가이드

Agent Gateway 리소스를 보고, 업데이트하고, 연결 해제하고, 삭제하는 방법을 알아봅니다.

가이드

Agent Gateway를 모니터링하는 방법을 알아봅니다.

가이드

Agent Gateway를 통해 Gemini Enterprise 트래픽을 라우팅하는 방법을 알아봅니다.