使用 Terraform 為 AI/ML 工作負載設定 Amazon EKS 叢集

本節將逐步引導您建立使用 Terraform 在 Amazon EKS 上執行訓練或推論工作負載所需的基礎設施。這些步驟包括建立 EKS 叢集、使用 EKS Auto Mode 或 Karpenter 啟用 GPU 的節點、使用 Prometheus 和 Grafana 的監控堆疊，以及用於模型權重的 Amazon S3 儲存。

如需這些功能如何在 EKS 叢集中佈建和自動擴展 EC2 執行個體的詳細資訊，請參閱 EKS Auto Mode 和 Karpenter 的文件。 EC2

高階架構和工作流程

圖表顯示本節設定的 AWS 高階架構。

先決條件

驗證您的工具版本：

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

步驟 1：下載並部署 Terraform 程式碼

本演練使用 sample-eks-docs AWS Samples GitHub 儲存庫中的 Terraform 程式碼。將儲存庫複製到工作目錄中：

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

儲存庫在您剛變更為的ai-ml/set-up-cluster/目錄下具有下列結構：

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

儲存庫提供兩個部署路徑。請只選擇一個，並在整個指南中使用它。

EKS 叢集選項：EKS Auto Mode 和自我管理 Karpenter

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

部署叢集

將 變更為所選路徑的 目錄，初始化 Terraform，然後套用：

這兩個變體預設為 us-east-2區域。若要在不同區域中部署，請在下列步驟中將 -var "region=region-code"新增至 terraform apply命令，其中 region-code 是 AWS 您要部署的區域。

Terraform 程式碼使用目標區域中所有可用的可用區域，但 use1-az3、 和 除外usw1-az2，cac1-az3因為 Amazon EKS 不支援在這些區域中放置控制平面。

檢閱 Terraform 輸出

當套用完成時，Terraform 會列印下列輸出 （值根據您的組態而有所不同）：

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_kubectl 輸出是kubectl指向叢集的ready-to-run命令。model_bucket 輸出包含模型權重的 S3 儲存貯體名稱。node_iam_role_name 輸出會顯示節點使用的 IAM 角色。

設定 kubectl

kubectl 指向新的叢集。configure_kubectl 輸出是ready-to-run命令：

eval "$(terraform output -raw configure_kubectl)"

驗證叢集

步驟 2：建立動態 GPU NodePool

GPU NodePools 為選擇加入。根據預設， 會terraform apply建立沒有 GPU 容量且沒有 GPU 計費的叢集和監控堆疊。若要佈建 GPU 節點，請使用策略名稱傳遞 nodepools變數。

啟用 spot-ondemand策略，該策略使用 Spot 容量搭配隨需做為備用，以佈建產生大於 4 的 G 系列 GPU 執行個體：

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

此命令會從 nodepools/spot-ondemand/目錄套用 NodePool 和 NodeClass 範本。兩個路徑都使用相同的 NodePool API，但它們在 NodeClass 中的 NodePool 參考不同。

兩個路徑都會顯示 的0節點，gpu-inf直到排定 GPU 工作負載為止。EKS Auto Mode 和 Karpenter 只會在待定 Pod 需要時啟動節點。

步驟 3：使用範例 Pod 進行測試

使用 Pod 測試 GPU NodePool nvidia-smi 設定：

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

確認 Pod 已排程並成功完成：

kubectl get pods nvidia-smi

預期的輸出結果：

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

STATUS: Completed 表示nvidia-smi命令已執行並結束。檢查 Pod 日誌以查看節點偵測到的 GPU：

kubectl logs nvidia-smi

預期的輸出結果：

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

輸出會顯示 GPU 模型、驅動程式版本、CUDA 版本和可用的記憶體。在此範例中，Karpenter 佈建了具有 NVIDIA L4 GPU 和 24 GB 記憶體的 G6 執行個體。GPU 模型和記憶體會根據 Karpenter 選取的執行個體類型而有所不同。G5 執行個體具有 NVIDIA A10G GPUs (24 GB)、G6 執行個體具有 NVIDIA L4 GPUs (24 GB)，而 G6e 執行個體具有 NVIDIA L40S GPUs (48 GB)。

若要了解 Karpenter 和 Kubernetes 排程器如何協調以佈建節點並放置 Pod，請檢查 Pod 的生命週期事件：

kubectl describe pod nvidia-smi

預期的輸出結果：

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

這些事件會顯示 Pod 排程序列：Pod 一開始無法排程，因為 GPU 節點不存在 (FailedScheduling)，Karpenter 會指定新的 NodeClaim (Nominated)，排程器會在節點就緒時指派 Pod (Scheduled)，然後提取並啟動容器映像。EKS Auto Mode 預設會在 G、P 和 Trn 執行個體上安裝和設定 SOCI （可尋求 OCI) 平行提取，而自我管理 Karpenter 路徑會透過FastImagePull功能閘道明確設定。

