Menyiapkan cluster Amazon EKS untuk AI/ML beban kerja menggunakan Terraform

Bagian ini memandu Anda melalui langkah-langkah untuk membuat infrastruktur yang diperlukan untuk menjalankan beban kerja pelatihan atau inferensi di Amazon EKS dengan menggunakan Terraform. Langkah-langkahnya termasuk membuat cluster EKS, GPU-enabled node dengan EKS Auto Mode atau Karpenter, tumpukan pemantauan dengan Prometheus dan Grafana, dan penyimpanan Amazon S3 untuk bobot model.

Lihat dokumentasi untuk Mode Otom atis EKS dan Karpenter untuk informasi selengkapnya tentang bagaimana fitur tersebut menyediakan dan menskalakan instans EC2 secara otomatis di cluster EKS.

High-level arsitektur dan alur kerja

Diagram menunjukkan arsitektur AWS tingkat tinggi untuk pengaturan bagian ini.

Prasyarat

Verifikasi versi alat Anda:

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

Langkah 1: Unduh dan terapkan kode Terraform

Panduan ini menggunakan kode Terraform di repositori Samples sample-eks-docs AWS . GitHub Kloning repositori ke direktori kerja:

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

Repositori memiliki struktur berikut di bawah ai-ml/set-up-cluster/ direktori yang baru saja Anda ubah menjadi:

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

Repositori menyediakan dua jalur penerapan. Pilih hanya satu dan gunakan di seluruh panduan.

Opsi cluster EKS: Mode Otomatis EKS dan Karpenter yang dikelola sendiri

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

Menyebarkan cluster

Ubah ke direktori untuk jalur yang Anda pilih, inisialisasi Terraform, dan terapkan:

Kedua varian default ke us-east-2 wilayah. Untuk menerapkan di wilayah yang berbeda, tambahkan -var "region=region-code" ke terraform apply perintah pada langkah berikut, di region-code mana Wil AWS ayah yang ingin Anda terapkan.

Kode Terraform menggunakan semua Zona Ketersediaan yang tersedia di wilayah target, tidak termasuk, use1-az3usw1-az2, dan cac1-az3 karena Amazon EKS tidak mendukung penempatan pesawat kontrol di zona tersebut.

Tinjau keluaran Terraform

Ketika aplikasi selesai, Terraform mencetak output berikut (nilainya bervariasi berdasarkan konfigurasi Anda):

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"

configure_kubectlOutputnya adalah perintah siap dijalankan yang kubectl menunjuk ke cluster. model_bucketOutput berisi nama bucket S3 untuk bobot model. node_iam_role_nameOutput menunjukkan peran IAM yang digunakan node.

Konfigurasikan kubectl

kubectlArahkan ke cluster baru. configure_kubectlOutputnya adalah perintah siap dijalankan:

eval "$(terraform output -raw configure_kubectl)"

Verifikasi cluster

Langkah 2: Buat GPU dinamis NodePool

GPU NodePools adalah opt-in. Secara default, membuat terraform apply cluster dan tumpukan pemantauan tanpa kapasitas GPU dan tanpa penagihan GPU. Untuk menyediakan node GPU, berikan nodepools variabel dengan nama strategi.

Aktif spot-ondemand kan strategi, yang menyediakan instans G-family GPU dengan generasi lebih besar dari 4, menggunakan kapasitas Spot dengan On-Demand sebagai fallback:

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

Perintah ini menerapkan NodeClass template NodePool dan dari nodepools/spot-ondemand/ direktori. Kedua jalur menggunakan NodePool API yang sama, tetapi mereka berbeda NodeClass dalam NodePool referensi.

Kedua jalur menunjukkan 0 node gpu-inf hingga beban kerja GPU dijadwalkan. Mode Otomatis EKS dan Karpenter hanya meluncurkan node ketika Pod yang tertunda membutuhkannya.

