SpyBara
Go Premium

claude-apps-gateway-on-aws.md 2026-10-06 23:59 UTC to 2026-10-07 05:58 UTC

This page contains 36 additions and 32 deletions.

2026
Wed 7 07:00

AWS に Claude apps gateway をデプロイする

AWS で Claude apps gateway を実行する実装例：ECS Fargate または EKS、Amazon RDS for PostgreSQL、AWS Secrets Manager、および Amazon Bedrock への IAM ロール認証。

この例では、Amazon Bedrock をモデルアップストリームとして使用し、Amazon ECS を AWS Fargate で実行するか、Amazon EKS をコンピュートに使用して、AWS に Claude apps gateway をプロビジョニングします。Okta は例の ID プロバイダー（IdP）ですが、OpenID Connect（OIDC）準拠の任意の IdP が機能します。IdP ごとの詳細については、ID プロバイダーのセットアップを参照してください。

アーキテクチャ

AWS 上の Claude apps gateway の図：Claude Code クライアントは HTTPS 経由でゲートウェイ（ECS Fargate または EKS）の前にある内部アプリケーションロードバランサーに接続し、プライベートサブネット内で Amazon RDS for PostgreSQL インスタンスと並行して実行されます。ゲートウェイは OIDC 経由でユーザーを企業 IdP に対してサインインさせ、AWS Secrets Manager からシークレットを読み取り、IAM ロールを使用してモデルリクエストを Amazon Bedrock に転送し、デプロイ時に Amazon ECR からイメージをプルします。

ゲートウェイは、開発者が IdP を通じてサインインするネットワーク上のプライベート HTTPS エンドポイントとして実行されます。Claude Code セッションは、ゲートウェイの IAM ロールを通じて Amazon Bedrock 上の Claude モデルに到達するため、モデル認証情報は開発者マシンに到達しません。参照設定は以下をプロビジョニングします：

  • 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 用）

前提条件

このウォークスルーではゲートウェイ独自のリソースを作成しますが、既に存在するネットワークおよびアイデンティティインフラストラクチャの上に構築されます。開始する前に、以下が必要です。

環境変数を設定する

このページのすべてのコマンドはシェルから 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 ec2 describe-subnets --filters "Name=vpc-id,Values=<your-vpc-id>" \
  --query 'Subnets[].{ID:SubnetId,AZ:AvailabilityZone,CIDR:CidrBlock}' --output table

続行する前に、4 つすべてをエクスポートしてください。

export AWS_REGION=us-east-1   # a US region where Bedrock serves the Claude models you need
export ACCOUNT_ID="$(aws sts get-caller-identity --query Account --output text)"
export VPC_ID=<your-vpc-id>
export PRIVATE_SUBNETS="<subnet-id-a> <subnet-id-b>"

ゲートウェイをデプロイする

以下の手順は、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 の代わりに許可します。
ALB_SG="$(aws ec2 create-security-group --group-name claude-gateway-alb \
--description "Claude gateway ALB" --vpc-id "$VPC_ID" \
--query GroupId --output text)"
GW_SG="$(aws ec2 create-security-group --group-name claude-gateway-svc \
--description "Claude gateway service" --vpc-id "$VPC_ID" \
--query GroupId --output text)"
DB_SG="$(aws ec2 create-security-group --group-name claude-gateway-db \
--description "Claude gateway Postgres" --vpc-id "$VPC_ID" \
--query GroupId --output text)"

aws ec2 authorize-security-group-ingress --group-id "$ALB_SG" \
--protocol tcp --port 443 --cidr <your-corporate-cidr>
aws ec2 authorize-security-group-ingress --group-id "$GW_SG" \
--protocol tcp --port 8080 --source-group "$ALB_SG"
aws ec2 authorize-security-group-ingress --group-id "$DB_SG" \
--protocol tcp --port 5432 --source-group "$GW_SG"
2

IAM ロールを作成して使用例フォームを送信する

ゲートウェイは、Bedrock で Claude モデルを呼び出す唯一の権限を持つ専用タスクロールで実行されます。Bedrock アップストリームリファレンスに従い、ポリシーはクロスリージョン推論プロファイル ARN と基盤となるファウンデーションモデル ARN の両方をカバーする必要があります。