NodeClaim 是 Karpenter 建立來佈建特定節點的請求。它會顯示執行個體類型、容量類型、AZ，以及節點是否已就緒：

kubectl get nodeclaims

預期的輸出結果：

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

執行個體類型和 AZ 會有所不同。產生大於 4 的任何 G 系列執行個體都符合資格。

kubectl get events | grep InsufficientCapacityError

步驟 4：將預留容量新增至 NodePool （選用）

雖然步驟 2 的 GPU NodePool 動態佈建 Spot 或隨需執行個體，但某些使用案例需要保證容量。您可以建立隨需容量保留 (ODCR)，以確保 GPU 容量在需要時可用。

使用 Terraform 時，單一命令會建立 ODCR，這是依標籤參考保留的自訂 NodeClass，並更新 NodePool 以包含 reserved做為容量類型。Terraform 使用 標記 ODCR，nodepool=reserved-spot-ondemandNodeClass 會依該標籤選取它。

使用預設值 (g6e.4xlarge、1 個執行個體、第一個叢集 AZ)：

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

選擇執行個體類型、計數和可用區域：

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

reservation 物件支援下列欄位：

如果您收到InsufficientInstanceCapacity錯誤，則無法在指定的 AZ 中完成保留。取消 Terraform 操作 (Ctrl+C)，然後使用不同的az值重新執行：

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

套用後，Terraform 會將 NodePool 更新為在容量類型需求on-demand中包含 spot、 reserved和 。Karpenter reserved將 視為最具成本效益的選項，並優先啟動。一旦保留已滿，就會回到 Spot 或隨需。

在 EKS Auto Mode 路徑上，Terraform 會建立自訂 gpu-inf NodeClass （因為 Bundled default NodeClass 為唯讀），透過 標籤參考 ODCRcapacityReservationSelectorTerms。在自我管理的 Karpenter 路徑上，Terraform 會重新套用 gpu-inf EC2NodeClass，並capacityReservationSelectorTerms新增和更新 NodePool 以包含 reserved。

驗證是否已建立 ODCR：

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)

驗證 NodeClass 參考 ODCR：

驗證 NodePool 已就緒：

kubectl get nodepools gpu-inf

預期的輸出結果：

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

監控

在步驟 1 terraform apply中，Terraform 已在 期間佈建完整的監控堆疊。堆疊包含 Amazon Managed Service for Prometheus (AMP) 工作區、IAM 政策和 EKS Pod Identity Associations for Prometheus remote-write and Grafana 查詢存取、kube-prometheus-stack Helm Chart (Prometheus、Grafana、kube-state-metrics、 node-exporter)，以及適用於 GPU 指標的 NVIDIA DCGM Exporter。

本節涵蓋已部署監控元件的驗證。

驗證監控 Pod

等待所有監控 Pod 就緒：

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

預期的輸出結果：

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

存取 Grafana

Grafana 透過 Internet-facing AWS Application Load Balancer (ALB) 公開，僅限於您在 中設定的 CIDRvar.my_cidr。列印負載平衡器 URL （允許 ALB 佈建一兩分鐘）：

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

在瀏覽器中開啟 URL。從admin下列命令使用使用者名稱和密碼登入：

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

驗證指標管道

若要驗證指標管道是否端對端運作：

如果 up顯示結果，則管道 （叢集 → Prometheus → AMP → Grafana) 正在運作。

驗證 DCGM GPU 指標

DCGM Exporter DaemonSet 會在 GPU 節點上執行，並報告 GPU 使用率、記憶體、溫度、耗電量、NVLink 頻寬和張量活動指標。

驗證 DCGM 匯出工具 DaemonSet：

kubectl get daemonset dcgm-exporter -n monitoring

一旦 GPU 節點執行 （從步驟 2 或步驟 4)，您應該會看到一或多個就緒的 Pod。若要驗證 DCGM 指標，請導覽至 Grafana 中的向下切入 > 指標，並搜尋 DCGM_。

在 Grafana 中驗證 DCGM 指標

若要檢視儀表板，請導覽至儀表板 > GPU 監控 > NVIDIA DCGM 匯出工具儀表板。

Grafana 中的 NVIDIA DCGM 匯出工具儀表板

模型權重 S3 儲存貯體

Terraform 已建立用於存放模型權重的 Amazon S3 儲存貯體、default命名空間中的 model-storage-sa ServiceAccount、範圍為儲存貯體的 IAM 政策，以及連結它們的 EKS Pod Identity Association。設定的工作負載 Pod serviceAccountName: model-storage-sa可以讀取和寫入儲存貯體。

驗證儲存貯體

從 Terraform 輸出擷取儲存貯體名稱：

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

驗證儲存貯體是否存在：

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

預期的輸出結果：

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

後續步驟

叢集準備就緒後，您可以繼續載入並提供模型，以部署大型語言模型並與推論端點互動。

清除

刪除測試工作負載，讓 Pod 不會保留 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