このページは、AWS で Claude apps gateway を実行する 1 つの方法を説明しています。この設定は、サポートされている本番環境デプロイメントではなく、カスタマー管理インフラストラクチャの実装例です。各部分がどのように組み合わさるかを確認してから、自分の環境に適応させてください。プラットフォーム非依存の要件については、デプロイメントガイドを参照してください。
Bedrock は AWS 上の唯一の Claude アップストリームではありません。ゲートウェイは、Bedrock の代わりに、または Bedrock と並行して、AWS 認証と AWS Marketplace 課金を備えた Anthropic 運営の Claude API である Claude Platform on AWS もサポートしています。そのアップストリームエントリ、認証情報、および IAM 権限は、このページの Bedrock スコープのものとは異なります。Claude Platform on AWS アップストリームリファレンスは何が変わるかをカバーしており、このページの残りは変わらずに適用されます。
アーキテクチャ
例のアーキテクチャ。Amazon Bedrock をモデルアップストリームとして使用しています。Claude Platform on AWS アップストリームは同じ位置を占めます。
- Amazon ECS on AWS Fargate サービスまたは Amazon EKS デプロイメント(ゲートウェイコンテナを実行)
- Amazon ECR リポジトリ(ゲートウェイイメージ用)
- Amazon RDS for PostgreSQL インスタンス(プライベートサブネット内、公開アクセス不可、ゲートウェイのストア用)
- AWS Secrets Manager シークレット(JWT 署名キー、OIDC クライアントシークレット、Postgres URL 用)
- IAM ロール(
bedrock:InvokeModel、bedrock:InvokeModelWithResponseStream、bedrock:CountTokens権限付き、ECS タスクロールとしてアタッチされるか、EKS 上の IAM Roles for Service Accounts(IRSA)経由でバインドされる) - 内部アプリケーションロードバランサー(HTTPS 用)
前提条件
このウォークスルーではゲートウェイ独自のリソースを作成しますが、既に存在するネットワークおよびアイデンティティインフラストラクチャの上に構築されます。開始する前に、以下が必要です。- 上記のリソースを作成する権限を持つ AWS アカウント
- AWS CLI v2 がインストールされ認証済みであること、および Docker がローカルにインストールされていること
- 異なるアベイラビリティゾーンに少なくとも 2 つのプライベートサブネットを持つ VPC。NAT ゲートウェイを通じたアウトバウンドインターネットアクセスがあること。内部ロードバランサーは 2 つの AZ のサブネットが必要であり、ゲートウェイは Bedrock および IdP へのエグレスが必要です
- リダイレクト URI が
https://<gateway-host>/oauth/callbackの Okta OIDC ウェブアプリケーション。ID プロバイダーのセットアップを参照してください - ゲートウェイ用の TLS ホスト名。通常は Route 53 プライベートホストゾーン内の内部 DNS 名でロードバランサーを指し、そのホスト名用の ACM 証明書があり、AWS Private CAによってインポートまたは発行されていること
環境変数を設定する
このページのすべてのコマンドはシェルから 4 つの値を読み込みます。AWS_REGION、ACCOUNT_ID、VPC_ID、および PRIVATE_SUBNETS です。
必要な Claude モデルを Bedrock が提供する US リージョンを選択してください。このウォークスルーはゲートウェイの組み込みモデルカタログに依存しており、これは us.anthropic.* 推論プロファイルに解決され、IAM ポリシーはそれらの ARN を許可します。US 以外のリージョンでは、そのジオの推論プロファイル ID を含む models: ブロックを追加し、IAM ポリシーの ARN プレフィックスを変更して一致させてください。
VPC ID が手元にない場合は、aws ec2 describe-vpcs で VPC をリストアップし、その VPC のサブネットをリストアップして、異なるアベイラビリティゾーンにある 2 つのプライベートサブネットを見つけてください。
ゲートウェイをデプロイする
以下の手順は、aws コマンドを使用して完全なデプロイをプロビジョニングします。
1
セキュリティグループを作成する
3 つのセキュリティグループがトラフィックパスをチェーンします。企業ネットワークはロードバランサーに 443 で到達し、ロードバランサーはゲートウェイに 8080 で到達し、ゲートウェイは Postgres に 5432 で到達します。それ以外は到達不可能です。それらをアタッチする方法は、コンピュートトラックによって異なります。
- ECS Fargate では、デプロイステップが
$ALB_SGをロードバランサーにアタッチし、$GW_SGをサービスにアタッチします。 - EKS では、AWS Load Balancer Controller が ALB 用に独自のフロントエンドセキュリティグループを作成するため、
$ALB_SGと$GW_SGは使用されません。デプロイステップのinbound-cidrsアノテーションがリスナーを企業ネットワークに制限し、データベースセキュリティグループはクラスタのセキュリティグループを$GW_SGの代わりに許可します。
2
IAM ロールを作成して使用例フォームを送信する
ゲートウェイは、Bedrock で Claude モデルを呼び出す唯一の権限を持つ専用タスクロールで実行されます。Bedrock アップストリームリファレンスに従い、ポリシーはクロスリージョン推論プロファイル ARN と基盤となるファウンデーションモデル ARN の両方をカバーする必要があります。ECS には実行ロールも必要です。これは ECS エージェント自体が ECR からイメージをプルし、後で作成される Secrets Manager 値を注入するために使用します。これはゲートウェイの AWS SDK が実行時に使用するタスクロールとは別です。ポリシーは、ベアの
gateway-* ワイルドカードではなく、シークレットごとに 1 つの ARN を指定します。共有アカウントでは、ベアのワイルドカードは無関係なシークレットにも一致します。末尾の -?????? は、Secrets Manager がすべてのシークレットの ARN に追加する 6 文字のランダムサフィックスと正確に一致します。末尾の -* はプレーンプレフィックスグロブであり、gateway-postgres-url-prod などのより長い名前にも一致します。IAM ポリシーはゲートウェイに Bedrock を呼び出す権限を付与し、Bedrock は商用リージョンでデフォルトでモデルアクセスを有効にします。残りのアカウントレベルのゲートは Anthropic の 1 回限りの使用例フォームです。アカウント内の誰もそれを送信していない場合は、Amazon Bedrock コンソールを開き、モデルカタログから Anthropic モデルを選択して、フォームを完成させます。アクセスは送信直後に付与されます。Claude Code on Amazon Bedrockで AWS Organizations フォームと送信者が必要な IAM 権限を参照してください。EKS トラックは、2 つの ECS ロールの代わりに IRSA ロール上で両方のポリシードキュメントを再利用します。デプロイステップを参照してください。3
Amazon RDS for PostgreSQL をプロビジョニングする
インスタンスはプライベートサブネットで実行され、パブリックアドレスがなく、ストレージ暗号化がオンです。エンジンバージョンは Postgres 16 に固定されており、ゲートウェイがサポートする PostgreSQL 14 の下限を満たし、以下のパラメータグループファミリーがインスタンスが実行するエンジンと一致することを保証します。まず、プライベートサブネットにデータベースを配置するサブネットグループと、次に、生成されたマスターパスワードでインスタンスを作成します。リテラル
rds.force_ssl=1 を使用してサーバーがプレーンテキスト接続を拒否するパラメータグループを作成します。エンジンバージョンは 1 回固定されます。パラメータグループのファミリーはインスタンスが実行するエンジンのメジャーバージョンと一致する必要があるためです。--master-user-password 引数は、コマンド実行中のプロセステーブルおよび監査/EDR ログに表示されます。これは、シークレットステップのメモがカバーする同じ露出です。共有またはモニタリングされたホストでは、代わりに 0600 ファイルを介して --cli-input-json でパスワードを渡してください。バンドルの setup.sh は、0600 一時ファイルを --cli-input-json に渡すことで、同じ方法でシークレット値をプロセス argv から保ちます。インスタンスが起動するのを待ちます。これには数分かかる場合があります。その後、プライベートエンドポイントを読み取り、ゲートウェイが使用する接続文字列を組み立てます。sslmode=verify-full は、ゲートウェイが RDS サーバー証明書のチェーンとホスト名を検証し、暗号化するだけでなく検証することを確認します。トラストアンカーは AWS RDS 証明書バンドルです。これは、以下のイメージビルドステップで /etc/claude/rds-global-bundle.pem にコピーされ、NODE_EXTRA_CA_CERTS を介して信頼されます。libpq スタイルの sslrootcert= パラメータを URL に追加しないでください。ゲートウェイのドライバーはクエリ文字列から sslmode のみを読み取り、sslrootcert を Postgres スタートアップパラメータとして転送します。サーバーはこれを拒否します。ECS サービスまたは EKS ポッドはこの VPC で実行され、インスタンスのプライベートエンドポイントに到達でき、claude-gateway-db セキュリティグループはゲートウェイのセキュリティグループのみを許可します。4
gateway.yaml を書き込む
upstreams ブロックは auth: {} で Bedrock を指します。ゲートウェイは ECS のタスクロールまたは EKS の IRSA ロールから AWS デフォルト認証情報チェーンを介して認証します。すべてのフィールドについては、設定リファレンスを参照してください。2 つの listen フィールドは、ゲートウェイの前にあるものに依存します。public_url:外部https://オリジン。ロードバランサーの背後で必須です。listenリファレンスを参照してください。ゲートウェイは IdPredirect_uriと検出ドキュメントをこの値からのみ構築し、X-Forwarded-*ヘッダーからは構築しません。trusted_proxies:フロントエンドのソース範囲。ゲートウェイは TCP ピアがこのリストにある場合にのみX-Forwarded-Forを尊重し、信頼できるホップを過ぎてチェーンをウォークします。IP ごとのサインイン率制限と監査イベントは、ロードバランサーの代わりに開発者 IP を記録します。
trusted_proxies をそれらのサブネットの CIDR に設定します。これはそれらのサブネット内のすべてのホストをプロキシとして信頼します。ALB のイングレスソース(企業 CIDR)がそれらと重複しないようにし、X-Forwarded-For を介してクライアント IP をスプーフできる信頼できないワークロードとサブネットを共有しないでください。ALB のクライアントポート保存属性 routing.http.xff_client_port.enabled は、どちらの設定でも保つことができます。オンの場合、ALB はクライアントを 203.0.113.7:54321 または [2001:db8::1]:54321 として書き込み、ゲートウェイはポートをドロップして両方を読み取ります。gateway.yaml
oidc ブロックのみが Okta 固有です。Microsoft Entra ID を代わりに使用するには、issuer を https://login.microsoftonline.com/<tenant-id>/v2.0 に設定し、userinfo_fallback と groups スコープをドロップし、Entra がグループ名ではなくグループ Object ID を発行することに注意してください。managed.policiesは GUID で一致するか、oidc.groups_claim: roles を使用した App Roles で一致する必要があります。ID プロバイダーセットアップを参照してください。5
AWS Secrets Manager にシークレットを保存する
3 つのシークレットを作成します。IAM ステップからの実行ロールはすでにそれらを読み取ることができます。各呼び出しが出力する ARN に注意してください。ECS タスク定義は ARN でシークレットを参照します。シークレットとは異なり、
リテラル
--secret-string 引数は、各コマンド実行中のプロセステーブルおよび監査/EDR ログに表示されます。共有またはモニタリングされたホストでは、値を 0600 ファイルに入れ、代わりに --secret-string file://<path> を渡してください。バンドルの setup.sh は、0600 一時ファイルを --cli-input-json に渡すことで、同じ方法でシークレット値をプロセス argv から保ちます。gateway.yaml 自体にはシークレット値が含まれていません。すべての認証情報は ${VAR} または ${file:...} 展開を通じてブート時に解決されるためです。すべてがコンテナに到達する方法はトラックによって異なります。- ECS では、次のステップのビルドが
gateway.yamlをイメージにコピーして/etc/claude/gateway.yamlに配置し、タスク定義は 3 つのシークレットを環境変数としてsecretsフィールドを介して注入するため、YAML は${GATEWAY_JWT_SECRET}、${OIDC_CLIENT_SECRET}、および${GATEWAY_POSTGRES_URL}を参照します。 - EKS では、
gateway.yamlを ConfigMap からマウントし、シークレットを/secretsのファイルとしてマウントし、${file:/secrets/...}として参照します。Kubernetes Secrets を External Secrets Operator または Secrets Store CSI ドライバーの AWS プロバイダーで Secrets Manager からソースするか、kubectlで直接作成します。
6
イメージを構築して Amazon ECR にプッシュする
コンテナイメージ要件に従ってイメージを構築し、コンテナイメージ要件はバンドルをカバーしていないため、独自の Dockerfile を作成する場合は、それをコピーして信頼する 2 行を追加してください。バンドルの ECR リポジトリを作成し、Docker をそれにサインインします。イミュータブルタグは、デプロイステップがピンする イメージを構築してプッシュします。以下のタスク定義は
linux-x64 glibc バイナリをビルドコンテキストの ./claude に配置します。これらの要件に従って独自の Dockerfile を作成するか、バンドルの Dockerfileから始めます。これは、前のステップから入力された gateway.yaml をイメージにコピーして /etc/claude/gateway.yaml に配置します。ECS では、その埋め込みコピーは設定がコンテナに到達する方法です。これが、ファイルが書き込まれた後にビルドが行われる理由です。EKS トラックは代わりにデプロイ時に ConfigMap から gateway.yaml をマウントするため、埋め込みコピーはそこで使用されません。イメージは、接続文字列の sslmode=verify-full のトラストアンカーとして AWS RDS 証明書バンドルも搭載しているため、最初にビルドコンテキストにダウンロードします。AWS はバンドルをローテーションします(新しい地域の CA が追加されます)。ため、チェックサムをピンするか、コミットするのではなく、ビルドごとにダウンロードします。Dockerfile にはすでに両方が含まれています。<version> タグが後で別のイメージに静かに再ポイントされることはできないことを意味します。linux/amd64 を実行するため、プラットフォームはここで一致する必要があります。Fargate on ARM64(Graviton)の場合は、linux-arm64 バイナリで linux/arm64 を構築し、代わりに cpuArchitecture を ARM64 に設定します。7
デプロイ
- ECS Fargate
- EKS
クラスターと、ゲートウェイの stderr 用のロググループを作成します。stderr は監査イベントと運用ログの両方を搭載しています。保持は別の呼び出しであり、保持がない場合、CloudWatch はログを永遠に保ちます。90 日を監査保持ポリシーと調整します。タスク定義を書き込みます。タスクロールは Bedrock 権限を搭載し、実行ロールはシークレットを注入します。Secrets Manager ステップからシークレット ARN を使用します。それを登録します。ゲートウェイをヘルスチェックするターゲットグループを持つ内部 ALB を前に配置します。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 プライベートホストゾーンで、ゲートウェイの内部 DNS 名を ALB にエイリアスし、listen.public_url をそのホスト名に設定します。ALB 自体の *.elb.amazonaws.com 名は内部 ALB のプライベートアドレスに解決されますが、ACM 証明書を搭載できないため、独自の名前を使用します。最初のサインイン前に OAuth クライアントの認可リダイレクト URI を <public_url>/oauth/callback に更新します。public_url を変更した後、新しいタグの下でイメージを再構築してプッシュし、新しいタスク定義リビジョンを登録し、再デプロイします。ECS では、設定はイメージの埋め込み gateway.yaml に存在し、ゲートウェイはその設定からのみパブリックオリジンを構築し、X-Forwarded-Host と X-Forwarded-Proto を無視します。X-Forwarded-For は、listen.trusted_proxies が設定されている場合にのみクライアント IP に対して尊重されます。8
ゲートウェイ URL を開発者マシンにプッシュする
ゲートウェイは実行されていますが、開発者は
/login からそれに到達できません。ゲートウェイ URL がマシンに存在するまで。MDM を介して各デバイスにデプロイするマネージド設定ファイルで forceLoginMethod と forceLoginGatewayUrl を設定します。ログインピッカーにはゲートウェイオプションがなく、開発者が手動で選択することはできません。Terraform リファレンス
examples/gateway/aws の付属バンドルは、このページをコードとしてパッケージ化しています。
setup.shは、上記のプロビジョニング手順を ECS Fargate トラックで同じawsコマンドでスクリプト化しています。べき等性があります。既存のリソースは検出されてスキップされるため、再実行しても安全です。また、デフォルト値は環境変数で上書きできます。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 リポジトリを作成しますがイメージはビルドしません。サービス定義はイメージを参照するため、apply は 2 パスです。リポジトリの対象 apply、その後ビルドとプッシュ、その後フル apply です。バンドルのterraform/README.mdは変数、リモート状態、およびティアダウンについて説明しています。
トラブルシューティング
ゲートウェイのブートおよびログインエラーについては、プラットフォーム非依存のトラブルシューティングテーブルを参照してください。以下のエントリは AWS に固有です。テレメトリ
ゲートウェイは、マシンごとの OTEL 設定なしで開発者ごとの使用メトリクスを提供します。Claude Code は OpenTelemetry(OTLP)メトリクス、ログ、およびオプトインのトレースを発行します。使用状況の監視は CLI が報告するすべてをカバーしています。ゲートウェイセッションでは、CLI は各エクスポートに認証された IdP ID 属性user.id、user.email、および user.groups でスタンプを付けるため、使用状況は OTEL_RESOURCE_ATTRIBUTES 配管なしで開発者ごとにロールアップされます。
ゲートウェイ自体は認証された OTLP リレーです。telemetry.forward_to を listen.public_url と一緒に設定し、OTEL エクスポーター設定をすべての接続されたクライアントにプッシュし、OTLP トラフィックを逐語的にリストするすべての宛先に転送します。各宛先はメトリクス、ログ、およびトレースを独立して選択し、デフォルトはメトリクスのみです。telemetry リファレンスを参照してください。シグナルごとのフィールドとそれらの感度トレードオフについて。ゲートウェイはバッファ、集約、またはテレメトリを保存しないため、データが到達する場所は完全にコレクターのエクスポーター設定です。
クライアントテレメトリはデフォルトでオフです。telemetry.forward_to を設定することは、接続された開発者のためにそれをオンにするものです。各インタラクティブクライアントは、設定リファレンスで説明されているように、プッシュされた設定の 1 回限りのセキュリティ承認ダイアログを表示します。AWS では、各シグナルは次のように宛先にマップされます。
クライアントメトリクス、ログ、およびトレース
telemetry.forward_to を OpenTelemetry コレクター(AWS Distro for OpenTelemetry(ADOT)コレクターなど)に指し、Amazon CloudWatch、Amazon Managed Service for Prometheus、または任意の OTLP バックエンドにエクスポートします。
https:// 経由で到達可能な独自の内部サービスとしてコレクターを実行します。ゲートウェイはループバック URL に対してのみプレーンテキスト http:// を受け入れ、その場合でも SSRF ガードはデフォルトで送信時にループバック接続をブロックします。http://localhost:4318 のサイドカーコレクターは設定検証を渡しますが、トラフィックを受け取りません。エクスポートは ECONNREFUSED_SSRF として失敗します。ゲートウェイログで、CLAUDE_GATEWAY_ALLOW_LOOPBACK=1 がゲートウェイの環境に設定されていない限り。その変数はすべてのオペレーター設定 URL のループバックブロックを緩和し、テレメトリのみではなく、ネットワークが他の方法でロックダウンされているタスクのサイドカープラスフラグセットアップを予約してください。内部サービスパターンを優先します。
ゲートウェイログ
ECS Fargate では、追加のセットアップはありません。awslogs ドライバーはゲートウェイの stderr を配信します。これは監査イベントと運用ログを運びます。/ecs/claude-gateway ロググループに上記で作成されました。EKS では、ポッドログはデフォルトで 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.yamlオプション。managed.policiesとtelemetryを含む - デプロイメントと運用:IdP セットアップ、ヘルスチェック、JWT シークレットローテーション、アップグレード、およびセキュリティモデル
- Claude apps gateway 概要:クイックスタートと開発者の接続
- Claude apps gateway の AWS サンプル:顧客環境の範囲をカバーする AWS 保守デプロイメントサンプル