cat > bedrock-invoke.json <<EOF
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": ["bedrock:InvokeModel", "bedrock:InvokeModelWithResponseStream", "bedrock:CountTokens"],
"Resource": [
"arn:aws:bedrock:${AWS_REGION}:${ACCOUNT_ID}:inference-profile/us.anthropic.*",
"arn:aws:bedrock:*::foundation-model/anthropic.*"
]
}]
}
EOF
cat > ecs-trust.json <<'EOF'
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Principal": { "Service": "ecs-tasks.amazonaws.com" },
"Action": "sts:AssumeRole"
}]
}
EOF

aws iam create-role --role-name claude-gateway-task \
--assume-role-policy-document file://ecs-trust.json
aws iam put-role-policy --role-name claude-gateway-task \
--policy-name bedrock-invoke --policy-document file://bedrock-invoke.json

ECS には実行ロールも必要です。これは ECS エージェント自体が ECR からイメージをプルし、後で作成される Secrets Manager 値を注入するために使用します。これはゲートウェイの AWS SDK が実行時に使用するタスクロールとは別です。

aws iam create-role --role-name claude-gateway-execution \
--assume-role-policy-document file://ecs-trust.json
aws iam attach-role-policy --role-name claude-gateway-execution \
--policy-arn arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy
cat > secrets-read.json <<EOF
{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Action": ["secretsmanager:GetSecretValue", "secretsmanager:DescribeSecret"],
"Resource": [
"arn:aws:secretsmanager:${AWS_REGION}:${ACCOUNT_ID}:secret:gateway-jwt-secret-??????",
"arn:aws:secretsmanager:${AWS_REGION}:${ACCOUNT_ID}:secret:gateway-oidc-client-secret-??????",
"arn:aws:secretsmanager:${AWS_REGION}:${ACCOUNT_ID}:secret:gateway-postgres-url-??????"
]
}]
}
EOF
aws iam put-role-policy --role-name claude-gateway-execution \
--policy-name read-gateway-secrets --policy-document file://secrets-read.json

ポリシーは、ベアの 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 を実行し、パブリックアドレスを持たず、ストレージ暗号化が有効です。

まず、プライベートサブネットにデータベースを配置するサブネットグループと、rds.force_ssl=1 を使用してサーバーがプレーンテキスト接続を拒否するパラメータグループを作成します。エンジンバージョンは 1 回固定されます。パラメータグループのファミリーはインスタンスが実行するエンジンのメジャーバージョンと一致する必要があるためです。

aws rds create-db-subnet-group --db-subnet-group-name claude-gateway-db \
--db-subnet-group-description "Claude gateway" --subnet-ids $PRIVATE_SUBNETS

PG_VERSION=16
PG_FAMILY="postgres${PG_VERSION}"
aws rds create-db-parameter-group --db-parameter-group-name claude-gateway-db \
--db-parameter-group-family "$PG_FAMILY" \
--description "Claude gateway - require TLS on every connection"
aws rds modify-db-parameter-group --db-parameter-group-name claude-gateway-db \
--parameters "ParameterName=rds.force_ssl,ParameterValue=1,ApplyMethod=immediate"

次に、生成されたマスターパスワードでインスタンスを作成します。

PGPASS="$(openssl rand -hex 24)"
aws rds create-db-instance --db-instance-identifier claude-gateway-db \
--engine postgres --engine-version "$PG_VERSION" \
--db-instance-class db.t4g.micro \
--allocated-storage 20 --db-name claude_gateway \
--master-username gateway --master-user-password "$PGPASS" \
--db-subnet-group-name claude-gateway-db \
--db-parameter-group-name claude-gateway-db \
--vpc-security-group-ids "$DB_SG" \
--no-publicly-accessible --storage-encrypted

リテラル --master-user-password 引数は、コマンド実行中のプロセステーブルおよび監査/EDR ログに表示されます。これは、シークレットステップのメモがカバーする同じ露出です。共有またはモニタリングされたホストでは、バンドルの setup.sh と同様に、代わりに 0600 ファイルから --cli-input-json を介してパスワードを渡してください。

