Skip to main content
Diese Seite zeigt eine Möglichkeit, Claude-Apps-Gateway auf AWS auszuführen. Die Konfiguration ist ein funktionierendes Beispiel für kundenverwaltete Infrastruktur und keine unterstützte Produktionsbereitstellung. Nutzen 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.
Dieses Beispiel stellt Claude-Apps-Gateway auf AWS mit Amazon Bedrock als Modell-Upstream bereit und nutzt entweder Amazon ECS auf AWS Fargate oder Amazon EKS für die Berechnung. Okta ist der Beispiel-Identitätsanbieter (IdP), aber jeder OpenID Connect (OIDC) konforme IdP funktioniert. Siehe Identitätsanbieter-Setup für Details pro IdP.
Bedrock ist nicht der einzige Claude-Upstream auf AWS. Das Gateway unterstützt auch Claude Platform on AWS, die von Anthropic betriebene Claude-API mit AWS-Authentifizierung und AWS-Marketplace-Abrechnung, anstelle von Bedrock oder neben ihm. Der Upstream-Eintrag, die Anmeldedaten und die IAM-Berechtigungen unterscheiden sich von den auf dieser Seite beschriebenen Bedrock-spezifischen; die Claude Platform on AWS Upstream-Referenz behandelt, was sich ändert, und der Rest dieser Seite gilt unverändert.

Architektur

Diagramm von Claude-Apps-Gateway auf AWS: Claude Code Clients verbinden sich über HTTPS mit einem internen Application Load Balancer, der das Gateway (ECS Fargate oder EKS) frontet, das in privaten Subnetzen neben einer Amazon RDS für PostgreSQL Instanz für Sitzungszustand läuft. Das Gateway meldet Benutzer über OIDC gegen den Unternehmens-IdP an, liest Geheimnisse aus AWS Secrets Manager, leitet Modellanfragen an Amazon Bedrock mit seiner IAM-Rolle weiter und zieht sein Image bei der Bereitstellung aus Amazon ECR.

Die Beispielarchitektur mit Amazon Bedrock als Modell-Upstream. Ein Claude Platform on AWS Upstream nimmt die gleiche Position ein.

Das Gateway läuft als privater HTTPS-Endpunkt in Ihrem Netzwerk, bei dem sich Entwickler über Ihren IdP anmelden. Ihre Claude Code Sitzungen erreichen Claude-Modelle auf Amazon Bedrock über die IAM-Rolle des Gateways, sodass keine Modellanmeldedaten auf Entwicklermaschinen landen. Die Referenzkonfiguration stellt bereit:
  • 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:InvokeModelWithResponseStream und bedrock: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:

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:
Exportieren Sie alle vier, bevor Sie fortfahren:

Stellen Sie das Gateway bereit

Die folgenden Schritte stellen die vollständige Bereitstellung mit aws Befehlen bereit.
1

Erstellen Sie die Sicherheitsgruppen

Drei Sicherheitsgruppen verketten den Verkehrspfad: Ihr Unternehmensnetzwerk erreicht den Load Balancer auf 443, der Load Balancer erreicht das Gateway auf 8080, und das Gateway erreicht Postgres auf 5432. Nichts anderes ist erreichbar. Wie Sie sie anhängen, hängt vom Compute-Pfad ab:
  • Auf ECS Fargate hängt der Bereitstellungsschritt $ALB_SG an den Load Balancer und $GW_SG an den Service an.
  • Auf EKS erstellt der AWS Load Balancer Controller seine eigene Frontend-Sicherheitsgruppe für den ALB, daher werden $ALB_SG und $GW_SG nicht verwendet: die Annotation inbound-cidrs des Bereitstellungsschritts beschränkt den Listener auf Ihr Unternehmensnetzwerk, und die Datenbanksicherheitsgruppe lässt stattdessen die Sicherheitsgruppe des Clusters zu.
2

Erstellen Sie die IAM-Rollen und reichen Sie das Use-Case-Formular ein

