Configurer le cluster Amazon EKS pour les AI/ML charges de travail à l'aide de Terraform

Cette section explique les étapes à suivre pour créer l'infrastructure requise pour exécuter des charges de travail de formation ou d'inférence sur Amazon EKS à l'aide de Terraform. Les étapes incluent la création d'un cluster EKS, de GPU-enabled nœuds avec EKS Auto Mode ou Karpenter, d'une pile de surveillance avec Prometheus et Grafana et du stockage Amazon S3 pour les pondérations des modèles.

Consultez la documentation relative au mode automatique EKS et à Karpenter pour plus d'informations sur la manière dont ces fonctionnalités provisionnent et dimensionnent automatiquement les instances EC2 dans les clusters EKS.

High-level architecture et flux de travail

Le schéma montre l'architecture AWS de haut niveau pour la configuration de cette section.

Conditions préalables

Vérifiez les versions de vos outils :

terraform --version
aws --version
kubectl version --client
jq --version

Étape 1 : Téléchargez et déployez le code Terraform

Cette procédure pas à pas utilise le code Terraform dans le référentiel d'échantillons AWS sample-eks-docs. GitHub Clonez le référentiel dans un répertoire de travail :

git clone git@github.com:aws-samples/sample-eks-docs.git
cd sample-eks-docs/ai-ml/set-up-cluster

Le référentiel a la structure suivante dans le ai-ml/set-up-cluster/ répertoire dans lequel vous venez de changer :

set-up-cluster/
├── scripts/
│   └── cleanup.sh
└── terraform/
    ├── auto-mode/
    └── karpenter/

Le référentiel propose deux voies de déploiement. Choisissez-en une seule et utilisez-la tout au long du guide.

Options du cluster EKS : mode automatique EKS et Karpenter autogéré

export MY_CIDR="$(curl -s https://checkip.amazonaws.com)/32"
terraform apply -var "my_cidr=${MY_CIDR}"

Déploiement du cluster

Accédez au répertoire correspondant au chemin que vous avez choisi, initialisez Terraform et appliquez :

Les deux variantes utilisent par défaut la us-east-2 région. Pour déployer dans une autre région, ajoutez -var "region=region-code" à la terraform apply commande de l'étape suivante la AWS région dans laquelle region-code vous souhaitez effectuer le déploiement.

Le code Terraform utilise toutes les zones de disponibilité disponibles dans la région cible, à l'exception de use1-az3usw1-az2, et cac1-az3 parce qu'Amazon EKS ne prend pas en charge le placement de plans de contrôle dans ces zones.

Passez en revue les sorties Terraform

Une fois l'application terminée, Terraform imprime les sorties suivantes (les valeurs varient en fonction de votre configuration) :

Apply complete! Resources: 74 added, 0 changed, 0 destroyed.

Outputs:

cluster_name         = "ai-eks-docs"
configure_kubectl    = "aws eks update-kubeconfig --region us-east-2 --name ai-eks-docs --alias ai-eks-docs"
configure_model_bucket = "export MODEL_BUCKET=ai-eks-docs-models-20250612abc1"
model_bucket         = "ai-eks-docs-models-20250612abc1"
node_iam_role_name   = "ai-eks-docs-eks-auto-20250612..."
region               = "us-east-2"

La configure_kubectl sortie est une commande prête à être exécutée qui kubectl pointe vers le cluster. La model_bucket sortie contient le nom du compartiment S3 pour les pondérations des modèles. La node_iam_role_name sortie indique le rôle IAM utilisé par les nœuds.

Configurer kubectl

kubectlPointez sur le nouveau cluster. La configure_kubectl sortie est une commande prête à être exécutée :

eval "$(terraform output -raw configure_kubectl)"

Vérifiez le cluster

Étape 2 : Création d'un GPU dynamique NodePool

NodePools Les GPU sont optionnels. Par défaut, terraform apply crée le cluster et la pile de surveillance sans capacité GPU et sans facturation GPU. Pour provisionner des nœuds GPU, transmettez la nodepools variable avec un nom de stratégie.

Activez la spot-ondemand stratégie, qui provisionne des instances G-family GPU d'une génération supérieure à 4, en utilisant la capacité Spot On-Demand comme solution de repli :

