Fare il deploy del gateway delle app Claude su Google Cloud

Un esempio pratico di esecuzione del gateway delle app Claude su Google Cloud: Cloud Run o GKE, Cloud SQL per PostgreSQL, Secret Manager e autenticazione tramite account di servizio verso Agent Platform di Google Cloud.

[!NOTE]

Questa pagina illustra un modo per eseguire il gateway delle app Claude su Google Cloud. La configurazione è un esempio funzionante per l'infrastruttura gestita dal cliente piuttosto che una distribuzione di produzione supportata; utilizzatela per vedere come i componenti si incastrano insieme prima di adattarla al vostro ambiente. Per i requisiti indipendenti dalla piattaforma, consultate la guida alla distribuzione.

Questo esempio esegue il provisioning del gateway delle app Claude su Google Cloud con Agent Platform di Google Cloud come upstream del modello, utilizzando Cloud Run o GKE per il calcolo. Google Workspace è l'esempio di provider di identità (IdP), ma funziona qualsiasi provider conforme a OpenID Connect (OIDC); solo il blocco oidc cambia. Consultate Configurazione del provider di identità per i dettagli specifici per ogni IdP.

Cosa costruirete

Il deploy è composto da:

• Servizio Cloud Run o Deployment GKE che esegue il contenitore del gateway
• Repository Artifact Registry per l'immagine del gateway
• Istanza Cloud SQL per PostgreSQL, solo IP privato, per lo store del gateway
• Segreti Secret Manager per gateway.yaml, la chiave di firma JWT, il segreto client OIDC e l'URL Postgres
• Account di servizio con roles/aiplatform.user, allegato direttamente su Cloud Run o associato tramite Workload Identity su GKE
• Front end HTTPS fornito da te: un Internal Application Load Balancer davanti a Cloud Run, per il quale questa guida configura il gateway ma che non crea, oppure un GKE Ingress interno di classe gce-internal su GKE

Prerequisiti

• Un progetto GCP con fatturazione abilitata e autorizzazione per creare le risorse di cui sopra
• La CLI gcloud, autenticata con gcloud auth login, e Docker installato localmente
• Per il percorso GKE: kubectl e un cluster GKE sul VPC creato nella procedura dettagliata di seguito
• Accesso ai modelli Claude di cui avete bisogno in Model Garden, in una regione che li pubblica
• Un client applicazione web OAuth 2.0 di Google Workspace con URI di reindirizzamento https://<gateway-host>/oauth/callback; consultate Configurazione del provider di identità
• Un nome host TLS per il gateway, in genere un nome DNS interno che punta al load balancer

Impostate il progetto e la regione una volta:

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"

Distribuire il gateway

I passaggi seguenti eseguono il provisioning della distribuzione completa con comandi gcloud.

1. Abilitare le API

Abilitate le API di servizio utilizzate dalla procedura dettagliata:

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

Le API di cui avete bisogno dipendono dal percorso di distribuzione:

• compute e servicenetworking: necessarie per il percorso Cloud SQL con IP privato
• run: solo Cloud Run
• container: solo GKE

2. Creare l'account di servizio e concedere IAM

Il gateway viene eseguito come account di servizio dedicato con autorizzazione per chiamare Agent Platform. Raggiunge Cloud SQL sul VPC con un utente con password, quindi non è richiesto alcun ruolo IAM di Cloud SQL:

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

Quindi abilitate i modelli Claude per il progetto in Model Garden; i modelli vengono pubblicati in regioni specifiche, quindi controllate ogni scheda del modello.

3. Compilare e inviare l'immagine ad Artifact Registry

Compilate l'immagine secondo i requisiti dell'immagine del contenitore, utilizzando il binario glibc linux-x64, e inviatela:

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>"

4. Eseguire il provisioning di Cloud SQL per PostgreSQL

Create l'istanza su un VPC tramite Private Services Access in modo che non abbia IP pubblico; questo soddisfa anche i progetti in cui constraints/sql.restrictPublicIp è applicato:

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"

Il runtime Cloud Run o GKE deve essere su, o instradato in, questo VPC.

5. Scrivere gateway.yaml

Il blocco upstreams punta ad Agent Platform con auth: {}, quindi il gateway si autentica tramite Application Default Credentials dall'account di servizio del runtime. Consultate il riferimento di configurazione per ogni campo.

Due campi listen descrivono cosa si trova davanti al gateway:

• public_url: l'origine https:// esterna, richiesta per qualsiasi bind non loopback; consulta il riferimento di listen. Il gateway costruisce il redirect_uri dell'IdP e il suo documento di discovery solo da questo valore, mai da intestazioni X-Forwarded-*.
• trusted_proxies: gli intervalli di origine del front end. Il gateway onora X-Forwarded-For solo quando il peer TCP è in questo elenco, quindi percorre la catena oltre gli hop affidabili, in modo che i rate limit di accesso per IP e gli eventi di audit registrino gli IP degli sviluppatori invece di quello del load balancer.