Das Gateway läuft mit einer dedizierten Task-Rolle, deren einzige Berechtigung das Aufrufen von Claude-Modellen auf Bedrock ist. Gemäß der Bedrock Upstream-Referenz muss die Richtlinie sowohl die Cross-Region-Inferenzprofil-ARNs als auch die zugrunde liegenden Foundation-Model-ARNs abdecken:
ECS benötigt auch eine Ausführungsrolle, die der ECS-Agent selbst verwendet, um das Image aus ECR zu ziehen und die später erstellten Secrets Manager-Werte einzuspritzen. Sie ist getrennt von der Task-Rolle, die das Gateway zur Laufzeit mit dem AWS SDK verwendet:
Die Richtlinie nennt eine ARN pro Geheimnis statt eines bloßen 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.
3

Stellen Sie Amazon RDS für PostgreSQL bereit

Die Instanz läuft mit Postgres 16 in den privaten Subnetzen, ohne öffentliche Adresse und mit aktivierter Speicherverschlüsselung.Erstellen Sie zunächst die Subnet-Gruppe, die die Datenbank in den privaten Subnetzen platziert, und eine Parametergruppe mit 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:
Erstellen Sie dann die Instanz mit einem generierten Master-Passwort:
Das Literal --master-user-password Argument ist in der Prozesstabelle und in Audit-/EDR-Logs 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.
4

Schreiben Sie gateway.yaml

Der 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 externe https:// Herkunft, erforderlich für jeden nicht-Loopback-Bind; 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, geht dann die Kette über vertrauenswürdige Hops, sodass Anmelde-Rate-Limits pro IP und Audit-Events Entwickler-IPs statt der Load-Balancer-IP aufzeichnen.
Auf beiden Pfaden ist das Front-End ein interner ALB, ob direkt erstellt oder vom AWS Load Balancer Controller, und ALB-Knoten nehmen Adressen aus den Subnetzen, an die sie angehängt sind, daher setzen Sie 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.
gateway.yaml
Nur der 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.
5

Speichern Sie Geheimnisse in AWS Secrets Manager

Erstellen Sie drei Geheimnisse; die Ausführungsrolle aus dem IAM-Schritt kann sie bereits lesen:
Beachten Sie die ARN, die jeder Aufruf ausgibt; die ECS-Task-Definition referenziert Geheimnisse nach ARN.
Literal --secret-string Argumente sind in der Prozesstabelle und in Audit-/EDR-Logs 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.
Im Gegensatz zu den Geheimnissen enthält gateway.yaml selbst keine Geheimniswerte, da alle Anmeldedaten beim Start über ${VAR} oder ${file:...} Erweiterung aufgelöst werden. Wie alles den Container erreicht, unterscheidet sich je nach Pfad:
  • Auf ECS kopiert der Build des nächsten Schritts gateway.yaml in das Image bei /etc/claude/gateway.yaml, und die Task-Definition injiziert die drei Geheimnisse als Umgebungsvariablen über ihr secrets Feld, daher referenziert die YAML ${GATEWAY_JWT_SECRET}, ${OIDC_CLIENT_SECRET} und ${GATEWAY_POSTGRES_URL}.
  • Auf EKS mounten Sie gateway.yaml aus 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 mit kubectl.
6

Erstellen Sie das Image und pushen Sie es zu Amazon ECR

Erstellen Sie das Image gemäß den Container-Image-Anforderungen, wobei Sie die 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:
Die Container-Image-Anforderungen decken das Bundle nicht ab, daher müssen Sie, wenn Sie Ihr eigenes Dockerfile schreiben, die zwei Zeilen hinzufügen, die es kopieren und vertrauen; das Dockerfile des Bundles enthält bereits beide:
Erstellen Sie das ECR-Repository und melden Sie Docker darin an. Unveränderliche Tags bedeuten, dass das <version> Tag, das der Bereitstellungsschritt pinnt, später nicht stillschweigend auf ein anderes Image umgeleitet werden kann:
Erstellen und pushen Sie das Image. Die Task-Definition unten führt 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:
7

Bereitstellen

