Diese Seite zeigt eine Möglichkeit, Claude-Apps-Gateway auf Google Cloud auszuführen. Die Konfiguration ist ein funktionierendes Beispiel für kundenverwaltete Infrastruktur und keine unterstützte Produktionsbereitstellung. Verwenden Sie sie, um zu verstehen, wie die einzelnen Komponenten zusammenpassen, bevor Sie sie an Ihre eigene Umgebung anpassen. Für die plattformunabhängigen Anforderungen siehe den Bereitstellungsleitfaden.
oidc-Block ändert sich. Siehe Identitätsanbieter-Setup für IdP-spezifische Details.
Was Sie erstellen werden
- 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 - HTTPS-Front-End, das Sie bereitstellen: ein interner Application Load Balancer vor Cloud Run, für den diese Anleitung das Gateway konfiguriert, aber nicht erstellt, oder ein interner GKE Ingress der Klasse
gce-internalauf GKE
Voraussetzungen
- Ein GCP-Projekt mit aktivierter Abrechnung und Berechtigung zum Erstellen der oben genannten Ressourcen
- Die
gcloud-CLI, authentifiziert mitgcloud auth login, und Docker lokal installiert - Für den GKE-Pfad:
kubectlund 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
Gateway bereitstellen
Die folgenden Schritte stellen die vollständige Bereitstellung mitgcloud-Befehlen bereit.
1
APIs aktivieren
Aktivieren Sie die Service-APIs, die die Anleitung verwendet:Die APIs, die Sie benötigen, hängen vom Bereitstellungspfad ab:
computeundservicenetworking: erforderlich für den Private-IP-Cloud-SQL-Pfadrun: nur Cloud Runcontainer: nur GKE
2
Dienstkonto erstellen und IAM-Berechtigung erteilen
Das Gateway wird als dediziertes Dienstkonto ausgeführt, das berechtigt ist, Google Cloud’s Agent Platform aufzurufen. Es erreicht Cloud SQL über das VPC mit einem Passwortbenutzer, daher ist keine Cloud-SQL-IAM-Rolle erforderlich: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: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 Die Cloud-Run- oder GKE-Laufzeit muss sich auf diesem VPC befinden oder in diesen VPC weitergeleitet werden.
constraints/sql.restrictPublicIp erzwungen wird:5
gateway.yaml schreiben
Der
upstreams-Block verweist auf Google Cloud’s Agent Platform mit auth: {}, sodass sich das Gateway über Application Default Credentials vom Laufzeit-Dienstkonto authentifiziert. Siehe die Konfigurationsreferenz für jedes Feld.Zwei listen-Felder beschreiben, was das Gateway frontet:public_url: der externehttps://-Ursprung, erforderlich für jede Bindung, die nicht Loopback ist. Siehe dielisten-Referenz. Das Gateway erstellt den IdPredirect_uriund sein Discovery-Dokument nur aus diesem Wert, niemals ausX-Forwarded-*-Headern.trusted_proxies: die Quellbereiche des Front-End. Das Gateway berücksichtigtX-Forwarded-Fornur, wenn der TCP-Peer in dieser Liste ist, durchläuft dann die Kette vorbei an vertrauenswürdigen Hops, sodass Anmelderate-Limits pro IP und Audit-Events Entwickler-IPs statt der IP des Load Balancers aufzeichnen.
trusted_proxies so, dass es Ihrem Front-End entspricht. Ein externes GKE-Ingress der Klasse gce ist nicht aufgelistet: Es stellt eine öffentliche Forwarding-Rule-Adresse bereit, die die /login-Private-Netzwerk-Prüfung ablehnt.Das folgende Beispiel verwendet die Werte des internen Load Balancers vor Cloud Run.
gateway.yaml
Google-ID-Token enthalten keinen
groups-Anspruch. Um gruppenbasierte Richtlinien in managed.policies mit Google Workspace als IdP zu verwenden, konfigurieren Sie oidc.google_groups, das die Gruppen jedes Benutzers über die Admin SDK Directory API mit einem Dienstkonto mit Domain-Wide-Delegation nachschlägt. Ohne dies sollten Sie stattdessen auf email_domain abgleichen.6
Geheimnisse in Secret Manager speichern
Erstellen Sie vier Geheimnisse und erteilen Sie
roles/secretmanager.secretAccessor dem claude-gateway-Dienstkonto:Wie die Geheimnisse den Container erreichen, unterscheidet sich je nach Pfad:
- Auf GKE werden sie als Dateien über den Secret Manager CSI-Treiber bereitgestellt, und
gateway.yamlverweist auf${file:/secrets/...}. - Auf Cloud Run, das mehrere Geheimnisse nicht in ein Verzeichnis einbinden kann, wird
gateway.yamlals Datei bereitgestellt und die anderen drei werden als Umgebungsvariablen eingespritzt, sodassgateway.yamlstattdessen auf${GATEWAY_JWT_SECRET},${OIDC_CLIENT_SECRET}und${GATEWAY_POSTGRES_URL}verweist.
7
Bereitstellen
- Cloud Run
- GKE
Der folgende Befehl stellt für die Produktion hinter einem internen Load Balancer bereit.Direkter VPC-Egress über
--network, --subnet und --vpc-egress=private-ranges-only ermöglicht dem Service, die private Cloud-SQL-IP direkt zu erreichen. Jede Instanz hält bis zu store.max_connections Postgres-Verbindungen, standardmäßig fünf, daher halten Sie maximale Instanzen × store.max_connections unter dem Verbindungslimit Ihres Cloud-SQL-Tiers. Die Referenz-Assets begrenzen Instanzen auf 8 für das db-g1-small-Tier aus diesem Grund. Öffentlicher Egress zu Google Cloud’s Agent Platform-Endpunkten und accounts.google.com geht direkt ins Internet statt durch das VPC, daher ist kein 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 Cloud Run’s 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 Domänen sich anmelden dürfen.Zwei Flags lassen unauthentifizierte Anfragen zu:--no-invoker-iam-check: deaktiviert die Prüfung ohneallUsers-Bindung zum Verwalten und funktioniert unter Domain Restricted Sharing--allow-unauthenticated: erteiltallUsersdierun.invoker-Rolle. Verwenden Sie dies, wenn Ihre Organisation--no-invoker-iam-checknicht zulässt
--ingress ist eine separate, unabhängige Schicht von der Invoker-Prüfung. Halten Sie sie gesetzt, 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-Netzwerk-Prüfung ablehnt. Zwei Topologien geben Entwicklern einen privat auflösbaren Hostnamen, und Cloud Run stellt keinen davon für Sie bereit:- Interner Application Load Balancer, die Topologie, die die
gateway.yamldieser Seite annimmt: Stellen Sie einen internen Application Load Balancer vor dem Service mit einem internen DNS-Namen und Zertifikat bereit, und setzen Sielisten.public_urlauf diesen Hostnamen. Dieinternal-Ingress-Einstellung lässt bereits Traffic von internen Application Load Balancern zu.internal-and-cloud-load-balancinglässt zusätzlich externe Application Load Balancer zu, deren öffentliche Adressen die/login-Private-Netzwerk-Prüfung ablehnt, daher benötigt keine Topologie auf dieser Seite dies. - Nur-interner Ingress ohne Load Balancer: Halten Sie den Deploy-Befehl wie er ist und lassen Sie
listen.public_urlals die*.run.app-URL, die Standardeinstellung in den Referenz-Assets unten. Damit*.run.appprivat aufgelöst wird, muss Ihr Netzwerk-Team bereits einen Private Service Connect-Endpunkt für Google APIs betreiben, eine Cloud-DNS-Private-Zone, die*.run.appdarauf auflöst, und On-Premises-Routing zu diesem Endpunkt.
<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. Stellen Sie das vollständige verwaltete Einstellungs-Snippet mit forceLoginMethod, forceLoginGatewayUrl und dem parentSettingsBehavior: "merge"-Opt-in über MDM auf jedem Gerät bereit. Es gibt keine Gateway-Option in der Anmeldungs-Auswahl, 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 idempotentergcloud-Provisioner, der den vollständigen Cloud Run-Pfad durchläuft, vom Aktivieren von APIs bis zur ersten Bereitstellungterraform/: 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 Applygateway.yaml.exampleund einDockerfilefür das Distroless-Runtime-Image
internal, was dem Bereitstellungsbefehl auf dieser Seite entspricht; diese Einstellung funktioniert mit oder ohne einen internen Application Load Balancer vor dem Service, und die Artefakte erstellen den Load Balancer auch nicht. 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.Nächste Schritte
- Konfigurationsreferenz: jede
gateway.yaml-Option, einschließlichmanaged.policiesundtelemetry - Bereitstellung und Betrieb: IdP-Setup, Integritätsprüfungen, JWT-Geheimnis-Rotation, Upgrades und das Sicherheitsmodell
- Claude-Apps-Gateway-Übersicht: Schnellstart und Verbindung von Entwicklern