SpyBara
Go Premium

claude-apps-gateway-on-gcp.md 2026-06-29 23:02 UTC to 2026-06-30 23:02 UTC

330 added, 0 removed.

2026
Tue 30 23:02 Mon 29 23:02 Sat 27 01:01 Fri 26 23:00 Thu 25 23:58 Wed 24 22:02 Tue 23 22:00 Mon 22 23:59 Fri 19 22:58 Thu 18 22:00 Wed 17 17:02 Tue 16 21:57 Mon 15 23:02 Sat 13 21:59 Fri 12 22:00 Thu 11 23:01 Wed 10 23:57 Tue 9 06:34 Mon 8 06:52 Sat 6 06:24 Fri 5 06:45 Thu 4 06:52 Wed 3 06:53 Tue 2 06:51

Claude-Apps-Gateway auf Google Cloud bereitstellen

Ein praktisches Beispiel für die Ausführung von Claude-Apps-Gateway auf Google Cloud: Cloud Run oder GKE, Cloud SQL für PostgreSQL, Secret Manager und Service-Account-Authentifizierung für Agent Platform.

Dieses Beispiel stellt Claude-Apps-Gateway auf Google Cloud mit Google Clouds Agent Platform als Modell-Upstream bereit und verwendet entweder Cloud Run oder GKE für die Berechnung. Google Workspace ist der Beispiel-Identitätsanbieter (IdP), aber jeder OpenID Connect (OIDC) konforme IdP funktioniert. Nur der oidc-Block ändert sich. Siehe Identitätsanbieter-Setup für IdP-spezifische Details.

Was Sie erstellen werden

Diagramm von Claude-Apps-Gateway auf Google Cloud: Claude-Code-Clients verbinden sich über HTTPS mit dem Gateway (Cloud Run oder GKE), das sich in einem VPC neben einer privaten IP-Cloud-SQL-Datenbank für Sitzungszustand befindet. Das Gateway meldet Benutzer über OIDC gegen Google Workspace an, liest Konfiguration und Geheimnisse aus Secret Manager, leitet Modellanfragen an Agent Platform weiter und ruft sein Image bei der Bereitstellung aus Artifact Registry ab.

Die Referenzkonfiguration stellt Folgendes bereit:

  • Cloud Run-Service oder GKE-Deployment mit dem Gateway-Container
  • Artifact Registry-Repository für das Gateway-Image
  • Cloud SQL für PostgreSQL-Instanz, nur private IP, für den Store des Gateways
  • Secret Manager-Geheimnisse für gateway.yaml, den JWT-Signaturschlüssel, das OIDC-Client-Geheimnis und die Postgres-URL
  • Service Account mit roles/aiplatform.user, direkt auf Cloud Run angehängt oder über Workload Identity auf GKE gebunden
  • Interner Application Load Balancer auf Cloud Run oder ein interner GKE Ingress der Klasse gce-internal auf GKE für HTTPS

Voraussetzungen

  • Ein GCP-Projekt mit aktivierter Abrechnung und Berechtigung zum Erstellen der oben genannten Ressourcen
  • Die gcloud-CLI, authentifiziert mit gcloud auth login, und Docker lokal installiert
  • Für den GKE-Pfad: kubectl und ein GKE-Cluster auf dem VPC, der in der folgenden Anleitung erstellt wird
  • Zugriff auf die Claude-Modelle, die Sie benötigen, in Model Garden, in einer Region, die sie veröffentlicht
  • Ein Google Workspace OAuth 2.0-Webanwendungs-Client mit Umleitungs-URI https://<gateway-host>/oauth/callback. Siehe Identitätsanbieter-Setup
  • Ein TLS-Hostname für das Gateway, typischerweise ein interner DNS-Name, der auf den Load Balancer verweist

Legen Sie das Projekt und die Region einmal fest:

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"

Gateway bereitstellen

Die folgenden Schritte stellen die vollständige Bereitstellung mit gcloud-Befehlen bereit.

1

APIs aktivieren

Aktivieren Sie die Service-APIs, die die Anleitung verwendet:

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

Die APIs, die Sie benötigen, hängen vom Bereitstellungspfad ab:

  • compute und servicenetworking: erforderlich für den privaten IP-Cloud-SQL-Pfad
  • run: nur Cloud Run
  • container: nur GKE