Langkah 3: Uji dengan Pod sampel

Uji NodePool pengaturan GPU Anda dengan 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

Verifikasi Pod telah dijadwalkan dan berhasil diselesaikan:

kubectl get pods nvidia-smi

Keluaran yang diharapkan

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

STATUS: CompletedArtinya nvidia-smi perintah berjalan dan keluar. Periksa log Pod untuk melihat GPU yang terdeteksi oleh node:

kubectl logs nvidia-smi

Keluaran yang diharapkan

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

Output menunjukkan model GPU, versi driver, versi CUDA, dan memori yang tersedia. Dalam contoh ini, Karpenter menyediakan instance G6 yang memiliki GPU NVIDIA L4 dengan memori 24 GB. Model GPU dan memori bervariasi tergantung pada jenis instance yang dipilih Karpenter. Instans G5 memiliki GPU NVIDIA A10G (24 GB), instans G6 memiliki GPU NVIDIA L4 (24 GB), dan instans G6e memiliki GPU NVIDIA L40S (48 GB).

Untuk memahami bagaimana Karpenter dan penjadwal Kubernetes berkoordinasi untuk menyediakan node dan menempatkan Pod, periksa peristiwa siklus hidup Pod:

kubectl describe pod nvidia-smi

Keluaran yang diharapkan

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

Peristiwa ini menunjukkan urutan penjadwalan Pod: Pod awalnya gagal menjadwalkan karena tidak ada node GPU (FailedScheduling), Karpenter menominasikan new NodeClaim (Nominated), penjadwal menetapkan Pod setelah node siap (Scheduled), dan kemudian image container ditarik dan dimulai. Mode Otomatis EKS memiliki tarik paralel SOCI (Seekable OCI) yang diinstal dan dikonfigurasi secara default pada instance G, P, dan Trn, dan jalur Karpenter yang dikelola sendiri mengonfigurasinya secara eksplisit melalui gerbang fitur. FastImagePull

A NodeClaim adalah permintaan yang dibuat Karpenter untuk menyediakan node tertentu. Ini menunjukkan jenis instance, tipe kapasitas, AZ, dan apakah node siap:

kubectl get nodeclaims

Keluaran yang diharapkan

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

Jenis instance dan AZ bervariasi. Inst G-family ans apa pun dengan generasi lebih dari 4 memenuhi syarat.

kubectl get events | grep InsufficientCapacityError

Langkah 4: Tambahkan kapasitas cadangan ke NodePool (opsional)

Sementara GPU NodePool dari Langkah 2 menyediakan Spot atau On-Demand instance secara dinamis, beberapa kasus penggunaan memerlukan kapasitas yang dijamin. Anda dapat membuat Reservasi On-Demand Kapasitas (ODCR) untuk memastikan kapasitas GPU tersedia bila diperlukan.

Dengan Terraform, satu perintah membuat ODCR, kustom NodeClass yang mereferensikan reservasi berdasarkan tag, dan memperbarui NodePool untuk disertakan reserved sebagai tipe kapasitas. Terraform menandai ODCR dengan nodepool=reserved-spot-ondemand dan memilihnya dengan NodeClass tag itu.

Gunakan default (g6e.4xlarge, 1 instance, cluster pertama AZ):

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

Pilih jenis instance, hitungan, dan AZ:

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

Ob reservation jek mendukung bidang berikut:

Jika Anda mendapatkan InsufficientInstanceCapacity kesalahan, reservasi tidak dapat dipenuhi di AZ yang ditentukan. Batalkan operasi Terraform (Ctrl+C), lalu jalankan kembali dengan nilai yang berbeda: az

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

Setelah mendaftar, Terraform memperbarui NodePool untuk menyertakanreserved,spot, dan on-demand dalam persyaratan tipe kapasitas. Karpenter memperlakukan reserved sebagai opsi yang paling hemat biaya dan meluncurkannya terlebih dahulu. Setelah reservasi penuh, reservasi akan kembali ke Spot atau On-Demand.

