EKS Node Group Migration Runbook¶
概念概覽
遷移前置條件¶
核心知識¶
遷移前置條件¶
- 必須先關閉 EKS Auto Mode：Auto Mode 開啟時縮減舊 Node Group 會觸發非預期 c 系列節點擴展
- 確認無殘留 DELETING ng 後再建立新 ng
- 建立前先驗證 Node Role 已附加
AmazonEKS_CNI_Policy
五層失敗診斷優先順序¶
- ASG N/A → 不一定是 Subnet IP 不足，可能是 developer 缺少
ec2:DescribeInstances權限 - CloudFormation StackEvents →
NodeCreationFailure: Unhealthy nodes確認 EC2 已建立但未健康加入 - aws-node ½ Running → CNI 層問題，非控制平面問題
- Probe 訊息 :50051 → IPAM daemon 無法啟動的精確訊號
- hop limit / SG / IAM Node Role Policy → 三者需同時確認，不能只查一個
IAM 限制繞過方式¶
developer 帳號通常缺少 eks:DescribeClusterVersions（eksctl 403）與 ec2:DescribeInstances：
- 改用 aws eks list-nodegroups 取代 eksctl get nodegroup
- 透過 CloudFormation StackEvents 查失敗原因（不需 ec2 權限）
- kubectl get pods -n kube-system 觀察 aws-node 狀態
關鍵操作注意¶
- CloudFormation JMESPath
--query參數**不能換行**，否則 parse error Health.issues空陣列只代表 EKS 控制平面無問題，真正失敗需查 CloudFormation StackEvents- 新 ng 的 aws-node 必須全部 2/2 Running（不是 ½）才能開始 Drain 舊節點
- 建立後 5-10 分鐘即可早期診斷，無需等 20 分鐘超時
經驗教訓¶
-
Auto Mode 必須在手動 ng 操作前關閉，否則會觸發非預期節點擴展干擾遷移
-
CloudFormation StackEvents 是 developer 帳號受限時的主要診斷工具
-
Health.issues 空陣列不等於節點健康，不要被這個誤導
常見陷阱¶
-
ASG Name 顯示 N/A 不代表 ASG 未建立，可能是 IAM 權限問題
-
Health.issues 空陣列不代表萬事 OK，真正失敗需查 CloudFormation StackEvents
-
eksctl get nodegroup 需要 eks:DescribeClusterVersions，developer IAM 通常缺少
最佳實踐¶
-
遷移前先關閉 EKS Auto Mode
-
建立 ng 後 5-10 分鐘即可觀察 aws-node pod 狀態做早期診斷
-
使用 aws cli 而非 eksctl，因為 developer 帳號通常缺少 eks:DescribeClusterVersions
-
CloudFormation --query 參數必須寫在同一行，不能換行
相關概念¶
- Alertmanager ExternalSecret
- aws-node CNI IPAM Daemon Diagnosis
- CCU Capacity Planning（壓測數據推算法）
- Cluster Autoscaler Node Protection
- eks-auto-mode----dangling-------dangling---
- eks-node-group----dangling-------dangling---
- EKS Node Group Creation with eksctl
- EKS NoExecute Taint Toleration Scheduling
- Jenkins Pipeline kubectl exec Target
- K8s 多站點分支 Image 部署診斷
- Kubernetes env vs envFrom Precedence
- MSK IAM Auth JAR Classpath 管理
- Observability Maturity Framework
- Preview Environment PR-Level Isolation
- RDS PostgreSQL Connection Pool (Transaction Mode)
相關視角¶
以下頁面與本概念共享主題，但從不同角度切入。保留獨立視角同時提供交叉參考：
- Cluster Autoscaler ASG Tag Mechanism — 共享：
asg,eks,eksctl/ 獨特：cluster-autoscaler,node-protection
來源 Sessions¶
| 日期 | Session | 貢獻摘要 |
|---|---|---|
| 2026-03-23 | 030a873f-a7ad-47be-aaa1-7556ee57df36 | 記錄 m7i.2xlarge → t3.xlarge 藍綠遷移的四次失敗根因與完整五層診斷鏈，含多個被推翻的假設 |