Erstellen Sie den Cluster und eine Log-Gruppe für die stderr des Gateways, die sowohl seine Audit-Events als auch Betriebslogs trägt. Die Aufbewahrung ist ein separater Aufruf, und ohne einen behält CloudWatch die Logs für immer; richten Sie die 90 Tage auf Ihre Audit-Aufbewahrungsrichtlinie aus:
Schreiben Sie die Task-Definition. Die Task-Rolle trägt die Bedrock-Berechtigung und die Ausführungsrolle injiziert die Geheimnisse; verwenden Sie die Geheimnis-ARNs aus dem Secrets Manager-Schritt:
claude-gateway-task.json
Registrieren Sie es:
Setzen Sie einen internen ALB davor mit einer Zielgruppe, die das Gateway health-checkt. --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:
Fügen Sie den HTTPS-Listener hinzu. --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 Zeile zu abgebrochenen Streams in der Fehlerbehebung behandelt den Mechanismus und ältere Gateways. Die folgenden Befehle fügen den Listener hinzu und erhöhen den Timeout:
Erstellen Sie den Service. Der Deployment-Schalter rollt eine Bereitstellung, deren Tasks weiterhin fehlschlagen, von einem schlechten Image oder einer nicht bootfähigen Konfiguration, zurück zum letzten stabilen Zustand, statt fehlgeschlagene Tasks für immer neu zu starten:
Die 60-Sekunden-Gnadenfrist gibt einer kalten Task Zeit, das Image zu ziehen, sich mit dem Store zu verbinden und seinen ersten Health-Check zu beantworten, bevor ECS beginnt, Fehler gegen die Bereitstellung zu zählen.Der Health-Check der Zielgruppe auf GET /readyz überprüft, ob der Store erreichbar ist, daher kommt eine Task, die Postgres nicht erreichen kann, nie in Rotation. Um Tasks durch einen kurzen Datenbankausfall wie ein RDS-Failover hindurch den Health-Check bestehen zu lassen, setzen Sie store.readiness_grace_seconds wie in Ausfallverhalten beschrieben, das auch die /healthz Alternative abdeckt.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 vor der ersten 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 für Client-IPs nur berücksichtigt, wenn listen.trusted_proxies gesetzt ist.
8

Pushen Sie die Gateway-URL zu Entwicklermaschinen

Das Gateway läuft jetzt, aber Entwickler können es von /login nicht erreichen, bis die Gateway-URL auf ihren Maschinen ist. Stellen Sie das vollständige Snippet für verwaltete Einstellungen mit forceLoginMethod, forceLoginGatewayUrl und dem Opt-in parentSettingsBehavior: "merge" über MDM auf jedem Gerät bereit. Es gibt keine Gateway-Option im Login-Picker, die ein Entwickler manuell auswählen könnte.

Terraform-Referenz

Das Begleit-Bundle bei examples/gateway/aws packt diese Seite als Code:
  • setup.sh skriptet die Bereitstellungs-Anleitung oben mit den gleichen aws Befehlen 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 den create-secret Befehl; 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.example ist die Konfigurationsvorlage aus dem gateway.yaml-Schritt, mit den optionalen Schlüsseln kommentiert. Kopieren Sie sie zu gateway.yaml und ersetzen Sie jeden REPLACE_ME, bevor Sie erstellen.
  • Dockerfile erstellt das Runtime-Image aus der vorkompilierten linux-x64 Binärdatei und kopiert Ihre ausgefüllte gateway.yaml bei /etc/claude/gateway.yaml, plus das AWS RDS Zertifikat-Bundle, das das sslmode=verify-full des Stores verankert. setup.sh lä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.sh automatisiert 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. Das terraform/README.md des Bundles behandelt die Variablen, den Remote-State und den Abbau.
