크로스 클라우드 에이전트형 엔터프라이즈 배포 보안

1. 소개

이 Codelab에서는 에이전트 개발 키트 (ADK), Agent Engine, Google Kubernetes Engine을 사용하여 단일 에이전트 / 멀티 도구 배포를 안전하게 배포합니다. Gemini Enterprise에서 사용자가 시작한 AI 에이전트가 서비스 확장 프로그램이 포함된 GKE 게이트웨이를 사용하여 MCP 도구 응답에서 전송 중인 민감한 데이터를 수정하는 등 Google Cloud를 안전하게 탐색하는 방법을 알아봅니다.

학습 내용

• OpenTelemetry 계측을 사용하여 ADK 모기지 어시스턴트 에이전트를 Agent Engine에 배포
• 내부 게이트웨이 뒤의 Google Kubernetes Engine (GKE)에 백엔드 MCP 서버 배포
• PSC 인터페이스 및 DNS 피어링을 사용하여 에이전트 엔진을 프로젝트 VPC에 연결
• Apigee MCP 검색 프록시를 사용하여 REST API를 MCP 도구로 노출
• DLP 수정 및 MCP 승인을 위한 Service Extensions를 사용하여 관리되는 에이전트 이그레스를 위해 GKE Gateway 구성
• 프롬프트 및 응답 검사를 위해 Model Armor로 AI 보호 장치 적용

필요한 항목

• 웹브라우저(예: Chrome)
• 결제가 사용 설정된 Google Cloud 프로젝트
• Terraform, Kubernetes, Python에 대한 기본 지식

이 Codelab은 엔터프라이즈 환경에서 에이전트 워크플로를 배포하고 보호하려는 개발자와 보안 전문가를 대상으로 합니다.

2. 시작하기 전에

Google Cloud 프로젝트를 만들고 필요한 API를 사용 설정합니다.

1. Google Cloud 콘솔의 프로젝트 선택기 페이지에서 Google Cloud 프로젝트 를 선택하거나 만듭니다.
2. Cloud 프로젝트에 결제가 사용 설정되어 있는지 확인합니다. 프로젝트에 결제가 사용 설정되어 있는지 확인하는 방법을 알아보세요.

필요한 IAM 역할

이 Codelab에서는 Google Cloud 프로젝트에 대해 프로젝트 소유자 역할이 있다고 가정합니다.

API 사용 설정

1. Google Cloud 콘솔에서 Cloud Shell 활성화를 클릭합니다. Cloud Shell을 이전에 사용한 적이 없는 경우 신뢰할 수 있는 환경에서 부스트를 사용하거나 사용하지 않고 Cloud Shell을 시작할 수 있는 선택사항이 표시된 창이 나타납니다. Cloud Shell을 승인하라는 메시지가 표시되면 승인을 클릭합니다.
2. Cloud Shell에서 필요한 모든 API를 사용 설정합니다.

   gcloud services enable \
   compute.googleapis.com \
   container.googleapis.com \
   dns.googleapis.com \
   certificatemanager.googleapis.com \
   dlp.googleapis.com \
   aiplatform.googleapis.com \
   discoveryengine.googleapis.com \
   apigee.googleapis.com
   

종속 항목 설치

Cloud Shell에서 필수 도구가 설치되어 있는지 확인합니다. Terraform, kubectl, Go는 일반적으로 사전 설치되어 있습니다. uv (Python 패키지 관리자)와 Skaffold를 설치해야 합니다.

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install Skaffold
curl -Lo skaffold https://storage.googleapis.com/skaffold/releases/latest/skaffold-linux-amd64 && \
sudo install skaffold /usr/local/bin/

환경 변수 설정하기

이 Codelab 전체에서 사용할 다음 환경 변수를 설정합니다.

export PROJECT_ID=$(gcloud config get project)
export REGION=us-central1
export LOCATION=${REGION}

공개 DNS 영역 만들기

이 Codelab에서는 Terraform 구성을 적용하기 전에 프로젝트에 공개 DNS 영역이 미리 있어야 합니다. 이 영역은 설정에서 인증서 관리자에 필요한 레코드 생성을 자동화할 수 있도록 네임서버 위임에 필요합니다.

