EKS Node Group Creation with eksctl¶
概念概覽
eksctl 建立 Managed NG 的常見陷阱¶
核心知識¶
eksctl 建立 Managed NG 的常見陷阱¶
Launch Template 殘留衝突
exsctl 建立 NG 失敗後會保留殘留 LT，同名重建時報 InvalidLaunchTemplateName.AlreadyExistsException。若無 ec2:DeleteLaunchTemplate 權限，唯一解法是改名重建，殘留 LT 留待管理員清理。
非法欄位 capacityType
exsctl YAML schema 不接受 capacityType 欄位，會報 json: unknown field "capacityType"。直接移除即可，AWS 預設已是 ON_DEMAND。
IAM Role 必須明確指定
新 NG 若用 AmazonEKSAutoNodeRole 而非現有 NG 的 IAM Role，Node CNI 無法初始化（cni plugin not initialized）。必須在 eksctl YAML 明確指定 instanceRoleARN，從現有 NG 複製正確的 Role ARN。
Security Group 必須帶兩個
EKS NG 有兩個 SG：cluster SG（eks-cluster-sg-*）和 remoteAccess SG（eksctl-*-remoteAccess）。兩個都必須在 securityGroups.attachIDs 明確列出，少一個導致 NodeCreationFailure。用 compare_ng_launch_templates.sh 對比現有 NG 的 LT 可快速找出差異。
diskSize 不可從 eksctl describe-nodegroup 讀取
exsctl 讀取現有 NG 的 diskSize 會回傳 null，需從 Launch Template 的 EBS 設定取得真實值（本例為 100GB gp3）。
CloudFormation Stack ROLLBACK_FAILED 強制刪除
建立失敗後 Stack 狀態若為 ROLLBACK_FAILED，需用 --deletion-mode FORCE_DELETE_STACK 才能強制刪除。
經驗教訓¶
-
每次建立 NG 前必須 preflight 檢查確保無 LT/Stack/NG 殘留
-
eksctl YAML 不要加 capacityType 欄位
-
diskSize 要從 Launch Template EBS 設定查，不要信 eksctl describe-nodegroup 的輸出
-
Security Group 要帶齊兩個：cluster SG 和 remoteAccess SG
-
建立失敗無刪除 LT 權限時，直接改名重建是最快解法
常見陷阱¶
-
eksctl 建立失敗後 LT 殘留，同名重建報 AlreadyExistsException
-
capacityType 欄位在 eksctl schema 中非法，直接加會報錯
-
只帶 cluster SG 不帶 remoteAccess SG 導致 NodeCreationFailure
-
diskSize 從 eksctl describe-nodegroup 查到 null，必須改從 LT 查
最佳實踐¶
-
用 compare_ng_launch_templates.sh 對比現有 NG 的 LT，驗證新 NG SG 配置是否一致
-
明確指定 instanceRoleARN，從現有 NG 複製，不要讓 eksctl 自動建立新 Role
-
建立失敗後先確認 Stack 狀態，ROLLBACK_FAILED 需加 --deletion-mode FORCE_DELETE_STACK
相關概念¶
- AWS SSM Session Manager Zero-SSH Deployment
- Cluster Autoscaler ASG Tag Mechanism
- Cluster Autoscaler Node Protection
- EKS Node Group Migration Runbook
- EKS NoExecute Taint Toleration Scheduling
- K8s Web Container Logs/Batch Permission Denied Root Cause
- Mutation Pipeline DB-backed Idempotency Backstop
來源 Sessions¶
| 日期 | Session | 貢獻摘要 |
|---|---|---|
| 2026-04-09 | 9678fdc0-346d-4959-94b9-7caae9731d2f | 完整記錄了用 eksctl 建立 Managed NG 的 5 次失敗與最終成功路徑，涵蓋 LT 衝突、IAM Role、非法欄位、SG 遺漏等所有常見陷阱 |