Deploy Claude apps gateway trên Google Cloud

Chú ý

Trang này hướng dẫn một cách triển khai Claude apps gateway trên Google Cloud. Đây là ví dụ hoạt động cho hạ tầng do khách hàng tự quản lý, không phải production deployment được hỗ trợ chính thức. Vì chi tiết lệnh gcloud có thể thay đổi, đối chiếu lại bản gốc trước khi áp dụng production.

Ví dụ này cấp phát Claude apps gateway trên Google Cloud với Google Cloud’s Agent Platform làm model upstream, dùng Cloud Run hoặc GKE cho compute. Google Workspace là IdP mẫu, nhưng bất kỳ IdP tương thích OIDC nào cũng dùng được - chỉ block oidc thay đổi.

Những gì bạn sẽ dựng

Cấu hình tham chiếu cấp phát:

• Cloud Run hoặc GKE Deployment chạy container gateway
• Artifact Registry repository cho image gateway
• Cloud SQL for PostgreSQL, chỉ private IP, cho store của gateway
• Secret Manager secret cho gateway.yaml, JWT signing key, OIDC client secret, Postgres URL
• Service account với roles/aiplatform.user, gắn trực tiếp trên Cloud Run hoặc qua Workload Identity trên GKE
• Internal Application Load Balancer (Cloud Run) hoặc internal GKE Ingress class gce-internal, cho HTTPS

Prerequisites

• Một GCP project bật billing, quyền tạo các resource trên
• gcloud CLI đã authenticate, Docker cài local
• Track GKE cần thêm kubectl và cluster GKE trên VPC tạo trong walkthrough
• Model Claude bạn cần đã bật trong Model Garden, ở region publish chúng
• Google Workspace OAuth 2.0 web-application client với redirect URI https://<gateway-host>/oauth/callback

export PROJECT_ID=<your-project>
export REGION=us-east5
gcloud config set project "$PROJECT_ID"

Các bước triển khai

1. Bật API: aiplatform, artifactregistry, sqladmin, secretmanager, iamcredentials, iam, compute, servicenetworking, cộng run hoặc container tùy track.

2. Tạo service account và cấp IAM: gateway chạy với service account riêng, chỉ có quyền gọi Google Cloud’s Agent Platform:

gcloud iam service-accounts create claude-gateway --display-name="Claude apps gateway"
SA="claude-gateway@${PROJECT_ID}.iam.gserviceaccount.com"
gcloud projects add-iam-policy-binding "$PROJECT_ID" \
  --member="serviceAccount:${SA}" --role="roles/aiplatform.user" --condition=None

Sau đó bật model Claude cho project trong Model Garden (model publish theo region riêng, kiểm tra từng model card).

3. Build và push image lên Artifact Registry: build theo yêu cầu container image, dùng binary glibc linux-x64. Cloud Run cần linux/amd64; dùng --provenance=false để tránh buildx tạo OCI image index mà Cloud Run từ chối.

4. Cấp Cloud SQL for PostgreSQL: tạo instance qua Private Services Access để không có public IP (đáp ứng cả ràng buộc constraints/sql.restrictPublicIp nếu tổ chức bật):

gcloud sql instances create claude-gateway-db \
  --database-version=POSTGRES_16 --tier=db-g1-small --region="$REGION" \
  --network="projects/${PROJECT_ID}/global/networks/${VPC}" --no-assign-ip

5. Viết gateway.yaml: block upstreams trỏ Google Cloud’s Agent Platform với auth: {} (Application Default Credentials từ service account runtime). trusted_proxies tùy front end:

Front end	trusted_proxies
Cloud Run trực tiếp, không load balancer	[169.254.0.0/16]
Internal ALB trước Cloud Run	169.254.0.0/16 cộng CIDR proxy-only subnet
GKE internal Ingress, class gce-internal	CIDR proxy-only subnet

listen:
  host: 0.0.0.0
  port: 8080
  public_url: https://claude-gateway.internal.example.com
  trusted_proxies: [169.254.0.0/16, <your-proxy-only-subnet-cidr>]

oidc:
  issuer: https://accounts.google.com
  client_id: <your-oauth-client-id>
  client_secret: ${OIDC_CLIENT_SECRET}
  allowed_email_domains: [example.com]
  scopes: [openid, profile, email]
  extra_auth_params: { access_type: offline, prompt: consent }

session:
  jwt_secret: ${GATEWAY_JWT_SECRET}

store:
  postgres_url: ${GATEWAY_POSTGRES_URL}

