Arquitectura
La arquitectura de ejemplo, con Amazon Bedrock como el upstream del modelo. Un upstream de Claude Platform on AWS ocupa la misma posición.
- Servicio Amazon ECS en AWS Fargate o Amazon EKS Deployment ejecutando el contenedor del gateway
- Repositorio Amazon ECR para la imagen del gateway
- Instancia Amazon RDS para PostgreSQL en subredes privadas, no accesible públicamente, para el almacén del gateway
- Secretos de AWS Secrets Manager para la clave de firma JWT, el secreto del cliente OIDC y la URL de Postgres
- Rol de IAM con
bedrock:InvokeModel,bedrock:InvokeModelWithResponseStreamybedrock:CountTokens, adjunto como el rol de tarea de ECS o vinculado a través de Roles de IAM para Cuentas de Servicio (IRSA) en EKS - Application Load Balancer interno para HTTPS
Requisitos previos
El tutorial crea los recursos propios del gateway, pero se basa en la infraestructura de red e identidad que ya tiene. Antes de comenzar, necesita:- Una cuenta de AWS con permiso para crear los recursos anteriores
- AWS CLI v2 instalado y autenticado, y Docker instalado localmente
- Una VPC con al menos dos subredes privadas en diferentes Zonas de Disponibilidad, con acceso a internet saliente a través de una puerta de enlace NAT; el equilibrador de carga interno necesita subredes en dos AZ, y el gateway necesita salida a Bedrock y su IdP
- Una aplicación web OIDC de Okta con URI de redirección
https://<gateway-host>/oauth/callback; consulte Configuración del proveedor de identidad - Un nombre de host TLS para el gateway, típicamente un nombre DNS interno en una zona alojada privada de Route 53 que apunta al equilibrador de carga, con un certificado ACM para ese nombre, importado o emitido por AWS Private CA
Establezca sus variables de entorno
Cada comando en esta página lee cuatro valores de su shell:AWS_REGION, ACCOUNT_ID, VPC_ID y PRIVATE_SUBNETS.
Elija una región de EE.UU. donde Bedrock sirva los modelos de Claude que necesita. El tutorial se basa en el catálogo de modelos integrado del gateway, que se resuelve en perfiles de inferencia us.anthropic.*, y la política de IAM otorga esos ARN. En una región que no sea de EE.UU., agregue un bloque models: con los ID de perfil de inferencia de esa geografía y cambie el prefijo ARN de la política de IAM para que coincida.
Si no tiene el ID de VPC a mano, enumere sus VPC con aws ec2 describe-vpcs, luego enumere las subredes de esa VPC para encontrar dos privadas en diferentes Zonas de Disponibilidad:
Implemente el gateway
Los pasos a continuación aprovisionan la implementación completa con comandosaws.
Cree los grupos de seguridad
- En ECS Fargate, el paso de implementación adjunta
$ALB_SGal equilibrador de carga y$GW_SGal servicio. - En EKS, el Controlador de Equilibrador de Carga de AWS crea su propio grupo de seguridad frontend para el ALB, por lo que
$ALB_SGy$GW_SGno se usan: la anotacióninbound-cidrsdel paso de implementación restringe el oyente a su red corporativa, y el grupo de seguridad de la base de datos admite el grupo de seguridad del clúster en su lugar.
Cree los roles de IAM y envíe el formulario de caso de uso
gateway-*, que en una cuenta compartida también coincidiría con secretos no relacionados; el sufijo -?????? al final coincide exactamente con el sufijo de seis caracteres aleatorios que Secrets Manager añade al ARN de cada secreto. Un -* al final sería un glob de prefijo simple y también coincidiría con nombres más largos como gateway-postgres-url-prod.La política de IAM otorga al gateway permiso para llamar a Bedrock, y Bedrock habilita el acceso al modelo de forma predeterminada en regiones comerciales. La puerta de nivel de cuenta restante es el formulario de caso de uso único de Anthropic: si nadie en su cuenta lo ha enviado, abra la consola de Amazon Bedrock, seleccione un modelo de Anthropic del catálogo de modelos y complete el formulario. El acceso se otorga inmediatamente después del envío; consulte Claude Code en Amazon Bedrock para el formulario de AWS Organizations y los permisos de IAM que el remitente necesita.La pista de EKS reutiliza ambos documentos de política en un rol de IRSA en lugar de los dos roles de ECS; consulte el paso de implementación.Aprovisiona Amazon RDS para PostgreSQL
rds.force_ssl=1 para que el servidor rechace las conexiones de texto sin formato. La versión del motor se fija una vez porque la familia del grupo de parámetros debe coincidir con la versión principal del motor que ejecuta la instancia:--master-user-password es visible en la tabla de procesos y en registros de auditoría/EDR mientras se ejecuta el comando, la misma exposición que cubre la nota del paso de secretos. En un host compartido o monitoreado, pase la contraseña a través de --cli-input-json desde un archivo 0600 en su lugar, de la forma que lo hace setup.sh del paquete.Espere a que la instancia se levante, lo que puede tomar varios minutos, luego lea su endpoint privado y ensamble la cadena de conexión que usará el gateway:sslmode=verify-full hace que el gateway verifique la cadena del certificado del servidor RDS y el nombre de host, no solo cifre. El ancla de confianza es el paquete de certificados de AWS RDS, que el paso de compilación de imagen a continuación copia a /etc/claude/rds-global-bundle.pem y confía a través de NODE_EXTRA_CA_CERTS. No agregue un parámetro de estilo libpq sslrootcert= a la URL: el controlador del gateway lee solo sslmode de la cadena de consulta y reenviaría sslrootcert a Postgres como parámetro de inicio, que el servidor rechaza.El servicio de ECS o los pods de EKS deben ejecutarse en esta VPC para que puedan alcanzar el endpoint privado de la instancia, y el grupo de seguridad claude-gateway-db solo admite el grupo de seguridad del gateway.Escriba gateway.yaml
upstreams apunta a Bedrock con auth: {}, por lo que el gateway se autentica a través de la cadena de credenciales predeterminada de AWS desde el rol de tarea en ECS o el rol de IRSA en EKS. Consulte la referencia de configuración para cada campo.Dos campos listen describen qué está delante del gateway:public_url: el origenhttps://externo, requerido para cualquier enlace que no sea loopback; consulte la referencialisten. El gateway construye elredirect_uridel IdP y su documento de descubrimiento solo a partir de este valor, nunca a partir de encabezadosX-Forwarded-*.trusted_proxies: los rangos de origen del front end. El gateway honraX-Forwarded-Forsolo cuando el par TCP está en esta lista, luego camina la cadena pasada los saltos confiables, por lo que los límites de velocidad de inicio de sesión por IP y los eventos de auditoría registran las IP de los desarrolladores en lugar de la del equilibrador de carga.
trusted_proxies en los CIDR de esas subredes. Esto confía en cada host en esas subredes como un proxy. Mantenga la fuente de ingreso del ALB, su CIDR corporativo, sin superponerse a ellas, y no comparta las subredes con cargas de trabajo no confiables que podrían falsificar las IP de los clientes a través de X-Forwarded-For.El atributo de preservación del puerto del cliente del ALB, routing.http.xff_client_port.enabled, puede permanecer en cualquier configuración: con él activado, el ALB escribe el cliente como 203.0.113.7:54321 o [2001:db8::1]:54321, y el gateway lee ambos con el puerto descartado.oidc es específico de Okta. Para usar Microsoft Entra ID en su lugar, establezca issuer en https://login.microsoftonline.com/<tenant-id>/v2.0, elimine userinfo_fallback y el alcance groups, y tenga en cuenta que Entra emite ID de objeto de grupo en lugar de nombres, por lo que managed.policies debe coincidir en los GUID, o en Roles de Aplicación con oidc.groups_claim: roles. Consulte Configuración del proveedor de identidad.Almacene secretos en AWS Secrets Manager
--secret-string son visibles en la tabla de procesos y en registros de auditoría/EDR mientras se ejecuta cada comando. En un host compartido o monitoreado, coloque el valor en un archivo 0600 y pase --secret-string file://<path> en su lugar. El setup.sh del paquete mantiene los valores secretos fuera de argv del proceso de la misma manera, pasando archivos temporales 0600 a --cli-input-json.gateway.yaml en sí no contiene valores secretos, porque cada credencial se resuelve al arranque a través de expansión ${VAR} o ${file:...}. Cómo todo llega al contenedor difiere por pista:- En ECS, el paso siguiente copia
gateway.yamlen la imagen en/etc/claude/gateway.yaml, y la definición de tarea inyecta los tres secretos como variables de entorno a través de su camposecrets, por lo que el YAML hace referencia a${GATEWAY_JWT_SECRET},${OIDC_CLIENT_SECRET}y${GATEWAY_POSTGRES_URL}. - En EKS, monte
gateway.yamldesde un ConfigMap y los secretos como archivos en/secrets, referenciados como${file:/secrets/...}. Obtenga los Secretos de Kubernetes de Secrets Manager con External Secrets Operator o el proveedor de AWS del controlador CSI de Secrets Store, o créelos directamente conkubectl.
Compile e inserte la imagen en Amazon ECR
linux-x64 en ./claude en el contexto de compilación. Escriba su propio Dockerfile según esos requisitos o comience desde el Dockerfile del paquete, que copia el gateway.yaml completado de los pasos anteriores en la imagen en /etc/claude/gateway.yaml. En ECS esa copia incrustada es cómo la configuración llega al contenedor, por eso la compilación viene después de que se escribe el archivo. La pista de EKS en su lugar monta gateway.yaml desde un ConfigMap en la implementación, por lo que la copia incrustada no se usa allí.La imagen también lleva el paquete de certificados de AWS RDS como el ancla de confianza para la cadena de conexión sslmode=verify-full, así que descárguelo en el contexto de compilación primero. AWS rota el paquete (se añaden nuevas CA regionales), así que descárguelo por compilación en lugar de fijar un checksum o confirmarlo:Dockerfile del paquete ya incluye ambas:<version> que el paso de implementación fija no puede ser reapuntada silenciosamente a una imagen diferente más adelante:linux/amd64, por lo que la plataforma debe coincidir aquí; para Fargate en ARM64 (Graviton), compile linux/arm64 con el binario linux-arm64 y establezca cpuArchitecture en ARM64 en su lugar:Implemente
- ECS Fargate
- EKS
--ip-address-type ipv4 importa: un ALB dual-stack interno publica registros AAAA de rango público, que la verificación de red privada de /login rechaza:--ssl-policy fija un piso TLS moderno, ya que omitirlo vuelve a la política predeterminada heredada ELBSecurityPolicy-2016-08, que aún acepta TLS 1.0/1.1.El ALB cierra una conexión después de 60 segundos sin datos de forma predeterminada. Los pings de keepalive del gateway mantienen los streams dentro de ese predeterminado, por lo que aumentar el tiempo de espera añade margen por encima de la cadencia de ping; la fila Solución de problemas sobre streams descartados cubre el mecanismo y gateways más antiguos. Los comandos a continuación añaden el oyente y aumentan el tiempo de espera:GET /readyz verifica que el almacén sea alcanzable, por lo que una tarea que no puede alcanzar Postgres nunca entra en rotación. Para mantener las tareas pasando la verificación a través de una interrupción breve de la base de datos como una conmutación por error de RDS, establezca store.readiness_grace_seconds como se describe en Comportamiento de interrupción, que también cubre la alternativa /healthz.Las tareas se ejecutan en subredes privadas sin IP pública, por lo que todo el tráfico saliente (a Bedrock, su IdP, Secrets Manager, ECR y CloudWatch Logs) va a través de la puerta de enlace NAT. Para mantener el tráfico de Bedrock fuera de la ruta pública, cree un endpoint de VPC de interfaz bedrock-runtime y apunte el base_url del upstream a él, como se muestra en la referencia de upstream de Bedrock; el IdP aún necesita salida a internet.Termine dando a los desarrolladores un nombre de host privadamente resoluble: en una zona alojada privada de Route 53, alias el nombre DNS interno del gateway al ALB, y establezca listen.public_url en ese nombre de host. El nombre *.elb.amazonaws.com propio del ALB se resuelve en direcciones privadas en un ALB interno, pero no puede llevar su certificado ACM, así que use su propio nombre.Actualice el URI de redirección autorizado del cliente OAuth a <public_url>/oauth/callback antes del primer inicio de sesión. Después de cambiar public_url, recompile e inserte la imagen bajo una etiqueta nueva, registre una nueva revisión de definición de tarea e reimplemente. En ECS la configuración vive en el gateway.yaml incrustado de la imagen, y el gateway construye su origen público solo a partir de esa configuración, ignorando X-Forwarded-Host y X-Forwarded-Proto. X-Forwarded-For se honra para las IP de los clientes solo cuando se establece listen.trusted_proxies.Envía la URL del gateway a las máquinas de los desarrolladores
/login hasta que la URL del gateway esté en sus máquinas. Despliega el fragmento completo de configuración administrada, con forceLoginMethod, forceLoginGatewayUrl y la opción parentSettingsBehavior: "merge", en cada dispositivo mediante MDM. No hay ninguna opción de gateway en el selector de inicio de sesión que un desarrollador pueda seleccionar manualmente.Referencia de Terraform
El paquete complementario enexamples/gateway/aws empaqueta esta página como código:
setup.shsecuencia el tutorial de aprovisionamiento anterior con los mismos comandosaws, en la pista de ECS Fargate. Es idempotente: los recursos existentes se detectan y se omiten, por lo que volver a ejecutarlo es seguro, y cualquier predeterminado se puede anular a través de variable de entorno. Aún crea el secreto del cliente OIDC de Okta y el certificado ACM usted mismo: una ejecución sin ellos omite la implementación de ECS/ALB, nombra las entradas faltantes e imprime el comandocreate-secret; cree ambos y vuelva a ejecutar. El formulario de caso de uso de Bedrock y el alias de Route 53 se imprimen como pasos siguientes en lugar de ejecutarse automáticamente, y el push de MDM del cliente permanece como un paso manual de esta página.gateway.yaml.examplees la plantilla de configuración del paso gateway.yaml, con las claves opcionales incluidas comentadas. Cópielo agateway.yamly reemplace cadaREPLACE_MEantes de compilar.Dockerfilecompila la imagen de tiempo de ejecución desde el binario precompiladolinux-x64y copia sugateway.yamlcompletado en/etc/claude/gateway.yaml, más el paquete de certificados de AWS RDS que ancla elsslmode=verify-fulldel almacén.setup.shdescarga el paquete solo cuando no está ya en el contexto de compilación; elimine el archivo y recompile bajo una etiqueta nueva para recoger una rotación de CA de AWS. El archivo de configuración no contiene valores secretos, ya que cada credencial se resuelve al arranque a través de expansión${VAR}. Una edición de configuración por lo tanto significa una recompilación bajo una etiqueta nueva;setup.shautomatiza esto etiquetando imágenes con un hash del archivo.terraform/aprovisiona el mismo alcance de ECS Fargate de forma declarativa: los grupos de seguridad, roles de IAM, repositorio de ECR, instancia de RDS, secretos de Secrets Manager y el servicio de ECS detrás del ALB interno. La VPC y las subredes privadas permanecen como requisitos previos, pasadas como variables. Terraform crea el repositorio de ECR pero no compila la imagen, y la definición del servicio hace referencia a la imagen, por lo que la aplicación es dos pasadas: una aplicación dirigida para el repositorio, luego la compilación e inserción, luego la aplicación completa. Elterraform/README.mddel paquete cubre las variables, estado remoto y desmontaje.
Solución de problemas
Para errores de arranque y inicio de sesión del gateway, consulte la tabla de solución de problemas agnóstica de plataforma. Las entradas a continuación son específicas de AWS.Telemetría
El gateway te proporciona métricas de uso por desarrollador sin ninguna configuración OTEL por máquina. Claude Code emite métricas, registros y trazas opcionales de OpenTelemetry (OTLP); Monitoring usage cubre todo lo que reporta la CLI. En sesiones iniciadas a través de/login, la CLI marca cada exportación con los atributos de identidad del IdP autenticado user.id, user.email y user.groups, por lo que el uso se agrupa por desarrollador.
La puerta de enlace en sí es un relé OTLP autenticado. Configure telemetry.forward_to junto con listen.public_url, y empujará la configuración del exportador OTEL a cada cliente conectado y reenviará su tráfico OTLP textualmente a cada destino que enumere. Cada destino se suscribe a métricas, registros y trazas de forma independiente, y el valor predeterminado es solo métricas; consulte la referencia de telemetry para los campos por señal y sus compensaciones de sensibilidad. La puerta de enlace no almacena en búfer, agrega ni almacena telemetría, por lo que dónde llegan los datos depende completamente de la configuración del exportador del recopilador.
La telemetría del cliente está desactivada de forma predeterminada; configurar telemetry.forward_to es lo que la activa para los desarrolladores conectados, y cada cliente interactivo muestra un diálogo de aprobación de seguridad para la configuración enviada, como se describe en la referencia de configuración. En AWS, cada señal se asigna a un destino de la siguiente manera.
Client metrics, logs, and traces
Apuntetelemetry.forward_to a un recopilador de OpenTelemetry, como el AWS Distro for OpenTelemetry (ADOT) collector, y exporte desde allí a Amazon CloudWatch, Amazon Managed Service for Prometheus, o cualquier backend OTLP.
Ejecute el recopilador como su propio servicio interno accesible a través de https://; la referencia de telemetry cubre la excepción de loopback y CLAUDE_GATEWAY_ALLOW_LOOPBACK.
Gateway logs
En ECS Fargate, sin configuración adicional: el controladorawslogs entrega stderr de la puerta de enlace, que lleva sus eventos de auditoría y registros operacionales, al grupo de registros /ecs/claude-gateway creado anteriormente. En EKS, los registros de pod no llegan a CloudWatch de forma predeterminada, por lo que el rastro de auditoría se pierde hasta que instale la recopilación de registros: el complemento Amazon CloudWatch Observability con captura de registros de contenedor habilitada, o un DaemonSet de Fluent Bit. En cualquier caso, consulte los registros con CloudWatch Logs Insights e impulse alarmas desde filtros de métricas.
Container metrics
Habilite Container Insights en el clúster conaws ecs update-cluster-settings --cluster claude-gateway --settings name=containerInsights,value=enabled para CPU, memoria y red por tarea. En EKS, instale el complemento Amazon CloudWatch Observability.
Spend
La telemetría muestra el uso después del hecho; los límites de gasto son la vista y el cumplimiento en vivo por desarrollador de la puerta de enlace.Atribución de costos
La puerta de enlace firma cada solicitud de Bedrock con su propio principal, el rol de tarea de ECS o el rol de IRSA de EKS, por lo que de forma predeterminada AWS ve todo ese gasto bajo un único principal de IAM. Hay dos formas de dividirlo en los datos de facturación propios de AWS, y se combinan.Por desarrollador con assume_role
Cree un segundo rol de IAM que contenga los permisos de Bedrock y confíe en el principal de la puerta de enlace, otorgue a ese principal sts:AssumeRole en él, y establezca assume_role con session_name: email en el upstream de Bedrock. La puerta de enlace entonces asume ese rol una vez por desarrollador por hora con el nombre de sesión establecido en su correo electrónico y firma sus solicitudes con el resultado. Requiere una puerta de enlace que ejecute Claude Code v2.1.281 o posterior. El rol también puede estar en otra cuenta de AWS: consulte Bedrock en otra cuenta de AWS. En Terraform, junto al rol de tarea en el paquete de Terraform:
assume_role establecido, la puerta de enlace firma cada llamada de Bedrock, la llamada gratuita de CountTokens para medición de gasto incluida, con las credenciales del rol asumido, por lo que el principal de la puerta de enlace necesita una política de Bedrock propia solo para un upstream sin assume_role.
Debido a que la puerta de enlace llama a STS en tiempo de solicitud, las subredes privadas necesitan una ruta a sts.<region>.amazonaws.com. La puerta de enlace NAT de los requisitos previos proporciona una, y también lo hace un punto de enlace de VPC de interfaz de STS que responde para ese nombre de host. Cada desarrollador activo cuesta una llamada de STS por hora por réplica de puerta de enlace.
Las solicitudes de cada desarrollador llegan a AWS como el principal arn:aws:sts::<account>:assumed-role/<role>/<email>. Para ver el gasto por principal, use una exportación de facturación que incluya datos de principal de IAM; la página de asignación de costos de principal de IAM de AWS cubre cómo habilitarla y qué herramientas de facturación la muestran.
Por equipo con perfiles de inferencia de aplicaciones
Esta ruta utiliza solo las seccionesmodels y managed. Cree un perfil de inferencia de aplicación de Bedrock por equipo y modelo, etiquete cada perfil con el equipo, y active esa etiqueta como etiqueta de asignación de costos. Luego, dé a cada equipo su propio id de modelo en gateway.yaml y fije cada grupo de IdP a sus ids de equipo:
--model platform-claude-opus-4-8, usando el id de su equipo, porque una sesión iniciada sin él ejecuta el modelo predeterminado, que la puerta de enlace rechaza para ellos.
La puerta de enlace aplica availableModels en cada solicitud, no solo en el selector de modelo, y AWS agrupa el gasto por la etiqueta que activó. Sin el catch-all match: {}, un desarrollador que no coincida con ninguna política obtiene cada modelo en el catálogo y puede facturar el perfil de cualquier equipo.
Los costos:
- La configuración crece en proporción a equipos por modelos
- El rol que firma las solicitudes de Bedrock de este upstream también debe tener permiso para invocar los ARN de
application-inference-profile/*. Ese rol es el principal del gateway o, conassume_role, el rol que asume.
Permitir que un desarrollador elija a qué equipo facturar
Para permitir que un desarrollador que trabaja para dos equipos elija a qué equipo factura cada sesión, asigna a ese par de equipos un grupo del IdP y una política propios.Agrega un grupo para el par
team-platform-and-data. Si ya inició sesión, pídele que ejecute /login de nuevo, o espera a la próxima actualización silenciosa, para que el gateway vea el nuevo grupo.Coloca su política en primer lugar
Inicia cada sesión con el id de un equipo
claude --model data-claude-opus-4-8.team-platform. Sus sesiones con el id del equipo de datos fallan con is not in your role's availableModels allowlist, mencionando el modelo predeterminado de Claude Code y no el id que escribió. Si en cambio incluyes ambos grupos de equipo en el groups de una sola política, cualquier miembro de cualquiera de los dos equipos puede facturar al perfil de cualquiera de ellos.
En los límites de gasto propios del gateway, el desarrollador tiene un total y un límite por período, de forma predeterminada el más bajo de los límites de sus grupos, sin importar qué id use una sesión. Para evitar que el límite más bajo de un equipo detenga el trabajo para el otro, establece un límite por usuario para el desarrollador.
Pasos siguientes
- Referencia de configuración: cada opción de
gateway.yaml, incluyendomanaged.policiesytelemetry - Implementación y operaciones: configuración de IdP, verificaciones de salud, rotación de secretos JWT, actualizaciones y el modelo de seguridad
- Descripción general de Claude apps gateway: inicio rápido y conexión de desarrolladores
- Ejemplos de AWS para Claude apps gateway: ejemplos de implementación mantenidos por AWS que cubren una variedad de entornos de clientes