Configura il cluster Amazon EKS per i AI/ML carichi di lavoro utilizzando Terraform

Questa sezione illustra i passaggi per creare l'infrastruttura necessaria per eseguire carichi di lavoro di formazione o inferenza su Amazon EKS utilizzando Terraform. I passaggi includono la creazione di un cluster EKS, GPU-enabled nodi con EKS Auto Mode o Karpenter, uno stack di monitoraggio con Prometheus e Grafana e lo storage Amazon S3 per i pesi dei modelli.

Consulta la documentazione per EKS Auto Mode e Karpenter per ulteriori informazioni su come queste funzionalità forniscono e scalano automaticamente le istanze EC2 nei cluster EKS.

High-level architettura e flusso di lavoro

Il diagramma mostra l'architettura AWS di alto livello per la configurazione di questa sezione.

Prerequisiti

Verifica le versioni dei tuoi strumenti:

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

Passaggio 1: scarica e distribuisci il codice Terraform

Questa procedura dettagliata utilizza il codice Terraform nel repository sample-eks-docs Samples. AWS GitHub Clona il repository in una directory di lavoro:

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

Il repository ha la seguente struttura ai-ml/set-up-cluster/ nella directory in cui hai appena cambiato:

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

Il repository fornisce due percorsi di distribuzione. Scegline solo uno e utilizzalo in tutta la guida.

Opzioni del cluster EKS: EKS Auto Mode e Karpenter autogestito

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

Distribuzione del cluster

Entra nella directory del percorso scelto, inizializza Terraform e applica:

Entrambe le varianti utilizzano per impostazione predefinita la regione. us-east-2 Per eseguire la distribuzione in una regione diversa, aggiungi -var "region=region-code" al terraform apply comando nel passaggio successivo, region-code dov'è la AWS regione in cui desideri eseguire la distribuzione.

Il codice Terraform utilizza tutte le zone di disponibilità disponibili nella regione di destinazione use1-az3usw1-az2, escluse e cac1-az3 perché Amazon EKS non supporta il posizionamento dei piani di controllo in quelle zone.

Esamina gli output di Terraform

Al termine dell'applicazione, Terraform stampa i seguenti output (i valori variano in base alla configurazione):

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"

L'configure_kubectloutput è un comando pronto per l'esecuzione che punta al cluster. kubectl L'model_bucketoutput contiene il nome del bucket S3 per i pesi del modello. L'node_iam_role_nameoutput mostra il ruolo IAM utilizzato dai nodi.

Configura kubectl

Indicate il kubectl nuovo cluster. L'configure_kubectloutput è un comando pronto per l'esecuzione:

eval "$(terraform output -raw configure_kubectl)"

Verifica il cluster

Passaggio 2: crea una GPU dinamica NodePool

Le GPU NodePools sono attivate. Per impostazione predefinita, terraform apply crea il cluster e lo stack di monitoraggio senza capacità GPU e senza fatturazione GPU. Per eseguire il provisioning dei nodi GPU, passate la nodepools variabile con un nome di strategia.

Attivate la spot-ondemand strategia, che prevede il provisioning di istanze G-family GPU con una generazione superiore a 4, utilizzando la capacità Spot con On-Demand come riserva:

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

Questo comando applica i NodeClass modelli NodePool e contenuti nella directory. nodepools/spot-ondemand/ Entrambi i percorsi utilizzano la stessa NodePool API, ma differiscono NodeClass nei NodePool riferimenti.

Entrambi i percorsi mostrano i 0 nodi gpu-inf fino alla pianificazione del carico di lavoro della GPU. EKS Auto Mode e Karpenter avviano i nodi solo quando i Pod in sospeso li richiedono.

Fase 3: Esegui il test con un Pod di esempio

Verifica la NodePool configurazione della GPU con 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

Verifica che il Pod sia pianificato e completato correttamente:

kubectl get pods nvidia-smi

Output previsto:

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

Indica STATUS: Completed che il nvidia-smi comando è stato eseguito ed è terminato. Controlla i log del Pod per vedere la GPU rilevata dal nodo:

kubectl logs nvidia-smi

Output previsto:

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

L'output mostra il modello della GPU, la versione del driver, la versione CUDA e la memoria disponibile. In questo esempio, Karpenter ha effettuato il provisioning di un'istanza G6 con una GPU NVIDIA L4 con 24 GB di memoria. Il modello e la memoria della GPU variano a seconda del tipo di istanza selezionato da Karpenter. Le istanze G5 hanno GPU NVIDIA A10G (24 GB), le istanze G6 hanno GPU NVIDIA L4 (24 GB) e le istanze G6e hanno GPU NVIDIA L40S (48 GB).

Per capire come Karpenter e lo scheduler Kubernetes si sono coordinati per fornire un nodo e posizionare il Pod, controlla gli eventi del ciclo di vita del Pod:

kubectl describe pod nvidia-smi

Output previsto:

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

Questi eventi mostrano la sequenza di pianificazione del Pod: il Pod inizialmente non riesce a pianificare perché non esistono nodi GPU (FailedScheduling), Karpenter ne nomina un nuovo (), lo scheduler assegna il Pod una volta che il nodo è pronto NodeClaim (Nominated), quindi l'immagine del contenitore viene estratta e avviata. Scheduled EKS Auto Mode ha il pull parallelo SOCI (Seekable OCI) installato e configurato di default sulle istanze G, P e Trn e il percorso Karpenter autogestito lo configura esplicitamente tramite il FastImagePull feature gate.

