1. 소개
이 Codelab에서는 VPC 서비스 제어 경계를 사용하여 에이전트와 Agent Gateway를 설정하도록 Google Cloud 환경을 구성하는 방법을 안내합니다. VPC 서비스 제어 경계를 설정하고, 네트워킹 및 DNS를 구성하고, IAP (Identity-Aware Proxy) 요청 승인으로 에이전트 게이트웨이를 배포하고, 에이전트를 안전하게 테스트합니다.
빌드할 항목
이 Codelab에서는 다음을 수행하는 Gemini Enterprise Agent Platform 및 Agent Gateway를 위한 안전한 Google Cloud 아키텍처를 빌드합니다.
- VPC 서비스 제어를 사용하여 승인되지 않은 데이터 무단 반출로부터 프로젝트 리소스를 보호합니다.
- 비공개 API 라우팅을 위해 비공개 Google 액세스, Private Service Connect (PSC), Cloud DNS 비공개 영역을 구성합니다.
- 중앙 집중식 트래픽 프록시, 이그레스 규칙, 프로토콜 구성으로 Agent Gateway를 프로비저닝합니다.
- Identity-Aware Proxy (IAP) 요청 승인 정책을 적용합니다.
- 비공개 연결을 통해 Agent Engine 에이전트를 배포하고 안전하게 테스트합니다.
학습할 내용
- 에이전트 플랫폼 및 보안에 필요한 Google Cloud API를 사용 설정하는 방법
- VPC 서비스 제어 경계 및 인그레스 액세스 규칙을 구성하는 방법
- 비공개 네트워크 연결 및 비공개 DNS 레코드를 설정하는 방법
- Agent Gateway 및 에이전트 연결 템플릿을 만드는 방법
- IAP 요청 승인 확장 프로그램 및 정책을 구성하는 방법
- Agent Engine 에이전트를 안전하게 배포하고 테스트하는 방법
필요한 항목
- Google Cloud CLI가 설치되어 있고 최신 버전으로 업데이트되어 있습니다.
- 워크스테이션에 Python 3이 설치되어 있어야 합니다.
- 워크스테이션에 Git이 설치되어 있어야 합니다.
- 활성 Google Cloud 조직 및 결제 계정 권한
2. 기본 요건
이 섹션에서는 설정 스크립트를 실행하기 전에 필요한 기본 명령줄 도구 요구사항과 환경 구성을 간략하게 설명합니다.
- Google Cloud CLI가 설치되어 있고 최신 버전으로 업데이트되어 있는지 확인한 다음 Google 계정으로 인증합니다. Google Cloud CLI 구성요소를 업데이트하여 네트워크 서비스 및 VPC 서비스 제어에 대한 최신 기능 지원을 확보하세요.
gcloud components update
gcloud auth login
gcloud config set account USER_EMAIL
- Python 3이 설치되어 있는지 확인하여 맞춤 에이전트 프레임워크를 구성하고 배포합니다. 안내는 Python 모듈 설치를 참고하세요.
python3 --version
- 설정 코드와 구성 템플릿이 포함된 샘플 저장소를 클론하려면 Git이 설치되어 있어야 합니다. 자세한 내용은 Git 설치를 참고하세요.
3. Google Cloud 프로젝트 구성
조직 내에 격리된 프로젝트를 만들면 이 Codelab에서 사용되는 모든 리소스, 네트워크, 권한이 캡슐화되어 관리 가능하게 됩니다. 프로젝트 만들기 및 관리에 대해 자세히 알아보세요.
이 설정의 리소스를 호스팅할 조직 아래에 새 Google Cloud 프로젝트를 초기화합니다. 자체 프로젝트를 사용할 수도 있습니다.
export PROJ_ID="YOUR_PROJECT_ID"
gcloud projects create ${PROJ_ID} --organization=YOUR_ORG_ID
gcloud config set project $PROJ_ID
gcloud auth application-default set-quota-project $PROJ_ID
로그인하여 애플리케이션 기본 사용자 인증 정보를 가져옵니다.
gcloud auth application-default login
구성을 확인합니다
gcloud config list
결제 사용 설정
새로 만든 프로젝트에 활성 결제 계정을 연결하여 서비스 사용을 사용 설정합니다.
결제를 사용 설정하는 것은 API 할당량을 사용하고 에이전트 게이트웨이, 가상 프라이빗 클라우드, 컴퓨팅 노드와 같은 Google Cloud 인프라를 프로비저닝하기 위한 필수 요건입니다. 결제 구성에 대한 자세한 내용은 Google Cloud Billing 문서를 참고하세요.
gcloud billing accounts list
# Copy the billing account to assign to your GCP project
gcloud billing projects link $PROJ_ID --billing-account=BILLING_ACCOUNT_ID
4. 서비스 사용 설정
에이전트, Agent Gateway, 네트워킹, 보안, 관측 가능성 기능에 필요한 모든 Google Cloud API를 사용 설정합니다.
API 활성화는 보안 에이전트 연결에 필요한 리소스 관리, 관측 가능성, 네트워킹 기능을 위한 백엔드 클라우드 서비스를 노출합니다. Service Usage API 문서에서 자세히 알아보세요.
gcloud services enable \
agentregistry.googleapis.com \
aiplatform.googleapis.com \
apphub.googleapis.com \
apptopology.googleapis.com \
cloudapiregistry.googleapis.com \
cloudtrace.googleapis.com \
compute.googleapis.com \
dataform.googleapis.com \
iam.googleapis.com \
iap.googleapis.com \
logging.googleapis.com \
modelarmor.googleapis.com \
monitoring.googleapis.com \
networksecurity.googleapis.com \
networkservices.googleapis.com \
notebooks.googleapis.com \
observability.googleapis.com \
securitycenter.googleapis.com
gcloud services enable \
saasservicemgmt.googleapis.com \
storage.googleapis.com \
telemetry.googleapis.com \
texttospeech.googleapis.com \
run.googleapis.com \
artifactregistry.googleapis.com \
cloudbuild.googleapis.com \
dns.googleapis.com \
accesscontextmanager.googleapis.com \
discoveryengine.googleapis.com \
agentidentity.googleapis.com \
agentidentitycredentials.googleapis.com
5. 환경 변수 내보내기
리전, 프로젝트 ID, 프로젝트 번호, 조직 ID, 사용자 ID에 재사용 가능한 환경 변수를 정의합니다. 셸 변수를 설정하면 단계별로 리소스 구성 명령어가 표준화되어 스크립트 실행 중에 수동 대체 오류가 최소화됩니다.
export REGION="us-central1"
export PROJ_ID=$(gcloud config list --format="value(core.project)")
export PROJ_NO=$(gcloud projects describe ${PROJ_ID} --format="value(projectNumber)")
export ORG_ID=$(gcloud projects get-ancestors ${PROJ_ID} --format="value(id)" | tail -n 1)
export USER_IDENTITY=$(gcloud config get-value account)
6. VPC 서비스 제어 경계 만들기
VPC 서비스 제어 경계를 만들어 프로젝트 리소스를 격리하고 데이터 무단 반출을 방지합니다. 자세한 내용은 VPC 서비스 제어 개요를 참고하세요.
액세스 정책 가져오기
조직과 연결된 Access Context Manager 정책 ID를 가져옵니다. Access Context Manager 정책은 VPC 서비스 제어 경계가 연결되고 적용되는 조직 경계를 정의합니다.
gcloud access-context-manager policies list --organization=$ORG_ID
액세스 정책 내보내기
gcloud CLI 구성에서 액세스 정책을 설정하고 지원되는 제한된 서비스 목록을 수집합니다. 지원되는 모든 서비스를 수집하면 Google Cloud API 엔드포인트 전반에서 무단 액세스를 방지하는 제한된 경계 규칙 집합을 빌드할 수 있습니다.
export ACCESS_POLICY=ACCESS_POLICY_ID
gcloud config set access_context_manager/policy $ACCESS_POLICY
SUPPORTED_SERVICES=$(gcloud access-context-manager supported-services list --format="value(name)" | paste -sd, -)
경계 만들기
서비스 경계 이름을 정의하고 프로젝트 내에서 지원되는 Google Cloud 서비스 전반에 제한사항을 적용합니다. 경계는 프로젝트 리소스를 둘러싸는 경계 역할을 하며, 인그레스/이그레스 규칙에 의해 명시적으로 허용되지 않는 한 직접적인 인바운드 및 아웃바운드 트래픽을 제한합니다.
export PERIMETER_NAME="perimeter_${PROJ_NO}"
gcloud access-context-manager perimeters create accessPolicies/${ACCESS_POLICY}/servicePerimeters/${PERIMETER_NAME} \
--title="${PERIMETER_NAME}" \
--perimeter-type=regular \
--resources=projects/${PROJ_NO} \
--restricted-services=${SUPPORTED_SERVICES}
인그레스 정책 만들기
인그레스 정책은 트래픽이 경계 외부에서 시작되어 경계 내부의 제한된 리소스에 도달하도록 허용되는 명시적 조건(예: 특정 사용자 ID 또는 액세스 수준)을 정의합니다.
모든 서비스에서 사용자 ID에 대한 명시적 액세스를 허용하는 YAML 파일을 만듭니다.
cat > ingress-policy.yaml << EOF
- ingressFrom:
identities:
- user:${USER_IDENTITY}
sources:
- accessLevel: '*'
ingressTo:
operations:
- serviceName: '*'
resources:
- '*'
EOF
gcloud access-context-manager perimeters update $PERIMETER_NAME --set-ingress-policies="ingress-policy.yaml"
이 Codelab에서는 기본적으로 VPC 서비스 제어 액세스 거부를 방지하도록 환경을 구성합니다. 하지만 테스트 중에 문제를 해결할 수 있도록 VPC 서비스 제어는 거부 로그와 정책 인텔리전스 도구를 자세히 제공합니다.
VPC 서비스 제어 거부 문제 해결
테스트하는 동안 다음 문제 해결 도움말을 참고하세요.
- 위반 대시보드를 사용 설정하여 환경의 최신 위반을 추적합니다.
- VPC 서비스 제어 액세스 거부 (403) 로그에 대해 Cloud 감사 로그를 모니터링합니다.
- 위반 분석 도구에서 위반 고유 ID 또는 토큰을 사용하여 위반을 진단합니다.
- 자세한 안내는 VPC 서비스 제어 문제 해결 동영상을 참고하세요.
7. 네트워킹 설정
Google API 및 서비스와의 비공개 통신을 지원하도록 VPC 네트워크 설정을 구성합니다. 적절한 네트워크 구성은 에이전트, 게이트웨이, Google Cloud API 간의 네트워크 트래픽이 비공개 내부 네트워크에 유지되도록 보장합니다. 자세한 네트워킹 패턴은 Google Cloud VPC 문서를 참고하세요.
비공개 Google 액세스 사용 설정
VM 인스턴스와 내부 워크로드가 공개 IP 주소 대신 내부 IP 주소를 사용하여 Google API에 연결할 수 있도록 기본 서브넷에서 비공개 Google 액세스를 사용 설정합니다.
export NETWORK_NAME="default"
export SUBNET_NAME="default"
gcloud compute networks subnets update $SUBNET_NAME --region=$REGION --enable-private-ip-google-access
PSC 네트워크 연결 만들기
에이전트 게이트웨이 연결을 위한 Private Service Connect (PSC) 네트워크 연결을 만듭니다. 네트워크 연결은 Private Service Connect (PSC) 인터페이스를 제공하여 Agent Gateway 서비스와 내부 서브넷 간의 안전한 교차 VPC 통신을 지원합니다.
gcloud compute network-attachments create psc-agw-${REGION} \
--region=${REGION} \
--subnets=${SUBNET_NAME} \
--connection-preference=ACCEPT_AUTOMATIC
확인
새로 생성된 네트워크 연결의 self-link 리소스 URI를 가져와 검사합니다. 리소스 URI를 검증하면 네트워크 연결이 성공적으로 인스턴스화되었으며 연결 템플릿에서 참조할 수 있습니다.
export PSC_NA_URI=$(gcloud compute network-attachments describe psc-agw-${REGION} \
--region=${REGION} \
--format="value(selfLink.scope(v1))")
echo ${PSC_NA_URI}
Cloud DNS 비공개 영역 만들기
비공개 IP 범위를 통해 googleapis.com 트래픽을 라우팅하도록 Cloud DNS 비공개 영역을 구성합니다. 비공개 DNS 영역은 googleapis.com의 공개 도메인 조회를 재정의하여 모든 아웃바운드 트래픽을 VPC 네트워크 내의 비공개 내부 가상 IP (VIP)로 전달합니다. 자세한 내용은 Cloud DNS 비공개 영역을 참고하세요.
export ZONE_NAME="gapis"
gcloud dns managed-zones create ${ZONE_NAME} \
--visibility=private \
--networks=https://www.googleapis.com/compute/v1/projects/${PROJ_ID}/global/networks/${NETWORK_NAME} \
--description="Privately reach Google APIs" \
--dns-name=googleapis.com
gcloud dns record-sets transaction start --zone=${ZONE_NAME}
비공개 라우팅을 위해 다음 도메인 옵션 중 하나를 선택합니다 (트랜잭션을 실행하기 전에 옵션 1 또는 옵션 2 아래의 명령만 실행). 자세한 내용은 비공개 Google 액세스 구성 옵션을 참고하세요.
옵션 1: 비공개 VIP[권장]
gcloud dns record-sets transaction add --name="*.googleapis.com." \
--type=CNAME private.googleapis.com. \
--zone=${ZONE_NAME} \
--ttl=300
gcloud dns record-sets transaction add --name=private.googleapis.com. \
--type=A 199.36.153.8 199.36.153.9 199.36.153.10 199.36.153.11 \
--zone=${ZONE_NAME} \
--ttl=300
옵션 2: 제한된 VIP
gcloud dns record-sets transaction add --name="*.googleapis.com." \
--type=CNAME restricted.googleapis.com. \
--zone=${ZONE_NAME} \
--ttl=300
gcloud dns record-sets transaction add --name=restricted.googleapis.com. \
--type=A 199.36.153.4 199.36.153.5 199.36.153.6 199.36.153.7 \
--zone=${ZONE_NAME} \
--ttl=300
DNS 트랜잭션을 커밋합니다.
gcloud dns record-sets transaction execute --zone=${ZONE_NAME}
8. Agent Gateway 만들기
Agent Gateway를 프로비저닝하고 연결 템플릿과 라우팅 규칙을 정의합니다. Agent Gateway는 에이전트 트래픽, 이그레스 정책, 프로토콜 처리, 보안 서비스 검색을 관리하는 중앙 집중식 프록시 역할을 합니다. 아키텍처 참조는 에이전트 게이트웨이 개요를 참고하세요.
export AGW_NAME="gateway-${USER_IDENTITY}"
export AGW_CONNECTIVITY_TEMPLATE="agw-connectivity-template-${USER_IDENTITY}"
Create Agent Connectivity Template(에이전트 연결 템플릿 만들기)
연결 템플릿은 게이트웨이가 아웃바운드 요청을 처리하는 데 필요한 네트워크 구성, 이그레스 라우팅 정책, DNS 피어링 설정, 네트워크 연결 URI를 지정합니다.
cat > ${AGW_CONNECTIVITY_TEMPLATE}.yaml << EOF
name: projects/${PROJ_NO}/locations/${REGION}/agentConnectivityTemplates/${AGW_CONNECTIVITY_TEMPLATE}
accessPath: AGENT_TO_ANYWHERE
deploymentModel: CENTRALIZED
egressNetworkConfig:
networkAttachment: ${PSC_NA_URI}
dnsPeeringConfig:
domain: googleapis.com.
targetNetwork: projects/${PROJ_ID}/global/networks/${NETWORK_NAME}
vpcEgress: ALL_TRAFFIC
EOF
gcloud network-services agent-connectivity-templates import ${AGW_CONNECTIVITY_TEMPLATE} \
--source="${AGW_CONNECTIVITY_TEMPLATE}.yaml" \
--location=${REGION}
Agent Gateway 만들기
cat > ${AGW_NAME}-config.yaml << EOF
name: ${AGW_NAME}
protocols:
- MCP
googleManaged:
governedAccessPath: AGENT_TO_ANYWHERE
agentConnectivityTemplate: projects/${PROJ_NO}/locations/${REGION}/agentConnectivityTemplates/${AGW_CONNECTIVITY_TEMPLATE}
registries:
- //agentregistry.googleapis.com/projects/${PROJ_NO}/locations/global
EOF
gcloud network-services agent-gateways import ${AGW_NAME} \
--source="${AGW_NAME}-config.yaml" \
--location=${REGION}
생성 확인
Agent Gateway 리소스가 성공적으로 배포되고 구성되었는지 확인합니다. 배포된 에이전트 게이트웨이를 설명하면 작동 상태가 활성 상태인지 확인하고 연결된 연결 템플릿과 레지스트리가 올바르게 연결되었는지 확인할 수 있습니다.
gcloud network-services agent-gateways describe ${AGW_NAME} \
--location=${REGION}
9. IAP를 통해 승인 만들기
에이전트 게이트웨이에 대한 액세스 권한을 부여하기 전에 요청 사용자 인증 정보를 확인하도록 IAP (Identity-Aware Proxy) 요청 승인 정책 및 서비스 확장 프로그램을 구성합니다. 자세한 내용은 IAP 문서를 참고하세요.
export AUTHZ_EXT="iap-authz-extension-${USER_IDENTITY}"
export AUTHZ_POLICY="iap-authz-policy-${USER_IDENTITY}"
승인 확장 프로그램 만들기
cat > ${AUTHZ_EXT}.yaml << EOF
name: ${AUTHZ_EXT}
service: iap.googleapis.com
failOpen: false
timeout: 1s
metadata:
iapPolicyVersion: "V2"
EOF
gcloud service-extensions authz-extensions import ${AUTHZ_EXT} \
--source=${AUTHZ_EXT}.yaml \
--location=${REGION}
인증 정책을 만들고 Agent Gateway에 바인딩
cat > ${AUTHZ_POLICY}.yaml << EOF
name: ${AUTHZ_POLICY}
target:
resources:
- "projects/${PROJ_ID}/locations/${REGION}/agentGateways/${AGW_NAME}"
policyProfile: REQUEST_AUTHZ
action: CUSTOM
customProvider:
authzExtension:
resources:
- "projects/${PROJ_ID}/locations/${REGION}/authzExtensions/${AUTHZ_EXT}"
EOF
gcloud network-security authz-policies import ${AUTHZ_POLICY} \
--source=${AUTHZ_POLICY}.yaml \
--location=${REGION}
이 Codelab에서는 기본적으로 IAP 액세스가 거부되지 않도록 합니다. 하지만 테스트를 지원하기 위해 Agent Gateway는 액세스 거부에 대한 자세한 관측 가능성을 제공합니다.
IAP 승인 거부 문제 해결 및 모니터링
- _Default 로깅 버킷에서 로그 애널리틱스를 사용 설정합니다.
gcloud logging buckets update _Default --location=global --enable-analytics --async
- Agent Gateway 모니터링 가능성 대시보드를 엽니다.
- Google Cloud 콘솔에서 에이전트 게이트웨이 페이지로 이동합니다.
- 게이트웨이 이름 (예: gateway-xyz)을 클릭합니다.
- 모니터링 가능성 탭을 클릭합니다.
- 승인 실패 및 403 거부 대시보드를 검토합니다.
10. Agent Engine 에이전트 만들기
스테이징 버킷 만들기
런타임 초기화 중에 임시 스테이징 아티팩트, 종속 항목, 배포 구성을 저장할 타겟 리전에 Cloud Storage 버킷을 만듭니다.
#Staging bucket name needs to be globally unique
export STAGING_BUCKET="agent-temp-bucket-${PROJ_NO}-${USER_IDENTITY}"
gcloud storage buckets create gs://${STAGING_BUCKET} --location=${REGION}
Python 가상 환경 활성화
python3 -m venv .venv
source .venv/bin/activate
에이전트 코드 다운로드
git clone https://github.com/gpratikab/gcp-vpcsc-agent.git
cd gcp-vpcsc-agent
종속 항목 설치
python3 -m pip install --upgrade -r requirements.txt
Agent Platform 서비스 에이전트에 IAM 역할 부여
gcloud projects add-iam-policy-binding ${PROJ_ID} \
--member="serviceAccount:service-${PROJ_NO}@gcp-sa-aiplatform.iam.gserviceaccount.com" \
--role="roles/agentgateway.serviceAgent"
gcloud projects add-iam-policy-binding ${PROJ_ID} \
--member="serviceAccount:service-${PROJ_NO}@gcp-sa-aiplatform.iam.gserviceaccount.com" \
--role="roles/ml.serviceAgent"
gcloud projects add-iam-policy-binding ${PROJ_ID} \
--member="serviceAccount:service-${PROJ_NO}@gcp-sa-aiplatform.iam.gserviceaccount.com" \
--role="roles/networkservices.viewer"
에이전트 배포
python3 deploy_gcp_agent.py create
이전 명령어의 출력에 인쇄된 에이전트 ID를 환경 변수로 내보냅니다.
#Paste identity of your Agent, it will be printed as the output of the previous command
export AGENT_IDENTITY="principal://PRINCIPAL_ID"
echo $AGENT_IDENTITY
11. 게이트웨이를 통한 에이전트 이그레스 허용
새로 만든 에이전트가 googleapis.com으로 이그레스 트래픽을 전송하도록 허용합니다.
참고: 에이전트 게이트웨이 관측 가능성을 사용하여 엔드포인트를 선택적으로 허용 목록에 추가할 수 있습니다. 간단하게 하기 위해 이 Codelab에서는 모든 API에 대한 액세스를 허용합니다.
명시적 IAM 이그레스 정책 규칙을 구성하면 에이전트가 Agent Gateway 및 IAP 프록시를 통해 API 호출을 라우팅하여 외부 Google Cloud 서비스에 도달할 수 있는 권한이 부여됩니다.
IAM 정책 만들기
cat > agent-access-rules.json << EOF
{
"conditions": {
"iap.googleapis.com": {
"description": "Allow access to agent",
"expression": "(destination.agent_registry.location == 'global') || (destination.unregistered.host.endsWith('googleapis.com'))",
"title": "agenttogapis"
}
},
"description": "agenttogapis",
"effect": "ALLOW",
"excludedPrincipals": [],
"operation": {
"excludedPermissions": [],
"permissions": [
"iap.googleapis.com/resources.egressViaIAP"
]
},
"principals": [
"${AGENT_IDENTITY}"
]
}
EOF
액세스 정책 업데이트
기존 액세스 정책이 있는지 확인합니다.
gcloud iam access-policies list --project=${PROJ_ID} --location=global
액세스 정책 이름을 설정합니다.
export IAM_ACCESS_POLICY="agent-access-policy"
새 정책을 만드는 방법은 다음과 같습니다.
gcloud iam access-policies create ${IAM_ACCESS_POLICY} \
--details-rules=agent-access-rules.json \
--project=${PROJ_ID} \
--location=global
또는 기존 정책을 업데이트합니다.
gcloud iam access-policies update ${IAM_ACCESS_POLICY} \
--add-details-rules=agent-access-rules.json \
--project=${PROJ_ID} \
--location=global
12. 에이전트 테스트
Google Cloud 콘솔에서 에이전트 작업을 검증하면 엔드 투 엔드 통신, IAM 정책, VPC 서비스 제어 경계가 올바르게 작동하는지 확인할 수 있습니다. 이제 에이전트를 테스트할 준비가 되었습니다.
- Google Cloud 콘솔에서 에이전트 배포 페이지로 이동합니다.
- 배포된 에이전트를 선택합니다 (
gcp_agent_...). - Playground 탭을 엽니다.
- 프롬프트 필드에
List storage buckets in the current project.를 입력합니다. - 에이전트가 비공개 Agent Gateway를 통해 버킷 목록을 성공적으로 반환하는지 확인합니다.
- 액세스 거부로 인해 에이전트가 다른 프로젝트에서 버킷을 가져올 수 없는지 확인합니다. Cloud 감사 로그 또는 VPC 서비스 제어 위반 대시보드에서 거부를 검사할 수 있습니다.
13. 삭제
이 Codelab에서 사용한 리소스 비용이 Google Cloud 계정에 청구되지 않도록 하려면 만든 프로젝트를 삭제하세요.
gcloud projects delete ${PROJ_ID}
14. 축하합니다
수고하셨습니다 Google Cloud의 보안 VPC 서비스 제어 경계 내에서 에이전트와 Agent Gateway를 성공적으로 구성했습니다.
다음 단계
- VPC 서비스 제어의 세분화된 인그레스 및 이그레스 규칙을 살펴봅니다.
- Agent Gateway를 사용하여 액세스 및 시맨틱 정책을 구성합니다.
- 고급 안전 및 보안 필터링을 위해 Model Armor를 통합합니다.