На этой странице описан один из способов запуска Claude apps gateway на AWS. Конфигурация представляет собой рабочий пример для инфраструктуры, управляемой клиентом, а не поддерживаемое развёртывание в production; используйте её, чтобы понять, как компоненты работают вместе, прежде чем адаптировать её к своей среде. Требования, независимые от платформы, см. в руководстве по развёртыванию.
Bedrock — не единственный Claude upstream на AWS. Gateway также поддерживает Claude Platform on AWS, управляемый Anthropic Claude API с аутентификацией AWS и выставлением счётов через AWS Marketplace, вместо Bedrock или наряду с ним. Его upstream запись, учётные данные и разрешения IAM отличаются от ориентированных на Bedrock на этой странице; справочник upstream Claude Platform on AWS охватывает, что изменяется, а остальная часть этой страницы применяется без изменений.
Архитектура
Пример архитектуры с Amazon Bedrock в качестве upstream модели. Upstream Claude Platform on AWS занимает ту же позицию.
- Сервис Amazon ECS на AWS Fargate или Amazon EKS Deployment, запускающий контейнер gateway
- Репозиторий Amazon ECR для образа gateway
- Экземпляр Amazon RDS для PostgreSQL в приватных подсетях, не доступный публично, для хранилища gateway
- Секреты AWS Secrets Manager для ключа подписи JWT, секрета клиента OIDC и URL Postgres
- IAM-роль с
bedrock:InvokeModel,bedrock:InvokeModelWithResponseStreamиbedrock:CountTokens, присоединённая как роль задачи ECS или привязанная через IAM Roles for Service Accounts (IRSA) на EKS - Внутренний Application Load Balancer для HTTPS
Предварительные требования
Пошаговое руководство создаёт собственные ресурсы gateway, но строится на сетевой и инфраструктуре идентификации, которая у вас уже есть. Прежде чем начать, вам нужно:- Учётная запись AWS с разрешением на создание ресурсов выше
- AWS CLI v2 установлен и аутентифицирован, а также Docker установлен локально
- VPC с минимум двумя приватными подсетями в разных Availability Zones с исходящим доступом в интернет через NAT gateway; внутреннему load balancer нужны подсети в двух AZ, а gateway нужен исходящий доступ к Bedrock и вашему IdP
- Веб-приложение Okta OIDC с URI перенаправления
https://<gateway-host>/oauth/callback; см. Настройка поставщика идентификации - TLS имя хоста для gateway, обычно внутреннее имя DNS в приватной зоне Route 53, указывающее на load balancer, с сертификатом ACM для этого имени, импортированным или выданным AWS Private CA
Установите переменные окружения
Каждая команда на этой странице читает четыре значения из вашей оболочки:AWS_REGION, ACCOUNT_ID, VPC_ID и PRIVATE_SUBNETS.
Выберите регион США, где Bedrock обслуживает нужные вам модели Claude. Пошаговое руководство полагается на встроенный каталог моделей gateway, который разрешается в профили вывода us.anthropic.*, и политика IAM предоставляет эти ARN. В регионе, отличном от США, добавьте models: блок с ID профилей вывода этого региона и измените префикс ARN в политике IAM, чтобы он совпадал.
Если у вас нет ID VPC под рукой, перечислите ваши VPC с помощью aws ec2 describe-vpcs, затем перечислите подсети этого VPC, чтобы найти две приватные в разных Availability Zones:
Развёртывание gateway
Шаги ниже предусматривают полное развёртывание с командамиaws.
1
Создайте группы безопасности
Три группы безопасности связывают путь трафика: ваша корпоративная сеть достигает load balancer на 443, load balancer достигает gateway на 8080, и gateway достигает Postgres на 5432. Ничего больше не доступно. Как вы их присоединяете, зависит от трека вычислений:
- На ECS Fargate шаг развёртывания присоединяет
$ALB_SGк load balancer и$GW_SGк сервису. - На EKS AWS Load Balancer Controller создаёт свою собственную группу безопасности фронтенда для ALB, поэтому
$ALB_SGи$GW_SGне используются: аннотацияinbound-cidrsшага развёртывания ограничивает слушатель вашей корпоративной сетью, а группа безопасности базы данных допускает группу безопасности кластера вместо$GW_SG.
2
Создайте IAM-роли и отправьте форму использования
Gateway работает с выделённой ролью задачи, единственное разрешение которой — вызывать модели Claude на Bedrock. Согласно справочнику upstream Bedrock, политика должна охватывать как ARN профилей вывода между регионами, так и базовые ARN моделей фундамента:ECS также нуждается в роли выполнения, которую сам агент ECS использует для извлечения образа из ECR и внедрения значений Secrets Manager, созданных позже. Она отделена от роли задачи, которую AWS SDK gateway использует во время выполнения:Политика называет один ARN на секрет, а не простой подстановочный знак
gateway-*, который в общей учётной записи также совпадал бы с несвязанными секретами; конечный -?????? совпадает ровно с случайным суффиксом из шести символов, который Secrets Manager добавляет к ARN каждого секрета. Конечный -* был бы простым глобусом префикса и также совпадал бы с более длинными именами, такими как gateway-postgres-url-prod.Политика IAM предоставляет gateway разрешение на вызов Bedrock, и Bedrock включает доступ к модели по умолчанию в коммерческих регионах. Оставшиеся ворота на уровне учётной записи — это одноразовая форма использования Anthropic: если никто в вашей учётной записи её не отправил, откройте консоль Amazon Bedrock, выберите модель Anthropic из каталога моделей и заполните форму. Доступ предоставляется сразу после отправки; см. Claude Code на Amazon Bedrock для формы AWS Organizations и разрешений IAM, которые нужны отправителю.Трек EKS повторно использует оба документа политики на роли IRSA вместо двух ролей ECS; см. шаг развёртывания.3
Подготовьте Amazon RDS для PostgreSQL
Экземпляр работает в приватных подсетях без публичного адреса и с включённым шифрованием хранилища. Версия движка закреплена на Postgres 16, что удовлетворяет поддерживаемому минимуму gateway PostgreSQL 14 и гарантирует, что семейство группы параметров ниже совпадает с экземпляром.Сначала создайте группу подсетей, которая размещает базу данных в приватных подсетях, и группу параметров с Затем создайте экземпляр с сгенерированным главным паролем:Буквальный аргумент
rds.force_ssl=1, чтобы сервер отклонял открытые соединения. Версия движка закреплена один раз, потому что семейство группы параметров должно совпадать с основной версией движка, которую запускает экземпляр:--master-user-password виден в таблице процессов и в журналах аудита/EDR во время выполнения команды, то же самое воздействие, которое охватывает примечание шага секретов. На общем или контролируемом хосте передайте пароль через --cli-input-json из файла 0600 вместо этого, так же как это делает setup.sh пакета.Дождитесь, пока экземпляр запустится, что может занять несколько минут, затем прочитайте его приватную конечную точку и соберите строку подключения, которую будет использовать gateway:sslmode=verify-full заставляет gateway проверять цепь сертификата сервера RDS и имя хоста, а не только шифровать. Якорь доверия — это пакет сертификатов AWS RDS, который шаг сборки образа ниже копирует в /etc/claude/rds-global-bundle.pem и доверяет через NODE_EXTRA_CA_CERTS. Не добавляйте параметр sslrootcert= в стиле libpq к URL: драйвер gateway читает только sslmode из строки запроса и передал бы sslrootcert Postgres как параметр запуска, который сервер отклоняет.Сервис ECS или поды EKS должны работать в этом VPC, чтобы они могли достичь приватной конечной точки экземпляра, и группа безопасности claude-gateway-db допускает только группу безопасности gateway.4
Напишите gateway.yaml
Блок
upstreams указывает на Bedrock с auth: {}, поэтому gateway аутентифицируется через цепь учётных данных AWS по умолчанию из роли задачи на ECS или роли IRSA на EKS. См. справочник конфигурации для каждого поля.Два поля listen описывают, что находится перед gateway:public_url: внешний источникhttps://, требуется для любого привязывания, отличного от loopback; см. справочникlisten. Gateway строитredirect_uriIdP и его документ обнаружения только из этого значения, никогда из заголовковX-Forwarded-*.trusted_proxies: диапазоны источников фронтенда. Gateway соблюдаетX-Forwarded-Forтолько когда TCP-пир находится в этом списке, затем проходит цепь мимо доверенных переходов, поэтому ограничения скорости входа на IP и события аудита записывают IP разработчиков вместо load balancer.
trusted_proxies на CIDR этих подсетей. Это доверяет каждому хосту в этих подсетях как прокси. Не допускайте, чтобы источник входа ALB, ваша корпоративная CIDR, перекрывался с ними, и не делитесь подсетями с ненадёжными рабочими нагрузками, которые могли бы подделать IP клиентов через X-Forwarded-For.Атрибут сохранения клиентского порта ALB, routing.http.xff_client_port.enabled, может остаться в любом параметре: с ним включённым, ALB записывает клиента как 203.0.113.7:54321 или [2001:db8::1]:54321, и gateway читает оба с опущенным портом.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, или на App Roles с 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, смонтируйте
gateway.yamlиз ConfigMap и секреты как файлы в/secrets, на которые ссылаются как${file:/secrets/...}. Получите Kubernetes Secrets из Secrets Manager с External Secrets Operator или поставщиком AWS драйвера Secrets Store CSI, или создайте их напрямую с помощьюkubectl.
6
Соберите и отправьте образ в Amazon ECR
Соберите образ согласно требованиям образа контейнера, разместив двоичный файл Требования образа контейнера не охватывают пакет, поэтому если вы напишете свой собственный Dockerfile, добавьте две строки, которые копируют и доверяют ему; Создайте репозиторий ECR и подпишите Docker в него. Неизменяемые теги означают, что тег Соберите и отправьте образ. Определение задачи ниже запускает
linux-x64 glibc в ./claude в контексте сборки. Напишите свой собственный Dockerfile согласно этим требованиям или начните с Dockerfile пакета, который копирует заполненный gateway.yaml из предыдущих шагов в образ в /etc/claude/gateway.yaml. На ECS эта встроенная копия — это то, как конфигурация достигает контейнера, поэтому сборка идёт после написания файла. Трек EKS вместо этого монтирует gateway.yaml из ConfigMap при развёртывании, поэтому встроенная копия там не используется.Образ также содержит пакет сертификатов AWS RDS как якорь доверия для sslmode=verify-full строки подключения, поэтому загрузите его в контекст сборки сначала. AWS ротирует пакет (новые региональные CA добавляются), поэтому загружайте его при каждой сборке, а не закрепляйте контрольную сумму или фиксируйте её:Dockerfile пакета уже включает оба:<version>, который закрепляет шаг развёртывания, не может позже молча переуказываться на другой образ:linux/amd64, поэтому платформа должна совпадать здесь; для Fargate на ARM64 (Graviton), соберите linux/arm64 с двоичным файлом linux-arm64 и установите cpuArchitecture на ARM64 вместо этого:7
Развёртывание
- ECS Fargate
- EKS
Создайте кластер и группу журналов для stderr gateway, которая содержит как события аудита, так и операционные журналы. Удержание — это отдельный вызов, и без него CloudWatch хранит журналы вечно; выровняйте 90 дней с вашей политикой удержания аудита:Напишите определение задачи. Роль задачи несёт разрешение Bedrock, а роль выполнения внедряет секреты; используйте ARN секретов из шага Secrets Manager:Зарегистрируйте его:Поместите внутренний 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 секунд без данных по умолчанию. Keepalive пинги gateway держат потоки внутри этого значения по умолчанию, поэтому повышение времени ожидания добавляет запас выше кадра пинга; строка Troubleshooting на разорванных потоках охватывает механизм и более старые gateway. Команды ниже добавляют слушатель и повышают время ожидания:GET /readyz проверяет, что хранилище доступно, поэтому задача, которая не может достичь Postgres, никогда не входит в ротацию; см. Поведение при сбое для компромисса и альтернативы /healthz.Задачи работают в приватных подсетях без публичного IP, поэтому весь исходящий трафик (в Bedrock, ваш IdP, Secrets Manager, ECR и CloudWatch Logs) проходит через NAT gateway. Чтобы держать трафик Bedrock вне публичного пути, создайте интерфейсную конечную точку VPC bedrock-runtime и укажите base_url upstream на неё, как показано в справочнике upstream Bedrock; IdP всё ещё нуждается в исходящем доступе в интернет.Завершите, дав разработчикам приватно разрешаемое имя хоста: в приватной зоне Route 53 создайте псевдоним внутреннего имени DNS gateway на ALB и установите listen.public_url на это имя хоста. Собственное имя *.elb.amazonaws.com ALB разрешается на приватные адреса на внутреннем ALB, но оно не может нести ваш сертификат ACM, поэтому используйте своё имя.Обновите URI перенаправления авторизованного клиента OAuth на <public_url>/oauth/callback перед первым входом. После изменения public_url, пересоберите и отправьте образ под новым тегом, зарегистрируйте новую редакцию определения задачи и переразвёртывайте. На ECS параметр живёт в встроенном gateway.yaml образа, и gateway строит свой публичный источник только из этого параметра, игнорируя X-Forwarded-Host и X-Forwarded-Proto. X-Forwarded-For соблюдается для IP клиентов только когда установлен listen.trusted_proxies.8
Отправьте URL gateway на машины разработчиков
Gateway теперь работает, но разработчики не могут достичь его из
/login до тех пор, пока URL gateway не будет на их машинах. Установите forceLoginMethod и forceLoginGatewayUrl в файле управляемых параметров, который вы развёртываете на каждом устройстве через MDM. Нет опции gateway в средстве выбора входа для разработчика, чтобы выбрать вручную.Справочник Terraform
Сопутствующий пакет вexamples/gateway/aws упаковывает эту страницу как код:
setup.shскриптирует пошаговое руководство по подготовке выше с теми же командамиaws, на треке ECS Fargate. Это идемпотентно: существующие ресурсы обнаруживаются и пропускаются, поэтому повторный запуск безопасен, и любое значение по умолчанию может быть переопределено через переменную окружения. Вы всё ещё создаёте секрет клиента Okta OIDC и сертификат ACM сами: запуск без них пропускает развёртывание ECS/ALB, называет отсутствующие входы и печатает командуcreate-secret; создайте оба и переразвёртывайте. Форма использования Bedrock и псевдоним Route 53 печатаются как следующие шаги, а не запускаются автоматически, и push MDM клиента остаётся ручным шагом с этой страницы.gateway.yaml.example— это шаблон конфигурации из шага gateway.yaml, с дополнительными ключами, включёнными в комментарии. Скопируйте его вgateway.yamlи замените каждыйREPLACE_MEперед сборкой.Dockerfileсобирает образ среды выполнения из предварительно собранного двоичного файлаlinux-x64и копирует ваш заполненныйgateway.yamlв/etc/claude/gateway.yaml, плюс пакет сертификатов AWS RDS, который якорируетsslmode=verify-fullхранилища.setup.shзагружает пакет только когда его ещё нет в контексте сборки; удалите файл и пересоберите под новым тегом, чтобы подобрать ротацию AWS CA. Файл конфигурации не содержит значений секретов, так как каждое учётное данные разрешается при загрузке через расширение${VAR}. Редактирование конфигурации, следовательно, означает пересборку под новым тегом;setup.shавтоматизирует это, помечая образы хешем файла.terraform/предусматривает ту же область ECS Fargate декларативно: группы безопасности, роли IAM, репозиторий ECR, экземпляр RDS, секреты Secrets Manager и сервис ECS за внутренним ALB. VPC и приватные подсети остаются предварительными условиями, переданными как переменные. Terraform создаёт репозиторий ECR, но не собирает образ, и определение сервиса ссылается на образ, поэтому применение — это два прохода: целевое применение для репозитория, затем сборка и отправка, затем полное применение.terraform/README.mdпакета охватывает переменные, удалённое состояние и разборку.
Troubleshooting
Для ошибок загрузки gateway и входа см. независимую от платформы таблицу troubleshooting. Записи ниже специфичны для AWS.Телеметрия
Gateway даёт вам метрики использования на разработчика без какой-либо конфигурации OTEL на машину. Claude Code выдаёт метрики OpenTelemetry (OTLP), журналы и дополнительные трассировки; Мониторинг использования охватывает всё, что сообщает CLI. На сессиях gateway CLI штампует каждый экспорт с аутентифицированными атрибутами идентификации IdPuser.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) collector, и экспортируйте оттуда в Amazon CloudWatch, Amazon Managed Service for Prometheus или любой backend OTLP.
Запустите сборщик как его собственный внутренний сервис, доступный через https://; справочник telemetry охватывает исключение loopback и CLAUDE_GATEWAY_ALLOW_LOOPBACK.
Журналы Gateway
На ECS Fargate, никакой дополнительной установки: драйверawslogs доставляет stderr gateway, который содержит события аудита и операционные журналы, в группу журналов /ecs/claude-gateway, созданную выше. На EKS, журналы подов не достигают CloudWatch по умолчанию, поэтому аудит теряется до тех пор, пока вы не установите сбор журналов: надстройка Amazon CloudWatch Observability с включённым захватом журналов контейнера или DaemonSet Fluent Bit. На любом треке запросите журналы с помощью CloudWatch Logs Insights и управляйте сигналами тревоги из фильтров метрик.
Метрики контейнера
Включите Container Insights на кластере сaws ecs update-cluster-settings --cluster claude-gateway --settings name=containerInsights,value=enabled для CPU, памяти и сети на задачу. На EKS установите надстройку Amazon CloudWatch Observability.
Расходы
Телеметрия показывает использование после факта; ограничения расходов — это живой вид gateway на разработчика и принуждение поверх общего учётного данные upstream.Следующие шаги
- Справочник конфигурации: каждая опция
gateway.yaml, включаяmanaged.policiesиtelemetry - Развёртывание и операции: настройка IdP, проверки здоровья, ротация секрета JWT, обновления и модель безопасности
- Обзор Claude apps gateway: быстрый старт и подключение разработчиков
- Примеры AWS для Claude apps gateway: примеры развёртывания, поддерживаемые AWS, охватывающие диапазон сред клиентов