Créer les groupes de sécurité

Trois groupes de sécurité chaînent le chemin du trafic : votre réseau d'entreprise atteint l'équilibreur de charge sur le port 443, l'équilibreur de charge atteint la passerelle sur le port 8080, et la passerelle atteint Postgres sur le port 5432. Rien d'autre n'est accessible. La façon dont vous les attachez dépend de la piste de calcul :

• Sur ECS Fargate, l'étape de déploiement attache $ALB_SG à l'équilibreur de charge et $GW_SG au service.
• Sur EKS, le contrôleur AWS Load Balancer crée son propre groupe de sécurité frontal pour l'ALB, donc $ALB_SG et $GW_SG ne sont pas utilisés : l'annotation inbound-cidrs de l'étape de déploiement restreint l'écouteur à votre réseau d'entreprise, et le groupe de sécurité de la base de données admet le groupe de sécurité du cluster à la place.

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"

Créer les rôles IAM et soumettre le formulaire de cas d'usage

La passerelle s'exécute avec un rôle de tâche dédié dont la seule permission est d'invoquer les modèles Claude sur Bedrock. Selon la référence upstream Bedrock, la politique doit couvrir à la fois les ARN de profil d'inférence inter-régions et les ARN de modèle de base sous-jacents :

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 a également besoin d'un rôle d'exécution, que l'agent ECS lui-même utilise pour extraire l'image d'ECR et injecter les valeurs Secrets Manager créées ultérieurement. Il est séparé du rôle de tâche que le SDK AWS de la passerelle utilise à l'exécution :

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

La politique nomme un ARN par secret plutôt qu'un wildcard nu gateway-*, qui dans un compte partagé correspondrait également à des secrets non liés ; le suffixe -?????? à la fin correspond exactement au suffixe aléatoire de six caractères que Secrets Manager ajoute à l'ARN de chaque secret. Un -* à la fin serait un glob de préfixe simple et correspondrait également à des noms plus longs tels que gateway-postgres-url-prod.

La politique IAM accorde à la passerelle la permission d'appeler Bedrock, et Bedrock active l'accès au modèle par défaut dans les régions commerciales. La porte au niveau du compte restante est le formulaire de cas d'usage unique d'Anthropic : si personne dans votre compte ne l'a soumis, ouvrez la console Amazon Bedrock, sélectionnez un modèle Anthropic dans le catalogue de modèles et complétez le formulaire. L'accès est accordé immédiatement après la soumission ; consultez Claude Code sur Amazon Bedrock pour le formulaire AWS Organizations et les permissions IAM dont le soumetteur a besoin.

La piste EKS réutilise les deux documents de politique sur un rôle IRSA à la place des deux rôles ECS ; consultez l'étape de déploiement.

Provisionner Amazon RDS pour PostgreSQL

L'instance s'exécute dans les sous-réseaux privés sans adresse publique et avec le chiffrement du stockage activé. La version du moteur est épinglée à Postgres 16, ce qui satisfait le plancher pris en charge de PostgreSQL 14 de la passerelle et garantit que la famille du groupe de paramètres ci-dessous correspond à l'instance.

Tout d'abord, créez le groupe de sous-réseaux qui place la base de données dans les sous-réseaux privés, et un groupe de paramètres avec rds.force_ssl=1 pour que le serveur rejette les connexions en texte brut. La version du moteur est épinglée une fois car la famille du groupe de paramètres doit correspondre à la version majeure du moteur que l'instance exécute :

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"

Ensuite, créez l'instance avec un mot de passe maître généré :

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

L'argument littéral --master-user-password est visible dans la table des processus et dans les journaux d'audit/EDR pendant l'exécution de la commande, la même exposition que celle couverte par la note de l'étape des secrets. Sur un hôte partagé ou surveillé, passez le mot de passe via --cli-input-json à partir d'un fichier 0600 à la place, de la même façon que le setup.sh du bundle.

Attendez que l'instance soit opérationnelle, ce qui peut prendre plusieurs minutes, puis lisez son point de terminaison privé et assemblez la chaîne de connexion que la passerelle utilisera :

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 fait que la passerelle vérifie la chaîne du certificat du serveur RDS et le nom d'hôte, pas seulement le chiffrement. L'ancre de confiance est le bundle de certificats AWS RDS, que l'étape de construction d'image ci-dessous copie à /etc/claude/rds-global-bundle.pem et approuve via NODE_EXTRA_CA_CERTS. N'ajoutez pas de paramètre sslrootcert= de style libpq à l'URL : le pilote de la passerelle lit uniquement sslmode à partir de la chaîne de requête et transmettrait sslrootcert à Postgres en tant que paramètre de démarrage, que le serveur rejette.

Le service ECS ou les pods EKS doivent s'exécuter dans ce VPC pour pouvoir atteindre le point de terminaison privé de l'instance, et le groupe de sécurité claude-gateway-db n'admet que le groupe de sécurité de la passerelle.

Écrire gateway.yaml

Le bloc upstreams pointe vers Bedrock avec auth: {}, donc la passerelle s'authentifie via la chaîne de credentials par défaut d'AWS à partir du rôle de tâche sur ECS ou du rôle IRSA sur EKS. Consultez la référence de configuration pour chaque champ.

Deux champs listen dépendent de ce qui est en face de la passerelle :

• public_url : l'origine https:// externe, requise pour tout bind non-loopback ; consultez la référence listen. La passerelle construit l'redirect_uri de l'IdP et son document de découverte uniquement à partir de cette valeur, jamais à partir des en-têtes X-Forwarded-*.
• trusted_proxies : les plages source du frontal. La passerelle honore X-Forwarded-For uniquement lorsque le pair TCP est dans cette liste, puis parcourt la chaîne au-delà des sauts de confiance, donc les limites de taux de connexion par IP et les événements d'audit enregistrent les adresses IP des développeurs au lieu de celle de l'équilibreur de charge.

