Architektur
Die Beispielarchitektur mit Amazon Bedrock als Modell-Upstream. Ein Claude Platform on AWS Upstream nimmt die gleiche Position ein.
- Amazon ECS auf AWS Fargate Service oder Amazon EKS Deployment, das den Gateway-Container ausführt
- Amazon ECR Repository für das Gateway-Image
- Amazon RDS für PostgreSQL Instanz in privaten Subnetzen, nicht öffentlich zugänglich, für den Store des Gateways
- AWS Secrets Manager Geheimnisse für den JWT-Signaturschlüssel, das OIDC-Client-Geheimnis und die Postgres-URL
- IAM-Rolle mit
bedrock:InvokeModel,bedrock:InvokeModelWithResponseStreamundbedrock:CountTokens, angehängt als ECS-Task-Rolle oder gebunden über IAM Roles for Service Accounts (IRSA) auf EKS - Interner Application Load Balancer für HTTPS
Voraussetzungen
Die Anleitung erstellt die eigenen Ressourcen des Gateways, basiert aber auf Netzwerk- und Identitätsinfrastruktur, die Sie bereits haben. Bevor Sie beginnen, benötigen Sie:- Ein AWS-Konto mit Berechtigung zum Erstellen der oben genannten Ressourcen
- Die AWS CLI v2 installiert und authentifiziert, sowie Docker lokal installiert
- Ein VPC mit mindestens zwei privaten Subnetzen in verschiedenen Verfügbarkeitszonen mit ausgehendem Internetzugang über ein NAT-Gateway; der interne Load Balancer benötigt Subnetze in zwei AZs, und das Gateway benötigt Egress zu Bedrock und Ihrem IdP
- Eine Okta OIDC-Webanwendung mit Redirect-URI
https://<gateway-host>/oauth/callback; siehe Identitätsanbieter-Setup - Ein TLS-Hostname für das Gateway, typischerweise ein interner DNS-Name in einer Route 53 privaten gehosteten Zone, der auf den Load Balancer zeigt, mit einem ACM-Zertifikat für diesen Namen, importiert oder ausgestellt von AWS Private CA
Legen Sie Ihre Umgebungsvariablen fest
Jeder Befehl auf dieser Seite liest vier Werte aus Ihrer Shell:AWS_REGION, ACCOUNT_ID, VPC_ID und PRIVATE_SUBNETS.
Wählen Sie eine US-Region, in der Bedrock die Claude-Modelle bereitstellt, die Sie benötigen. Die Anleitung basiert auf dem integrierten Modellkatalog des Gateways, der zu us.anthropic.* Inferenzprofilen aufgelöst wird, und die IAM-Richtlinie gewährt diese ARNs. In einer nicht-US-Region fügen Sie einen models: Block mit den Inferenzprofil-IDs dieser Region hinzu und ändern das ARN-Präfix der IAM-Richtlinie entsprechend.
Wenn Sie die VPC-ID nicht zur Hand haben, listen Sie Ihre VPCs mit aws ec2 describe-vpcs auf und listen Sie dann die Subnetze dieser VPC auf, um zwei private in verschiedenen Verfügbarkeitszonen zu finden:
Stellen Sie das Gateway bereit
Die folgenden Schritte stellen die vollständige Bereitstellung mitaws Befehlen bereit.
Erstellen Sie die Sicherheitsgruppen
- Auf ECS Fargate hängt der Bereitstellungsschritt
$ALB_SGan den Load Balancer und$GW_SGan den Service an. - Auf EKS erstellt der AWS Load Balancer Controller seine eigene Frontend-Sicherheitsgruppe für den ALB, daher werden
$ALB_SGund$GW_SGnicht verwendet: die Annotationinbound-cidrsdes Bereitstellungsschritts beschränkt den Listener auf Ihr Unternehmensnetzwerk, und die Datenbanksicherheitsgruppe lässt stattdessen die Sicherheitsgruppe des Clusters zu.
Erstellen Sie die IAM-Rollen und reichen Sie das Use-Case-Formular ein
gateway-* Wildcards, das in einem gemeinsamen Konto auch nicht verwandte Geheimnisse abgleichen würde; das nachfolgende -?????? gleicht genau das zufällige sechsstellige Suffix ab, das Secrets Manager an jede Geheimnis-ARN anhängt. Ein nachfolgendes -* wäre ein einfaches Präfix-Glob und würde auch längere Namen wie gateway-postgres-url-prod abgleichen.Die IAM-Richtlinie gewährt dem Gateway die Berechtigung, Bedrock aufzurufen, und Bedrock ermöglicht den Modellzugriff standardmäßig in kommerziellen Regionen. Das verbleibende Konto-Level-Gate ist Anthropics einmaliges Use-Case-Formular: Wenn niemand in Ihrem Konto es eingereicht hat, öffnen Sie die Amazon Bedrock Konsole, wählen Sie ein Anthropic-Modell aus dem Modellkatalog und füllen Sie das Formular aus. Der Zugriff wird unmittelbar nach der Einreichung gewährt; siehe Claude Code auf Amazon Bedrock für das AWS Organizations Formular und die IAM-Berechtigungen, die der Einreicher benötigt.Der EKS-Pfad verwendet beide Richtliniendokumente stattdessen auf einer IRSA-Rolle anstelle der zwei ECS-Rollen; siehe den Bereitstellungsschritt.Stellen Sie Amazon RDS für PostgreSQL bereit
rds.force_ssl=1, damit der Server Klartextverbindungen ablehnt. Die Engine-Version ist einmal festgelegt, da die Parametergruppen-Familie mit der Engine-Hauptversion übereinstimmen muss, die die Instanz ausführt:--master-user-password Argument ist in der Prozesstabelle und in Audit-/EDR-Protokollen sichtbar, während der Befehl ausgeführt wird, die gleiche Exposition, die der Geheimnisse-Schritt behandelt. Auf einem gemeinsamen oder überwachten Host übergeben Sie das Passwort stattdessen über --cli-input-json aus einer 0600 Datei, wie es das setup.sh des Bundles tut.Warten Sie, bis die Instanz hochfährt, was mehrere Minuten dauern kann, lesen Sie dann ihren privaten Endpunkt und stellen Sie die Verbindungszeichenfolge zusammen, die das Gateway verwendet:sslmode=verify-full lässt das Gateway das RDS-Serverzertifikat und den Hostnamen überprüfen, nicht nur verschlüsseln. Der Vertrauensanker ist das AWS RDS Zertifikat-Bundle, das der Image-Build-Schritt unten zu /etc/claude/rds-global-bundle.pem kopiert und über NODE_EXTRA_CA_CERTS vertraut. Hängen Sie keinen libpq-Stil sslrootcert= Parameter an die URL an: Der Gateway-Treiber liest nur sslmode aus der Abfragezeichenfolge und würde sslrootcert als Startup-Parameter an Postgres weiterleiten, das der Server ablehnt.Der ECS-Service oder die EKS-Pods müssen in diesem VPC ausgeführt werden, damit sie den privaten Endpunkt der Instanz erreichen können, und die claude-gateway-db Sicherheitsgruppe lässt nur die Sicherheitsgruppe des Gateways zu.Schreiben Sie gateway.yaml
upstreams Block zeigt auf Bedrock mit auth: {}, daher authentifiziert sich das Gateway über die AWS-Standard-Anmeldekette aus der Task-Rolle auf ECS oder der IRSA-Rolle auf EKS. Siehe die Konfigurationsreferenz für jedes Feld.Zwei listen Felder beschreiben, was das Gateway frontet:public_url: die externehttps://Herkunft, erforderlich für jeden nicht-Loopback-Bind; siehe dielistenReferenz. 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, geht dann die Kette über vertrauenswürdige Hops, sodass Anmelderate-Limits pro IP und Audit-Events Entwickler-IPs statt der Load-Balancer-IP aufzeichnen.
trusted_proxies auf die CIDRs dieser Subnetze. Dies vertraut jedem Host in diesen Subnetzen als Proxy. Halten Sie die Ingress-Quelle des ALB, Ihre Unternehmens-CIDR, davon ab, sich zu überlappen, und teilen Sie die Subnetze nicht mit nicht vertrauenswürdigen Workloads, die Client-IPs über X-Forwarded-For fälschen könnten.Das ALB-Attribut zur Beibehaltung des Client-Ports, routing.http.xff_client_port.enabled, kann bei beiden Einstellungen bleiben: Wenn es aktiviert ist, schreibt der ALB den Client als 203.0.113.7:54321 oder [2001:db8::1]:54321, und das Gateway liest beide mit dem Port gelöscht.oidc Block ist Okta-spezifisch. Um stattdessen Microsoft Entra ID zu verwenden, setzen Sie issuer auf https://login.microsoftonline.com/<tenant-id>/v2.0, lassen Sie userinfo_fallback und den groups Scope weg, und beachten Sie, dass Entra Gruppen-Objekt-IDs statt Namen ausgibt, daher müssen managed.policies auf den GUIDs abgleichen, oder auf App-Rollen mit oidc.groups_claim: roles. Siehe Identitätsanbieter-Setup.Speichern Sie Geheimnisse in AWS Secrets Manager
--secret-string Argumente sind in der Prozesstabelle und in Audit-/EDR-Protokollen sichtbar, während jeder Befehl ausgeführt wird. Auf einem gemeinsamen oder überwachten Host legen Sie den Wert in eine 0600 Datei und übergeben Sie stattdessen --secret-string file://<path>. Das setup.sh des Bundles hält Geheimniswerte auf die gleiche Weise aus dem Prozess-argv, indem es 0600 temporäre Dateien an --cli-input-json übergibt.gateway.yaml selbst keine Geheimniswerte, da jede Anmeldedaten beim Start über ${VAR} oder ${file:...} Erweiterung aufgelöst wird. Wie alles den Container erreicht, unterscheidet sich je nach Pfad:- Auf ECS kopiert der Build des nächsten Schritts
gateway.yamlin das Image bei/etc/claude/gateway.yaml, und die Task-Definition injiziert die drei Geheimnisse als Umgebungsvariablen über seinsecretsFeld, daher referenziert die YAML${GATEWAY_JWT_SECRET},${OIDC_CLIENT_SECRET}und${GATEWAY_POSTGRES_URL}. - Auf EKS mounten Sie
gateway.yamlaus einer ConfigMap und die Geheimnisse als Dateien bei/secrets, referenziert als${file:/secrets/...}. Beziehen Sie die Kubernetes Secrets aus Secrets Manager mit dem External Secrets Operator oder dem AWS-Provider des Secrets Store CSI-Treibers, oder erstellen Sie sie direkt mitkubectl.
Erstellen Sie das Image und pushen Sie es zu Amazon ECR
linux-x64 glibc-Binärdatei bei ./claude im Build-Kontext platzieren. Schreiben Sie Ihr eigenes Dockerfile gemäß diesen Anforderungen oder beginnen Sie mit dem Dockerfile des Bundles, das die ausgefüllte gateway.yaml aus den vorherigen Schritten in das Image bei /etc/claude/gateway.yaml kopiert. Auf ECS ist diese eingebettete Kopie, wie die Konfiguration den Container erreicht, weshalb der Build nach dem Schreiben der Datei kommt. Der EKS-Pfad mountet stattdessen gateway.yaml aus einer ConfigMap bei der Bereitstellung, daher ist die eingebettete Kopie dort ungenutzt.Das Image trägt auch das AWS RDS Zertifikat-Bundle als Vertrauensanker für das sslmode=verify-full der Verbindungszeichenfolge, daher laden Sie es zunächst in den Build-Kontext herunter. AWS rotiert das Bundle (neue regionale CAs werden angehängt), daher laden Sie es pro Build herunter, statt einen Checksum zu pinnen oder es zu committen:Dockerfile des Bundles enthält bereits beide:<version> Tag, das der Bereitstellungsschritt pinnt, später nicht stillschweigend auf ein anderes Image umgeleitet werden kann:linux/amd64 aus, daher muss die Plattform hier übereinstimmen; für Fargate auf ARM64 (Graviton) erstellen Sie linux/arm64 mit der linux-arm64 Binärdatei und setzen Sie cpuArchitecture stattdessen auf ARM64:Bereitstellen
- ECS Fargate
- EKS
--ip-address-type ipv4 ist wichtig: Ein interner Dual-Stack-ALB veröffentlicht öffentliche AAAA-Datensätze, die die /login private-Netzwerk-Prüfung ablehnt:--ssl-policy pinnt einen modernen TLS-Boden, da das Weglassen auf die Legacy-Standard-Richtlinie ELBSecurityPolicy-2016-08 zurückfällt, die immer noch TLS 1.0/1.1 akzeptiert.Der ALB schließt eine Verbindung nach 60 Sekunden ohne Daten standardmäßig. Die Keepalive-Pings des Gateways halten Streams innerhalb dieses Standards, daher erhöht das Erhöhen des Timeouts die Marge über der Ping-Kadenz; die Troubleshooting Zeile auf abgebrochenen Streams behandelt den Mechanismus und ältere Gateways. Die folgenden Befehle fügen den Listener hinzu und erhöhen das Timeout:GET /readyz überprüft, ob der Store erreichbar ist, daher kommt eine Task, die Postgres nicht erreichen kann, nie in Rotation; siehe Ausfallverhalten für den Tradeoff und die /healthz Alternative.Die Tasks laufen in privaten Subnetzen ohne öffentliche IP, daher geht der gesamte Egress (zu Bedrock, Ihrem IdP, Secrets Manager, ECR und CloudWatch Logs) durch das NAT-Gateway. Um Bedrock-Verkehr vom öffentlichen Pfad zu halten, erstellen Sie einen bedrock-runtime Interface VPC-Endpunkt und zeigen Sie die base_url des Upstream darauf, wie in der Bedrock Upstream-Referenz gezeigt; der IdP benötigt immer noch Internet-Egress.Beenden Sie, indem Sie Entwicklern einen privat auflösbaren Hostnamen geben: In einer Route 53 privaten gehosteten Zone, alias den internen DNS-Namen des Gateways zum ALB, und setzen Sie listen.public_url auf diesen Hostnamen. Der eigene *.elb.amazonaws.com Name des ALB wird zu privaten Adressen auf einem internen ALB aufgelöst, kann aber Ihr ACM-Zertifikat nicht tragen, daher verwenden Sie Ihren eigenen Namen.Aktualisieren Sie die autorisierte Redirect-URI des OAuth-Clients auf <public_url>/oauth/callback, bevor die erste Anmeldung. Nach dem Ändern von public_url erstellen Sie das Image unter einem neuen Tag neu, registrieren Sie eine neue Task-Definition-Revision und stellen Sie erneut bereit. Auf ECS lebt die Einstellung in der eingebetteten gateway.yaml des Images, und das Gateway erstellt seinen öffentlichen Ursprung nur aus dieser Einstellung, ignoriert X-Forwarded-Host und X-Forwarded-Proto. X-Forwarded-For wird nur berücksichtigt, wenn listen.trusted_proxies gesetzt ist.Pushen Sie die Gateway-URL zu Entwicklermaschinen
/login nicht erreichen, bis die Gateway-URL auf ihren Maschinen ist. Setzen Sie forceLoginMethod und forceLoginGatewayUrl in der verwalteten Einstellungsdatei, die Sie über MDM auf jedes Gerät bereitstellen. Es gibt keine Gateway-Option im Login-Picker für einen Entwickler, um manuell auszuwählen.Terraform-Referenz
Das Begleit-Bundle beiexamples/gateway/aws packt diese Seite als Code:
setup.shskriptet die Bereitstellungs-Anleitung oben mit den gleichenawsBefehlen auf dem ECS Fargate-Pfad. Es ist idempotent: Bestehende Ressourcen werden erkannt und übersprungen, daher ist das erneute Ausführen sicher, und jeder Standard kann über Umgebungsvariable überschrieben werden. Sie erstellen immer noch das Okta OIDC-Client-Geheimnis und das ACM-Zertifikat selbst: Ein Lauf ohne sie überspringt die ECS/ALB-Bereitstellung, nennt die fehlenden Eingaben und druckt dencreate-secretBefehl; erstellen Sie beide und führen Sie erneut aus. Das Bedrock-Use-Case-Formular und der Route 53-Alias werden als nächste Schritte statt automatisch ausgeführt, und der Client-MDM-Push bleibt ein manueller Schritt von dieser Seite.gateway.yaml.exampleist die Konfigurationsvorlage aus dem gateway.yaml-Schritt, mit den optionalen Schlüsseln kommentiert. Kopieren Sie sie zugateway.yamlund ersetzen Sie jedenREPLACE_ME, bevor Sie erstellen.Dockerfileerstellt das Runtime-Image aus der vorkompiliertenlinux-x64Binärdatei und kopiert Ihre ausgefülltegateway.yamlbei/etc/claude/gateway.yaml, plus das AWS RDS Zertifikat-Bundle, das dassslmode=verify-fulldes Stores verankert.setup.shlädt das Bundle nur herunter, wenn es nicht bereits im Build-Kontext ist; löschen Sie die Datei und erstellen Sie unter einem neuen Tag neu, um eine AWS CA-Rotation zu erhalten. Die Konfigurationsdatei enthält keine Geheimniswerte, da jede Anmeldedaten beim Start über${VAR}Erweiterung aufgelöst wird. Eine Konfigurationsbearbeitung bedeutet daher einen Rebuild unter einem neuen Tag;setup.shautomatisiert dies durch Tagging-Images mit einem Hash der Datei.terraform/stellt den gleichen ECS Fargate-Umfang deklarativ bereit: die Sicherheitsgruppen, IAM-Rollen, ECR-Repository, RDS-Instanz, Secrets Manager-Geheimnisse und den ECS-Service hinter dem internen ALB. Das VPC und die privaten Subnetze bleiben Voraussetzungen, die als Variablen übergeben werden. Terraform erstellt das ECR-Repository, erstellt aber nicht das Image, und die Service-Definition referenziert das Image, daher ist die Anwendung zwei Durchläufe: eine gezielte Anwendung für das Repository, dann der Build und Push, dann die vollständige Anwendung. Dasterraform/README.mddes Bundles behandelt die Variablen, den Remote-State und den Abbau.
Troubleshooting
Für Gateway-Boot- und Login-Fehler siehe die plattformunabhängige Troubleshooting-Tabelle. Die Einträge unten sind spezifisch für AWS.Telemetrie
Das Gateway gibt Ihnen pro-Entwickler Nutzungsmetriken ohne jede pro-Maschinen OTEL-Konfiguration. Claude Code gibt OpenTelemetry (OTLP) Metriken, Protokolle und Opt-in-Traces aus; Überwachung der Nutzung behandelt alles, was die CLI meldet. Bei Gateway-Sitzungen stempelt die CLI jeden Export mit den authentifizierten IdP-Identitätsattributenuser.id, user.email und user.groups, daher wird die Nutzung pro Entwickler ohne OTEL_RESOURCE_ATTRIBUTES Rohrleitungen zusammengefasst.
Das Gateway selbst ist ein authentifiziertes OTLP-Relais. Setzen Sie telemetry.forward_to zusammen mit listen.public_url, und es pusht die OTEL-Exporter-Einstellungen zu jedem verbundenen Client und leitet seinen OTLP-Verkehr wörtlich zu jedem Ziel weiter, das Sie auflisten. Jedes Ziel entscheidet sich unabhängig für Metriken, Protokolle und Traces, und der Standard ist nur Metriken; siehe die telemetry Referenz für die pro-Signal-Felder und ihre Empfindlichkeits-Tradeoffs. Das Gateway puffert, aggregiert oder speichert keine Telemetrie, daher ist, wo die Daten landen, vollständig die Exporter-Konfiguration des Collectors.
Client-Telemetrie ist standardmäßig aus; das Konfigurieren von telemetry.forward_to ist, was sie für verbundene Entwickler einschaltet, und jeder interaktive Client zeigt einen einmaligen Sicherheitsgenehmigungsdialog für die gepushten Einstellungen, wie in der Konfigurationsreferenz beschrieben. Auf AWS wird jedes Signal wie folgt einem Ziel zugeordnet.
Client-Metriken, Protokolle und Traces
Zeigen Sietelemetry.forward_to auf einen OpenTelemetry-Collector, wie den AWS Distro for OpenTelemetry (ADOT) Collector, und exportieren Sie von dort zu Amazon CloudWatch, Amazon Managed Service for Prometheus oder einem beliebigen OTLP-Backend.
Führen Sie den Collector als seinen eigenen internen Service aus, der über https:// erreichbar ist; die telemetry Referenz behandelt die Loopback-Ausnahme und CLAUDE_GATEWAY_ALLOW_LOOPBACK.
Gateway-Protokolle
Auf ECS Fargate, kein zusätzliches Setup: Derawslogs Treiber liefert die stderr des Gateways, die seine Audit-Events und Betriebsprotokolle trägt, zur /ecs/claude-gateway Log-Gruppe, die oben erstellt wurde. Auf EKS erreichen Pod-Protokolle CloudWatch nicht standardmäßig, daher geht die Audit-Spur verloren, bis Sie Log-Erfassung installieren: Das Amazon CloudWatch Observability Add-on mit aktivierter Container-Log-Erfassung, oder ein Fluent Bit DaemonSet. Auf beiden Pfaden fragen Sie die Protokolle mit CloudWatch Logs Insights ab und fahren Alarme von Metrik-Filtern.
Container-Metriken
Aktivieren Sie Container Insights auf dem Cluster mitaws ecs update-cluster-settings --cluster claude-gateway --settings name=containerInsights,value=enabled für pro-Task CPU, Speicher und Netzwerk. Auf EKS installieren Sie das Amazon CloudWatch Observability Add-on.
Ausgaben
Telemetrie zeigt Nutzung im Nachhinein; Ausgabenlimits sind die Live-Ansicht des Gateways pro Entwickler und Durchsetzung auf der gemeinsamen Upstream-Anmeldedaten.Nächste Schritte
- Konfigurationsreferenz: jede
gateway.yamlOption, einschließlichmanaged.policiesundtelemetry - Bereitstellung und Betrieb: IdP-Setup, Health-Checks, JWT-Geheimnis-Rotation, Upgrades und das Sicherheitsmodell
- Claude-Apps-Gateway Übersicht: Schnellstart und Verbindung von Entwicklern
- AWS-Beispiele für Claude-Apps-Gateway: Von AWS verwaltete Bereitstellungsbeispiele, die eine Reihe von Kundenumgebungen abdecken