Cloud Shell에서 다음 명령어를 실행하여 영역을 만듭니다.

gcloud dns managed-zones create "inference-gateway-zone" \
    --dns-name="gateway.example.com." \
    --description="Public zone for Inference Gateway" \
    --visibility="public" \
    --project="${PROJECT_ID}"

gateway.example.com.을 관리하는 도메인 또는 하위 도메인으로 바꿉니다. 이 영역의 Cloud DNS 네임서버를 가리키도록 도메인 등록기관에서 네임서버 위임을 구성해야 합니다.

3. GitHub 저장소 클론

1. 로컬 머신의 터미널에서 cloud-networking-solutions 저장소를 클론합니다.

   git clone https://github.com/googleCloudPlatform/cloud-networking-solutions.git
   

2. 다운로드한 저장소 디렉터리로 이동합니다.

   cd cloud-networking-solutions/demos/service-extensions-gke-gateway
   

4. Terraform으로 인프라 배포

Terraform을 사용하여 기본 네트워크, GKE 클러스터, 필수 ID 구성을 프로비저닝합니다.

1. 클론된 저장소의 terraform 디렉터리로 이동합니다.

   cd terraform
   

2. Terraform 백엔드를 구성합니다. 부분 백엔드 구성을 위한 backend.conf 파일을 만듭니다. 을 전역적으로 고유한 버킷 이름으로 바꿉니다.

   cat <<EOF > backend.conf
   bucket = "<YOUR_TERRAFORM_STATE_BUCKET>"
   prefix = "terraform"
   EOF
   

상태 버킷이 없는 경우 gcloud storage buckets create gs://<YOUR_TERRAFORM_STATE_BUCKET>를 실행하여 버킷을 만들 수 있습니다.

3. 예시 변수 파일을 복사하고 프로젝트 값으로 업데이트합니다.

   cp example.tfvars terraform.tfvars
   

4. terraform.tfvars을 수정하고 자리표시자 값을 바꿉니다. 다음을 바꿉니다.
   • project_id: Google Cloud 프로젝트 ID입니다.
   • organization_id: 숫자 형식의 GCP 조직 ID입니다.
   • dns_zone_domain: 관리하는 도메인 (예: demo.example.com.)입니다. 점으로 끝나야 합니다.
   다음 기능 플래그가 사용 설정되어 있는지 확인합니다 (예시 파일에 사전 구성되어 있음).
   • enable_certificate_manager = true
   • enable_model_armor = true
   • enable_agent_engine = true
   • enable_psc_interface = true
5. Terraform 구성을 초기화하고 적용합니다.

   terraform init -backend-config=backend.conf
   terraform plan -out=tfplan
   terraform apply "tfplan"
   

5. Skaffold를 사용하여 샘플 워크로드 배포

참고: 원활하고 재현 가능한 환경을 보장하기 위해 이 실습의 모든 MCP 서버는 GKE에 배포됩니다. 실제 엔터프라이즈 시나리오에서는 이러한 데이터가 다양한 클라우드 및 온프레미스 환경에 분산되어 있는 경우가 많습니다.

그런 다음 MCP 서버와 외부 처리 서비스를 GKE 클러스터에 배포합니다.

1. Terraform으로 만든 GKE 클러스터에 연결합니다.

   gcloud container clusters get-credentials gateway-cluster \
       --region=${REGION} \
       --project=${PROJECT_ID}
   

2. 프로젝트 루트로 돌아가 Kubernetes 매니페스트 템플릿을 구성합니다. 예시 구성을 복사하고 프로젝트 ID와 기본 도메인을 설정합니다. 환경에 맞게 BASE_DOMAIN를 설정합니다. BASE_DOMAIN는 dns_zone_domain Terraform 변수와 일치해야 합니다 (끝에 오는 점 제외).

   export BASE_DOMAIN=example.com
   

3. 템플릿에서 Kubernetes 매니페스트와 skaffold.yaml를 생성합니다.

   bash k8s/generate.sh
   envsubst '${PROJECT_ID}' < skaffold.yaml.tmpl > skaffold.yaml
   