インスタンスが起動するのを待ちます。これには数分かかる場合があります。その後、プライベートエンドポイントを読み取り、ゲートウェイが使用する接続文字列を組み立てます。

aws rds wait db-instance-available --db-instance-identifier claude-gateway-db
DB_HOST="$(aws rds describe-db-instances --db-instance-identifier claude-gateway-db \
--query 'DBInstances[0].Endpoint.Address' --output text)"
GATEWAY_POSTGRES_URL="postgres://gateway:${PGPASS}@${DB_HOST}:5432/claude_gateway?sslmode=verify-full"

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 リファレンスを参照してください。ゲートウェイは IdP redirect_uri と検出ドキュメントをこの値からのみ構築し、X-Forwarded-* ヘッダーからは構築しません。
  • trusted_proxies：フロントエンドのソース範囲。ゲートウェイは TCP ピアがこのリストにある場合にのみ X-Forwarded-For を尊重し、信頼できるホップを過ぎてチェーンをウォークします。そのため、IP ごとのサインインレート制限と監査イベントは、ロードバランサーの IP ではなく開発者の IP を記録します。

両方のトラックでフロントエンドは内部 ALB です。直接作成されるか、AWS Load Balancer Controller によって作成されるかは関係ありません。ALB のノードはアタッチされたサブネットからアドレスを取得するため、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 として書き込み、ゲートウェイはポートをドロップして両方を読み取ります。

listen:
host: 0.0.0.0
port: 8080
public_url: https://claude-gateway.internal.example.com
trusted_proxies: [<your-alb-subnet-cidrs>]

oidc:
issuer: https://example.okta.com
client_id: 0oa1example2
client_secret: ${OIDC_CLIENT_SECRET}           # EKS: ${file:/secrets/oidc-client-secret}
allowed_email_domains: [example.com]
# Okta org 認可サーバーは、メールとグループを省略した薄い id_token を返します。
# ゲートウェイは /userinfo からそれらを入力します。
userinfo_fallback: true
# Okta は、`groups` スコープがリクエストされ、アプリのグループクレーム
# フィルターがそれらを許可する場合にのみグループを発行します。
scopes: [openid, profile, email, offline_access, groups]

session:
jwt_secret: ${GATEWAY_JWT_SECRET}              # EKS: ${file:/secrets/jwt-secret}
ttl_hours: 8 # デプロビジョニングレイテンシーを制限します。より厳密な
# 取り消しのために 1 に向かって下げます

store:
postgres_url: ${GATEWAY_POSTGRES_URL}          # EKS: ${file:/secrets/postgres-url}
# readiness_grace_seconds: 300                 # RDS フェイルオーバー中も
# ヘルスチェックを通過し続けます

upstreams:
- provider: bedrock
region: <your-region>                        # IAM ポリシーの ARN がカバーするように
# $AWS_REGION と一致させます
auth: {} # AWS デフォルト認証情報チェーン：
# ECS タスクロール、または EKS の IRSA
5

AWS Secrets Manager にシークレットを保存する

3 つのシークレットを作成します。IAM ステップからの実行ロールはすでにそれらを読み取ることができます。

aws secretsmanager create-secret --name gateway-jwt-secret \
--secret-string "$(openssl rand -base64 32)"
aws secretsmanager create-secret --name gateway-oidc-client-secret \
--secret-string '<your-okta-client-secret>'
aws secretsmanager create-secret --name gateway-postgres-url \
--secret-string "$GATEWAY_POSTGRES_URL"

各呼び出しが出力する ARN に注意してください。ECS タスク定義は ARN でシークレットを参照します。

シークレットとは異なり、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 にプッシュする