terraform apply -var 'nodepools={"spot-ondemand"={}}'

Cette commande applique les NodeClass modèles NodePool et du nodepools/spot-ondemand/ répertoire. Les deux chemins utilisent la même NodePool API, mais leurs NodePool références diffèrent. NodeClass

Les deux chemins indiquent les 0 nœuds gpu-inf jusqu'à ce qu'une charge de travail du GPU soit planifiée. EKS Auto Mode et Karpenter ne lancent des nœuds que lorsque des pods en attente en ont besoin.

Étape 3 : Testez avec un échantillon de pod

Testez la NodePool configuration de votre GPU avec un nvidia-smi Pod :

cat << EOF | kubectl apply -f -
apiVersion: v1
kind: Pod
metadata:
  name: nvidia-smi
  labels:
    guide: ai-eks-docs
spec:
  restartPolicy: OnFailure
  tolerations:
    - key: "nvidia.com/gpu"
      operator: "Exists"
      effect: "NoSchedule"
  containers:
    - name: nvidia-smi
      image: public.ecr.aws/amazonlinux/amazonlinux:2023-minimal
      command: ["nvidia-smi"]
      resources:
        limits:
          nvidia.com/gpu: 1
EOF

Vérifiez que le Pod est planifié et terminé correctement :

kubectl get pods nvidia-smi

Sortie attendue :

NAME         READY   STATUS      RESTARTS   AGE
nvidia-smi   0/1     Completed   0          67s

STATUS: CompletedCela signifie que la nvidia-smi commande a été exécutée et terminée. Consultez les journaux du Pod pour voir le GPU détecté par le nœud :

kubectl logs nvidia-smi

Sortie attendue :

+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 580.159.03             Driver Version: 580.159.03     CUDA Version: 13.0     |
+-----------------------------------------+------------------------+----------------------+
| GPU  Name                 Persistence-M | Bus-Id          Disp.A | Volatile Uncorr. ECC |
| Fan  Temp   Perf          Pwr:Usage/Cap |           Memory-Usage | GPU-Util  Compute M. |
|                                         |                        |               MIG M. |
|=========================================+========================+======================|
|   0  NVIDIA L4                      On  |   00000000:31:00.0 Off |                    0 |
| N/A   41C    P8             13W /   72W |       0MiB /  23034MiB |      0%      Default |
|                                         |                        |                  N/A |
+-----------------------------------------+------------------------+----------------------+

La sortie indique le modèle de GPU, la version du pilote, la version CUDA et la mémoire disponible. Dans cet exemple, Karpenter a provisionné une instance G6 dotée d'un GPU NVIDIA L4 avec 24 Go de mémoire. Le modèle de GPU et la mémoire varient en fonction du type d'instance sélectionné par Karpenter. Les instances G5 sont équipées de GPU NVIDIA A10G (24 Go), les instances G6 de GPU NVIDIA L4 (24 Go) et les instances G6e de GPU NVIDIA L40S (48 Go).

Pour comprendre comment Karpenter et le planificateur Kubernetes se sont coordonnés pour provisionner un nœud et placer le Pod, consultez les événements du cycle de vie du Pod :

kubectl describe pod nvidia-smi

Sortie attendue :

Events:
  Type     Reason            Age   From                   Message
  ----     ------            ----  ----                   -------
  Warning  FailedScheduling  75s   default-scheduler      0/2 nodes are available: 2 node(s) had untolerated taint(s).
  Normal   Nominated         74s   eks-auto-mode/compute  Pod should schedule on: nodeclaim/gpu-inf-z6q75
  Normal   Scheduled         35s   default-scheduler      Successfully assigned default/nvidia-smi to i-0eb897a8302551589
  Normal   Pulling           27s   kubelet                spec.containers{nvidia-smi}: Pulling image "public.ecr.aws/amazonlinux/amazonlinux:2023-minimal"
  Normal   Pulled            22s   kubelet                spec.containers{nvidia-smi}: Successfully pulled image "public.ecr.aws/amazonlinux/amazonlinux:2023-minimal" in 5.625s (5.626s including waiting). Image size: 37440620 bytes.
  Normal   Created           22s   kubelet                spec.containers{nvidia-smi}: Container created
  Normal   Started           21s   kubelet                spec.containers{nvidia-smi}: Container started

