Skip to main content
На этой странице описан один из способов запуска Claude apps gateway на AWS. Конфигурация представляет собой рабочий пример для инфраструктуры, управляемой клиентом, а не поддерживаемое развёртывание в production; используйте её, чтобы понять, как компоненты работают вместе, прежде чем адаптировать её к своей среде. Требования, независимые от платформы, см. в руководстве по развёртыванию.
Этот пример развёртывает Claude apps gateway на AWS с Amazon Bedrock в качестве upstream модели, используя либо Amazon ECS на AWS Fargate, либо Amazon EKS для вычислений. Okta — это пример поставщика идентификации (IdP), но подходит любой поставщик, совместимый с OpenID Connect (OIDC); см. Настройка поставщика идентификации для получения деталей для каждого IdP.
Bedrock — не единственный Claude upstream на AWS. Gateway также поддерживает Claude Platform on AWS, управляемый Anthropic Claude API с аутентификацией AWS и выставлением счётов через AWS Marketplace, вместо Bedrock или наряду с ним. Его upstream запись, учётные данные и разрешения IAM отличаются от ориентированных на Bedrock на этой странице; справочник upstream Claude Platform on AWS охватывает, что изменяется, а остальная часть этой страницы применяется без изменений.

Архитектура

Диаграмма Claude apps gateway на AWS: клиенты Claude Code подключаются по HTTPS к внутреннему Application Load Balancer, который находится перед gateway (ECS Fargate или EKS), работающим в приватных подсетях рядом с экземпляром Amazon RDS для PostgreSQL для состояния сессии. Gateway выполняет вход пользователей через OIDC по корпоративному IdP, читает секреты из AWS Secrets Manager, перенаправляет запросы модели в Amazon Bedrock, используя свою IAM-роль, и извлекает свой образ из Amazon ECR при развёртывании.

Пример архитектуры с Amazon Bedrock в качестве upstream модели. Upstream Claude Platform on AWS занимает ту же позицию.

Gateway работает как приватная HTTPS конечная точка в вашей сети, на которую разработчики входят через ваш IdP. Их сессии Claude Code достигают моделей Claude на Amazon Bedrock через IAM-роль gateway, поэтому учётные данные модели не попадают на машины разработчиков. Эталонная конфигурация предусматривает:
  • Сервис 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_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_uri IdP и его документ обнаружения только из этого значения, никогда из заголовков X-Forwarded-*.
  • trusted_proxies: диапазоны источников фронтенда. Gateway соблюдает X-Forwarded-For только когда TCP-пир находится в этом списке, затем проходит цепь мимо доверенных переходов, поэтому ограничения скорости входа на IP и события аудита записывают IP разработчиков вместо load balancer.
На обоих треках фронтенд — это внутренний ALB, создан ли он напрямую или AWS Load Balancer Controller, и узлы ALB берут адреса из подсетей, к которым он присоединён, поэтому установите 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

Соберите образ согласно требованиям образа контейнера, разместив двоичный файл 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, добавьте две строки, которые копируют и доверяют ему; Dockerfile пакета уже включает оба:
Создайте репозиторий ECR и подпишите Docker в него. Неизменяемые теги означают, что тег <version>, который закрепляет шаг развёртывания, не может позже молча переуказываться на другой образ:
Соберите и отправьте образ. Определение задачи ниже запускает linux/amd64, поэтому платформа должна совпадать здесь; для Fargate на ARM64 (Graviton), соберите linux/arm64 с двоичным файлом linux-arm64 и установите cpuArchitecture на ARM64 вместо этого:
7

Развёртывание

Создайте кластер и группу журналов для stderr gateway, которая содержит как события аудита, так и операционные журналы. Удержание — это отдельный вызов, и без него CloudWatch хранит журналы вечно; выровняйте 90 дней с вашей политикой удержания аудита:
Напишите определение задачи. Роль задачи несёт разрешение Bedrock, а роль выполнения внедряет секреты; используйте ARN секретов из шага Secrets Manager:
claude-gateway-task.json
Зарегистрируйте его:
Поместите внутренний ALB впереди с целевой группой, которая проверяет здоровье gateway. --ip-address-type ipv4 имеет значение: внутренний двойной стек ALB публикует записи AAAA общественного диапазона, которые проверка приватной сети /login отклоняет:
Добавьте слушатель HTTPS. --ssl-policy закрепляет современный минимум TLS, так как его опущение возвращается к устаревшему значению по умолчанию ELBSecurityPolicy-2016-08, которое всё ещё принимает TLS 1.0/1.1.ALB закрывает соединение после 60 секунд без данных по умолчанию. Keepalive пинги gateway держат потоки внутри этого значения по умолчанию, поэтому повышение времени ожидания добавляет запас выше кадра пинга; строка Troubleshooting на разорванных потоках охватывает механизм и более старые gateway. Команды ниже добавляют слушатель и повышают время ожидания:
Создайте сервис. Выключатель развёртывания откатывает развёртывание, чьи задачи продолжают отказывать, из-за плохого образа или неустойчивой конфигурации, обратно к последнему стабильному состоянию вместо перезапуска отказывающих задач вечно:
Период благодати в 60 секунд даёт холодной задаче время на извлечение образа, подключение к хранилищу и ответ на первую проверку здоровья перед тем, как ECS начнёт считать отказы против развёртывания. Проверка здоровья целевой группы на 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 пакета охватывает переменные, удалённое состояние и разборку.
Как эта страница, пакет — это рабочий пример для инфраструктуры, управляемой клиентом, а не поддерживаемое развёртывание в production; просмотрите и адаптируйте его к своей среде перед тем, как полагаться на него.

Troubleshooting

Для ошибок загрузки gateway и входа см. независимую от платформы таблицу troubleshooting. Записи ниже специфичны для 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) 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.

Следующие шаги