2

Service Account erstellen und IAM-Berechtigung erteilen

Das Gateway wird als dedizierter Service Account ausgeführt, der die Berechtigung hat, Agent Platform aufzurufen. Es erreicht Cloud SQL über das VPC mit einem Passwort-Benutzer, daher ist keine Cloud SQL IAM-Rolle erforderlich:

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

Aktivieren Sie dann die Claude-Modelle für das Projekt in Model Garden. Modelle werden in bestimmten Regionen veröffentlicht, überprüfen Sie daher jede Modellkarte.

3

Image erstellen und in Artifact Registry pushen

Erstellen Sie das Image gemäß den Container-Image-Anforderungen mit der linux-x64 glibc-Binärdatei und pushen Sie es:

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

Cloud SQL für PostgreSQL bereitstellen

Erstellen Sie die Instanz auf einem VPC über Private Services Access, damit sie keine öffentliche IP hat. Dies erfüllt auch Projekte, bei denen constraints/sql.restrictPublicIp erzwungen wird:

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"

Die Cloud Run- oder GKE-Laufzeit muss sich auf diesem VPC befinden oder in ihn geroutet werden.

5

gateway.yaml schreiben

Der upstreams-Block verweist auf Agent Platform mit auth: {}, sodass sich das Gateway über Application Default Credentials vom Runtime-Service-Account authentifiziert. Siehe die Konfigurationsreferenz für jedes Feld.

Zwei listen-Felder hängen davon ab, was das Gateway frontet:

  • public_url: erforderlich hinter Cloud Run oder einem GKE Ingress. Das Gateway erstellt die IdP redirect_uri und sein Erkennungsdokument nur aus diesem Wert, niemals aus X-Forwarded-*-Headern.
  • trusted_proxies: die Quellbereiche des Front-End. Das Gateway berücksichtigt X-Forwarded-For nur, wenn der TCP-Peer in dieser Liste ist, durchläuft dann die Kette über vertrauenswürdige Hops, sodass Anmelderate-Limits pro IP und Audit-Events Entwickler-IPs statt der IP des Load Balancers aufzeichnen.

Legen Sie trusted_proxies fest, um Ihr Front-End zu entsprechen. Ein externer GKE Ingress der Klasse gce ist nicht aufgelistet: Er stellt eine öffentliche Forwarding-Rule-Adresse bereit, die die /login Private-Network-Prüfung ablehnt.

Front-End trusted_proxies
Cloud Run direkt erreicht, kein Load Balancer [169.254.0.0/16]
Interner Application Load Balancer vor Cloud Run 169.254.0.0/16 plus CIDR Ihres Proxy-Only-Subnetzes
GKE interner Ingress, Klasse gce-internal CIDR Ihres Proxy-Only-Subnetzes

Das folgende Beispiel verwendet die Werte des internen-Load-Balancers-vor-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}

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

Geheimnisse in Secret Manager speichern

Erstellen Sie vier Geheimnisse und erteilen Sie roles/secretmanager.secretAccessor dem claude-gateway-Service-Account:

Geheimnis Quelle
gateway-jwt-secret openssl rand -base64 32
gateway-oidc-client-secret Google Cloud Console → OAuth-Client
gateway-postgres-url $GATEWAY_POSTGRES_URL aus dem Cloud SQL-Schritt
gateway-config die vollständige gateway.yaml aus dem vorherigen Schritt

Wie die Geheimnisse den Container erreichen, unterscheidet sich je nach Pfad:

  • Auf GKE werden sie über den Secret Manager CSI-Treiber als Dateien unter /secrets bereitgestellt, und gateway.yaml verweist auf ${file:/secrets/...}.
  • Auf Cloud Run, das mehrere Geheimnisse nicht in ein Verzeichnis einbinden kann, wird gateway.yaml als Datei bereitgestellt und die anderen drei werden als Umgebungsvariablen eingespritzt, sodass gateway.yaml stattdessen auf ${GATEWAY_JWT_SECRET}, ${OIDC_CLIENT_SECRET} und ${GATEWAY_POSTGRES_URL} verweist.