4. 모든 백엔드 서비스를 배포합니다.

   skaffold run -m legacy-dms,income-verification-api,corporate-email,dlp-ext-proc
   

5. 게이트웨이 및 HTTPRoute 구성을 배포합니다.

   kubectl apply -k k8s/gateway-internal/
   

6. Model Armor로 AI 가드레일 적용

유해한 프롬프트 삭제 또는 데이터 유출 방지와 같은 콘텐츠 보안 결정을 Model Armor에 위임할 수 있습니다.

기본 요건: IAM 역할 부여

GKE Gateway 서비스 계정에 필요한 역할을 부여해야 합니다. 서비스 계정은 [e-mail] 형식을 따릅니다.

다음 명령어를 실행하여 필요한 권한을 부여합니다.

export GATEWAY_PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")

# Grant roles in the Gateway project
gcloud projects add-iam-policy-binding $PROJECT_ID \
 --member=serviceAccount:service-${GATEWAY_PROJECT_NUMBER}@gcp-sa-dep.iam.gserviceaccount.com \
 --role=roles/modelarmor.calloutUser

gcloud projects add-iam-policy-binding $PROJECT_ID \
 --member=serviceAccount:service-${GATEWAY_PROJECT_NUMBER}@gcp-sa-dep.iam.gserviceaccount.com \
 --role=roles/serviceusage.serviceUsageConsumer

# Grant role in the project containing Model Armor templates
gcloud projects add-iam-policy-binding $PROJECT_ID \
 --member=serviceAccount:service-${GATEWAY_PROJECT_NUMBER}@gcp-sa-dep.iam.gserviceaccount.com \
 --role=roles/modelarmor.user

Model Armor 승인 확장 프로그램 만들기

리전의 Model Armor 서비스를 가리키는 확장 프로그램을 정의합니다. 이 구성을 ma-content-authz-extension.yaml로 저장합니다.

Terraform에서 생성된 Model Armor 템플릿 ID를 내보냅니다.

export MA_TEMPLATE_ID=$(cd terraform && terraform output -raw model_armor_template_id)

cat >ma-content-authz-extension.yaml <<EOF
name: ma-ext
service: modelarmor.$LOCATION.rep.googleapis.com
metadata:
  model_armor_settings: '[
  {
  "response_template_id": "projects/${PROJECT_ID}/locations/$LOCATION/templates/${MA_TEMPLATE_ID}",
  "request_template_id": "projects/${PROJECT_ID}/locations/$LOCATION/templates/${MA_TEMPLATE_ID}"
  }
  ]'
failOpen: true
EOF

gcloud beta service-extensions authz-extensions import ma-ext \
    --source=ma-content-authz-extension.yaml \
    --location=$LOCATION

Model Armor 승인 정책 만들기

Model Armor 확장 프로그램을 에이전트 게이트웨이와 연결하는 정책을 만듭니다. 이 구성을 ma-content-authz-policy.yaml로 저장합니다.

cat >ma-content-authz-policy.yaml <<EOF
name: ma-content-authz-policy
target:
  resources:
  -   "projects/$PROJECT_ID/locations/$LOCATION/gateways/mortgage-gateway"
policyProfile: CONTENT_AUTHZ
action: CUSTOM
customProvider:
  authzExtension:
    resources:
    -   "projects/$PROJECT_ID/locations/$LOCATION/authzExtensions/ma-ext"
EOF

gcloud network-security authz-policies import ma-content-authz-policy \
    --source=ma-content-authz-policy.yaml \
    --location=$LOCATION

7. Gemini Enterprise 구성

관측 가능성 사용 설정

모기지 상담사는 OpenTelemetry 계측과 다음 원격 분석 환경 변수가 기본적으로 사용 설정된 상태로 배포됩니다.

• GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true
• OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
• OTEL_TRACES_SAMPLER=parentbased_traceidratio

Gemini Enterprise에서 트레이스 및 스팬을 구성하는 방법에 대한 자세한 내용은 관측 가능성 설정 관리를 참고하세요.

Gemini Enterprise에서 Model Armor 사용 설정