A NodeClaim è una richiesta creata da Karpenter per eseguire il provisioning di un nodo specifico. Mostra il tipo di istanza, il tipo di capacità, l'AZ e se il nodo è pronto:

kubectl get nodeclaims

Output previsto:

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

Il tipo di istanza e l'AZ variano. Qualsiasi G-family istanza con una generazione superiore a 4 è idonea.

kubectl get events | grep InsufficientCapacityError

Fase 4: Aggiungere capacità riservata a (opzionale) NodePool

Sebbene la GPU della Fase 2 NodePool esegua il provisioning di Spot o On-Demand delle istanze in modo dinamico, alcuni casi d'uso richiedono una capacità garantita. Puoi creare un On-Demand Capacity Reservation (ODCR) per assicurarti che la capacità della GPU sia disponibile quando necessario.

Con Terraform, un singolo comando crea l'ODCR, una personalizzazione NodeClass che fa riferimento alla prenotazione per tag e lo aggiorna NodePool per includerlo reserved come tipo di capacità. Terraform contrassegna l'ODCR con nodepool=reserved-spot-ondemand e poi lo NodeClass seleziona in base a quel tag.

Usa i valori predefiniti (g6e.4xlarge, 1 istanza, primo cluster AZ):

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

Scegli il tipo di istanza, il numero e la AZ:

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

L'reservationoggetto supporta i seguenti campi:

Se si InsufficientInstanceCapacity verifica un errore, la prenotazione non può essere soddisfatta nell'AZ specificato. Annulla l'operazione Terraform (Ctrl+C), quindi eseguila nuovamente con un valore diverso: az

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

Dopo l'applicazione, Terraform li aggiorna NodePool per includerereserved, e nei requisiti relativi al tipo di spot capacità. on-demand Karpenter considera l'opzione più conveniente e reserved la lancia per prima. Una volta completata, la prenotazione torna a Spot o. On-Demand

Nel percorso EKS Auto Mode, Terraform crea un codice personalizzato gpu-inf NodeClass (perché il pacchetto default NodeClass è di sola lettura) che fa riferimento all'ODCR tramite tag. capacityReservationSelectorTerms Sul percorso Karpenter autogestito, Terraform riapplica le impostazioni aggiunte e le aggiorna per includere. gpu-inf EC2NodeClass capacityReservationSelectorTerms NodePool reserved

Verifica che l'ODCR sia stato creato:

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)

Verifica i NodeClass riferimenti all'ODCR:

Verifica che NodePool sia pronto:

kubectl get nodepools gpu-inf

Output previsto:

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

Monitoraggio

Terraform ha già fornito l'intero stack di monitoraggio durante la fase 1terraform apply. Lo stack include uno spazio di lavoro Amazon Managed Service for Prometheus (AMP), policy IAM e EKS Pod Identity Associations per l'accesso alla scrittura remota e alle query Grafana di Prometheus, il grafico Helm kube-prometheus-stack (Prometheus, Grafana, kube-state-metrics, node-exporter) e NVIDIA DCGM Exporter per le metriche GPU.

Questa sezione riguarda la verifica dei componenti di monitoraggio implementati.

Verifica i pod di monitoraggio

Attendi che tutti i pod di monitoraggio siano pronti:

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

Output previsto:

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

Accedi a Grafana

Grafana è esposta tramite un AWS Application Load Balancer (ALB) connesso a Internet, limitato al CIDR impostato. var.my_cidr Stampa l'URL del load balancer (attendi uno o due minuti per il provisioning dell'ALB):

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

Apri l'URL nel tuo browser. Accedi con nome utente admin e password con il seguente comando:

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

Verifica la pipeline delle metriche

Per verificare che la pipeline delle metriche funzioni integralmente:

Se up vengono visualizzati i risultati, la pipeline (cluster → Prometheus → AMP → Grafana) funziona.

Convalida le metriche della GPU DCGM

Il DCGM Exporter DaemonSet funziona su nodi GPU e riporta le metriche relative all'utilizzo della GPU, alla memoria, alla temperatura, al consumo energetico, alla larghezza di banda NVLink e all'attività tensoriale.

Verifica l'esportatore DCGM: DaemonSet

kubectl get daemonset dcgm-exporter -n monitoring

Una volta che un nodo GPU è in esecuzione (dal passaggio 2 o dal passaggio 4), dovresti vedere uno o più pod pronti. Per convalidare le metriche DCGM, accedi a Drilldown > Metrics in Grafana e cerca. DCGM_

Convalida le metriche DCGM in Grafana

Per visualizzare la dashboard, vai su Dashboard > Monitoraggio GPU > NVIDIA DCGM Exporter Dashboard.

Dashboard di NVIDIA DCGM Exporter a Grafana

Il modello pesa un secchio S3

Terraform ha già creato un bucket Amazon S3 per memorizzare i pesi dei modelli, uno model-storage-sa ServiceAccount nel default namespace, una policy IAM con ambito per il bucket e un'EKS Pod Identity Association che li collega. I Workload Pod impostati possono leggere e scrivere nel bucket. serviceAccountName: model-storage-sa

Verifica il bucket

Recupera il nome del bucket dagli output di Terraform:

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

Verifica che il bucket esista:

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

Output previsto:

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

Fasi successive

Con il cluster pronto, puoi passare a Load & Serve Model per implementare un modello linguistico di grandi dimensioni e interagire con l'endpoint di inferenza.

Pulizia

Elimina i carichi di lavoro di test in modo che nessun Pod contenga nodi 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