コンテナイメージ要件に従ってイメージをビルドし、linux-x64 glibc バイナリをビルドコンテキストの ./claude に配置します。これらの要件に従って独自の Dockerfile を作成するか、バンドルの Dockerfileから始めます。これは、前のステップで記入した gateway.yaml をイメージにコピーして /etc/claude/gateway.yaml に配置します。ECS では、その埋め込みコピーによって設定がコンテナに届きます。これが、ファイルを書き込んだ後にビルドを行う理由です。EKS トラックは代わりにデプロイ時に ConfigMap から gateway.yaml をマウントするため、埋め込みコピーはそこでは使用されません。

イメージは、接続文字列の sslmode=verify-full のトラストアンカーとして AWS RDS 証明書バンドルも搭載しているため、最初にビルドコンテキストにダウンロードします。AWS はバンドルをローテーションする（新しいリージョンの CA が追加される）ため、チェックサムをピンしたりコミットしたりするのではなく、ビルドごとにダウンロードします。

curl -fL --proto '=https' -o rds-global-bundle.pem \
https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem

コンテナイメージ要件はバンドルをカバーしていないため、独自の Dockerfile を作成する場合は、それをコピーして信頼する 2 行を追加してください。バンドルの Dockerfile にはすでに両方が含まれています。

COPY rds-global-bundle.pem /etc/claude/rds-global-bundle.pem
ENV NODE_EXTRA_CA_CERTS=/etc/claude/rds-global-bundle.pem

ECR リポジトリを作成し、Docker をそれにサインインします。イミュータブルタグにより、デプロイステップがピンする <version> タグが後で別のイメージに気付かないうちに再ポイントされることはありません。

aws ecr create-repository --repository-name claude-gateway \
--image-tag-mutability IMMUTABLE \
--image-scanning-configuration scanOnPush=true
aws ecr get-login-password --region "$AWS_REGION" \
| docker login --username AWS --password-stdin \
"${ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com"

イメージをビルドしてプッシュします。以下のタスク定義は linux/amd64 を実行するため、プラットフォームはここで一致する必要があります。Fargate on ARM64（Graviton）の場合は、linux-arm64 バイナリで linux/arm64 をビルドし、代わりに cpuArchitecture を ARM64 に設定します。

docker build --platform=linux/amd64 \
-t "${ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com/claude-gateway:<version>" .
docker push "${ACCOUNT_ID}.dkr.ecr.${AWS_REGION}.amazonaws.com/claude-gateway:<version>"
7

デプロイ

クラスターと、ゲートウェイの stderr 用のロググループを作成します。stderr には監査イベントと運用ログの両方が含まれます。保持期間は別の呼び出しで設定し、設定しない場合、CloudWatch はログを永久に保持します。90 日を監査保持ポリシーに合わせて調整してください。

aws ecs create-cluster --cluster-name claude-gateway
aws logs create-log-group --log-group-name /ecs/claude-gateway
aws logs put-retention-policy --log-group-name /ecs/claude-gateway \
--retention-in-days 90

タスク定義を書き込みます。タスクロールは Bedrock 権限を持ち、実行ロールはシークレットを注入します。Secrets Manager ステップからのシークレット ARN を使用します。

{
"family": "claude-gateway",
"networkMode": "awsvpc",
"requiresCompatibilities": ["FARGATE"],
"cpu": "1024",
"memory": "2048",
"runtimePlatform": { "cpuArchitecture": "X86_64", "operatingSystemFamily": "LINUX" },
"executionRoleArn": "arn:aws:iam::<account-id>:role/claude-gateway-execution",
"taskRoleArn": "arn:aws:iam::<account-id>:role/claude-gateway-task",
"containerDefinitions": [
{
"name": "gateway",
"image": "<account-id>.dkr.ecr.<region>.amazonaws.com/claude-gateway:<version>",
"portMappings": [{ "containerPort": 8080 }],
"secrets": [
{ "name": "GATEWAY_JWT_SECRET",   "valueFrom": "<gateway-jwt-secret ARN>" },
{ "name": "OIDC_CLIENT_SECRET",   "valueFrom": "<gateway-oidc-client-secret ARN>" },
{ "name": "GATEWAY_POSTGRES_URL", "valueFrom": "<gateway-postgres-url ARN>" }
],
"logConfiguration": {
"logDriver": "awslogs",
"options": {
"awslogs-group": "/ecs/claude-gateway",
"awslogs-region": "<region>",
"awslogs-stream-prefix": "gateway"
}
}
}
]
}