Model Armor 필터링을 Gemini Enterprise 어시스턴트에 적용하여 사용자 프롬프트와 모델 응답을 모두 검사합니다. 전역 Gemini Enterprise 앱에는 us 멀티 리전의 모델 아머 템플릿이 필요하므로 Terraform은 이 용도로 별도의 템플릿을 배포합니다.

Terraform 출력에서 템플릿 이름을 가져옵니다.

cd terraform
export GE_MA_TEMPLATE_NAME=$(terraform output -raw model_armor_gemini_enterprise_template_name)

Gemini Enterprise 인스턴스의 앱 ID를 가져옵니다.

1. Google Cloud 콘솔에서 Gemini Enterprise 페이지로 이동합니다.
2. 탐색 메뉴에서 앱을 클릭합니다.
3. Gemini Enterprise 인스턴스의 ID 복사

ID를 환경 변수로 내보냅니다.

export APP_ID=<PASTE_APP_ID>

어시스턴트를 패치하여 Model Armor를 사용 설정합니다.

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "X-Goog-User-Project: ${PROJECT_ID}" \
  "https://global-discoveryengine.googleapis.com/v1/projects/${PROJECT_ID}/locations/global/collections/default_collection/engines/${APP_ID}/assistants/default_assistant?update_mask=customerPolicy" \
  -d '{
    "customerPolicy": {
      "modelArmorConfig": {
        "userPromptTemplate": "'"$GE_MA_TEMPLATE_NAME"'",
        "responseTemplate": "'"$GE_MA_TEMPLATE_NAME"'",
        "failureMode": "FAIL_OPEN"
      }
    }
  }'

Model Armor를 사용할 수 없는 경우 요청을 허용하려면 failureMode를 FAIL_OPEN로 설정하고 요청을 차단하려면 FAIL_CLOSED로 설정합니다.

8. Gemini Enterprise에서 에이전트 배포 및 추가

승인 세부정보 가져오기

다음 단계에 따라 승인 세부정보를 가져오세요.

1. Google Cloud 콘솔의 API 및 서비스 페이지에서 사용자 인증 정보 페이지로 이동합니다.
2. 사용자 인증 정보로 이동
3. 사용자 인증 정보 만들기를 클릭하고 OAuth 클라이언트 ID를 선택합니다.
4. 애플리케이션 유형에서 웹 애플리케이션을 선택합니다.
5. '승인된 리디렉션 URI' 섹션에 다음 URI를 추가합니다.

• https://vertexaisearch.cloud.google.com/oauth-redirect
• https://vertexaisearch.cloud.google.com/static/oauth/oauth.html

6. '만들기'를 클릭합니다.
7. 배포를 위해 클라이언트 ID와 클라이언트 보안 비밀번호를 내보냅니다.

export OAUTH_CLIENT_ID=<Client ID>
export OAUTH_CLIENT_SECRET=<Client Secret>

주택담보대출 에이전트 배포

src/mortgage-agent/deploy_agent.py 스크립트는 ADK 에이전트를 Agent Engine에 배포하고 선택적으로 Gemini Enterprise에 등록합니다. Gemini Enterprise 등록 흐름에 관한 배경 정보는 A2A 에이전트 등록 및 관리를 참고하세요.

Terraform 배포에서 변수를 내보냅니다.

export VPC_NAME=$(cd terraform && terraform output -raw vpc_name)
export PSC_ATTACHMENT=$(cd terraform && terraform output -raw psc_interface_network_attachment_id)
export DNS_PEERING_DOMAIN=$(cd terraform && terraform output -raw psc_interface_dns_peering_domain)

종속 항목을 설치하고 배포합니다.

cd src/mortgage-agent
uv sync

Vertex Agent Engine에 에이전트를 배포하고 Gemini Enterprise에 등록합니다.