7

Bereitstellen

Der folgende Befehl stellt für die Produktion hinter einem internen Load Balancer bereit.

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

Direkte VPC-Egress über --network, --subnet und --vpc-egress=private-ranges-only ermöglicht dem Service, die private IP von Cloud SQL direkt zu erreichen. Öffentliche Egress zu den Agent Platform-Endpunkten und accounts.google.com geht direkt ins Internet statt durch das VPC, daher ist keine Cloud NAT erforderlich.

Die Invoker IAM-Prüfung muss offen oder deaktiviert sein. Das Gateway führt sein eigenes OIDC aus und seine Clients tragen kein GCP-Token, daher muss die Cloud Run Invoker-Prüfung unauthentifizierte Anfragen zulassen. Die OIDC-Anmeldung des Gateways authentifiziert die Anfrage, sobald sie den Container erreicht, wobei allowed_email_domains bestimmt, welche Domains sich anmelden dürfen.

Zwei Flags lassen unauthentifizierte Anfragen zu:

  • --no-invoker-iam-check: deaktiviert die Prüfung ohne allUsers-Bindung zum Verwalten und funktioniert unter Domain Restricted Sharing
  • --allow-unauthenticated: erteilt allUsers die run.invoker-Rolle. Verwenden Sie dies, wenn Ihre Organisation --no-invoker-iam-check nicht zulässt

Ingress-Einschränkung über --ingress ist eine separate, unabhängige Schicht von der Invoker-Prüfung. Halten Sie sie aktiviert, um den Service auf Ihr Unternehmensnetzwerk zu beschränken.

Standardmäßig wird die Cloud Run *.run.app-URL zu einer öffentlichen Adresse aufgelöst, die die /login Private-Network-Prüfung ablehnt. Zwei Topologien geben Entwicklern einen privat auflösbaren Hostnamen, und Cloud Run stellt keinen für Sie bereit:

  • Interner Application Load Balancer, die Topologie, die der obige Deploy-Befehl annimmt: Stellen Sie mit --ingress=internal-and-cloud-load-balancing bereit, stellen Sie einen internen Application Load Balancer vor dem Service mit einem internen DNS-Namen und Zertifikat bereit, und legen Sie listen.public_url auf diesen Hostnamen fest.
  • Nur interne Ingress ohne Load Balancer: Stellen Sie mit --ingress=internal bereit und lassen Sie listen.public_url als *.run.app-URL, die Standardeinstellung in den Referenz-Assets unten. Damit *.run.app privat aufgelöst wird, muss Ihr Netzwerk-Team bereits einen Private Service Connect-Endpunkt für Google APIs betreiben, eine Cloud DNS-Privatzone, die *.run.app darauf auflöst, und On-Premises-Routing zu diesem Endpunkt.

Googles Private-Networking-Leitfaden für Cloud Run behandelt die Infrastruktur, die beide Optionen benötigen. Überprüfen Sie die Anmeldung, sobald das Gateway auf einem privaten Hostnamen bereitgestellt wird. Bestätigen Sie bis dahin, dass der Container aus seinen Logs in Cloud Run gestartet wurde.

Aktualisieren Sie die autorisierte Umleitungs-URI des OAuth-Clients auf <public_url>/oauth/callback vor der ersten Anmeldung. Stellen Sie erneut bereit, nachdem Sie public_url geändert haben, da das Gateway seinen öffentlichen Ursprung nur aus dieser Einstellung erstellt und X-Forwarded-Host und X-Forwarded-Proto ignoriert. X-Forwarded-For wird nur für Client-IPs berücksichtigt, wenn listen.trusted_proxies gesetzt ist.

8

Gateway-URL auf Entwicklermaschinen pushen

Das Gateway wird jetzt ausgeführt, aber Entwickler können es von /login aus nicht erreichen, bis die Gateway-URL auf ihren Maschinen vorhanden ist. Legen Sie forceLoginMethod und forceLoginGatewayUrl in der verwalteten Einstellungsdatei fest, die Sie über MDM auf jedem Gerät bereitstellen. Es gibt keine Gateway-Option in der Anmeldungsauswahl, die ein Entwickler manuell auswählen kann.

Terraform-Referenz