それを登録します。

aws ecs register-task-definition --cli-input-json file://claude-gateway-task.json

ゲートウェイをヘルスチェックするターゲットグループを持つ内部 ALB を前に配置します。--ip-address-type ipv4 は重要です。内部デュアルスタック ALB はパブリック範囲の AAAA レコードを公開し、/login プライベートネットワークチェックはそれらを拒否します。

ALB_ARN="$(aws elbv2 create-load-balancer --name claude-gateway \
--scheme internal --type application --ip-address-type ipv4 \
--subnets $PRIVATE_SUBNETS --security-groups "$ALB_SG" \
--query 'LoadBalancers[0].LoadBalancerArn' --output text)"

TG_ARN="$(aws elbv2 create-target-group --name claude-gateway \
--protocol HTTP --port 8080 --vpc-id "$VPC_ID" --target-type ip \
--health-check-path /readyz \
--query 'TargetGroups[0].TargetGroupArn' --output text)"

HTTPS リスナーを追加します。--ssl-policy は最新の TLS フロアをピンします。これを省略すると、レガシー ELBSecurityPolicy-2016-08 デフォルトにフォールバックします。これは TLS 1.0/1.1 をまだ受け入れます。

ALB はデフォルトで 60 秒間データがない接続を閉じます。ゲートウェイのキープアライブピングはストリームをそのデフォルト内に保つため、タイムアウトを上げるとピングの間隔に対するマージンが増えます。ドロップされたストリームに関するトラブルシューティングの行で、そのメカニズムと古いゲートウェイについて説明しています。以下のコマンドはリスナーを追加し、タイムアウトを上げます。

aws elbv2 create-listener --load-balancer-arn "$ALB_ARN" \
--protocol HTTPS --port 443 \
--ssl-policy ELBSecurityPolicy-TLS13-1-2-2021-06 \
--certificates CertificateArn=<your-acm-certificate-arn> \
--default-actions Type=forward,TargetGroupArn="$TG_ARN"

aws elbv2 modify-load-balancer-attributes --load-balancer-arn "$ALB_ARN" \
--attributes Key=idle_timeout.timeout_seconds,Value=3600

サービスを作成します。デプロイサーキットブレーカーは、不正なイメージやブート不可能な設定によってタスクが失敗し続けるデプロイを、失敗するタスクを永遠に再起動する代わりに、最後の安定した状態にロールバックします。

aws ecs create-service --cluster claude-gateway --service-name claude-gateway \
--task-definition claude-gateway --desired-count 1 --launch-type FARGATE \
--deployment-configuration "deploymentCircuitBreaker={enable=true,rollback=true}" \
--health-check-grace-period-seconds 60 \
--network-configuration "awsvpcConfiguration={subnets=[$(echo $PRIVATE_SUBNETS | tr ' ' ',')],securityGroups=[$GW_SG],assignPublicIp=DISABLED}" \
--load-balancers "targetGroupArn=$TG_ARN,containerName=gateway,containerPort=8080"

60 秒のグレースピリオドは、ECS がデプロイに対して失敗のカウントを始める前に、コールドタスクがイメージをプルし、ストアに接続し、最初のヘルスチェックに応答する時間を与えます。

ターゲットグループの GET /readyz のヘルスチェックはストアが到達可能であることを検証するため、Postgres に到達できないタスクはローテーションに入りません。RDS フェイルオーバーなどの短いデータベース停止中もタスクがチェックを通過し続けるようにするには、停止動作の説明に従って store.readiness_grace_seconds を設定します。同セクションでは /healthz 代替案についても説明しています。

タスクはパブリック IP なしのプライベートサブネットで実行されるため、すべてのエグレス（Bedrock、IdP、Secrets Manager、ECR、CloudWatch Logs へ）は NAT ゲートウェイを通過します。Bedrock トラフィックをパブリックパスから外すには、Bedrock アップストリームリファレンスに示されているように、bedrock-runtime インターフェース VPC エンドポイントを作成し、アップストリームの base_url をそれに向けます。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 を開発者マシンにプッシュする