uv run python deploy_agent.py \
    --project=${PROJECT_ID} \
    --dms-mcp-url=https://dms.${DNS_PEERING_DOMAIN%%.}/mcp \
    --income-verification-url=https://income-verification.${DNS_PEERING_DOMAIN%%.} \
    --email-mcp-url=https://email.${DNS_PEERING_DOMAIN%%.}/mcp \
    --network-attachment=projects/${PROJECT_ID}/regions/${REGION}/networkAttachments/${PSC_ATTACHMENT} \
    --dns-peering-domain=${DNS_PEERING_DOMAIN} \
    --dns-peering-target-project=${PROJECT_ID} \
    --dns-peering-target-network=${VPC_NAME} \
    --enable-agent-identity \
    --ge-deploy \
    --app-id=${APP_ID} \
    --oauth-client-id=${OAUTH_CLIENT_ID} \
    --agent-name=mortgage-agent

플래그 참조

플래그	기본값	설명
--project	$PROJECT_ID	GCP 프로젝트 ID
--dms-mcp-url	(필수)	DMS MCP 서버 URL
--income-verification-url	(필수)	수입 확인 API 기본 URL입니다. /mcp이 자동으로 추가됩니다.
--email-mcp-url	(필수)	이메일 MCP 서버 URL
--region	$REGION	GCP 리전
--staging-bucket	gs://PROJECT-staging	스테이징용 GCS 버킷
--display-name	Mortgage Assistant Agent	배포된 에이전트의 표시 이름
--update	(선택사항)	기존 에이전트를 인플레이스로 업데이트 (전체 리소스 이름 전달)
--network-attachment	(선택사항)	PSC 인터페이스의 네트워크 연결 (전체 경로 또는 이름)
--dns-peering-domain	(선택사항)	PSC-I DNS 피어링의 DNS 도메인 (점으로 끝나야 함)
--dns-peering-target-project	(선택사항)	DNS 피어링의 대상 VPC 네트워크를 호스팅하는 프로젝트
--dns-peering-target-network	(선택사항)	DNS 피어링의 VPC 네트워크 이름
--enable-agent-identity	false	상담사별 최소 권한 사용자 인증 정보 사용 설정
--ge-deploy	false	배포 후 Gemini Enterprise에 에이전트 등록
--app-id	(선택사항)	Gemini Enterprise 엔진 ID (--ge-deploy와 함께 필요)
--oauth-client-id	$OAUTH_CLIENT_ID	OAuth2 클라이언트 ID (--ge-deploy와 함께 필요)
--oauth-client-secret	$OAUTH_CLIENT_SECRET	OAuth2 클라이언트 보안 비밀번호 (--ge-deploy 필요)
--model	gemini-3.1-flash-lite-preview	에이전트의 Gemini 모델 이름
--agent-name	mortgage-agent	Gemini Enterprise 승인 및 에이전트 이름
--ge-deploy-only	(선택사항)	재배포 없이 Gemini Enterprise에 기존 추론 엔진 등록 (전체 리소스 이름 전달)

권한이 부여된 사용자 추가

Google Cloud 콘솔을 사용하여 권한이 있는 사용자를 ADK 에이전트에 추가하려면 사용자 및 권한 추가 또는 수정을 참고하세요.

9. 에이전트 테스트

이제 에이전트, GKE 게이트웨이, 모든 백엔드 서비스를 배포하고 구성했으므로 엔드 투 엔드 흐름을 테스트하여 보안 정책이 예상대로 작동하는지 확인합니다. Gemini Enterprise 인터페이스 내에서 'mortgage-agent'와 상호작용합니다.

에이전트 액세스

1. Google Cloud 콘솔에서 Gemini Enterprise 페이지로 이동합니다.
2. 이전에 구성한 Gemini Enterprise 앱을 선택합니다. 이 앱에 'mortgage-agent'가 등록되어 있습니다.
3. 개요 탭에서 'Gemini Enterprise 웹 앱이 준비되었습니다' 섹션에 표시된 URL로 이동합니다.
4. 왼쪽 메뉴에서 에이전트 갤러리라는 에이전트 탭을 선택합니다.
5. 이제 'Mortgage Assistant Agent'와 채팅할 수 있습니다.

테스트 사례 1: '해피 패스' - PII 수정으로 데이터 요약

이 테스트에서는 에이전트가 에이전트 게이트웨이를 통해 백엔드 시스템에 액세스할 수 있는지, 데이터 손실 방지 (DLP) 정책이 적용되어 민감한 정보가 수정되는지 확인합니다.

