Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

Gemini Enterprise Agent Platform에서 Apigee에 비공개로 액세스

이 페이지는 Apigee에 적용되지만 Apigee Hybrid에는 적용되지 않습니다.

이 문서에서는 Gemini Enterprise Agent Platform 에이전트 런타임에 배포된 에이전트에서 Private Service Connect를 사용하여 Apigee에 게시된 API 및 모델 컨텍스트 프로토콜 (MCP) 도구로의 비공개 연결을 구성하는 방법을 설명합니다. 이 패턴을 사용하면 에이전트에서 Apigee로 전송되는 트래픽이 완전히 비공개로 유지되고 공개 인터넷을 통과하지 않습니다.

개요

Agent Runtime은 Virtual Private Cloud (VPC) 네트워크에 액세스하지 않고도 안전한 Google 관리 네트워크에 에이전트를 배포합니다. Apigee도 마찬가지로 보안이 유지되는 Google 관리형 네트워크에서 실행됩니다. 에이전트가 Apigee를 통해 노출된 대규모 언어 모델 (LLM) 또는 MCP 도구에 대한 호출을 비공개로 이동하도록 하려면 사용자가 제어하는 VPC 네트워크를 통해 이러한 두 Google 관리 네트워크를 연결하는 방법이 필요합니다.

이 문서에서는 브리지에 대해 다음 패턴을 설명합니다.

에이전트 런타임은 소비자 VPC의 서브넷에 있는 네트워크 연결에 연결되는 Private Service Connect 인터페이스 (PSC 인터페이스)를 프로비저닝합니다. 에이전트의 아웃바운드 트래픽이 해당 VPC로 송신됩니다.
동일한 소비자 VPC에서 Apigee 인스턴스가 노출하는 서비스 연결을 타겟팅하는 Private Service Connect 엔드포인트를 만듭니다.
Apigee 환경 그룹 호스트 이름을 Private Service Connect 엔드포인트 IP 주소로 확인하는 소비자 VPC에 Cloud DNS 비공개 영역을 만듭니다.
Agent Runtime은 DNS 피어링을 사용하여 소비자 VPC의 비공개 영역을 통해 Agent Runtime 환경 내에서 호스트 이름을 확인합니다.

이 구성을 사용하면 에이전트가 https://APIGEE_HOSTNAME/...를 호출할 때 요청이 VPC의 Private Service Connect 엔드포인트 IP로 확인되고, 서비스 연결을 통해 Apigee 인스턴스로 전달되며, 요청 경로와 일치하는 API 프록시에 의해 처리됩니다.

시작하기 전에

이 문서에서는 명령어에 다음 자리표시자를 사용합니다. 환경의 값으로 바꿉니다.

APIGEE_PROJECT_ID: Apigee 조직이 포함된 Google Cloud 프로젝트 ID입니다.
SERVICE_PROJECT_ID: 에이전트 런타임에 에이전트를 배포하는 Google Cloud 프로젝트 ID입니다. Google Cloud 리소스를 구성하는 방식에 따라 APIGEE_PROJECT_ID와 동일하거나 다른 프로젝트일 수 있습니다.
SERVICE_PROJECT_NUMBER: SERVICE_PROJECT_ID의 숫자 프로젝트 번호입니다. gcloud projects describe SERVICE_PROJECT_ID --format="value(projectNumber)"을 사용하여 검색할 수 있습니다.
HOST_PROJECT_ID: 소비자 VPC 네트워크, 서브넷, Cloud DNS 비공개 영역이 포함된 Google Cloud 프로젝트 ID입니다. 공유 VPC를 사용하는 경우를 제외하고는 SERVICE_PROJECT_ID와 동일합니다. 공유 VPC를 사용하는 경우 서비스 프로젝트가 연결되는 호스트 프로젝트입니다.
REGION: Apigee 인스턴스의 리전입니다 (예: us-west1).
VPC_NAME: HOST_PROJECT_ID의 소비자 VPC 네트워크 이름
SUBNET_NAME: REGION에 있는 VPC_NAME의 서브넷 이름입니다.
APIGEE_HOSTNAME: Apigee 환경 그룹에서 구성한 호스트 이름입니다 (예: api.internal.example.com).
BASE_PATH: Apigee에 배포된 API 프록시의 기본 경로입니다 (예: /mcp 또는 /orders).
PARENT_DNS_NAME: 비공개 영역에서 제공할 APIGEE_HOSTNAME의 상위 DNS 도메인입니다 (예: internal.example.com.). 값은 점으로 끝나야 합니다.
APIGEE_INSTANCE_NAME: REGION의 Apigee 인스턴스 이름입니다.