Ces événements indiquent la séquence de planification du Pod : le Pod échoue initialement à planifier car aucun nœud GPU n'existe (FailedScheduling), Karpenter en désigne un nouveau NodeClaim (Nominated), le planificateur attribue le Pod une fois que le nœud est prêt (Scheduled), puis l'image du conteneur est extraite et démarrée. Le mode EKS Auto dispose de l'extraction parallèle SOCI (Seekable OCI) installée et configurée par défaut sur les instances G, P et Trn, et le chemin Karpenter autogéré le configure explicitement via la porte des fonctionnalités. FastImagePull

A NodeClaim est une demande créée par Karpenter pour approvisionner un nœud spécifique. Il indique le type d'instance, le type de capacité, AZ, et indique si le nœud est prêt :

kubectl get nodeclaims

Sortie attendue :

NAME            TYPE        CAPACITY   ZONE         NODE                  READY   AGE
gpu-inf-z6q75   g6.xlarge   spot       us-east-2a   i-0eb897a8302551589   True    5m

Le type d'instance et l'AZ varient. Toute G-family instance dont la génération est supérieure à 4 est éligible.

kubectl get events | grep InsufficientCapacityError

Étape 4 : Ajoutez de la capacité réservée au NodePool (facultatif)

Alors que le GPU NodePool de l'étape 2 provisionne le Spot ou On-Demand les instances de manière dynamique, certains cas d'utilisation nécessitent une capacité garantie. Vous pouvez créer une réservation On-Demand de capacité (ODCR) pour vous assurer que la capacité du GPU est disponible en cas de besoin.

Avec Terraform, une seule commande crée l'ODCR, une personnalisation NodeClass qui fait référence à la réservation par tag, et la met à jour NodePool pour l'inclure en reserved tant que type de capacité. Terraform étiquette l'ODCR avec nodepool=reserved-spot-ondemand et le NodeClass sélectionne par cette balise.

Utilisez les valeurs par défaut (g6e.4xlarge, 1 instance, premier cluster de A à Z) :

terraform apply -var 'nodepools={"reserved-spot-ondemand"={reservation={}}}'

Choisissez le type d'instance, le nombre et l'AZ :

terraform apply -var 'nodepools={"reserved-spot-ondemand"={reservation={instance_type="g6e.2xlarge",instance_count=1,az="us-east-2a"}}}'

L'reservationobjet prend en charge les champs suivants :

Si vous obtenez une InsufficientInstanceCapacity erreur, la réservation ne peut pas être exécutée dans la zone Z spécifiée. Annulez l'opération Terraform (Ctrl+C), puis relancez-la avec une valeur différente : az

terraform apply -var 'nodepools={"reserved-spot-ondemand"={reservation={instance_type="g6e.4xlarge",az="us-east-2b"}}}'

Après l'application, Terraform met à jour les exigences NodePool pour inclure reservedspot, et on-demand dans les exigences de type de capacité. Karpenter considère reserved que c'est l'option la plus rentable et la lance en premier. Une fois la réservation complète, elle revient à Spot or On-Demand.

Sur le chemin du mode automatique EKS, Terraform crée une configuration personnalisée gpu-inf NodeClass (car le bundle default NodeClass est en lecture seule) qui fait référence à l'ODCR par balise. capacityReservationSelectorTerms Sur le chemin autogéré de Karpenter, Terraform réapplique le gpu-inf EC2NodeClass with capacityReservationSelectorTerms added et met à jour le to include. NodePool reserved

Vérifiez que l'ODCR a été créé :

aws ec2 describe-capacity-reservations \
  --filters "Name=state,Values=active" "Name=tag:nodepool,Values=reserved-spot-ondemand" \
  --query 'CapacityReservations[0].{Id:CapacityReservationId,State:State,InstanceType:InstanceType,AvailableCount:AvailableInstanceCount}' \
  --output table \
  --region $(terraform output -raw region)

Vérifiez les NodeClass références à l'ODCR :

Vérifiez NodePool qu'il est prêt :

kubectl get nodepools gpu-inf

Sortie attendue :

NAME      NODECLASS   NODES   READY   AGE
gpu-inf   gpu-inf     0       True    30s

