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 Private-IP-Cloud-SQL-Pfad
• run: nur Cloud Run
• container: nur GKE

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:

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.

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 erfordert linux/amd64. --provenance=false vermeidet einen buildx OCI
# Image-Index, den Cloud Run ablehnt.
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>"

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: einmalig pro 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 diesen VPC weitergeleitet werden.

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 externe https://-Ursprung, erforderlich für jede Bindung, die nicht Loopback ist. Siehe die listen-Referenz. Das Gateway erstellt den IdP redirect_uri und sein Discovery-Dokument 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 vorbei an vertrauenswürdigen Hops, sodass Anmelderate-Limits pro IP und Audit-Events Entwickler-IPs statt der IP des Load Balancers aufzeichnen.

Setzen Sie 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.

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 ignoriert offline_access; diese ergeben Refresh-Token:
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

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

Bereitstellen

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"
# Auf einem Standard-Cluster benötigen auch vorhandene Node Pools GKE_METADATA.
# Autopilot aktiviert dies standardmäßig.
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"

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.