1. 모기지 어시스턴트 에이전트에게 다음 프롬프트를 보냅니다.

   I'm reviewing the Sterling family's current application. Can you summarize their 2024 and 2025 tax returns and verify if their total household income meets our 2026 debt-to-income requirements?
   

2. 백그라운드에서 발생하는 작업:
   • Gemini Enterprise의 에이전트는 필요한 도구 (예: 세금 신고용 문서 관리 시스템 (DMS), 소득 확인 API)에 대한 요청을 공식화합니다.
   • Model Armor는 요청 및 응답 페이로드에서 위협을 검사합니다.
   • 구성한 '콘텐츠 기반 승인 정책'이 맞춤 DLP 확장 프로그램 (dlp-content-authz-ext)을 트리거합니다. 이 확장 프로그램은 백엔드 시스템에서 가져온 데이터를 검사합니다.
   • DLP 서비스는 세금 신고 데이터가 상담사에게 도달하기 전에 주민등록번호 (SSN)와 같은 개인 식별 정보 (PII)를 수정합니다.
3. 예상 결과: 에이전트가 세금 신고 요약과 소득 확인 상태를 반환합니다. 중요한 점은 에이전트가 제공한 요약을 검토하는 것입니다. 납세자 ID (SSN)와 같은 민감한 정보가 자리표시자 (예: [REDACTED])로 대체된 것을 확인할 수 있습니다. 이는 게이트웨이를 통한 DLP 정책 실행을 확인해 줍니다.

관측 가능성 및 감사

이러한 테스트 전반에서 에이전트 플랫폼과 연결된 서비스는 원격 분석을 수집합니다.

• Cloud Logging: GKE Gateway, GKE 워크로드, 기타 서비스의 자세한 로그는 요청, 정책 평가, 결과의 감사 추적을 제공합니다.
• Cloud Trace: 에이전트 및 백엔드 서비스에 구성된 OpenTelemetry 계측을 사용하면 Gemini Enterprise부터 GKE 게이트웨이를 거쳐 백엔드 도구까지 전체 호출 흐름을 시각화할 수 있습니다. 이는 디버깅 및 요청 수명 주기를 이해하는 데 매우 유용합니다.

세션의 트레이스를 확인합니다.

1. Google Cloud 콘솔에서 Vertex AI Agent Engine 페이지로 이동합니다.
2. Agent Engine으로 이동합니다. 선택한 프로젝트에 속한 Agent Engine 인스턴스가 목록에 표시됩니다. 필터 필드를 사용하여 지정된 열을 기준으로 목록을 필터링할 수 있습니다.
3. Agent Engine 인스턴스의 이름을 클릭합니다.
4. 트레이스 탭을 클릭합니다.
5. 세션 뷰 또는 스팬 뷰를 선택할 수 있습니다.
6. 세션 또는 스팬을 클릭하여 스팬의 DAG (방향성 비순환 그래프), 입력 및 출력, 메타데이터 속성을 포함한 trace 세부정보를 검사하세요.

10. 선택사항: Apigee를 사용하여 트랜스코딩 REST API를 MCP로 변환

Google의 수입 확인 서비스는 기본적으로 모델 컨텍스트 프로토콜을 지원하지만 많은 엔터프라이즈 기존 시스템은 RESTful API만 제공합니다. 이 선택사항 단계에서는 Apigee MCP 검색 프록시를 사용하여 소득 확인 서비스의 REST 엔드포인트를 MCP 도구로 트랜스코딩합니다. 이를 통해 기존 도구에 Apigee의 고급 거버넌스, 비율 제한, 보안 정책을 적용할 수 있습니다.

자세한 내용은 Apigee MCP 개요를 참고하세요.

기본 요건

계속하기 전에 Apigee API Hub를 프로비저닝하고 구성했는지 확인하세요. API 허브 프로비저닝 문서의 단계에 따라 설정하고 Apigee 인스턴스를 연결합니다.

1단계: Apigee용 서비스 연결 만들기

Apigee가 GKE에서 실행되는 내부 서비스에 연결되도록 하려면 서비스 연결을 만들어야 합니다.