Pada jalur Mode Otomatis EKS, Terraform membuat kustom gpu-inf NodeClass (karena yang dibundel default NodeClass adalah read-only) yang mereferensikan ODCR berdasarkan tag melalui. capacityReservationSelectorTerms Pada jalur Karpenter yang dikelola sendiri, Terraform menerapkan kembali gpu-inf EC2NodeClass dengan capacityReservationSelectorTerms menambahkan dan memperbarui untuk disertakan. NodePool reserved

Verifikasi ODCR telah dibuat:

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)

Verifikasi NodeClass referensi ODCR:

Verifikasi NodePool sudah siap:

kubectl get nodepools gpu-inf

Keluaran yang diharapkan

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

Memantau

Terraform sudah menyediakan tumpukan pemantauan penuh selama terraform apply di Langkah 1. Tumpukan tersebut mencakup ruang kerja Amazon Managed Service for Prometheus (AMP), kebijakan IAM dan Asosiasi Identitas Pod EKS untuk akses kueri penulisan jarak jauh dan Grafana Prometheus, bagan Helm kube-prometheus-stack (Prometheus, Grafana, kube-state-metrics, node-eksportir), dan Eksportir NVIDIA DCGM untuk metrik GPU.

Bagian ini mencakup verifikasi komponen pemantauan yang digunakan.

Verifikasi pod pemantauan

Tunggu hingga semua pod pemantauan siap:

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

Keluaran yang diharapkan

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

Akses Grafana

Grafana diekspos melalui Application Load Balancer (ALB) yang menghadap ke internet AWS , terbatas pada CIDR yang Anda tetapkan. var.my_cidr Cetak URL penyeimbang beban (izinkan satu atau dua menit untuk penyediaan ALB):

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

Buka URL di browser Anda. Masuk dengan nama pengguna admin dan kata sandi dari perintah berikut:

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

Verifikasi pipeline metrik

Untuk memverifikasi pipeline metrik bekerja dari ujung ke ujung:

Jika up menunjukkan hasil, pipeline (cluster → Prometheus → AMP → Grafana) berfungsi.

Validasi metrik GPU DCGM

Eksportir DCGM DaemonSet berjalan pada node GPU dan melaporkan pemanfaatan GPU, memori, suhu, daya tarik, bandwidth NVLink, dan metrik aktivitas tensor.

Verifikasi eksportir DCGM: DaemonSet

kubectl get daemonset dcgm-exporter -n monitoring

Setelah node GPU berjalan (dari Langkah 2 atau Langkah 4), Anda akan melihat satu atau lebih Pod siap. Untuk memvalidasi metrik DCGM, navigasikan ke Drilldown > Metrics di Grafana dan cari. DCGM_

Validasi metrik DCGM di Grafana

Untuk melihat dasbor, navigasikan ke Dasbor> Pemantauan GPU> Dasbor Eksportir NVIDIA DCGM.

Dasbor Eksportir NVIDIA DCGM di Grafana

Model bobot ember S3

Terraform sudah membuat bucket Amazon S3 untuk menyimpan bobot model, a model-storage-sa ServiceAccount di default namespace, kebijakan IAM yang dicakup ke bucket, dan EKS Pod Identity Association yang menautkannya. Pod beban kerja yang diatur serviceAccountName: model-storage-sa dapat membaca dari dan menulis ke bucket.

Verifikasi ember

Ambil nama bucket dari output Terraform:

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

Verifikasi bucket ada:

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

Keluaran yang diharapkan

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

Langkah selanjutnya

Dengan cluster Anda siap, Anda dapat melanjutkan ke Load & Serve Model untuk menerapkan model bahasa besar dan berinteraksi dengan titik akhir inferensi.

Pembersihan

Hapus beban kerja pengujian sehingga tidak ada Pod yang menahan node 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