Impostate trusted_proxies in modo che corrisponda al vostro front end. Un GKE Ingress esterno di classe gce non è elencato: esegue il provisioning di un indirizzo di regola di inoltro pubblico, che il controllo rete privata di /login rifiuta.

L'esempio seguente utilizza i valori del load balancer interno davanti a Cloud Run.

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

[!NOTE]

I token id di Google non contengono alcuna rivendicazione groups. Per utilizzare le politiche basate su gruppi in managed.policies con Google Workspace come IdP, configurate oidc.google_groups, che cerca i gruppi di ogni utente tramite l'API Admin SDK Directory utilizzando un account di servizio con delega a livello di dominio. Senza di essa, abbinate invece su email_domain.

6. Archiviare i segreti in Secret Manager

Create quattro segreti e concedete roles/secretmanager.secretAccessor all'account di servizio claude-gateway:

Il modo in cui i segreti raggiungono il contenitore differisce per traccia:

• Su GKE vengono montati come file tramite il driver CSI di Secret Manager e gateway.yaml fa riferimento a ${file:/secrets/...}.
• Su Cloud Run, che non può montare più segreti in una directory, gateway.yaml viene montato come file e gli altri tre si iniettano come variabili di ambiente, quindi gateway.yaml fa riferimento a ${GATEWAY_JWT_SECRET}, ${OIDC_CLIENT_SECRET} e ${GATEWAY_POSTGRES_URL} invece.

7. Distribuire

[tab] Cloud Run

Il comando seguente distribuisce per la produzione dietro un load balancer interno.

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

L'uscita VPC diretta, tramite --network, --subnet e --vpc-egress=private-ranges-only, consente al servizio di raggiungere direttamente l'IP privato di Cloud SQL. L'uscita pubblica verso gli endpoint di Agent Platform di Google Cloud e accounts.google.com va direttamente a Internet anziché attraverso il VPC, quindi non è necessario Cloud NAT.

[!NOTE]

Ogni istanza mantiene fino a store.max_connections connessioni Postgres, cinque per impostazione predefinita. Usa Dimensionare il pool di connessioni per verificare --max-instances=8 rispetto alle connessioni che il tuo database ha ancora disponibili per il gateway, e includi le istanze aggiuntive avviate da un aggiornamento in sequenza.

Il controllo IAM dell'invoker deve essere aperto o disabilitato. Il gateway esegue il proprio OIDC e i suoi client non portano alcun token GCP, quindi il controllo dell'invoker di Cloud Run deve ammettere richieste non autenticate. Il gateway autentica la richiesta una volta che raggiunge il contenitore con OIDC, con allowed_email_domains che controlla quali domini possono accedere.

Due flag ammettono richieste non autenticate:

• --no-invoker-iam-check: disabilita il controllo senza alcun binding allUsers da gestire e funziona con Domain Restricted Sharing
• --allow-unauthenticated: concede al ruolo run.invoker allUsers; utilizzatelo se la vostra organizzazione non consente --no-invoker-iam-check

La restrizione dell'ingresso tramite --ingress è un livello separato e indipendente dal controllo dell'invoker; mantenetelo impostato per limitare il servizio alla vostra rete aziendale.

Per impostazione predefinita, l'URL *.run.app di Cloud Run si risolve in un indirizzo pubblico, che il controllo rete privata di /login rifiuta. Due topologie forniscono agli sviluppatori un nome host risolvibile privatamente e Cloud Run non ne esegue il provisioning per voi:

• Internal Application Load Balancer, la topologia che il gateway.yaml di questa pagina presuppone: esegui il provisioning di un Internal Application Load Balancer davanti al servizio con un nome DNS interno e un certificato, e imposta listen.public_url su quel nome host. L'impostazione di ingresso internal ammette già il traffico dagli Internal Application Load Balancer; internal-and-cloud-load-balancing ammette inoltre gli External Application Load Balancer, i cui indirizzi pubblici vengono rifiutati dal controllo di rete privata di /login, quindi nessuna topologia di questa pagina ne ha bisogno.
• Ingresso solo interno senza load balancer: mantieni il comando di deploy così com'è e lascia listen.public_url come URL *.run.app, l'impostazione predefinita negli asset di riferimento di seguito. Affinché *.run.app si risolva privatamente, il tuo team di rete deve già gestire un endpoint Private Service Connect per le API di Google, una zona privata Cloud DNS che risolve *.run.app verso di esso e il routing on-premises verso quell'endpoint.