1. 내부 GKE Gateway 전달 규칙을 조회합니다.

   export RULE_URI=$(gcloud compute forwarding-rules list \
     --filter="loadBalancingScheme=INTERNAL_MANAGED AND target~targetHttpsProxies" \
     --format="value(selfLink.segment(6), region.basename(), name)" | \
     awk '{print "projects/" $1 "/regions/" $2 "/forwardingRules/" $3}')
   

2. 서비스 연결을 만드세요.

   gcloud compute service-attachments create internal-gke-gateway-apigee \
       --region=${REGION} \
       --target-service=$RULE_URI \
       --connection-preference=ACCEPT_AUTOMATIC \
       --nat-subnets=gateway-psc-subnet
   

2단계: Terraform으로 Apigee 사용 설정

이제 인프라 구성을 업데이트하여 Apigee 조직과 인스턴스를 프로비저닝합니다.

1. terraform 디렉터리로 이동합니다.

   cd terraform
   

2. terraform.tfvars을 수정하고 enable_apigee = true을 설정합니다.
3. 변경사항을 적용합니다.

   terraform apply
   

참고: 초기 Apigee 조직 프로비저닝에는 30~50분이 걸릴 수 있습니다.

3단계: OpenAPI 사양 정의

Apigee는 표준 OpenAPI (OAS) 정의를 사용하여 도구를 검색하고 트랜스코딩합니다. 다음 콘텐츠로 income-verification-oas.yaml라는 파일을 만듭니다.

openapi: 3.0.0
info:
  title: Income Verification API
  description: Verify applicant income through third-party employer records.
  version: 1.0.0
servers:
  -   url: https://income-verification.internal.${DNS_PEERING_DOMAIN%%.}/api
paths:
  /income-verification/verify:
    post:
      summary: Verify applicant income
      operationId: verifyApplicant
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                first_name:
                  type: string
                last_name:
                  type: string
      responses:
        '200':
          description: Successful verification
          content:
            application/json:
              schema:
                type: object

4단계: Apigee MCP 탐색 프록시 배포

MCP 탐색 프록시는 MCP 서버 역할을 하는 특수 Apigee 프록시입니다.

1. Apigee UI에서 개발 > API 프록시로 이동합니다.
2. 새로 만들기를 클릭하고 MCP 탐색 프록시를 선택합니다.
3. 프록시 이름을 income-verification-discovery로 지정합니다.
4. OpenAPI 사양 섹션에서 생성한 income-verification-oas.yaml 파일을 업로드합니다.
5. 환경 그룹을 내부 게이트웨이에 액세스할 수 있는 그룹으로 설정합니다.
6. 배포를 클릭합니다.

(선택사항) 보안 정책 추가

프록시를 배포하거나 공유하기 전에 보안을 설정해야 합니다. OAuth 토큰 또는 API 키와 같은 보안 요구사항을 적용하는 정책을 추가할 수 있습니다. 보안 정책을 추가하는 방법은 API 보안에 관한 Apigee 문서를 참고하세요.

5단계: 트랜스코딩된 도구 액세스 확인

배포되면 Apigee는 POST /verify 엔드포인트를 verifyApplicant MCP 도구로 자동 트랜스코딩합니다.

1. Apigee MCP 엔드포인트를 통해 사용할 수 있는 도구를 나열합니다.

   curl -X POST https://api.internal.${DNS_PEERING_DOMAIN%%.}/income-verification-discovery/mcp \
     -H "Content-Type: application/json" \
     -d '{
       "jsonrpc": "2.0",
       "id": 1,
       "method": "tools/list",
       "params": {}
     }'
   

2. REST 사양에서 트랜스코딩된 verifyApplicant 도구가 대답에 표시됩니다. 이제 Apigee를 통해 이 도구를 호출할 수 있으며, Apigee는 구성된 보안 정책을 적용하면서 기본 REST 서비스로의 변환을 처리합니다.

6단계: Apigee를 사용하도록 Mortgage Agent 업데이트