ゲートウェイは実行されていますが、ゲートウェイ URL が開発者のマシンに配置されるまで、開発者は /login からゲートウェイに到達できません。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 に固有です。

症状 原因 修正
CLI /login: Gateway hosts must be on your organization's private network; <host> resolves to the public (or unrecognized) address <ip> ゲートウェイ名が少なくとも 1 つのパブリックアドレスに解決されます。デュアルスタック内部 ALB はパブリック範囲の AAAA レコードを公開し、プライベートネットワークチェックは解決されたすべてのアドレスがプライベートであることを要求します ALB を --ip-address-type ipv4 で作成するか、パブリック AAAA レコードのない別の内部専用 DNS 名を提供してください
すべての Bedrock リクエストが 502 を返す。ログに Could not load credentials from any providers が表示される タスクは ECS EC2 起動タイプでタスクロールなしで実行されるか、ポッドは IRSA なしで EKS ノードで実行されるため、認証情報はインスタンスメタデータから取得されます。IMDSv2 のデフォルトホップリミット 1 はコンテナ内で停止します。このページの両方のトラック（Fargate タスクロールと IRSA）はインスタンスメタデータを使用しません タスクロールと IRSA を優先してください。インスタンス認証情報が避けられない場合は、aws ec2 modify-instance-metadata-options --instance-id <id> --http-put-response-hop-limit 2 でホップリミットを上げてください。プラットフォーム非依存テーブルはトレードオフをカバーしています
Bedrock リクエストが 403 AccessDeniedException を返す アカウントが Anthropic のワンタイム使用ケースフォームを送信していない、アカウントの最初の呼び出しで開始される自動 AWS Marketplace サブスクリプションがまだ完了していない、またはタスクロールのポリシーに推論プロファイルまたは基盤モデル ARN が不足している Bedrock コンソールのモデルカタログから使用ケースフォームを送信してください。フォームが送信されたばかりの場合、またはこれがアカウントの最初の呼び出しの場合は、数分後に再試行してください。bedrock:InvokeModel と bedrock:InvokeModelWithResponseStream を両方の ARN ファミリーに付与してください。
Bedrock がオンデマンドスループットがサポートされていないと言う ValidationException を返す カスタム models: エントリが、リージョンが推論プロファイルを通じてのみ提供する基盤モデル ID にマップされている モデルをクロスリージョン推論プロファイル ID（us.anthropic.*）にマップしてください。組み込みカタログはすでにこれを行っています
ECS タスクがゲートウェイがログに何も出力する前に ResourceInitializationError で停止する 実行ロールが Secrets Manager シークレットを読み取ることができない、またはプライベートサブネットが Secrets Manager または ECR へのパスを持たない 実行ロールに 3 つの gateway- シークレット ARN に対する secretsmanager:GetSecretValue を付与し、NAT ゲートウェイ経由でエグレスを提供するか、NAT ゲートウェイなしで Secrets Manager、ECR、CloudWatch Logs のインターフェースエンドポイント（awslogs ドライバーが同じステージで必要とする）と S3 ゲートウェイエンドポイントを提供してください
ゲートウェイブートが Postgres 接続タイムアウトエラーで終了する データベースセキュリティグループがゲートウェイのセキュリティグループを 5432 で許可していない、またはサービスがデータベースの VPC 外で実行されている データベースのセキュリティグループでゲートウェイのセキュリティグループから 5432 を許可し、サービスを DB サブネットグループと同じ VPC で実行してください
ゲートウェイブートが Postgres TLS 証明書検証エラーで終了する 接続文字列が sslmode=verify-full を設定しているが、イメージが RDS CA バンドルを信頼していない。バンドルがイメージにコピーされていない、または NODE_EXTRA_CA_CERTS がそれを指していない ビルドステップの 2 つの Dockerfile 行を追加してバンドルをコピーし、NODE_EXTRA_CA_CERTS を設定してから、リビルドして新しいタグで プッシュし、再デプロイしてください
ストリーミング応答が静止期間後にストリーム途中でドロップする v2.1.229 より前のゲートウェイが Bedrock または AWS 上の Claude Platform 上流で、上流が静止している間（例えば、ストリーム出力のない拡張思考中）は何も送信しません。ALB はデフォルトで 60 秒間データがない場合に接続を閉じるため、そのギャップでストリームを切断します。v2.1.229 以降のゲートウェイはそのタイムアウト下で静止したストリームを保持します。これらの上流では、ゲートウェイはストリームデータがない状態で約 15 秒経過すると SSE ping イベントを 1 回発行し、Anthropic API 上流ではゲートウェイは API 自体のピングをリレーします ゲートウェイを v2.1.229 以降に更新するか、idle_timeout.timeout_seconds 属性を 3600 に設定してください。modify-load-balancer-attributes または EKS の load-balancer-attributes Ingress アノテーション経由で設定します