프로젝트 토폴로지에 관한 참고사항: APIGEE_PROJECT_ID, SERVICE_PROJECT_ID, HOST_PROJECT_ID는 독립적입니다. 모두 동일한 프로젝트일 수도 있고, 모두 다른 프로젝트일 수도 있으며, Google Cloud 리소스를 구성하는 방식에 맞는 조합일 수도 있습니다.

소비자 네트워크에 공유 VPC를 사용하는 경우 HOST_PROJECT_ID는 호스트 프로젝트이고 SERVICE_PROJECT_ID는 여기에 연결된 서비스 프로젝트입니다. 그렇지 않으면 HOST_PROJECT_ID는 SERVICE_PROJECT_ID와 동일합니다.
공유 VPC 배포에서 네트워크 연결을 소유하는 프로젝트와 해당 IAM 역할에 관한 자세한 내용은 Agent Platform 문서의 공유 VPC와 Private Service Connect 인터페이스 사용을 참고하세요.

필요한 사항은 다음과 같습니다.

결제가 사용 설정된 하나 이상의 Google Cloud 프로젝트 (위 참고사항에 설명됨)
APIGEE_PROJECT_ID에 있는 기존 Apigee 조직으로, 하나 이상의 인스턴스가 있습니다. 이 문서에서는 Apigee 인스턴스와 동일한 리전에 모든 소비자 네트워킹 리소스 (네트워크 연결, Private Service Connect 엔드포인트, 에이전트 런타임 배포)를 만듭니다. 이는 가장 간단한 구성입니다.
환경이 해당 Apigee 인스턴스에 배포되고 에이전트가 호출할 호스트 이름을 포함하는 환경 그룹 이 문서에서는 해당 호스트 이름을 APIGEE_HOSTNAME으로 참조합니다.
해당 환경 그룹의 환경에 배포된 API 프록시가 하나 이상 있어야 합니다. 에이전트가 호출할 프록시는 https://APIGEE_HOSTNAME/BASE_PATH에서 연결할 수 있어야 합니다.
HOST_PROJECT_ID의 VPC 네트워크 및 서브넷(Apigee 인스턴스와 동일한 리전) 이 문서에서는 이를 VPC_NAME 및 SUBNET_NAME이라고 합니다. Agent Runtime에는 최소 /28 서브넷이 필요하며 추가 범위 제한이 적용됩니다. 자세한 내용은 Agent Platform 문서의 서브네트워크 IP 범위 요구사항을 참고하세요.
적절한 프로젝트에서 다음 API가 사용 설정되어 있습니다.
- APIGEE_PROJECT_ID의 Apigee (apigee.googleapis.com)
- HOST_PROJECT_ID의 Compute Engine (compute.googleapis.com) 및 Cloud DNS(dns.googleapis.com)
- SERVICE_PROJECT_ID의 에이전트 플랫폼 (aiplatform.googleapis.com)
HOST_PROJECT_ID에서 Cloud DNS 영역 및 레코드, Compute Engine 주소, 네트워크 연결, Private Service Connect 전달 규칙을 만들고 APIGEE_PROJECT_ID에서 Apigee 인스턴스 및 환경 그룹 구성을 업데이트할 수 있는 충분한 IAM 권한 필요한 역할에 대한 자세한 내용은 Apigee 역할, Cloud DNS 액세스 제어, Compute Engine IAM 역할을 참고하세요.

아키텍처

다음 단계에서는 소비자 VPC의 Private Service Connect 엔드포인트를 브리지로 사용하여 Agent Runtime에 배포된 에이전트와 Apigee에서 호스팅되는 API 프록시 간의 트래픽 흐름을 설명합니다.

Agent Runtime에서 실행되는 에이전트가 APIGEE_HOSTNAME에 HTTPS 요청을 합니다.
Agent Runtime PSC 인터페이스에 구성된 DNS 피어링은 조회 요청을 소비자 VPC의 Cloud DNS 비공개 영역으로 전달하고, 이 영역은 Private Service Connect 엔드포인트의 IP 주소를 반환합니다.
에이전트의 요청은 PSC 인터페이스를 통해 소비자 VPC로 나가 해당 IP 주소의 Private Service Connect 엔드포인트에 도달합니다.
Private Service Connect 엔드포인트는 서비스 연결을 통해 요청을 Apigee 인스턴스의 서비스 연결로 전달합니다.
Apigee 인스턴스는 TLS를 종료하고, 요청 호스트 이름을 환경 그룹과 일치시키고, 올바른 API 프록시로 라우팅합니다.