이제 Apigee가 REST API를 MCP 호환 도구로 트랜스코딩하므로 에이전트의 배포 구성을 업데이트해야 합니다. 이제 에이전트를 Apigee 엔드포인트로 연결하면 모든 수입 확인 요청이 Apigee의 엔터프라이즈급 보안, 로깅, 트래픽 관리의 이점을 누릴 수 있습니다.

1. Apigee MCP URL 확인: 엔드포인트는 https://api.internal.${DNS_PEERING_DOMAIN%%.}/income-verification-discovery/mcp 패턴을 따라야 합니다.
2. 배포 스크립트 다시 실행: 새 --income-verification-url와 함께 --update 플래그를 사용합니다. 이렇게 하면 완전히 삭제하지 않고도 Agent Engine의 기존 에이전트가 업데이트됩니다.

   cd src/mortgage-agent
   
   # Update the agent to route income verification through Apigee
   uv run python deploy_agent.py \
       --project=${PROJECT_ID} \
       --update \
       --agent-name=mortgage-agent \
       --dms-mcp-url=https://dms.${DNS_PEERING_DOMAIN%%.}/mcp \
       --income-verification-url=https://api.internal.${DNS_PEERING_DOMAIN%%.}/income-verification-discovery/mcp \
       --email-mcp-url=https://email.${DNS_PEERING_DOMAIN%%.}/mcp \
       --network-attachment=projects/${PROJECT_ID}/regions/${REGION}/networkAttachments/${PSC_ATTACHMENT} \
       --dns-peering-domain=${DNS_PEERING_DOMAIN} \
       --dns-peering-target-project=${PROJECT_ID} \
       --dns-peering-target-network=${VPC_NAME} \
       --ge-deploy \
       --app-id=${APP_ID} \
       --oauth-client-id=${OAUTH_CLIENT_ID}
   

Apigee MCP 탐색 프록시를 사용하는 경우 에이전트는 트랜스코딩된 REST API를 기본 MCP 서버와 똑같이 취급합니다. deploy_agent.py 스크립트는 이러한 도구를 Agent Engine 환경에 등록하는 작업을 처리합니다.

3. 변경사항 확인: Gemini Enterprise 인터페이스로 돌아가 에이전트에게 지원자의 소득을 확인해 달라고 요청합니다.

   "Can you verify the joint income for the Sterlings using the verification service?"
   

   이제 Apigee 디버그 탭에 GKE 게이트웨이에서 수신되는 JSON-RPC 요청이 백엔드 GKE 서비스에 대한 표준 REST POST 요청으로 변환되어 표시됩니다.

11. 삭제

이 Codelab에서 만든 리소스의 비용이 Google Cloud 계정에 청구되지 않도록 하려면 완료 후 리소스를 삭제하세요.

1. 서비스 연결이 수동으로 생성된 경우 삭제합니다.

   gcloud compute service-attachments delete internal-gke-gateway \
       --region=${REGION} --quiet
   

2. terraform 디렉터리로 이동하여 모든 리소스를 삭제합니다.

   cd terraform
   terraform destroy
   

3. 원하는 경우 Google Cloud 프로젝트를 완전히 삭제합니다.

   gcloud projects delete ${PROJECT_ID}
   

12. 축하합니다

이 Codelab을 완료하고 크로스 클라우드 에이전트 엔터프라이즈 배포를 보호하는 방법을 알아봤습니다.

학습한 내용

• OpenTelemetry 계측을 사용하여 Agent Engine에 ADK 모기지 어시스턴트 에이전트 배포
• 내부 게이트웨이 뒤의 GKE에 백엔드 MCP 서버가 배포됨
• PSC 인터페이스 및 DNS 피어링을 사용하여 에이전트 엔진을 프로젝트 VPC에 연결
• DLP 수정 및 MCP 승인을 사용하여 관리되는 에이전트 이그레스를 위해 GKE Gateway 구성
• 프롬프트 및 응답 검사를 위해 Model Armor를 사용하여 AI 보호 장치 적용
• 선택적으로 Apigee MCP 탐색 프록시를 사용하여 REST API를 MCP로 트랜스코딩

다음 단계

• Model Armor 살펴보기
• Agent Engine에 대해 알아보기
• Gemini Enterprise 살펴보기