Cree los grupos de seguridad

Tres grupos de seguridad encadenan la ruta del tráfico: su red corporativa alcanza el equilibrador de carga en 443, el equilibrador de carga alcanza el gateway en 8080, y el gateway alcanza Postgres en 5432. Nada más es alcanzable. Cómo los adjunta depende de la pista de computación:

• En ECS Fargate, el paso de implementación adjunta $ALB_SG al equilibrador de carga y $GW_SG al 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_SG y $GW_SG no se usan: la anotación inbound-cidrs del 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.

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"

Cree los roles de IAM y envíe el formulario de caso de uso

El gateway se ejecuta con un rol de tarea dedicado cuyo único permiso es invocar modelos de Claude en Bedrock. Según la referencia de upstream de Bedrock, la política debe cubrir tanto los ARN de perfil de inferencia entre regiones como los ARN de modelo base subyacentes:

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 también necesita un rol de ejecución, que el agente de ECS mismo usa para extraer la imagen de ECR e inyectar los valores de Secrets Manager creados más adelante. Es separado del rol de tarea que el AWS SDK del gateway usa en tiempo de ejecución:

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

Los nombres de política especifican un ARN por secreto en lugar de un comodín simple 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.

Aprovisione Amazon RDS para PostgreSQL

La instancia se ejecuta en las subredes privadas sin dirección pública y con cifrado de almacenamiento activado. La versión del motor se fija en Postgres 16, que satisface el piso compatible del gateway de PostgreSQL 14 y garantiza que la familia del grupo de parámetros a continuación coincida con la instancia.

Primero, cree el grupo de subredes que coloca la base de datos en las subredes privadas, y un grupo de parámetros con 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:

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"

Luego cree la instancia con una contraseña maestra generada:

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

El argumento literal --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:

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 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

El bloque 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 origen https:// externo, requerido para cualquier enlace que no sea loopback; consulte la referencia listen. El gateway construye el redirect_uri del IdP y su documento de descubrimiento solo a partir de este valor, nunca a partir de encabezados X-Forwarded-*.
• trusted_proxies: los rangos de origen del front end. El gateway honra X-Forwarded-For solo 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.

En ambas pistas el front end es un ALB interno, ya sea creado directamente o por el Controlador de Equilibrador de Carga de AWS, y los nodos de un ALB toman direcciones de las subredes a las que está adjunto, por lo que establezca 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.

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]
# El servidor de autorización de la organización de Okta devuelve un id_token delgado que omite
# correo electrónico y grupos; el gateway los completa desde /userinfo.
userinfo_fallback: true
# Okta emite grupos solo cuando se solicita el alcance `groups` y el
# filtro de reclamación de grupos de la aplicación los permite.
scopes: [openid, profile, email, offline_access, groups]

session:
jwt_secret: ${GATEWAY_JWT_SECRET}              # EKS: ${file:/secrets/jwt-secret}
ttl_hours: 8 # limita la latencia de desaprovisionamiento; baje
# hacia 1 para una revocación más ajustada

store:
postgres_url: ${GATEWAY_POSTGRES_URL}          # EKS: ${file:/secrets/postgres-url}

upstreams:
- provider: bedrock
region: <your-region>                        # coincida con $AWS_REGION para que los ARN de la política de IAM
# lo cubran
auth: {} # cadena de credenciales predeterminada de AWS:
# rol de tarea de ECS, o IRSA en EKS

Almacene secretos en AWS Secrets Manager

Cree tres secretos; el rol de ejecución del paso de IAM ya puede leerlos:

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"

Tenga en cuenta el ARN que imprime cada llamada; la definición de tarea de ECS hace referencia a los secretos por ARN.

A diferencia de los secretos, 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.yaml en 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 campo secrets, por lo que el YAML hace referencia a ${GATEWAY_JWT_SECRET}, ${OIDC_CLIENT_SECRET} y ${GATEWAY_POSTGRES_URL}.
• En EKS, monte gateway.yaml desde 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 con kubectl.

Compile e inserte la imagen en Amazon ECR

Compile la imagen según los requisitos de imagen de contenedor, colocando el binario glibc 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:

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

Los requisitos de imagen de contenedor no cubren el paquete, así que si escribe su propio Dockerfile, agregue las dos líneas que lo copian y confían; el Dockerfile del paquete ya incluye ambas:

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

Cree el repositorio de ECR e inicie sesión en Docker. Las etiquetas inmutables significan que la etiqueta <version> que el paso de implementación fija no puede ser reapuntada silenciosamente a una imagen diferente más adelante:

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"

Compile e inserte la imagen. La definición de tarea a continuación ejecuta 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:

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>"

Implemente

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

{
"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_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)"

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"

BEDROCK_POLICY_ARN="$(aws iam create-policy --policy-name claude-gateway-bedrock-invoke \
--policy-document file://bedrock-invoke.json --query Policy.Arn --output text)"
SECRETS_POLICY_ARN="$(aws iam create-policy --policy-name claude-gateway-secrets-read \
--policy-document file://secrets-read.json --query Policy.Arn --output text)"

kubectl create namespace claude-gateway
eksctl create iamserviceaccount --cluster <your-cluster> --region "$AWS_REGION" \
--namespace claude-gateway --name gateway --role-name claude-gateway \
--attach-policy-arn "$BEDROCK_POLICY_ARN" \
--attach-policy-arn "$SECRETS_POLICY_ARN" \
--approve

Inserte la URL del gateway en las máquinas de los desarrolladores

El gateway ahora se está ejecutando, pero los desarrolladores no pueden alcanzarlo desde /login hasta que la URL del gateway esté en sus máquinas. Establezca forceLoginMethod y forceLoginGatewayUrl en el archivo de configuración administrada que implementa en cada dispositivo a través de MDM. No hay opción de gateway en el selector de inicio de sesión para que un desarrollador seleccione manualmente.