1단계: 소비자 VPC에서 네트워킹 구성

이 섹션에서는 두 프로젝트에 걸쳐 리소스를 구성합니다. 각 명령어에는 명시적 --project 플래그가 포함되어 있으므로 활성 gcloud 구성에서 명령어를 실행할 수 있습니다.

비공개 영역이 소비자 VPC 네트워크에 연결되므로 Cloud DNS 리소스 (비공개 영역 및 레코드)는 HOST_PROJECT_ID에 생성됩니다.
Private Service Connect 엔드포인트 리소스 (고정 내부 IP 주소 및 전달 규칙)와 네트워크 연결은 SERVICE_PROJECT_ID에 생성됩니다. 이러한 각 명령어는 HOST_PROJECT_ID의 공유 서브넷 또는 VPC 네트워크에 대한 교차 프로젝트 참조를 사용합니다. 단일 프로젝트 배포에서 SERVICE_PROJECT_ID와 HOST_PROJECT_ID은 동일하므로 단계 간 소유권 변경이 없습니다. Private Service Connect 엔드포인트의 공유 VPC 모델에 대한 자세한 내용은 공유 VPC 서비스 프로젝트에서 엔드포인트 만들기를 참고하세요.

Cloud DNS 비공개 영역 만들기

소비자 VPC에만 표시되는 Cloud DNS 비공개 영역을 만듭니다. 에이전트는 이 영역을 사용하여 (DNS 피어링을 통해) APIGEE_HOSTNAME를 비공개 IP 주소로 확인합니다.

gcloud dns managed-zones create apigee-private \
  --project=HOST_PROJECT_ID \
  --dns-name="PARENT_DNS_NAME" \
  --description="Private zone for Apigee PSC access" \
  --visibility=private \
  --networks=VPC_NAME

Cloud DNS 비공개 영역에 대한 자세한 내용은 비공개 영역을 참고하세요.

네트워크 연결 만들기

에이전트 런타임 PSC 인터페이스가 표시되도록 하려는 동일한 리전 및 서브넷에 네트워크 연결을 만듭니다. 에이전트가 배포되면 Agent Runtime은 PSC 인터페이스를 이 연결에 바인딩합니다.

단일 프로젝트 배포에서는 SERVICE_PROJECT_ID (HOST_PROJECT_ID이기도 함)에 네트워크 연결을 만듭니다. 공유 VPC 배포에서는 서비스 프로젝트 또는 호스트 프로젝트에 네트워크 연결을 만들 수 있습니다. Agent Platform에서는 권한을 간소화하기 위해 서비스 프로젝트를 권장합니다. 선택 및 해당 IAM 역할에 관한 안내는 공유 VPC에서 Private Service Connect 인터페이스 사용을 참고하세요.

다음 명령어는 SERVICE_PROJECT_ID에 네트워크 연결을 만듭니다. 공유 VPC 배포에서 서브넷 참조에는 호스트 프로젝트 ID가 포함되어야 합니다.

gcloud compute network-attachments create agent-network-attachment \
  --project=SERVICE_PROJECT_ID \
  --region=REGION \
  --subnets=projects/HOST_PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME \
  --connection-preference=ACCEPT_AUTOMATIC

고정 내부 IP 주소 예약

에이전트가 연결하는 Private Service Connect 엔드포인트의 IP로 사용할 내부 IP 주소를 예약합니다. SERVICE_PROJECT_ID에서 주소 리소스를 만들고 HOST_PROJECT_ID에서 공유 서브넷을 참조하여 주소 값이 해당 서브넷의 범위에서 할당되도록 합니다. 이는 공유 VPC에 고정 내부 IP 주소 사용의 공유 VPC 안내와 일치합니다.

gcloud compute addresses create apigee-psc-endpoint-ip \
  --project=SERVICE_PROJECT_ID \
  --region=REGION \
  --subnet=projects/HOST_PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME

이후 단계에서 사용할 예약된 주소를 가져옵니다.

gcloud compute addresses describe apigee-psc-endpoint-ip \
  --project=SERVICE_PROJECT_ID \
  --region=REGION \
  --format="value(address)"

이 문서에서는 이 주소를 PSC_ENDPOINT_IP로 참조합니다.

Apigee 인스턴스의 서비스 연결 가져오기

Apigee API의 organizations.instances.get 메서드를 사용하여 Apigee 인스턴스의 서비스 연결 URI를 가져옵니다. 이 URI를 Private Service Connect 엔드포인트의 타겟으로 사용합니다.

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://apigee.googleapis.com/v1/organizations/APIGEE_PROJECT_ID/instances/APIGEE_INSTANCE_NAME"