Die Referenz-Bereitstellungs-Assets automatisieren den Cloud Run-Pfad auf dieser Seite. Die Konfigurations- und Image-Assets gelten für beide Pfade:

  • setup.sh: ein idempotenter gcloud-Provisioner, der den vollständigen Cloud Run-Pfad durchläuft, vom Aktivieren von APIs bis zur ersten Bereitstellung
  • terraform/: dieselbe Bereitstellung als Infrastructure-as-Code für eine Greenfield-Bereitstellung: ein gezieltes Apply zum Erstellen des Artifact Registry-Repositorys, dann zum Erstellen und Pushen des Images, dann ein vollständiges Apply
  • gateway.yaml.example und ein Dockerfile für das Distroless-Runtime-Image

Die Artefakte standardisieren Cloud Run Ingress auf internal, daher ist kein Load Balancer erforderlich. Um die Bereitstellung dieser Seite hinter einem ALB zu entsprechen, führen Sie setup.sh mit INGRESS=internal-and-cloud-load-balancing aus oder legen Sie die Terraform-Variable ingress auf INGRESS_TRAFFIC_INTERNAL_LOAD_BALANCER fest. Die Artefakte standardisieren auch die Invoker-Schicht auf eine allUsers run.invoker-Gewährung statt --no-invoker-iam-check, das Gegenteil dieser Seite. Beide funktionieren, und die Wahl hängt von den Richtlinieneinschränkungen Ihrer Organisation ab.

Die Assets werden als funktionierende Beispiele bereitgestellt, nicht als unterstütztes Produktionsartefakt. Überprüfen und passen Sie sie an Ihre Umgebung an.

Fehlerbehebung

Für Gateway-Boot- und Anmeldungsfehler siehe die plattformunabhängige Fehlerbehebungstabelle. Die folgenden Einträge sind spezifisch für Google Cloud.

Symptom Ursache Behebung
Cloud Run gibt 403 Forbidden zurück, bevor der Container erreicht wird Die Invoker IAM-Prüfung ist noch aktiviert Stellen Sie mit --no-invoker-iam-check bereit oder erteilen Sie allUsers die run.invoker-Rolle mit --allow-unauthenticated
--no-invoker-iam-check wird mit invoker_iam_disabled is not currently available abgelehnt Blockiert durch constraints/run.managed.requireInvokerIam Verwenden Sie --allow-unauthenticated. Wenn Domain Restricted Sharing über constraints/iam.allowedPolicyMemberDomains dies auch blockiert, verwenden Sie den GKE-Pfad, der das Gateway auf der Netzwerkebene ohne allUsers-Bindung verfügbar macht.
Container manifest type … must support amd64/linux bei Bereitstellung Image wurde auf einem Nicht-amd64-Host erstellt oder buildx hat einen OCI-Image-Index ausgegeben Erstellen Sie mit --platform=linux/amd64 --provenance=false
Gateway-Boot beendet sich mit Postgres-Verbindungs-Timeout-Fehler auf Cloud Run Service ist nicht an das VPC angehängt oder Cloud SQL hat keine private IP auf diesem VPC. Der Store wartet nach 5 Sekunden nicht mehr Stellen Sie mit --network und --subnet für Direct VPC Egress bereit und erstellen Sie die Cloud SQL-Instanz mit --no-assign-ip und --network, das auf dasselbe VPC verweist
Agent Platform-Anfragen geben 403 PERMISSION_DENIED zurück Laufzeit verwendet nicht den claude-gateway-Service-Account oder das Modell ist nicht in Model Garden für das Projekt aktiviert Legen Sie --service-account auf Cloud Run fest oder binden Sie Workload Identity auf GKE, und aktivieren Sie jedes Claude-Modell in Model Garden für die Zielregion
Streaming-Antworten werden nach einer festen Dauer abgeschnitten Front-End-Anfrage-Timeout: Der Load Balancer Backend-Service hinter GKE Ingress hat standardmäßig 30 Sekunden und Cloud Run 300 Sekunden Hängen Sie eine BackendConfig mit erhöhtem timeoutSec auf GKE an oder stellen Sie mit --timeout=3600 auf Cloud Run bereit

Nächste Schritte