Sur les deux pistes, le frontal est un ALB interne, qu'il soit créé directement ou par le contrôleur AWS Load Balancer, et les nœuds d'un ALB prennent des adresses à partir des sous-réseaux auxquels il est attaché, donc définissez trusted_proxies sur les CIDR de ces sous-réseaux. Cela approuve chaque hôte de ces sous-réseaux en tant que proxy. Gardez la source d'entrée de l'ALB, votre CIDR d'entreprise, de ne pas chevaucher, et ne partagez pas les sous-réseaux avec des charges de travail non fiables qui pourraient usurper les adresses IP des clients via X-Forwarded-For.

L'attribut de préservation du port client de l'ALB, routing.http.xff_client_port.enabled, peut rester à l'un ou l'autre paramètre : avec lui activé, l'ALB écrit le client comme 203.0.113.7:54321 ou [2001:db8::1]:54321, et la passerelle lit les deux avec le port supprimé.

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]
# Le serveur d'autorisation org Okta retourne un id_token mince qui omet
# l'email et les groupes ; la passerelle les remplit à partir de /userinfo.
userinfo_fallback: true
# Okta émet des groupes uniquement lorsque la portée `groups` est demandée et que
# le filtre de revendication de groupes de l'application les autorise.
scopes: [openid, profile, email, offline_access, groups]

session:
jwt_secret: ${GATEWAY_JWT_SECRET}              # EKS: ${file:/secrets/jwt-secret}
ttl_hours: 8 # limite la latence de déprovision ; réduire
# vers 1 pour une révocation plus stricte

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

upstreams:
- provider: bedrock
region: <your-region>                        # correspondre à $AWS_REGION pour que les ARN de la politique IAM
# le couvrent
auth: {} # chaîne de credentials par défaut d'AWS :
# rôle de tâche ECS, ou IRSA sur EKS

Stocker les secrets dans AWS Secrets Manager

Créez trois secrets ; le rôle d'exécution de l'étape IAM peut déjà les lire :

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"

Notez l'ARN que chaque appel imprime ; la définition de tâche ECS référence les secrets par ARN.

Contrairement aux secrets, gateway.yaml lui-même ne contient aucune valeur secrète, car chaque credential se résout au démarrage via l'expansion ${VAR} ou ${file:...}. La façon dont tout atteint le conteneur diffère selon la piste :

• Sur ECS, l'étape de construction suivante copie gateway.yaml dans l'image à /etc/claude/gateway.yaml, et la définition de tâche injecte les trois secrets en tant que variables d'environnement via son champ secrets, donc le YAML référence ${GATEWAY_JWT_SECRET}, ${OIDC_CLIENT_SECRET} et ${GATEWAY_POSTGRES_URL}.
• Sur EKS, montez gateway.yaml à partir d'une ConfigMap et les secrets en tant que fichiers à /secrets, référencés comme ${file:/secrets/...}. Sourcez les secrets Kubernetes à partir de Secrets Manager avec External Secrets Operator ou le pilote AWS du pilote CSI Secrets Store, ou créez-les directement avec kubectl.

Construire et pousser l'image vers Amazon ECR

Construisez l'image selon les exigences d'image de conteneur, en plaçant le binaire glibc linux-x64 à ./claude dans le contexte de construction. Écrivez votre propre Dockerfile selon ces exigences ou commencez par le Dockerfile du bundle, qui copie le gateway.yaml rempli des étapes précédentes dans l'image à /etc/claude/gateway.yaml. Sur ECS, cette copie intégrée est la façon dont la configuration atteint le conteneur, c'est pourquoi la construction vient après l'écriture du fichier. La piste EKS monte plutôt gateway.yaml à partir d'une ConfigMap au déploiement, donc la copie intégrée n'est pas utilisée là.

L'image porte également le bundle de certificats AWS RDS comme ancre de confiance pour la chaîne de connexion sslmode=verify-full, donc téléchargez-le d'abord dans le contexte de construction. AWS fait tourner le bundle (les nouvelles autorités de certification régionales sont ajoutées), donc téléchargez-le par construction plutôt que d'épingler une somme de contrôle ou de le valider :

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

Les exigences d'image de conteneur ne couvrent pas le bundle, donc si vous écrivez votre propre Dockerfile, ajoutez les deux lignes qui le copient et le font confiance ; le Dockerfile du bundle les inclut déjà :

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

Créez le référentiel ECR et connectez Docker à celui-ci. Les balises immuables signifient que la balise <version> que l'étape de déploiement épingle ne peut pas être ultérieurement silencieusement réorientée vers une image différente :

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"

Construisez et poussez l'image. La définition de tâche ci-dessous exécute linux/amd64, donc la plateforme doit correspondre ici ; pour Fargate sur ARM64 (Graviton), construisez linux/arm64 avec le binaire linux-arm64 et définissez cpuArchitecture sur ARM64 à la place :

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

Déployer

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

Pousser l'URL de la passerelle vers les machines des développeurs

La passerelle s'exécute maintenant, mais les développeurs ne peuvent pas la atteindre à partir de /login jusqu'à ce que l'URL de la passerelle soit sur leurs machines. Définissez forceLoginMethod et forceLoginGatewayUrl dans le fichier de paramètres gérés que vous déployez sur chaque appareil via MDM. Il n'y a pas d'option de passerelle dans le sélecteur de connexion pour qu'un développeur sélectionne manuellement.