La guida alla rete privata di Google per Cloud Run copre l'infrastruttura di cui entrambe le opzioni hanno bisogno. Verificate l'accesso una volta che il gateway è in servizio su un nome host privato; fino ad allora, confermate che il contenitore si è avviato dai suoi log in Cloud Run.

Aggiornate l'URI di reindirizzamento autorizzato del client OAuth a <public_url>/oauth/callback prima del primo accesso. Ridistribuite dopo aver modificato public_url, perché il gateway costruisce la sua origine pubblica solo da quell'impostazione e ignora X-Forwarded-Host e X-Forwarded-Proto. X-Forwarded-For viene onorato per gli IP client solo quando listen.trusted_proxies è impostato.

[tab] GKE

Il cluster deve essere sul $VPC creato nel passaggio Cloud SQL in modo che i pod possano raggiungere l'IP privato del database; il peering VPC da solo non funziona, perché l'IP privato di Cloud SQL è esso stesso una rete peered e il peering non è transitivo. Per creare un nuovo cluster su quel VPC, passate --network="$VPC" --subnetwork=cc-gateway-subnet a gcloud container clusters create.

Abilitate Workload Identity sul cluster e sui suoi pool di nodi, quindi associate l'account di servizio Google all'account di servizio Kubernetes in modo che i pod ereditino le sue credenziali:

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"

Distribuite il gateway come Deployment standard più un Service e un Ingress interno, classe gce-internal, come descritto in Distribuzione Kubernetes, con:

• serviceAccountName: gateway
• il driver CSI di Secret Manager che monta i segreti in /secrets
• il probe di prontezza puntato a GET /readyz

Allegate un BackendConfig con un timeoutSec elevato al Service del gateway: il servizio backend del load balancer dietro GKE Ingress ha un timeout predefinito di 30 secondi, che interrompe le risposte di streaming lunghe.

Non applicate una NetworkPolicy di uscita che blocca 169.254.169.254 su un cluster Workload Identity; il pod deve raggiungere il server di metadati per le credenziali. La guardia SSRF integrata del gateway è la difesa lì.

Il gateway registra un avviso di avvio che l'endpoint dei metadati è raggiungibile e suggerisce di applicare una NetworkPolicy di uscita. Con Workload Identity quell'avviso è previsto, perché il pod ha bisogno dell'endpoint.

8. Inviare l'URL del gateway alle macchine degli sviluppatori

Il gateway è ora in esecuzione, ma gli sviluppatori non possono raggiungerlo da /login finché l'URL del gateway non è sulle loro macchine. Distribuisci a ogni dispositivo tramite MDM lo snippet completo delle impostazioni gestite, con forceLoginMethod, forceLoginGatewayUrl e l'opzione parentSettingsBehavior: "merge". Non c'è alcuna opzione di gateway nel selettore di accesso che uno sviluppatore possa selezionare manualmente.

Riferimento Terraform

Gli asset di distribuzione di riferimento automatizzano il percorso Cloud Run su questa pagina; gli asset di configurazione e immagine si applicano a entrambi i percorsi:

• setup.sh: un provisioner gcloud idempotente che percorre il percorso completo di Cloud Run, dall'abilitazione delle API alla prima distribuzione
• terraform/: la stessa distribuzione come infrastruttura come codice, per una distribuzione greenfield: un apply mirato per creare il repository Artifact Registry, quindi compilare e inviare l'immagine, quindi un apply completo
• gateway.yaml.example e un Dockerfile per l'immagine di runtime distroless

Gli artefatti impostano per impostazione predefinita l'ingresso di Cloud Run su internal, in linea con il comando di deploy di questa pagina; questa impostazione funziona con o senza un Application Load Balancer interno davanti al servizio, e nemmeno gli artefatti creano il load balancer. Gli artefatti impostano anche per impostazione predefinita il livello dell'invoker su una concessione run.invoker allUsers piuttosto che --no-invoker-iam-check, l'inverso della procedura dettagliata di questa pagina; entrambi funzionano e la scelta dipende dai vincoli di policy della tua organizzazione.

Gli asset sono forniti come esempi funzionanti, non come artefatto di produzione supportato; esaminate e adattate al vostro ambiente.

Risoluzione dei problemi

Per gli errori di avvio del gateway e di accesso, consultate la tabella risoluzione dei problemi indipendente dalla piattaforma. Le voci seguenti sono specifiche per Google Cloud.

Passaggi successivi

• Riferimento di configurazione: ogni opzione di gateway.yaml, incluse managed.policies e telemetry
• Distribuzione e operazioni: configurazione IdP, controlli di integrità, rotazione della chiave segreta JWT, aggiornamenti e il modello di sicurezza
• Panoramica del gateway delle app Claude: guida rapida e connessione degli sviluppatori