Arsitektur
Arsitektur contoh, dengan Amazon Bedrock sebagai upstream model. Upstream Claude Platform di AWS menempati posisi yang sama.
- Layanan Amazon ECS di AWS Fargate atau Amazon EKS Deployment yang menjalankan kontainer gateway
- Repositori Amazon ECR untuk gambar gateway
- Instans Amazon RDS untuk PostgreSQL di subnet pribadi, tidak dapat diakses secara publik, untuk store gateway
- Rahasia AWS Secrets Manager untuk kunci penandatanganan JWT, rahasia klien OIDC, dan URL Postgres
- Peran IAM dengan
bedrock:InvokeModel,bedrock:InvokeModelWithResponseStream, danbedrock:CountTokens, terpasang sebagai peran tugas ECS atau terikat melalui IAM Roles for Service Accounts (IRSA) di EKS - Application Load Balancer Internal untuk HTTPS
Prasyarat
Panduan ini membuat sumber daya gateway sendiri, tetapi dibangun di atas infrastruktur jaringan dan identitas yang sudah Anda miliki. Sebelum Anda mulai, Anda memerlukan:- Akun AWS dengan izin untuk membuat sumber daya di atas
- AWS CLI v2 terinstal dan terauthentikasi, dan Docker terinstal secara lokal
- VPC dengan setidaknya dua subnet pribadi di Zona Ketersediaan berbeda, dengan akses internet keluar melalui gateway NAT; load balancer internal memerlukan subnet di dua AZ, dan gateway memerlukan egress ke Bedrock dan IdP Anda
- Aplikasi web OIDC Okta dengan URI pengalihan
https://<gateway-host>/oauth/callback; lihat Pengaturan penyedia identitas - Nama host TLS untuk gateway, biasanya nama DNS internal di zona hosted pribadi Route 53 yang menunjuk ke load balancer, dengan sertifikat ACM untuk nama itu, diimpor atau dikeluarkan oleh AWS Private CA
Atur variabel lingkungan Anda
Setiap perintah di halaman ini membaca empat nilai dari shell Anda:AWS_REGION, ACCOUNT_ID, VPC_ID, dan PRIVATE_SUBNETS.
Pilih wilayah US tempat Bedrock melayani model Claude yang Anda butuhkan. Panduan ini bergantung pada katalog model bawaan gateway, yang diselesaikan ke profil inferensi us.anthropic.*, dan kebijakan IAM memberikan ARN tersebut. Di wilayah non-US, tambahkan blok models: dengan ID profil inferensi geo itu dan ubah awalan ARN kebijakan IAM agar sesuai.
Jika Anda tidak memiliki ID VPC di tangan, daftarkan VPC Anda dengan aws ec2 describe-vpcs, kemudian daftarkan subnet VPC itu untuk menemukan dua subnet pribadi di Zona Ketersediaan berbeda:
Terapkan gateway
Langkah-langkah di bawah menyediakan deployment lengkap dengan perintahaws.
Buat grup keamanan
- Di ECS Fargate, langkah deploy melampirkan
$ALB_SGke load balancer dan$GW_SGke layanan. - Di EKS, AWS Load Balancer Controller membuat grup keamanan frontend-nya sendiri, jadi
$ALB_SGdan$GW_SGtidak digunakan: anotasiinbound-cidrslangkah deploy membatasi pendengar ke jaringan perusahaan Anda, dan grup keamanan database mengakui grup keamanan kluster sebagai gantinya.
Buat peran IAM dan kirimkan formulir kasus penggunaan
gateway-* telanjang, yang dalam akun bersama juga akan cocok dengan rahasia yang tidak terkait; akhiran -?????? yang tertinggal cocok dengan tepat enam karakter acak yang ditambahkan Secrets Manager ke ARN setiap rahasia. Akhiran -* akan menjadi glob awalan biasa dan juga akan cocok dengan nama yang lebih panjang seperti gateway-postgres-url-prod.Kebijakan IAM memberikan gateway izin untuk memanggil Bedrock, dan Bedrock mengaktifkan akses model secara default di wilayah komersial. Gerbang tingkat akun yang tersisa adalah formulir kasus penggunaan Anthropic satu kali: jika tidak ada yang di akun Anda telah mengirimkannya, buka konsol Amazon Bedrock, pilih model Anthropic dari katalog Model, dan lengkapi formulir. Akses diberikan segera setelah pengajuan; lihat Claude Code di Amazon Bedrock untuk formulir AWS Organizations dan izin IAM yang dibutuhkan pengajuan.Trek EKS menggunakan kembali kedua dokumen kebijakan pada peran IRSA sebagai gantinya dari dua peran ECS; lihat langkah deploy.Sediakan Amazon RDS untuk PostgreSQL
rds.force_ssl=1 sehingga server menolak koneksi plaintext. Versi mesin disematkan sekali karena keluarga grup parameter harus cocok dengan versi utama mesin yang dijalankan instans:--master-user-password literal terlihat di tabel proses dan dalam log audit/EDR saat perintah berjalan, paparan yang sama yang dicakup catatan langkah rahasia. Di host bersama atau dipantau, teruskan kata sandi melalui --cli-input-json dari file 0600 sebagai gantinya, cara yang dilakukan setup.sh bundle.Tunggu instans naik, yang dapat memakan waktu beberapa menit, kemudian baca endpoint pribadinya dan kumpulkan string koneksi yang akan digunakan gateway:sslmode=verify-full membuat gateway memverifikasi rantai sertifikat server RDS dan nama host, bukan hanya enkripsi. Jangkar kepercayaan adalah bundel sertifikat AWS RDS, yang langkah build gambar di bawah menyalin ke /etc/claude/rds-global-bundle.pem dan mempercayai melalui NODE_EXTRA_CA_CERTS. Jangan menambahkan parameter sslrootcert= gaya libpq ke URL: driver gateway membaca hanya sslmode dari string kueri dan akan meneruskan sslrootcert ke Postgres sebagai parameter startup, yang ditolak server.Layanan ECS atau pod EKS harus berjalan di VPC ini sehingga mereka dapat mencapai endpoint pribadi instans, dan grup keamanan claude-gateway-db hanya mengakui grup keamanan gateway.Tulis gateway.yaml
upstreams menunjuk ke Bedrock dengan auth: {}, jadi gateway mengautentikasi melalui rantai kredensial default AWS dari peran tugas di ECS atau peran IRSA di EKS. Lihat referensi konfigurasi untuk setiap bidang.Dua bidang listen bergantung pada apa yang menghadap gateway:public_url: asalhttps://eksternal, diperlukan untuk bind non-loopback apa pun; lihat referensilisten. Gateway membangunredirect_uriIdP dan dokumen penemuannya hanya dari nilai ini, tidak pernah dari headerX-Forwarded-*.trusted_proxies: rentang sumber front end. Gateway menghormatiX-Forwarded-Forhanya ketika peer TCP berada dalam daftar ini, kemudian berjalan di rantai melewati hop terpercaya, jadi batas laju sign-in per-IP dan acara audit mencatat IP pengembang daripada load balancer.
trusted_proxies ke CIDR subnet tersebut. Ini mempercayai setiap host di subnet tersebut sebagai proxy. Jaga sumber ingress ALB, CIDR perusahaan Anda, dari tumpang tindih dengannya, dan jangan bagikan subnet dengan beban kerja yang tidak dipercaya yang dapat memalsukan IP klien melalui X-Forwarded-For.Atribut preservasi port klien ALB, routing.http.xff_client_port.enabled, dapat tetap di salah satu pengaturan: dengan itu aktif, ALB menulis klien sebagai 203.0.113.7:54321 atau [2001:db8::1]:54321, dan gateway membaca keduanya dengan port dijatuhkan.oidc yang spesifik Okta. Untuk menggunakan Microsoft Entra ID sebagai gantinya, atur issuer ke https://login.microsoftonline.com/<tenant-id>/v2.0, lepaskan userinfo_fallback dan cakupan groups, dan perhatikan bahwa Entra memancarkan Object ID grup daripada nama, jadi managed.policies harus cocok pada GUID, atau pada App Roles dengan oidc.groups_claim: roles. Lihat Pengaturan penyedia identitas.Simpan rahasia di AWS Secrets Manager
--secret-string literal terlihat di tabel proses dan dalam log audit/EDR saat setiap perintah berjalan. Di host bersama atau dipantau, masukkan nilai dalam file 0600 dan teruskan --secret-string file://<path> sebagai gantinya. setup.sh bundle menjaga nilai rahasia dari argv proses dengan cara yang sama, melewatkan file sementara 0600 ke --cli-input-json.gateway.yaml sendiri tidak berisi nilai rahasia, karena setiap kredensial diselesaikan saat boot melalui ekspansi ${VAR} atau ${file:...}. Bagaimana semuanya mencapai kontainer berbeda menurut trek:- Di ECS, build langkah berikutnya menyalin
gateway.yamlke dalam gambar di/etc/claude/gateway.yaml, dan definisi tugas menyuntikkan tiga rahasia sebagai variabel lingkungan melalui bidangsecrets-nya, jadi YAML mereferensikan${GATEWAY_JWT_SECRET},${OIDC_CLIENT_SECRET}, dan${GATEWAY_POSTGRES_URL}. - Di EKS, pasang
gateway.yamldari ConfigMap dan rahasia sebagai file di/secrets, direferensikan sebagai${file:/secrets/...}. Sumber Kubernetes Secrets dari Secrets Manager dengan External Secrets Operator atau penyedia AWS driver Secrets Store CSI, atau buat langsung dengankubectl.
Bangun dan dorong gambar ke Amazon ECR
linux-x64 di ./claude dalam konteks build. Tulis Dockerfile Anda sendiri sesuai persyaratan tersebut atau mulai dari Dockerfile bundle, yang menyalin gateway.yaml yang diisi dari langkah sebelumnya ke dalam gambar di /etc/claude/gateway.yaml. Di ECS salinan tertanam itu adalah cara konfigurasi mencapai kontainer, itulah mengapa build datang setelah file ditulis. Trek EKS sebagai gantinya memasang gateway.yaml dari ConfigMap saat deploy, jadi salinan tertanam tidak digunakan di sana.Gambar juga membawa bundel sertifikat AWS RDS sebagai jangkar kepercayaan untuk string koneksi sslmode=verify-full, jadi unduh ke dalam konteks build terlebih dahulu. AWS memutar bundel (CA regional baru ditambahkan), jadi unduh per build daripada menyematkan checksum atau melakukan commit:Dockerfile bundle sudah menyertakan keduanya:<version> yang disematkan langkah deploy tidak dapat kemudian diarahkan ulang secara diam-diam ke gambar yang berbeda:linux/amd64, jadi platform harus cocok di sini; untuk Fargate di ARM64 (Graviton), bangun linux/arm64 dengan biner linux-arm64 dan atur cpuArchitecture ke ARM64 sebagai gantinya:Terapkan
- ECS Fargate
- EKS
--ip-address-type ipv4 penting: ALB dual-stack internal menerbitkan catatan AAAA jangkauan publik, yang ditolak oleh pemeriksaan jaringan pribadi /login:--ssl-policy menyematkan lantai TLS modern, karena menghilangkannya kembali ke default ELBSecurityPolicy-2016-08 warisan, yang masih menerima TLS 1.0/1.1.ALB menutup koneksi setelah 60 detik tanpa data secara default. Ping keepalive gateway menjaga aliran di dalam default itu, jadi menaikkan timeout menambah margin di atas kecepatan ping; baris Troubleshooting pada aliran yang dijatuhkan mencakup mekanisme dan gateway yang lebih lama. Perintah di bawah menambahkan pendengar dan menaikkan timeout:GET /readyz memverifikasi toko dapat dijangkau, jadi tugas yang tidak dapat mencapai Postgres tidak pernah memasuki rotasi. Untuk menjaga tugas melewati pemeriksaan melalui pemadaman database singkat seperti failover RDS, atur store.readiness_grace_seconds seperti yang dijelaskan dalam Perilaku Pemadaman, yang juga mencakup alternatif /healthz.Tugas berjalan di subnet pribadi tanpa IP publik, jadi semua egress (ke Bedrock, IdP Anda, Secrets Manager, ECR, dan CloudWatch Logs) melalui gateway NAT. Untuk menjaga lalu lintas Bedrock dari jalur publik, buat endpoint VPC antarmuka bedrock-runtime dan arahkan base_url upstream ke sana, seperti yang ditunjukkan dalam referensi upstream Bedrock; IdP masih memerlukan egress internet.Selesaikan dengan memberikan pengembang nama host yang dapat diselesaikan secara pribadi: di zona hosted pribadi Route 53, alias nama DNS internal gateway ke ALB, dan atur listen.public_url ke nama host itu. Nama *.elb.amazonaws.com ALB sendiri diselesaikan ke alamat pribadi di ALB internal, tetapi tidak dapat membawa sertifikat ACM Anda, jadi gunakan nama Anda sendiri.Perbarui URI pengalihan otorisasi klien OAuth ke <public_url>/oauth/callback sebelum sign-in pertama. Setelah mengubah public_url, bangun kembali dan dorong gambar di bawah tag baru, daftarkan revisi definisi tugas baru, dan terapkan kembali. Di ECS pengaturan hidup dalam gateway.yaml tertanam gambar, dan gateway membangun asal publik hanya dari pengaturan itu, mengabaikan X-Forwarded-Host dan X-Forwarded-Proto. X-Forwarded-For dihormati untuk IP klien hanya ketika listen.trusted_proxies diatur.Dorong URL gateway ke mesin pengembang
/login sampai URL gateway ada di mesin mereka. Terapkan cuplikan pengaturan terkelola lengkap, dengan forceLoginMethod, forceLoginGatewayUrl, dan opt-in parentSettingsBehavior: "merge", ke setiap perangkat melalui MDM. Tidak ada opsi gateway dalam pemilih login untuk dipilih pengembang secara manual.Referensi Terraform
Bundle pendamping diexamples/gateway/aws mengemas halaman ini sebagai kode:
setup.shmengskrip panduan penyediaan di atas dengan perintahawsyang sama, di trek ECS Fargate. Ini adalah idempoten: sumber daya yang ada terdeteksi dan dilewati, jadi menjalankannya kembali aman, dan default apa pun dapat ditimpa melalui variabel lingkungan. Anda masih membuat rahasia klien OIDC Okta dan sertifikat ACM sendiri: jalankan tanpa mereka melewati deploy ECS/ALB, menamai input yang hilang, dan mencetak perintahcreate-secret; buat keduanya dan jalankan kembali. Formulir kasus penggunaan Bedrock dan alias Route 53 dicetak sebagai langkah berikutnya daripada berjalan secara otomatis, dan push MDM klien tetap menjadi langkah manual dari halaman ini.gateway.yaml.exampleadalah template konfigurasi dari langkah gateway.yaml, dengan kunci opsional disertakan berkomentar. Salin kegateway.yamldan ganti setiapREPLACE_MEsebelum membangun.Dockerfilemembangun gambar runtime dari binerlinux-x64yang telah dibangun sebelumnya dan menyalingateway.yamlyang diisi di/etc/claude/gateway.yaml, ditambah bundel sertifikat AWS RDS yang menambatkansslmode=verify-fulltoko.setup.shmengunduh bundel hanya ketika belum ada dalam konteks build; hapus file dan bangun kembali di bawah tag baru untuk mengambil rotasi CA AWS. File konfigurasi tidak menyimpan nilai rahasia, karena setiap kredensial diselesaikan saat boot melalui ekspansi${VAR}. Edit konfigurasi oleh karena itu berarti rebuild di bawah tag baru;setup.shmengotomatisasi ini dengan menandai gambar dengan hash file.terraform/menyediakan cakupan ECS Fargate yang sama secara deklaratif: grup keamanan, peran IAM, repositori ECR, instans RDS, rahasia Secrets Manager, dan layanan ECS di belakang ALB internal. VPC dan subnet pribadi tetap menjadi prasyarat, dilewatkan sebagai variabel. Terraform membuat repositori ECR tetapi tidak membangun gambar, dan definisi layanan mereferensikan gambar, jadi apply adalah dua pass: apply tertarget untuk repositori, kemudian build dan push, kemudian apply penuh.terraform/README.mdbundle mencakup variabel, status jarak jauh, dan teardown.
Troubleshooting
Untuk boot gateway dan kesalahan login, lihat tabel troubleshooting yang tidak bergantung pada platform. Entri di bawah khusus untuk AWS.Telemetry
Gateway memberikan Anda metrik penggunaan per-developer tanpa konfigurasi OTEL per-mesin apa pun. Claude Code memancarkan metrik OpenTelemetry (OTLP), log, dan trace opt-in; Monitoring usage mencakup semua yang dilaporkan CLI. Dalam sesi yang masuk melalui/login, CLI memberi stempel setiap ekspor dengan atribut identitas IdP yang diautentikasi user.id, user.email, dan user.groups, sehingga penggunaan terakumulasi per developer.
Gateway itu sendiri adalah relay OTLP yang diautentikasi. Atur telemetry.forward_to bersama dengan listen.public_url, dan itu mendorong pengaturan OTEL exporter ke setiap klien yang terhubung dan meneruskan lalu lintas OTLP mereka secara verbatim ke setiap tujuan yang Anda daftarkan. Setiap tujuan memilih metrik, log, dan trace secara independen, dan defaultnya hanya metrik; lihat referensi telemetry untuk bidang per-sinyal dan trade-off sensitivitasnya. Gateway tidak membuffer, mengagregasi, atau menyimpan telemetry, jadi tempat data mendarat sepenuhnya merupakan konfigurasi exporter collector.
Telemetry klien dimatikan secara default; mengonfigurasi telemetry.forward_to adalah apa yang mengaktifkannya untuk developer yang terhubung, dan setiap klien interaktif menampilkan dialog persetujuan keamanan untuk pengaturan yang didorong, seperti yang dijelaskan dalam referensi konfigurasi. Di AWS, setiap sinyal memetakan ke tujuan sebagai berikut.
Client metrics, logs, and traces
Arahkantelemetry.forward_to ke kolektor OpenTelemetry, seperti AWS Distro for OpenTelemetry (ADOT) collector, dan ekspor dari sana ke Amazon CloudWatch, Amazon Managed Service for Prometheus, atau backend OTLP apa pun.
Jalankan kolektor sebagai layanan internal tersendiri yang dapat dijangkau melalui https://; referensi telemetry mencakup pengecualian loopback dan CLAUDE_GATEWAY_ALLOW_LOOPBACK.
Gateway logs
Di ECS Fargate, tidak ada setup tambahan: driverawslogs mengirimkan stderr gateway, yang membawa acara audit dan log operasionalnya, ke grup log /ecs/claude-gateway yang dibuat di atas. Di EKS, log pod tidak mencapai CloudWatch secara default, jadi jejak audit hilang sampai Anda memasang pengumpulan log: add-on Amazon CloudWatch Observability dengan penangkapan log kontainer diaktifkan, atau DaemonSet Fluent Bit. Di kedua jalur, kueri log dengan CloudWatch Logs Insights dan jalankan alarm dari filter metrik.
Container metrics
Aktifkan Container Insights pada kluster denganaws ecs update-cluster-settings --cluster claude-gateway --settings name=containerInsights,value=enabled untuk CPU per-task, memori, dan jaringan. Di EKS, pasang add-on Amazon CloudWatch Observability.
Spend
Telemetry menunjukkan penggunaan setelah fakta; spend limits adalah tampilan dan penegakan per-developer live gateway.Atribusi biaya
Gateway menandatangani setiap permintaan Bedrock dengan principal-nya sendiri, peran tugas ECS atau peran IRSA EKS, jadi secara default AWS melihat semua pengeluaran itu di bawah satu principal IAM. Ada dua cara untuk membaginya dalam data penagihan AWS sendiri, dan keduanya dapat digabungkan.Per pengembang dengan assume_role
Buat peran IAM kedua yang memegang izin Bedrock dan mempercayai principal gateway, berikan principal itu sts:AssumeRole padanya, dan atur assume_role dengan session_name: email pada upstream Bedrock. Gateway kemudian mengasumsikan peran itu sekali per pengembang per jam dengan nama sesi diatur ke email mereka dan menandatangani permintaan mereka dengan hasilnya. Memerlukan gateway yang menjalankan Claude Code v2.1.281 atau lebih baru. Peran juga dapat berada di akun AWS lain: lihat Bedrock di akun AWS lain. Di Terraform, di sebelah peran tugas dalam bundle Terraform:
assume_role yang diatur, gateway menandatangani setiap panggilan Bedrock, panggilan CountTokens gratis untuk pengukuran pengeluaran yang disertakan, dengan kredensial peran yang diasumsikan, jadi principal gateway hanya memerlukan kebijakan Bedrock sendiri untuk upstream tanpa assume_role.
Karena gateway memanggil STS pada waktu permintaan, subnet pribadi memerlukan jalur ke sts.<region>.amazonaws.com. NAT gateway dari prasyarat menyediakan satu, dan begitu juga endpoint VPC antarmuka STS yang menjawab untuk nama host itu. Setiap pengembang aktif memerlukan satu panggilan STS per jam per replika gateway.
Permintaan setiap pengembang mencapai AWS sebagai principal arn:aws:sts::<account>:assumed-role/<role>/<email>. Untuk melihat pengeluaran per principal, gunakan ekspor penagihan yang mencakup data principal IAM; halaman alokasi biaya principal IAM AWS mencakup cara mengaktifkannya dan alat penagihan mana yang menampilkannya.
Per tim dengan profil inferensi aplikasi
Rute ini hanya menggunakan bagianmodels dan managed. Buat satu profil inferensi aplikasi Bedrock per tim dan model, tandai setiap profil dengan tim, dan aktifkan tag itu sebagai tag alokasi biaya. Kemudian berikan setiap tim id model-nya sendiri di gateway.yaml dan pin setiap grup IdP ke id tim-nya:
--model platform-claude-opus-4-8, menggunakan id tim mereka, karena sesi yang dimulai tanpanya menjalankan model default, yang gateway tolak untuk mereka.
Gateway memberlakukan availableModels pada setiap permintaan, bukan hanya di pemilih model, dan penagihan AWS mengelompokkan pengeluaran berdasarkan tag yang Anda aktifkan. Tanpa catch-all match: {}, pengembang yang tidak cocok dengan kebijakan apa pun mendapatkan setiap model dalam katalog dan dapat menagih profil tim mana pun.
Biayanya:
- Konfigurasi tumbuh dengan tim kali model
- Peran yang menandatangani permintaan Bedrock upstream ini juga harus diizinkan untuk memanggil ARN
application-inference-profile/*. Peran itu adalah principal gateway, atau denganassume_roleperan yang diasumsikannya.
Izinkan pengembang memilih tim yang akan ditagih
Untuk mengizinkan pengembang yang bekerja untuk dua tim memilih tim mana yang ditagih oleh setiap sesi, berikan pasangan tim tersebut grup IdP dan kebijakannya sendiri.Tambahkan grup untuk pasangan tersebut
team-platform-and-data. Jika mereka sudah masuk, minta mereka menjalankan /login lagi, atau tunggu penyegaran senyap berikutnya, agar gateway melihat grup baru tersebut.Cantumkan kebijakannya terlebih dahulu
Mulai setiap sesi dengan id tim
claude --model data-claude-opus-4-8.team-platform. Sesi mereka dengan id tim data gagal dengan is not in your role's availableModels allowlist, yang menyebutkan model default Claude Code dan bukan id yang mereka ketik. Jika Anda justru mencantumkan kedua grup tim dalam groups satu kebijakan, semua orang di kedua tim dapat menagih profil tim mana pun.
Dalam batas pengeluaran gateway sendiri, pengembang memiliki satu total dan satu batas per periode, secara default batas terendah dari grup-grup mereka, id mana pun yang digunakan sesi. Agar batas yang lebih rendah dari satu tim tidak menghentikan pekerjaan untuk tim lainnya, atur batas per pengguna untuk pengembang tersebut.
Langkah berikutnya
- Referensi konfigurasi: setiap opsi
gateway.yaml, termasukmanaged.policiesdantelemetry - Deployment dan operasi: pengaturan IdP, pemeriksaan kesehatan, rotasi rahasia JWT, upgrade, dan model keamanan
- Gambaran umum gateway aplikasi Claude: quickstart dan menghubungkan pengembang
- Sampel AWS untuk gateway aplikasi Claude: sampel yang dipertahankan AWS mencakup berbagai lingkungan pelanggan