응답에는 serviceAttachment 필드가 포함됩니다. 이 문서에서는 이 값을 APIGEE_SERVICE_ATTACHMENT으로 참조합니다. Apigee가 각 인스턴스에서 서비스 연결을 노출하는 방법에 대한 자세한 내용은 인스턴스 관리를 참고하세요.

Private Service Connect 엔드포인트 만들기

Private Service Connect 엔드포인트 역할을 하는 전달 규칙을 만듭니다. Apigee 서비스 연결을 타겟팅하고 예약한 고정 IP를 사용합니다. SERVICE_PROJECT_ID에서 전달 규칙을 만들고 HOST_PROJECT_ID의 공유 VPC 네트워크와 SERVICE_PROJECT_ID의 주소를 참조합니다.

gcloud compute forwarding-rules create apigee-psc-endpoint \
  --project=SERVICE_PROJECT_ID \
  --region=REGION \
  --network=projects/HOST_PROJECT_ID/global/networks/VPC_NAME \
  --address=projects/SERVICE_PROJECT_ID/regions/REGION/addresses/apigee-psc-endpoint-ip \
  --target-service-attachment=APIGEE_SERVICE_ATTACHMENT

Apigee 서비스가 연결을 수락했는지 확인합니다.

gcloud compute forwarding-rules describe apigee-psc-endpoint \
  --project=SERVICE_PROJECT_ID \
  --region=REGION \
  --format="value(pscConnectionStatus)"

엔드포인트가 트래픽을 전달하려면 상태가 ACCEPTED여야 합니다. Private Service Connect 엔드포인트에 대한 자세한 내용은 엔드포인트를 통해 게시된 서비스 액세스 정보를 참고하세요.

호스트 이름의 DNS 레코드 추가

비공개 영역에서 APIGEE_HOSTNAME을 PSC_ENDPOINT_IP로 확인하는 A 레코드를 만듭니다. 이 레코드는 VPC_NAME 내부에서만 표시되므로 외부 클라이언트는 공개 DNS를 통해 호스트 이름을 계속 확인합니다.

gcloud dns record-sets create APIGEE_HOSTNAME. \
  --project=HOST_PROJECT_ID \
  --zone=apigee-private \
  --type=A \
  --ttl=60 \
  --rrdatas=PSC_ENDPOINT_IP

2단계: Apigee 구성

인스턴스 소비자 허용 목록에 서비스 프로젝트 추가

Apigee 인스턴스는 consumerAcceptList에 있는 소비자 프로젝트의 Private Service Connect 연결만 수락합니다. 연결의 소비자 측면은 SERVICE_PROJECT_ID와 연결됩니다. 에이전트가 배포된 프로젝트이기 때문입니다.

기본적으로 Apigee 조직(APIGEE_PROJECT_ID)과 연결된 프로젝트가 이미 목록에 있습니다. SERVICE_PROJECT_ID이 APIGEE_PROJECT_ID과 동일한 경우 변경이 필요하지 않으므로 이 섹션을 건너뛸 수 있습니다. 그렇지 않으면 SERVICE_PROJECT_ID을 목록에 추가합니다.

먼저 organizations.instances.get 메서드를 사용하여 consumerAcceptList의 현재 값을 확인합니다.

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://apigee.googleapis.com/v1/organizations/APIGEE_PROJECT_ID/instances/APIGEE_INSTANCE_NAME"

응답에서 consumerAcceptList 필드를 찾습니다.

그런 다음 consumerAcceptList에서 업데이트 마스크를 사용하여 organizations.instances.patch 메서드를 호출하여 목록을 업데이트합니다. 이 필드는 기존 목록을 대체하므로 APIGEE_PROJECT_ID 및 에이전트를 배포하는 추가 서비스 프로젝트를 비롯하여 액세스 권한을 유지해야 하는 모든 프로젝트 ID를 포함합니다.

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{"consumerAcceptList": ["APIGEE_PROJECT_ID", "SERVICE_PROJECT_ID"]}' \
  "https://apigee.googleapis.com/v1/organizations/APIGEE_PROJECT_ID/instances/APIGEE_INSTANCE_NAME?updateMask=consumerAcceptList"

get 명령어를 다시 실행하고 SERVICE_PROJECT_ID이 이제 consumerAcceptList에 포함되었는지 확인하여 업데이트를 확인합니다.

환경 그룹 호스트 이름 확인