upstreams:
  - provider: vertex
    region: <your-region>
    project_id: <your-project>
    auth: {}

Ghi chú

Google id_token không có claim groups. Để dùng policy theo group với Google Workspace làm IdP, cấu hình oidc.google_groups (tra qua Admin SDK Directory API với service account domain-wide delegation). Không có nó, match theo email_domain thay vào đó.

6. Lưu secret vào Secret Manager: bốn secret - gateway-jwt-secret, gateway-oidc-client-secret, gateway-postgres-url, gateway-config (toàn bộ gateway.yaml). Trên GKE mount qua Secret Manager CSI driver; trên Cloud Run (không mount nhiều secret vào một thư mục), gateway.yaml mount như file, ba secret còn lại inject qua env var.

7. Deploy:

Cloud Run (production sau internal load balancer):

gcloud run deploy claude-gateway \
  --image="${REGION}-docker.pkg.dev/${PROJECT_ID}/claude-gateway/gateway:<version>" \
  --region="$REGION" \
  --service-account="claude-gateway@${PROJECT_ID}.iam.gserviceaccount.com" \
  --min-instances=1 --timeout=3600 \
  --ingress=internal-and-cloud-load-balancing \
  --network="$VPC" --subnet=cc-gateway-subnet --vpc-egress=private-ranges-only \
  --set-secrets=/etc/claude/gateway.yaml=gateway-config:latest,GATEWAY_JWT_SECRET=gateway-jwt-secret:latest,OIDC_CLIENT_SECRET=gateway-oidc-client-secret:latest,GATEWAY_POSTGRES_URL=gateway-postgres-url:latest \
  --no-invoker-iam-check

Invoker IAM check phải mở hoặc tắt, vì gateway tự chạy OIDC riêng và client không mang GCP token - dùng --no-invoker-iam-check (không có binding allUsers cần quản lý) hoặc --allow-unauthenticated. *.run.app mặc định resolve public, bị /login từ chối - cần một internal Application Load Balancer phía trước, hoặc internal-only ingress cùng Private Service Connect endpoint cho Google API.

GKE: cluster phải nằm trên VPC đã tạo ở bước Cloud SQL. Bật Workload Identity, bind Google service account vào Kubernetes service account, deploy Deployment + Service + internal Ingress class gce-internal.

8. Push gateway URL đến máy developer: deploy snippet managed settings đầy đủ (forceLoginMethod, forceLoginGatewayUrl, parentSettingsBehavior: "merge") qua MDM.

Terraform reference

Bộ tài nguyên tham chiếu tự động hóa track Cloud Run: setup.sh (idempotent), terraform/, gateway.yaml.example, và Dockerfile cho distroless runtime image.

Troubleshooting (đặc thù Google Cloud)

Triệu chứng	Nguyên nhân	Cách khắc phục
Cloud Run trả 403 Forbidden trước khi tới container	Invoker IAM check còn bật	Deploy với --no-invoker-iam-check hoặc --allow-unauthenticated
--no-invoker-iam-check bị từ chối	Bị chặn bởi constraints/run.managed.requireInvokerIam	Dùng --allow-unauthenticated, hoặc track GKE nếu Domain Restricted Sharing cũng chặn
Lỗi manifest phải hỗ trợ amd64/linux khi deploy	Image build trên host không phải amd64, hoặc buildx emit OCI image index	Build với --platform=linux/amd64 --provenance=false
Gateway boot exit lỗi timeout kết nối Postgres trên Cloud Run	Service chưa attach VPC, hoặc Cloud SQL chưa có private IP trên VPC đó	Deploy với --network/--subnet, tạo Cloud SQL với --no-assign-ip
Request Google Cloud’s Agent Platform trả 403 PERMISSION_DENIED	Runtime không dùng service account claude-gateway, hoặc model chưa bật trong Model Garden	Set --service-account hoặc bind Workload Identity, bật model cho region đích
Streaming response bị cắt sau một khoảng thời gian cố định	Timeout front-end: GKE Ingress 30s mặc định, Cloud Run 300s	Attach BackendConfig raised timeoutSec trên GKE, hoặc --timeout=3600 trên Cloud Run

Bước tiếp theo

• Configuration reference: mọi option gateway.yaml
• Deployment and operations: setup IdP, health check, rotate secret, upgrade, security model
• Claude apps gateway overview: quickstart và kết nối developer

Nguồn

Dịch và biên soạn từ Deploy Claude apps gateway on Google Cloud.