Wie diese Seite ist das Bundle ein funktionierendes Beispiel für kundenverwaltete Infrastruktur statt einer unterstützten Produktionsbereitstellung; überprüfen und passen Sie es an Ihre eigene Umgebung an, bevor Sie sich darauf verlassen.

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 bietet Ihnen Pro-Entwickler-Nutzungsmetriken ohne OTEL-Konfiguration pro Maschine. Claude Code gibt OpenTelemetry (OTLP) Metriken, Logs und optionale Traces aus; Überwachung der Nutzung behandelt alles, was die CLI meldet. In Sitzungen, die sich über /login anmelden, versieht die CLI jeden Export mit den authentifizierten IdP-Identitätsattributen user.id, user.email und user.groups, sodass die Nutzung pro Entwickler zusammengefasst wird. Das Gateway selbst ist ein authentifiziertes OTLP-Relay. Setzen Sie telemetry.forward_to zusammen mit listen.public_url, und es überträgt die OTEL-Exporter-Einstellungen an jeden verbundenen Client und leitet seinen OTLP-Verkehr wörtlich an jedes von Ihnen aufgelistete Ziel weiter. Jedes Ziel entscheidet sich unabhängig für Metriken, Protokolle und Traces, und die Standardeinstellung ist nur Metriken; siehe die telemetry-Referenz für die Pro-Signal-Felder und ihre Sensitivitäts-Kompromisse. Das Gateway puffert, aggregiert oder speichert Telemetrie nicht, daher ist es vollständig die Exporter-Konfiguration des Collectors, wo die Daten landen. Client-Telemetrie ist standardmäßig deaktiviert; das Konfigurieren von telemetry.forward_to ist das, was sie für verbundene Entwickler aktiviert, und jeder interaktive Client zeigt einen Sicherheitsgenehmigungsdialog für die übertragenen Einstellungen an, wie in der Konfigurationsreferenz beschrieben. Auf AWS wird jedes Signal wie folgt einem Ziel zugeordnet.

Client-Metriken, Protokolle und Traces

Richten Sie telemetry.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 ist keine zusätzliche Einrichtung erforderlich: der awslogs-Treiber liefert die Standardfehlerausgabe des Gateways, die seine Audit-Events und Betriebsprotokolle enthält, an die oben erstellte Log-Gruppe /ecs/claude-gateway. 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 Wegen können Sie die Protokolle mit CloudWatch Logs Insights abfragen und Alarme von Metrikfiltern steuern.

Container-Metriken

Aktivieren Sie Container Insights auf dem Cluster mit aws 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 die Nutzung im Nachhinein; Ausgabenlimits sind die Live-Pro-Entwickler-Ansicht und Durchsetzung des Gateways.

Kostenattribution

Das Gateway signiert jede Bedrock-Anfrage mit seinem eigenen Principal, der ECS-Task-Rolle oder EKS-IRSA-Rolle, sodass AWS standardmäßig alle diese Ausgaben unter einem IAM-Principal sieht. Es gibt zwei Möglichkeiten, dies in den eigenen Abrechnungsdaten von AWS aufzuteilen, und sie lassen sich kombinieren.

Pro Entwickler mit assume_role

Erstellen Sie eine zweite IAM-Rolle, die die Bedrock-Berechtigungen hält und der Principal des Gateways vertraut, gewähren Sie diesem Principal sts:AssumeRole darauf, und setzen Sie assume_role mit session_name: email auf dem Bedrock-Upstream. Das Gateway nimmt dann diese Rolle einmal pro Entwickler pro Stunde an, wobei der Sitzungsname auf ihre E-Mail gesetzt wird, und signiert ihre Anfragen mit dem Ergebnis. Erfordert ein Gateway mit Claude Code v2.1.281 oder später. Die Rolle kann sich auch in einem anderen AWS-Konto befinden: siehe Bedrock in einem anderen AWS-Konto. In Terraform, neben der Task-Rolle im Terraform-Bundle:
Mit assume_role signiert das Gateway jeden Bedrock-Aufruf, einschließlich des kostenlosen CountTokens-Aufrufs für die Ausgabenmessung, mit den Anmeldedaten der angenommenen Rolle, sodass der Principal des Gateways nur für einen Upstream ohne assume_role eine eigene Bedrock-Richtlinie benötigt. Da das Gateway STS zur Anfrageverarbeitungszeit aufruft, benötigen die privaten Subnetze einen Pfad zu sts.<region>.amazonaws.com. Das NAT-Gateway aus den Voraussetzungen bietet einen, ebenso wie ein STS-Interface-VPC-Endpunkt, der für diesen Hostnamen antwortet. Jeder aktive Entwickler kostet einen STS-Aufruf pro Stunde pro Gateway-Replik. Die Anfragen jedes Entwicklers erreichen AWS als Principal arn:aws:sts::<account>:assumed-role/<role>/<email>. Um die Ausgaben pro Principal zu sehen, verwenden Sie einen Abrechnungsexport, der IAM-Principal-Daten enthält; die IAM-Principal-Kostenallokation-Seite von AWS behandelt, wie man sie aktiviert und welche Abrechnungstools sie anzeigen.