cat << 'EOF' | kubectl apply -f -
apiVersion: apps/v1
kind: Deployment
metadata:
  name: gpu-overflow-test
  labels:
    guide: ai-eks-docs
spec:
  replicas: 2
  selector:
    matchLabels:
      app: gpu-overflow-test
  template:
    metadata:
      labels:
        app: gpu-overflow-test
        guide: ai-eks-docs
    spec:
      tolerations:
        - key: nvidia.com/gpu
          operator: Exists
          effect: NoSchedule
      containers:
        - name: nvidia-smi
          image: public.ecr.aws/amazonlinux/amazonlinux:2023-minimal
          command: ["sh", "-c", "nvidia-smi && sleep infinity"]
          resources:
            limits:
              nvidia.com/gpu: 1
EOF

kubectl get pods -l app=gpu-overflow-test -o wide

NAME                                 READY   STATUS    RESTARTS   AGE     IP            NODE                  NOMINATED NODE   READINESS GATES
gpu-overflow-test-55d55ff5b9-dvg52   1/1     Running   0          4m42s   10.0.75.210   i-08741a36089ff2088   <none>           <none>
gpu-overflow-test-55d55ff5b9-hw4m9   1/1     Running   0          4m43s   10.0.82.49    i-0f50cdbacb2017202   <none>           <none>

kubectl get nodeclaims

NAME            TYPE          CAPACITY   ZONE         NODE                  READY   AGE
gpu-inf-vw99m   g6e.4xlarge   reserved   us-east-2c   i-0f50cdbacb2017202   True    6m
gpu-inf-s65s6   g6.xlarge     spot       us-east-2b   i-08741a36089ff2088   True    5m59s

kubectl delete deployment gpu-overflow-test

Contrôle

Terraform a déjà provisionné la pile de surveillance complète lors terraform apply de l'étape 1. La pile comprend un espace de travail Amazon Managed Service for Prometheus (AMP), des politiques IAM et des associations d'identité de pod EKS pour l'écriture à distance de Prometheus et l'accès aux requêtes Grafana, le graphique Helm de la pile kube-prometheus (Prometheus, Grafana, kube-state-metrics, node-exporter) et l'exportateur NVIDIA DCGM pour les métriques GPU.

Cette section couvre la vérification des composants de surveillance déployés.

Vérifiez les modules de surveillance

Attendez que tous les modules de surveillance soient prêts :

kubectl wait --for=condition=Ready pod --all -n monitoring --timeout=300s
kubectl get pods -n monitoring

Sortie attendue :

NAME                                                       READY   STATUS    RESTARTS   AGE
kube-prometheus-stack-grafana-7c58f54f77-rftrj             3/3     Running   0          5m
kube-prometheus-stack-kube-state-metrics-d68dcbc84-5smxq   1/1     Running   0          5m
kube-prometheus-stack-operator-5895df479f-ttm47            1/1     Running   0          5m
kube-prometheus-stack-prometheus-node-exporter-t9q7s       1/1     Running   0          5m
kube-prometheus-stack-prometheus-node-exporter-x6vfb       1/1     Running   0          5m
prometheus-kube-prometheus-stack-prometheus-0              2/2     Running   0          5m

Accédez à Grafana

Grafana est exposé via un équilibreur de charge d' AWS application (ALB) connecté à Internet, limité au CIDR que vous avez défini. var.my_cidr Imprimez l'URL de l'équilibreur de charge (attendez une minute ou deux pour que l'ALB soit provisionné) :

echo "http://$(kubectl get ingress kube-prometheus-stack-grafana -n monitoring -o jsonpath='{.status.loadBalancer.ingress[0].hostname}')"

Ouvrez l'URL dans votre navigateur. Connectez-vous avec le nom d'utilisateur admin et le mot de passe à l'aide de la commande suivante :

kubectl --namespace monitoring get secrets kube-prometheus-stack-grafana -o jsonpath="{.data.admin-password}" | base64 -d ; echo

Vérifiez le pipeline de métriques

Pour vérifier que le pipeline de métriques fonctionne de bout en bout :

Si up les résultats s'affichent, le pipeline (cluster → Prometheus → AMP → Grafana) fonctionne.

Valider les métriques du GPU DCGM