テレメトリ

ゲートウェイは、マシンごとの OTEL 設定なしで、開発者ごとの使用状況メトリクスを提供します。Claude Code は OpenTelemetry（OTLP）メトリクス、ログ、およびオプトイン トレースを出力します。使用状況の監視は、CLI が報告するすべてをカバーしています。/login を通じてサインインしたセッションでは、CLI は各エクスポートに認証された IdP ID 属性 user.id、user.email、および user.groups をスタンプし、使用状況は開発者ごとにロールアップされます。

ゲートウェイ自体は認証された OTLP リレーです。telemetry.forward_to を listen.public_url と一緒に設定すると、OTEL エクスポーター設定をすべての接続クライアントにプッシュし、OTLP トラフィックを指定した各宛先に逐語的に転送します。各宛先はメトリクス、ログ、およびトレースに独立してオプトインでき、デフォルトはメトリクスのみです。telemetry リファレンスで、シグナルごとのフィールドとそれらの感度トレードオフを参照してください。ゲートウェイはテレメトリをバッファリング、集約、または保存しないため、データが到達する場所はコレクターのエクスポーター設定に完全に依存します。

クライアント テレメトリはデフォルトでオフです。telemetry.forward_to を設定することで、接続された開発者に対してオンになり、各インタラクティブ クライアントはプッシュされた設定に対するセキュリティ承認ダイアログを表示します。これは設定リファレンスで説明されています。AWS では、各シグナルは次のように宛先にマップされます。

クライアント メトリクス、ログ、およびトレース

telemetry.forward_to を OpenTelemetry コレクター（AWS Distro for OpenTelemetry（ADOT）コレクターなど）にポイントし、そこから Amazon CloudWatch、Amazon Managed Service for Prometheus、または任意の OTLP バックエンドにエクスポートします。

コレクターを https:// 経由で到達可能な独自の内部サービスとして実行します。telemetry リファレンスはループバック例外と CLAUDE_GATEWAY_ALLOW_LOOPBACK をカバーしています。

ゲートウェイ ログ

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 アドオンをインストールしてください。

支出

テレメトリは事後に使用状況を表示します。支出制限はゲートウェイのライブ開発者ごとのビューと実装です。

コスト属性

ゲートウェイはすべての Bedrock リクエストに独自のプリンシパル（ECS タスクロールまたは EKS IRSA ロール）で署名するため、デフォルトでは AWS はそのすべての支出を 1 つの IAM プリンシパルの下に表示します。AWS 独自の請求データで分割する方法は 2 つあり、これらは組み合わせることができます。

`assume_role` を使用した開発者ごと

Bedrock 権限を保持し、ゲートウェイのプリンシパルを信頼する 2 番目の IAM ロールを作成し、そのプリンシパルに対して sts:AssumeRole を付与し、Bedrock アップストリームで assume_role を session_name: email で設定します。ゲートウェイは、開発者ごとに 1 時間に 1 回そのロールを引き受け、セッション名をメールアドレスに設定して、その結果でリクエストに署名します。Claude Code v2.1.281 以降を実行しているゲートウェイが必要です。ロールは別の AWS アカウントに配置することもできます。別の AWS アカウントの Bedrock を参照してください。Terraform では、Terraform バンドル のタスクロールの隣に以下を配置します。

