本頁面介紹在 AWS 上執行 Claude apps gateway 的一種方式。此設定是客戶管理基礎設施的實際運作範例,而非受支援的生產部署;在將其調整至您自己的環境之前,請使用它來了解各個部分如何組合在一起。如需平台無關的需求,請參閱部署指南。
Bedrock 不是 AWS 上唯一的 Claude 上游。gateway 也支援 Claude Platform on AWS,這是 Anthropic 營運的 Claude API,具有 AWS 驗證和 AWS Marketplace 計費,可以代替 Bedrock 或與其並行使用。其上游項目、認證和 IAM 權限與本頁面的 Bedrock 範圍的不同;Claude Platform on AWS 上游參考涵蓋了哪些內容會改變,本頁面的其餘部分保持不變。
架構
範例架構,以 Amazon Bedrock 作為模型上游。Claude Platform on AWS 上游佔據相同位置。
- Amazon ECS on AWS Fargate 服務或 Amazon EKS Deployment 執行 gateway 容器
- Amazon ECR 儲存庫用於 gateway 映像
- Amazon RDS for PostgreSQL 實例在私有子網中,不可公開存取,用於 gateway 的儲存
- AWS Secrets Manager 機密用於 JWT 簽署金鑰、OIDC 客戶端機密和 Postgres URL
- IAM 角色具有
bedrock:InvokeModel和bedrock:InvokeModelWithResponseStream,附加為 ECS 任務角色或透過 EKS 上的 IAM Roles for Service Accounts (IRSA) 綁定 - 內部應用程式負載平衡器用於 HTTPS
先決條件
此逐步解說建立 gateway 自己的資源,但它建立在您已經擁有的網路和身份基礎設施之上。在開始之前,您需要:- 具有建立上述資源權限的 AWS 帳戶
- 已安裝並驗證的 AWS CLI v2,以及在本地安裝的 Docker
- 一個VPC,至少有兩個私有子網在不同的可用區中,透過NAT 閘道具有出站網際網路存取;內部負載平衡器需要兩個 AZ 中的子網,gateway 需要到 Bedrock 和您的 IdP 的出站流量
- 一個 Okta OIDC Web 應用程式,重新導向 URI 為
https://<gateway-host>/oauth/callback;請參閱身份提供者設定 - gateway 的 TLS 主機名稱,通常是Route 53 私有託管區域中的內部 DNS 名稱,指向負載平衡器,具有該名稱的 ACM 憑證,由AWS Private CA匯入或簽發
設定您的環境變數
此頁面上的每個命令都從您的 shell 讀取四個值:AWS_REGION、ACCOUNT_ID、VPC_ID 和 PRIVATE_SUBNETS。
選擇一個 Bedrock 提供您需要的 Claude 模型的美國區域。此逐步解說依賴 gateway 的內建模型目錄,該目錄解析為 us.anthropic.* 推論設定檔,IAM 原則授予這些 ARN。在非美國區域中,新增一個models: 區塊,其中包含該地理位置的推論設定檔 ID,並將 IAM 原則的 ARN 前綴更改為相符。
如果您手邊沒有 VPC ID,請使用 aws ec2 describe-vpcs 列出您的 VPC,然後列出該 VPC 的子網以找到兩個不同可用區中的私有子網:
部署 gateway
下面的步驟使用aws 命令佈建完整部署。
1
建立安全群組
三個安全群組鏈接流量路徑:您的公司網路在 443 上到達負載平衡器,負載平衡器在 8080 上到達 gateway,gateway 在 5432 上到達 Postgres。沒有其他任何東西是可到達的。您如何附加它們取決於計算軌道:
- 在 ECS Fargate 上,部署步驟將
$ALB_SG附加到負載平衡器,將$GW_SG附加到服務。 - 在 EKS 上,AWS Load Balancer Controller 為 ALB 建立自己的前端安全群組,因此
$ALB_SG和$GW_SG未使用:部署步驟的inbound-cidrs註釋將監聽器限制為您的公司網路,資料庫安全群組允許叢集的安全群組而不是$GW_SG。
2
建立 IAM 角色並提交使用案例表單
gateway 使用專用任務角色執行,其唯一權限是在 Bedrock 上叫用 Claude 模型。根據 Bedrock 上游參考,原則必須涵蓋跨區域推論設定檔 ARN 和基礎基礎模型 ARN:ECS 也需要執行角色,ECS 代理本身使用它從 ECR 提取映像並注入稍後建立的 Secrets Manager 值。它與 gateway 的 AWS SDK 在執行時使用的任務角色分開:原則按名稱一個 ARN 而不是裸
gateway-* 萬用字元,在共享帳戶中也會符合不相關的機密;尾部的 -?????? 完全符合 Secrets Manager 附加到每個機密 ARN 的隨機六字元後綴。尾部的 -* 將是純前綴 glob,也會符合更長的名稱,例如 gateway-postgres-url-prod。IAM 原則授予 gateway 呼叫 Bedrock 的權限,Bedrock 在商業區域中預設啟用模型存取。剩餘的帳戶級別閘道是 Anthropic 的一次性使用案例表單:如果您帳戶中沒有人提交過,請開啟 Amazon Bedrock 主控台,從模型目錄中選擇 Anthropic 模型,並完成表單。提交後立即授予存取權;有關 AWS Organizations 表單和提交者需要的 IAM 權限,請參閱 Claude Code on Amazon Bedrock。EKS 軌道改為在 IRSA 角色上重複使用兩個原則文件,而不是兩個 ECS 角色;請參閱部署步驟。3
佈建 Amazon RDS for PostgreSQL
實例在私有子網中執行,沒有公開地址,儲存加密已開啟。引擎版本固定為 Postgres 16,滿足 gateway 支援的 PostgreSQL 14 下限,並保證下面的參數群組系列與實例相符。首先,建立將資料庫放在私有子網中的子網群組,以及具有 然後使用生成的主密碼建立實例:字面
rds.force_ssl=1 的參數群組,以便伺服器拒絕純文字連接。引擎版本固定一次,因為參數群組的系列必須與實例執行的引擎主要版本相符:--master-user-password 引數在命令執行時在程序表和稽核/EDR 日誌中可見,與機密步驟的註釋涵蓋的相同曝露。在共享或受監控的主機上,改為從 0600 檔案透過 --cli-input-json 傳遞密碼,就像套件的 setup.sh 所做的那樣。等待實例啟動,這可能需要幾分鐘,然後讀取其私有端點並組合 gateway 將使用的連接字串:sslmode=verify-full 使 gateway 驗證 RDS 伺服器憑證的鏈和主機名稱,不僅加密。信任錨是 AWS RDS 憑證套件,映像建置步驟下面將其複製到 /etc/claude/rds-global-bundle.pem 並透過 NODE_EXTRA_CA_CERTS 信任。不要將 libpq 風格的 sslrootcert= 參數附加到 URL:gateway 的驅動程式只從查詢字串讀取 sslmode,並會將 sslrootcert 轉發給 Postgres 作為啟動參數,伺服器會拒絕。ECS 服務或 EKS pod 必須在此 VPC 中執行,以便它們可以到達實例的私有端點,claude-gateway-db 安全群組只允許 gateway 的安全群組。4
寫入 gateway.yaml
upstreams 區塊使用 auth: {} 指向 Bedrock,因此 gateway 透過 ECS 上的任務角色或 EKS 上的 IRSA 角色從 AWS 預設認證鏈進行驗證。有關每個欄位,請參閱設定參考。兩個 listen 欄位取決於什麼位於 gateway 前面:public_url:在負載平衡器後面時必需。gateway 僅從此值建置 IdPredirect_uri和其發現文件,絕不從X-Forwarded-*標頭建置。trusted_proxies:前端的來源範圍。gateway 僅當 TCP 對等體在此清單中時才接受X-Forwarded-For,然後在受信任的躍點之後遍歷鏈,因此每 IP 登入速率限制和稽核事件記錄開發人員 IP 而不是負載平衡器的。
trusted_proxies 設定為這些子網的 CIDR。這信任這些子網中的每個主機作為代理。保持 ALB 的入站來源(您的公司 CIDR)不與它們重疊,並且不要與可能透過 X-Forwarded-For 欺騙客戶端 IP 的不受信任的工作負載共享子網。gateway.yaml
只有
oidc 區塊是 Okta 特定的。若要改為使用 Microsoft Entra ID,請將 issuer 設定為 https://login.microsoftonline.com/<tenant-id>/v2.0,刪除 userinfo_fallback 和 groups 範圍,並注意 Entra 發出群組物件 ID 而不是名稱,因此 managed.policies 必須符合 GUID,或使用 oidc.groups_claim: roles 的應用程式角色。請參閱身份提供者設定。5
在 AWS Secrets Manager 中儲存機密
建立三個機密;IAM 步驟中的執行角色已經可以讀取它們:注意每個呼叫列印的 ARN;ECS 任務定義按 ARN 參考機密。與機密不同,
字面
--secret-string 引數在每個命令執行時在程序表和稽核/EDR 日誌中可見。在共享或受監控的主機上,將值放在 0600 檔案中,改為傳遞 --secret-string file://<path>。套件的 setup.sh 以相同方式將機密值保持在程序 argv 之外,將 0600 臨時檔案傳遞給 --cli-input-json。gateway.yaml 本身不包含機密值,因為每個認證在啟動時透過 ${VAR} 或 ${file:...} 擴展解析。一切如何到達容器因軌道而異:- 在 ECS 上,下一步的建置將
gateway.yaml複製到映像中的/etc/claude/gateway.yaml,任務定義透過其secrets欄位將三個機密注入為環境變數,因此 YAML 參考${GATEWAY_JWT_SECRET}、${OIDC_CLIENT_SECRET}和${GATEWAY_POSTGRES_URL}。 - 在 EKS 上,從 ConfigMap 掛載
gateway.yaml和機密作為/secrets中的檔案,參考為${file:/secrets/...}。使用 External Secrets Operator 或 Secrets Store CSI 驅動程式的 AWS 提供者從 Secrets Manager 來源 Kubernetes Secrets,或使用kubectl直接建立它們。
6
建置映像並推送到 Amazon ECR
根據容器映像需求建置映像,將 容器映像需求不涵蓋套件,因此如果您編寫自己的 Dockerfile,新增複製和信任它的兩行;套件的 建立 ECR 儲存庫並將 Docker 登入到它。不可變標籤意味著部署步驟固定的 建置並推送映像。下面的任務定義執行
linux-x64 glibc 二進位檔案放在建置上下文中的 ./claude。編寫您自己的 Dockerfile 根據這些需求或從套件的 Dockerfile 開始,它將填充的 gateway.yaml 從前面的步驟複製到映像中的 /etc/claude/gateway.yaml。在 ECS 上,該嵌入副本是設定到達容器的方式,這就是為什麼建置在檔案寫入後進行。EKS 軌道改為在部署時從 ConfigMap 掛載 gateway.yaml,因此嵌入副本在那裡未使用。映像也攜帶 AWS RDS 憑證套件作為連接字串的 sslmode=verify-full 的信任錨,因此首先將其下載到建置上下文中。AWS 輪換套件(新的區域 CA 被附加),因此每次建置時下載它,而不是固定校驗和或提交它:Dockerfile 已經包含兩者:<version> 標籤之後無法無聲地重新指向不同的映像:linux/amd64,因此平台必須在此處相符;對於 Fargate on ARM64 (Graviton),使用 linux-arm64 二進位檔案建置 linux/arm64 並改為將 cpuArchitecture 設定為 ARM64:7
部署
- ECS Fargate
- EKS
建立叢集和 gateway 的日誌群組,用於其 stderr,其中包含其稽核事件和操作日誌。保留是單獨的呼叫,沒有一個 CloudWatch 會永遠保留日誌;將 90 天與您的稽核保留原則對齊:寫入任務定義。任務角色攜帶 Bedrock 權限,執行角色注入機密;使用 Secrets Manager 步驟中的機密 ARN:註冊它:在前面放置內部 ALB,具有對 gateway 進行健康檢查的目標群組。新增 HTTPS 監聽器並提高空閒逾時。建立服務。部署斷路器將其任務持續失敗的部署(來自不良映像或無法啟動的設定)回滾到最後穩定狀態,而不是永遠重新啟動失敗的任務:60 秒的寬限期給冷任務時間拉取映像、連接到儲存並在 ECS 開始計算針對部署的失敗之前回答其第一個健康檢查。目標群組在
claude-gateway-task.json
--ip-address-type ipv4 很重要:內部雙堆疊 ALB 發佈公開範圍 AAAA 記錄,/login 私有網路檢查拒絕:--ssl-policy 固定現代 TLS 下限,因為省略它會回到舊版 ELBSecurityPolicy-2016-08 預設值,仍然接受 TLS 1.0/1.1。空閒逾時對串流很重要:ALB 預設在 60 秒後沒有資料的連接關閉,這會在安靜期間(例如第一個權杖之前的長提示處理)切斷串流:GET /readyz 上的健康檢查驗證儲存是否可到達,因此無法到達 Postgres 的任務永遠不會進入輪換;有關權衡和 /healthz 替代方案,請參閱中斷行為。任務在沒有公開 IP 的私有子網中執行,因此所有出站流量(到 Bedrock、您的 IdP、Secrets Manager、ECR 和 CloudWatch Logs)都透過 NAT 閘道。為了保持 Bedrock 流量不走公開路徑,建立 bedrock-runtime 介面 VPC 端點並將上游的 base_url 指向它,如 Bedrock 上游參考所示;IdP 仍然需要網際網路出站。完成方式是給開發人員一個私有可解析的主機名稱:在 Route 53 私有託管區域中,將 gateway 的內部 DNS 名稱別名到 ALB,並將 listen.public_url 設定為該主機名稱。ALB 自己的 *.elb.amazonaws.com 名稱解析為內部 ALB 上的私有地址,但它無法攜帶您的 ACM 憑證,因此使用您自己的名稱。在第一次登入之前,將 OAuth 客戶端的授權重新導向 URI 更新為 <public_url>/oauth/callback。更改 public_url 後,在新標籤下重建並推送映像,註冊新任務定義修訂版本,然後重新部署。在 ECS 上,設定位於映像的嵌入 gateway.yaml 中,gateway 僅從該設定建置其公開來源,忽略 X-Forwarded-Host 和 X-Forwarded-Proto。X-Forwarded-For 僅在設定 listen.trusted_proxies 時才被接受用於客戶端 IP。8
將 gateway URL 推送到開發人員機器
gateway 現在正在執行,但開發人員無法從
/login 到達它,直到 gateway URL 在他們的機器上。在受管設定檔中設定 forceLoginMethod 和 forceLoginGatewayUrl,您透過 MDM 部署到每個裝置。登入選擇器中沒有 gateway 選項供開發人員手動選擇。Terraform 參考
examples/gateway/aws 中的配套套件將此頁面打包為程式碼:
setup.sh使用相同的aws命令在 ECS Fargate 軌道上編寫佈建逐步解說。它是冪等的:現有資源被檢測並跳過,因此重新執行它是安全的,任何預設值都可以透過環境變數覆蓋。您仍然自己建立 Okta OIDC 客戶端機密和 ACM 憑證:沒有它們的執行會跳過 ECS/ALB 部署,命名缺失的輸入,並列印create-secret命令;建立兩者並重新執行。Bedrock 使用案例表單和 Route 53 別名列印為下一步而不是自動執行,客戶端 MDM 推送保持此頁面的手動步驟。gateway.yaml.example是 gateway.yaml 步驟中的設定範本,包含可選金鑰註釋掉。將其複製到gateway.yaml並在建置前替換每個REPLACE_ME。Dockerfile從預建的linux-x64二進位檔案建置執行時映像,並將您填充的gateway.yaml複製到/etc/claude/gateway.yaml,加上錨定儲存的sslmode=verify-full的 AWS RDS 憑證套件。setup.sh僅在建置上下文中尚不存在時下載套件;刪除檔案並在新標籤下重建以拾取 AWS CA 輪換。設定檔不包含機密值,因為每個認證在啟動時透過${VAR}擴展解析。因此,設定編輯意味著在新標籤下重建;setup.sh透過使用檔案的雜湊標記映像來自動化此操作。terraform/聲明性地佈建相同的 ECS Fargate 範圍:安全群組、IAM 角色、ECR 儲存庫、RDS 實例、Secrets Manager 機密和內部 ALB 後面的 ECS 服務。VPC 和私有子網保持先決條件,作為變數傳入。Terraform 建立 ECR 儲存庫但不建置映像,服務定義參考映像,因此應用是兩個通過:儲存庫的目標應用,然後建置和推送,然後完整應用。套件的terraform/README.md涵蓋變數、遠端狀態和拆除。
故障排除
如需 gateway 啟動和登入錯誤,請參閱平台無關的故障排除表。下面的項目特定於 AWS。遙測
gateway 為您提供每個開發人員的使用指標,無需任何每台機器的 OTEL 設定。Claude Code 發出 OpenTelemetry (OTLP) 指標、日誌和選擇加入的追蹤;監控使用涵蓋 CLI 報告的所有內容。在 gateway 工作階段上,CLI 使用已驗證的 IdP 身份屬性user.id、user.email 和 user.groups 標記每個匯出,因此使用按開發人員匯總,無需 OTEL_RESOURCE_ATTRIBUTES 配管。
gateway 本身是經過驗證的 OTLP 中繼。將 telemetry.forward_to 與 listen.public_url 一起設定,它將 OTEL 匯出器設定推送到每個連接的客戶端,並將其 OTLP 流量逐字轉發到您列出的每個目的地。每個目的地獨立選擇加入指標、日誌和追蹤,預設為僅指標;有關每個信號欄位及其敏感性權衡,請參閱 telemetry 參考。gateway 不緩衝、聚合或儲存遙測,因此資料落在何處完全是收集器的匯出器設定。
客戶端遙測預設關閉;設定 telemetry.forward_to 是為連接的開發人員開啟它的方式,每個互動式客戶端為推送的設定顯示一次性安全批准對話,如設定參考所述。在 AWS 上,每個信號對應到目的地如下。
客戶端指標、日誌和追蹤
將telemetry.forward_to 指向 OpenTelemetry 收集器,例如 AWS Distro for OpenTelemetry (ADOT) 收集器,並從那裡匯出到 Amazon CloudWatch、Amazon Managed Service for Prometheus 或任何 OTLP 後端。
將收集器作為其自己的內部服務執行,可透過 https:// 到達:gateway 僅接受純文字 http:// 用於環回 URL,即使這樣其SSRF 防護預設在傳送時阻止環回連接。http://localhost:4318 上的邊車收集器通過設定驗證但接收沒有流量,匯出失敗為 gateway 日誌中的 ECONNREFUSED_SSRF,除非在 gateway 的環境中設定 CLAUDE_GATEWAY_ALLOW_LOOPBACK=1。該變數放寬每個操作員設定的 URL 的環回塊,不僅遙測,因此偏好內部服務模式並為網路以其他方式鎖定的任務保留邊車加旗標設定。
Gateway 日誌
在 ECS Fargate 上,無需額外設定:awslogs 驅動程式將 gateway 的 stderr(其中包含其稽核事件和操作日誌)傳遞到上面建立的 /ecs/claude-gateway 日誌群組。在 EKS 上,pod 日誌預設不到達 CloudWatch,因此稽核軌跡丟失,直到您安裝日誌收集:啟用容器日誌擷取的 Amazon CloudWatch Observability 附加元件,或 Fluent Bit DaemonSet。在任一軌道上,使用 CloudWatch Logs Insights 查詢日誌並從指標篩選器驅動警報。
容器指標
使用aws ecs update-cluster-settings --cluster claude-gateway --settings name=containerInsights,value=enabled 在叢集上啟用 Container Insights,用於每個任務的 CPU、記憶體和網路。在 EKS 上,安裝 Amazon CloudWatch Observability 附加元件。
支出
遙測在事後顯示使用;支出限制是 gateway 在共享上游認證之上的即時每個開發人員檢視和執行。後續步驟
- 設定參考:每個
gateway.yaml選項,包括managed.policies和telemetry - 部署和操作:IdP 設定、健康檢查、JWT 機密輪換、升級和安全模型
- Claude apps gateway 概述:快速入門和連接開發人員
- Claude apps gateway 的 AWS 範例:AWS 維護的部署範例,涵蓋一系列客戶環境