Pro Team mit Anwendungs-Inferenzprofilen

Diese Route verwendet nur die Abschnitte models und managed. Erstellen Sie ein Bedrock-Anwendungs-Inferenzprofil pro Team und Modell, kennzeichnen Sie jedes Profil mit dem Team, und aktivieren Sie dieses Tag als Kostenallokations-Tag. Geben Sie dann jedem Team seine eigene Modell-ID in gateway.yaml und heften Sie jede IdP-Gruppe an die IDs seines Teams:
Weisen Sie Entwickler in einem angehefteten Team an, Claude Code mit --model platform-claude-opus-4-8 zu starten, wobei sie die ID ihres Teams verwenden, da eine Sitzung, die ohne sie gestartet wird, das Standardmodell ausführt, das das Gateway für sie ablehnt. Das Gateway erzwingt availableModels bei jeder Anfrage, nicht nur in der Modellauswahl, und AWS gruppiert die Ausgaben nach dem Tag, den Sie aktiviert haben. Ohne die match: {}-Catch-All-Regel erhält ein Entwickler, der keine Richtlinie erfüllt, jedes Modell im Katalog und kann das Profil eines Teams abrechnen. Die Kosten:
  • Die Konfiguration wächst mit Teams mal Modellen
  • Die Rolle, die die Bedrock-Anfragen dieses Upstreams signiert, muss auch berechtigt sein, die application-inference-profile/*-ARNs aufzurufen. Diese Rolle ist der Principal des Gateways, oder mit assume_role die Rolle, die es annimmt.
Siehe Wie Anfragen bepreist werden, um zu erfahren, wie das Ausgabenmessgerät des Gateways diese IDs bewertet.

Einen Entwickler wählen lassen, welchem Team abgerechnet wird

Damit ein Entwickler, der für zwei Teams arbeitet, wählen kann, welchem Team jede Sitzung abgerechnet wird, geben Sie diesem Teampaar eine eigene IdP-Gruppe und eine eigene Richtlinie.
1

Eine Gruppe für das Paar hinzufügen

Fügen Sie den Entwickler in Ihrem IdP einer neuen Gruppe hinzu, z. B. team-platform-and-data. Wenn er bereits angemeldet ist, lassen Sie ihn /login erneut ausführen, oder warten Sie auf die nächste stille Aktualisierung, damit das Gateway die neue Gruppe sieht.
2

Ihre Richtlinie zuerst aufführen

Setzen Sie die Richtlinie der Gruppe über die Einzelteam-Richtlinien und erlauben Sie darin die IDs beider Teams. Übernehmen Sie alle anderen Einstellungen, die die beiden Teamrichtlinien festlegen.
3

Jede Sitzung mit der ID eines Teams starten

Lassen Sie den Entwickler die ID des Teams übergeben, für das die Arbeit bestimmt ist, z. B. claude --model data-claude-opus-4-8.
Das Gateway wendet die erste passende Richtlinie an, sodass ein Entwickler, der nur in den beiden Teamgruppen ist, die Richtlinie team-platform erhält. Seine Sitzungen mit der ID des Datenteams schlagen mit is not in your role's availableModels allowlist fehl, wobei das Standardmodell von Claude Code genannt wird und nicht die eingegebene ID. Wenn Sie stattdessen beide Teamgruppen in den groups einer einzigen Richtlinie aufführen, kann jeder in einem der beiden Teams das Profil eines der beiden Teams abrechnen. In den eigenen Ausgabenlimits des Gateways hat der Entwickler eine Gesamtsumme und ein Limit pro Zeitraum, standardmäßig das niedrigste Limit seiner Gruppen, unabhängig davon, welche ID eine Sitzung verwendet. Damit das niedrigere Limit eines Teams nicht die Arbeit für das andere Team stoppt, legen Sie für den Entwickler ein benutzerspezifisches Limit fest.

Nächste Schritte