GCP에 Claude apps gateway 배포
공식 기준: https://code.claude.com/docs/en/claude-apps-gateway-on-gcp
기준일: 2026-07-26 · CLI 기준 2.1.220
개요
Google Cloud에서 Claude apps gateway를 돌리는 참고 구성입니다. 지원되는 완제품 배포가 아니라 구성 요소 결합 예제이므로 환경에 맞게 수정하세요. upstream 예시는 Google Cloud Agent Platform, IdP 예시는 Google Workspace(다른 OIDC도 oidc만 교체).
핵심 개념
프로비저닝 요소:
- Cloud Run 또는 GKE Deployment
- Artifact Registry 이미지
- Cloud SQL PostgreSQL (private IP) —
store - Secret Manager — gateway.yaml, JWT, OIDC secret, Postgres URL
- Service account —
roles/aiplatform.user(+ GKE Workload Identity) - Internal ALB / internal GKE Ingress
상세
사전 요구
- 결제 활성 GCP 프로젝트,
gcloud, Docker - GKE 경로 시
kubectl·VPC 클러스터 - Model Garden에서 필요 Claude 모델 리전
- OAuth web client redirect
https://<gateway-host>/oauth/callback - TLS용 내부 DNS 호스트명
export PROJECT_ID=<your-project>
export REGION=us-east5 # Model Garden 모델 게시 리전
gcloud config set project "$PROJECT_ID"
배포 단계 요지
- API enable: aiplatform, artifactregistry, sqladmin, secretmanager, iam, compute, servicenetworking, run, container 등 경로별
- SA 생성 +
roles/aiplatform.user - Artifact Registry에 게이트웨이 이미지 푸시 (공식 바이너리 기반 Dockerfile)
- Cloud SQL private IP + DB 유저/비밀번호
- Secret Manager에 설정·시크릿 등록
- Cloud Run 또는 GKE에 배포, 내부 LB,
public_url·trusted_proxies설정 - OIDC·Agent Platform 인증(E2E
/login·추론 스모크)
Terraform reference 절에 모듈/리소스 힌트가 있습니다. Troubleshooting은 SA 권한, VPC peering, private DNS, Model Garden 리전 불일치를 우선 봅니다.
체크리스트
- 모델 게시 리전과 REGION 일치
- Cloud SQL private only
- SA에 aiplatform.user
- 내부 HTTPS + private
/login가능 - Secret 마운트·env 확장 확인