Desplegar Claude apps gateway en Google Cloud

​

Lo que construirá

• Servicio Cloud Run o GKE Deployment ejecutando el contenedor de la puerta de enlace
• Repositorio de Artifact Registry para la imagen de la puerta de enlace
• Instancia de Cloud SQL para PostgreSQL, solo IP privada, para el store de la puerta de enlace
• Secretos de Secret Manager para gateway.yaml, la clave de firma JWT, el secreto del cliente OIDC y la URL de Postgres
• Cuenta de servicio con roles/aiplatform.user, adjunta directamente en Cloud Run o vinculada a través de Workload Identity en GKE
• Front end HTTPS que tú proporcionas: un equilibrador de carga de aplicaciones interno delante de Cloud Run, para el cual esta guía configura el gateway pero que no crea, o un GKE Ingress interno de clase gce-internal en GKE

​

Requisitos previos

• Un proyecto de GCP con facturación habilitada y permiso para crear los recursos anteriores
• La CLI gcloud, autenticada con gcloud auth login, y Docker instalado localmente
• Para la ruta de GKE: kubectl y un clúster de GKE en la VPC creada en el tutorial a continuación
• Acceso a los modelos de Claude que necesita en Model Garden, en una región que los publique
• Un cliente de aplicación web OAuth 2.0 de Google Workspace con URI de redirección https://<gateway-host>/oauth/callback; consulte Configuración del proveedor de identidad
• Un nombre de host TLS para la puerta de enlace, típicamente un nombre DNS interno que apunta al equilibrador de carga

export PROJECT_ID=<your-project>
export REGION=us-east5   # a region where the Claude models you need are published in Model Garden
gcloud config set project "$PROJECT_ID"

​

Implementar la puerta de enlace

gcloud services enable \
  aiplatform.googleapis.com \
  artifactregistry.googleapis.com \
  sqladmin.googleapis.com \
  secretmanager.googleapis.com \
  iamcredentials.googleapis.com \
  iam.googleapis.com \
  compute.googleapis.com \
  servicenetworking.googleapis.com \
  run.googleapis.com \
  container.googleapis.com

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

gcloud artifacts repositories create claude-gateway \
  --repository-format=docker --location="$REGION"
gcloud auth configure-docker "${REGION}-docker.pkg.dev" --quiet

# Cloud Run requires linux/amd64. --provenance=false avoids a buildx OCI
# image index that Cloud Run rejects.
docker build --platform=linux/amd64 --provenance=false \
  -t "${REGION}-docker.pkg.dev/${PROJECT_ID}/claude-gateway/gateway:<version>" .
docker push "${REGION}-docker.pkg.dev/${PROJECT_ID}/claude-gateway/gateway:<version>"

VPC=cc-gateway-vpc
gcloud compute networks create "$VPC" --subnet-mode=custom
gcloud compute networks subnets create cc-gateway-subnet \
  --network="$VPC" --region="$REGION" --range=10.0.0.0/24

# Private Services Access: one-time per VPC
gcloud compute addresses create "google-managed-services-${VPC}" \
  --global --purpose=VPC_PEERING --prefix-length=16 --network="$VPC"
gcloud services vpc-peerings connect \
  --service=servicenetworking.googleapis.com \
  --ranges="google-managed-services-${VPC}" --network="$VPC"

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
gcloud sql databases create claude_gateway --instance=claude-gateway-db
PGPASS="$(openssl rand -hex 24)"
gcloud sql users create gateway --instance=claude-gateway-db --password="$PGPASS"

PRIVATE_IP="$(gcloud sql instances describe claude-gateway-db \
  --format='value(ipAddresses[0].ipAddress)')"
GATEWAY_POSTGRES_URL="postgres://gateway:${PGPASS}@${PRIVATE_IP}:5432/claude_gateway?sslmode=require"

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}           # GKE: ${file:/secrets/oidc-client-secret}
  allowed_email_domains: [example.com]
  # Google ignores offline_access; these yield refresh tokens:
  scopes: [openid, profile, email]
  extra_auth_params: { access_type: offline, prompt: consent }

session:
  jwt_secret: ${GATEWAY_JWT_SECRET}              # GKE: ${file:/secrets/jwt-secret}

store:
  postgres_url: ${GATEWAY_POSTGRES_URL}          # GKE: ${file:/secrets/postgres-url}
  # readiness_grace_seconds: 300                 # keep passing the readiness probe
# through a Cloud SQL failover

upstreams:
  - provider: vertex
    region: <your-region>                        # must match $REGION
    project_id: <your-project>
    auth: {} # ADC via the runtime service account

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 \
  --max-instances=8 \
  --timeout=3600 \
  --ingress=internal \
  --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

gcloud container clusters update <cluster> --region="$REGION" \
  --workload-pool="${PROJECT_ID}.svc.id.goog"
# On a Standard cluster, existing node pools also need GKE_METADATA;
# Autopilot enables this by default.
gcloud container node-pools update <pool> --cluster=<cluster> \
  --region="$REGION" --workload-metadata=GKE_METADATA

kubectl create namespace claude-gateway
kubectl create serviceaccount gateway -n claude-gateway

gcloud iam service-accounts add-iam-policy-binding \
  "claude-gateway@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role roles/iam.workloadIdentityUser \
  --member "serviceAccount:${PROJECT_ID}.svc.id.goog[claude-gateway/gateway]"

kubectl annotate serviceaccount gateway -n claude-gateway \
  iam.gke.io/gcp-service-account="claude-gateway@${PROJECT_ID}.iam.gserviceaccount.com"

​

Referencia de Terraform

• setup.sh: un aprovisionador gcloud idempotente que recorre la ruta completa de Cloud Run, desde habilitar API hasta la primera implementación
• terraform/: la misma implementación como infraestructura como código, para una implementación de campo virgen: una aplicación dirigida para crear el repositorio de Artifact Registry, luego construir e insertar la imagen, luego una aplicación completa
• gateway.yaml.example y un Dockerfile para la imagen de tiempo de ejecución sin distro

​

Solución de problemas

​

Próximos pasos

• Referencia de configuración: cada opción de gateway.yaml, incluyendo managed.policies y telemetry
• Implementación y operaciones: configuración de IdP, verificaciones de salud, rotación de secretos JWT, actualizaciones y el modelo de seguridad
• Modo de prueba de carga: pruebas de carga de un gateway sin llamar a un proveedor de modelos
• Descripción general de Claude apps gateway: inicio rápido y conexión de desarrolladores