L'exportateur DCGM DaemonSet s'exécute sur des nœuds GPU et indique l'utilisation du GPU, la mémoire, la température, la consommation électrique, la bande passante NVLink et les mesures d'activité des tenseurs.

Vérifiez l'exportateur DaemonSet DCGM :

kubectl get daemonset dcgm-exporter -n monitoring

Une fois qu'un nœud GPU est en cours d'exécution (à partir de l'étape 2 ou de l'étape 4), vous devriez voir apparaître un ou plusieurs pods prêts. Pour valider les métriques DCGM, accédez à Drilldown > Metrics in Grafana et recherchez. DCGM_

Validez les métriques DCGM dans Grafana

Pour afficher le tableau de bord, accédez à Tableaux de bord > Surveillance du GPU > Tableau de bord NVIDIA DCGM Exporter.

Tableau de bord de l'exportateur NVIDIA DCGM dans Grafana

Le modèle pèse le godet S3

Terraform a déjà créé un compartiment Amazon S3 pour stocker les poids des modèles, un model-storage-sa ServiceAccount dans l'defaultespace de noms, une politique IAM limitée au compartiment et une association EKS Pod Identity qui les relie. Les modules de charge de travail qui définissent serviceAccountName: model-storage-sa peuvent lire et écrire dans le compartiment.

Vérifiez le compartiment

Récupérez le nom du compartiment à partir des sorties Terraform :

MODEL_BUCKET=$(terraform output -raw model_bucket)
echo ${MODEL_BUCKET}

Vérifiez que le compartiment existe :

aws s3api head-bucket --bucket ${MODEL_BUCKET}

Sortie attendue :

{
    "BucketArn": "arn:aws:s3:::ai-eks-docs-models-20250612abc1",
    "BucketRegion": "us-east-2",
    "AccessPointAlias": false
}

cat << EOF | kubectl apply -f -
apiVersion: v1
kind: Pod
metadata:
  name: s3-test
  labels:
    guide: ai-eks-docs
spec:
  serviceAccountName: model-storage-sa
  containers:
    - name: aws-cli
      image: public.ecr.aws/aws-cli/aws-cli:2.27.0
      command:
        - sh
        - -c
        - |
          echo "=== Caller Identity ==="
          aws sts get-caller-identity
          echo ""
          echo "=== S3 Write Test ==="
          echo "pod identity works" | aws s3 cp - s3://${MODEL_BUCKET}/test.txt
          echo ""
          echo "=== S3 List Test ==="
          aws s3 ls s3://${MODEL_BUCKET}/
          echo ""
          echo "=== S3 Delete Test ==="
          aws s3 rm s3://${MODEL_BUCKET}/test.txt
  restartPolicy: Never
EOF

kubectl wait --for=jsonpath='{.status.phase}'=Succeeded pod/s3-test --timeout=300s
kubectl logs s3-test

=== Caller Identity ===
{
    "UserId": "AROA...:eks-ai-eks-docs-model-s-...",
    "Account": "123456789012",
    "Arn": "arn:aws:sts::123456789012:assumed-role/ai-eks-docs-models-.../eks-ai-eks-docs-..."
}

=== S3 Write Test ===
upload: - to s3://ai-eks-docs-models-20250612abc1/test.txt

=== S3 List Test ===
2026-07-15 12:00:00         19 test.txt

=== S3 Delete Test ===
delete: s3://ai-eks-docs-models-20250612abc1/test.txt

kubectl delete pod s3-test

Étapes suivantes

Une fois votre cluster prêt, vous pouvez passer au modèle Load & Serve pour déployer un grand modèle de langage et interagir avec le point de terminaison d'inférence.

Nettoyage

Supprimez les charges de travail de test afin qu'aucun pod ne contienne de nœuds GPU :

kubectl delete pod nvidia-smi --ignore-not-found
kubectl delete deployment gpu-overflow-test --ignore-not-found

terraform apply -var 'nodepools={"spot-ondemand"={}}'

kubectl delete pdb -A --all --ignore-not-found
kubectl delete nodeclaim --all --wait=true --timeout=900s

terraform destroy

aws ec2 describe-capacity-reservations \
  --filters "Name=state,Values=active" "Name=tag:nodepool,Values=reserved-spot-ondemand" \
  --query 'CapacityReservations[].CapacityReservationId' \
  --output text