API 프록시를 호스팅하는 환경 그룹에 APIGEE_HOSTNAME가 나열되어 있는지 확인합니다. 그렇지 않으면 추가합니다.

자세한 내용은 환경 그룹 작업을 참고하세요.

3단계: PSC 인터페이스 및 DNS 피어링을 사용하여 에이전트 배포

에이전트를 Agent Runtime에 배포할 때 생성한 네트워크 연결을 참조하는 PSC 인터페이스로 구성하고 비공개 영역에 대한 DNS 피어링을 구성합니다. 전체 배포 절차 및 지원되는 프레임워크는 Agent Platform 문서의 Agent Runtime에서 Private Service Connect 인터페이스 사용 및 에이전트 배포를 참고하세요.

에이전트의 PSC 인터페이스 구성에서 다음 두 필드를 구성합니다 (PscInterfaceConfig 참조).

networkAttachment: 1단계에서 만든 네트워크 연결의 전체 리소스 이름을 projects/SERVICE_PROJECT_ID/regions/REGION/networkAttachments/agent-network-attachment 형식으로 설정합니다. 호스트 프로젝트에서 네트워크 연결을 만든 경우 이 경로에서 HOST_PROJECT_ID를 사용하세요.
dnsPeeringConfigs: Agent Runtime이 비공개 영역을 통해 APIGEE_HOSTNAME를 확인할 수 있도록 다음 필드가 있는 항목을 하나 추가합니다.
- domain: PARENT_DNS_NAME. 값은 점으로 끝나야 합니다.
- targetProject: HOST_PROJECT_ID. 소비자 VPC와 비공개 영역이 포함된 프로젝트입니다.
- targetNetwork: VPC_NAME.

SERVICE_PROJECT_ID(service-SERVICE_PROJECT_NUMBER@gcp-sa-aiplatform.iam.gserviceaccount.com)의 Agent Platform 서비스 에이전트에는 DNS 피어링을 구성하고 네트워크 연결을 업데이트할 권한이 있어야 합니다. Agent Platform 서비스 에이전트 필수 역할에 설명된 대로 필요한 역할을 부여합니다. 공유 VPC 배포에서는 호스트 프로젝트에 추가 역할이 적용됩니다. 공유 VPC에서 Private Service Connect 인터페이스 사용을 참고하세요.

에이전트 코드에서 https://APIGEE_HOSTNAME/BASE_PATH의 API 프록시를 호출합니다. Agent Runtime 환경 내에서 이 호스트 이름은 DNS 피어링을 통해 PSC_ENDPOINT_IP로 확인되고 요청은 Private Service Connect 엔드포인트를 통해 VPC로 이동한 후 Apigee로 이동합니다.

비공개 경로 확인

에이전트를 배포한 후 요청이 비공개 경로를 통해 Apigee에 도달하는지 확인합니다.

Private Service Connect 엔드포인트 만들기의 명령어를 사용하여 전달 규칙 상태가 ACCEPTED인지 확인합니다.
REGION의 VPC_NAME에 연결된 Compute Engine VM에서 (공유 VPC 배포에서 이 VM은 호스트 프로젝트 또는 공유 VPC에 연결된 서비스 프로젝트에 있을 수 있음) dig +short APIGEE_HOSTNAME를 실행합니다. 결과는 PSC_ENDPOINT_IP이어야 합니다. 이렇게 하면 비공개 영역이 VPC 내에서 호스트 이름을 올바르게 확인하는지 확인할 수 있습니다.
동일한 VM에서 배포된 API 프록시에 https://APIGEE_HOSTNAME/BASE_PATH로 요청을 보내고 예상된 응답을 수신하는지 확인합니다.
배포된 에이전트를 호출하고 요청이 처리되었는지 확인합니다. 그런 다음 Apigee 분석 또는 디버그를 사용하여 요청이 환경 그룹 호스트 이름의 예상 API 프록시에 도착했는지 확인합니다.

다음 단계

Agent Runtime에서 Private Service Connect 인터페이스 사용에 대해 자세히 알아보세요.
Agent Runtime에서 에이전트를 배포하는 방법을 알아봅니다.
관리형 TLS 인증서를 사용하는 부하 분산기 기반 변형인 Private Service Connect를 사용한 상위 네트워킹에 대해 알아봅니다.
Apigee가 백엔드 대상에 비공개로 연결되는 방법을 설명하는 Southbound 네트워킹 패턴에 대해 알아봅니다.
API를 에이전트형 애플리케이션에 MCP 도구로 노출하기 위한 Apigee의 MCP에 대해 알아봅니다.