resource "aws_iam_role" "bedrock_user" {
  name = "claude-gateway-bedrock-user"
  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{ Effect = "Allow", Action = "sts:AssumeRole", Principal = { AWS = aws_iam_role.task.arn } }]
  })
}
resource "aws_iam_role_policy" "bedrock_user_invoke" {   # same Bedrock policy as the task role's
  role   = aws_iam_role.bedrock_user.id
  policy = aws_iam_role_policy.bedrock_invoke.policy
}
resource "aws_iam_role_policy" "task_assume_bedrock_user" {
  role   = aws_iam_role.task.id
  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{ Effect = "Allow", Action = "sts:AssumeRole", Resource = aws_iam_role.bedrock_user.arn }]
  })
}

assume_role が設定されている場合、ゲートウェイはすべての Bedrock 呼び出し（支出メータリング用の無料 CountTokens 呼び出しを含む）に引き受けたロールの認証情報で署名するため、ゲートウェイのプリンシパルは assume_role のないアップストリームの場合のみ独自の Bedrock ポリシーが必要です。

ゲートウェイはリクエスト時に STS を呼び出すため、プライベートサブネットは sts.<region>.amazonaws.com へのパスが必要です。前提条件の NAT ゲートウェイがそのパスを提供し、そのホスト名に応答する STS インターフェース VPC エンドポイントも提供します。アクティブな開発者ごとに、ゲートウェイレプリカあたり 1 時間に 1 回の STS 呼び出しがかかります。

各開発者のリクエストは、プリンシパル arn:aws:sts::<account>:assumed-role/<role>/<email> として AWS に到達します。プリンシパルごとの支出を確認するには、IAM プリンシパルデータを含む請求エクスポートを使用します。AWS の IAM プリンシパルコスト配分 ページでは、有効にする方法と、どの請求ツールがそれを表示するかについて説明しています。

アプリケーション推論プロファイルを使用したチームごと

このルートは models と managed セクションのみを使用します。チームとモデルごとに 1 つの Bedrock アプリケーション推論プロファイル を作成し、各プロファイルにチームでタグを付け、そのタグをコスト配分タグとして有効化します。次に、各チームに gateway.yaml で独自のモデル ID を付与し、各 IdP グループをそのチームの ID にピン留めします。

models:
  - id: platform-claude-opus-4-8
    upstream_model:
      bedrock: arn:aws:bedrock:us-east-1:123456789012:application-inference-profile/abc123
  - id: data-claude-opus-4-8
    upstream_model:
      bedrock: arn:aws:bedrock:us-east-1:123456789012:application-inference-profile/def456
managed:
  policies:
    - match: {groups: [team-platform]}
      cli: {availableModels: [platform-claude-opus-4-8], enforceAvailableModels: true}
    - match: {groups: [team-data]}
      cli: {availableModels: [data-claude-opus-4-8], enforceAvailableModels: true}
    - match: {}
      cli: {availableModels: [claude-opus-4-8, claude-sonnet-4-6], enforceAvailableModels: true}

ピン留めされたチームの開発者に、チームの ID を使用して --model platform-claude-opus-4-8 で Claude Code を起動するよう指示します。セッションがそれなしで開始された場合、デフォルトモデルが実行され、ゲートウェイはそれらのモデルを拒否するためです。

ゲートウェイはモデルピッカーだけでなく、すべてのリクエストで availableModels を強制し、AWS 請求は有効化したタグで支出をグループ化します。match: {} キャッチオールがない場合、ポリシーに一致しない開発者はカタログ内のすべてのモデルを取得でき、どちらのチームのプロファイルでも請求できます。

コスト：設定はチーム数とモデル数で増加し、このアップストリームの Bedrock リクエストに署名するロールは、application-inference-profile/* ARN を呼び出すことも許可される必要があります。そのロールはゲートウェイのプリンシパル、または assume_role を使用する場合は引き受けるロールです。これらの ID の価格設定方法については、pricing を参照してください。

次のステップ