EKS locust-eks 叢集升級實戰：1.32 → 1.33 完整流程（Control Plane + Add-on + Node Group）¶

文檔資訊

分類: tools
難度: advanced
預估閱讀時間: 25 分鐘
標籤: EKS, Kubernetes, upgrade, add-on, timeout, vpc-cni, coredns, eksctl, pre-upgrade-check, resolve-conflicts, OVERWRITE, CrashLoopBackOff, aws-node, CNI, gRPC, grpc-health-probe, pod-rescheduling, nodegroup, NodeCreationFailure, CloudFormation, ASG, rolling-upgrade

摘要¶

記錄對 locust-eks（ap-southeast-1）執行 Kubernetes 1.32→1.33 升級的**完整四階段流程**：前置檢查 → Control Plane 升級（7分鐘）→ Add-on 升級（含 PRESERVE timeout、OVERWRITE 重試、aws-node CrashLoopBackOff 根因排查、coredns 重新排程解決）→ Node Group 升級（eksctl 首次失敗 NodeCreationFailure、debug 腳本診斷、AWS API 直接觸發成功）。

關鍵學習¶

腳本參數必須使用 flag 格式（-c/-r/-t），不支援 positional arguments
EKS Control Plane 升級（1.32→1.33）使用 eksctl 約需 7 分鐘，升級後無法 rollback
Add-on 升級使用 PRESERVE 模式在 ARM 架構環境可能 timeout（>31分鐘），建議改用 OVERWRITE
Add-on 卡在 UPDATING 的根本原因可能是特定節點的 aws-node CrashLoopBackOff（grpc-health-probe :50051 失敗）
解決 coredns ContainerCreating 卡住：刪除 Pod 讓 Deployment 重新排程到健康節點，不需修好問題節點
aws-ebs-csi-driver 可能出現 UPDATE_FAILED，需手動用 OVERWRITE 重試
eksctl upgrade nodegroup 失敗時，透過 CloudFormation stack events 查看 NodeCreationFailure 原因
Node Group 升級卡住時可改用 aws eks update-nodegroup-version API 直接觸發，並透過 ASG 活動和 console output 追蹤新節點啟動狀態
eksctl nodegroup upgrade 和 aws eks update-nodegroup-version 是兩種不同的觸發方式，後者更直接可控
問題節點（ip-192-168-95-51，aws-node CrashLoopBackOff）在 Node Group Rolling Upgrade 過程中自然被替換終止

技術細節¶

叢集基本資訊¶

叢集名稱：locust-eks
Region：ap-southeast-1
升級路徑：1.32 → 1.33
節點數量：6 個（升級後期減為 5 個），機型 c7g.2xlarge（ARM 架構）
kubelet 版本：v1.32.9-eks-ecaa3a6（全叢集一致，升級前）

Add-on 最終升級版本對照表¶

Add-on	升級前版本	最終版本	備註
vpc-cni	v1.20.4-eksbuild.2	v1.21.1-eksbuild.5	需 OVERWRITE + 等待
coredns	v1.11.4-eksbuild.2	v1.13.2-eksbuild.1	需 coredns pod 重新排程
kube-proxy	v1.32.6-eksbuild.12	v1.33.9-eksbuild.2	自動升級至最新版
eks-pod-identity-agent	v1.3.10-eksbuild.2	v1.3.10-eksbuild.2	無需升級
aws-ebs-csi-driver	v1.54.0-eksbuild.1	v1.56.0-eksbuild.1	UPDATE_FAILED → OVERWRITE 修復
metrics-server	v0.8.0-eksbuild.6	v0.8.0-eksbuild.6	維持不變
amazon-cloudwatch-observability	v4.9.0-eksbuild.1	v5.2.2-eksbuild.1	自動升級至最新版

aws-node CrashLoopBackOff 根因分析¶

Add-on 卡在 UPDATING 時，發現問題根因鏈：

aws-node-ssvp6（ip-192-168-95-51）CrashLoopBackOff（1/2 Ready）
  → liveness probe: grpc-health-probe -addr=:50051 失敗
  → CNI gRPC server（port 50051）connection refused
  → coredns-d544948f4-7f44g 無法在該節點創建 pod sandbox
  → coredns pod 卡在 ContainerCreating（持續 90 分鐘以上）
  → coredns Add-on 無法達到 ACTIVE
  → vpc-cni 升級也因節點 CNI 異常而阻塞

aws-node 的健康探針設定：

Liveness:   exec [/app/grpc-health-probe -addr=:50051 -connect-timeout=5s -rpc-timeout=5s] delay=60s timeout=10s period=10s
Readiness:  exec [/app/grpc-health-probe -addr=:50051 -connect-timeout=5s -rpc-timeout=5s] delay=1s timeout=10s period=10s

Node Group 升級失敗排查¶

exsctl 首次升級失敗原因（CloudFormation events）：

NodeCreationFailure: Couldn't proceed with upgrade process as new nodes
are not joining node group locust-ng-v3, ResourceIds=[]

ASG scaling activities 顯示新節點啟動後立即被終止，表示新節點未能成功加入叢集。

診斷確認： - nodegroup IAM role：AmazonEKSAutoNodeRole - aws-auth ConfigMap 中已有對應 role 映射 - AMI 類型：AL2023_ARM_64_STANDARD - 目標版本：1.33.8-20260304

最終使用 aws eks update-nodegroup-version API 直接觸發，新節點（i-080f8eb519d9fbd5b）成功啟動並加入叢集。

What Changed¶

舊版文檔記錄（已完整保留）¶

前三階段（Pre-upgrade Check、Control Plane 升級、Add-on Timeout 與 OVERWRITE 重試、aws-node CrashLoopBackOff 根因排查）均已詳細記錄於舊版文檔中，新版完整繼承。

新增：Add-on 全面完成確認¶

透過 check_addon_status.sh 腳本確認，coredns 重新排程後狀態陸續完成： - coredns：ACTIVE v1.13.2 ✓ - kube-proxy 和 cloudwatch-observability 自動升級至比預期更新的版本 - aws-ebs-csi-driver 意外出現 UPDATE_FAILED，需手動用 OVERWRITE 重新觸發升級

新增：Node Group 升級完整流程（舊版文檔的「後續步驟」）¶

eksctl upgrade nodegroup 首次嘗試失敗（約 30 分鐘後 CloudFormation 報 NodeCreationFailure）。透過 CloudFormation stack events、ASG scaling activities 診斷，確認新節點啟動後未能加入叢集。最終改用 aws eks update-nodegroup-version API 直接觸發，新節點（ARM c7g.2xlarge, release 1.33.8-20260304）成功啟動並加入叢集，問題節點 ip-192-168-95-51 在 Rolling Upgrade 過程中被自然替換。

So What¶

此更新使升級文檔真正**完整**：從前置檢查到 Control Plane、Add-on、Node Group 四個階段全部涵蓋，包含每個階段遇到的問題與解決方案。

新增的 Node Group 升級章節特別重要，因為 eksctl upgrade nodegroup 並不總是可靠的一鍵升級工具——在 ARM 架構（c7g.2xlarge）環境下，第一次嘗試失敗了。改用 aws eks update-nodegroup-version API 直接觸發是更可控的替代方案，並配合 ASG activities + console output 追蹤新節點狀態。

此外，aws-ebs-csi-driver UPDATE_FAILED 的出現提醒：Add-on 升級並非一帆風順，需要用 check_addon_status.sh 持續監控所有 Add-on 狀態，而非只關注最初觸發的幾個。

Trade-offs¶

PRESERVE vs OVERWRITE：PRESERVE 安全但 ARM 環境容易 timeout（>31分鐘）；建議直接使用 OVERWRITE
eksctl upgrade nodegroup vs aws eks update-nodegroup-version：eksctl 封裝更高層但失敗時難以診斷；直接 API 更透明可控但需自行監控
修好問題節點 vs 讓 Pod 繞過：修好 aws-node 耗時且不確定；直接讓 coredns 重新排程更快
Rolling Upgrade 期間問題節點自然消失：Node Group rolling upgrade 會自動替換問題節點，若不急於修復 aws-node，可等 Node Group 升級自然解決
腳本 timeout 31 分鐘對 ARM 架構過短：建議調整至 60-90 分鐘
Control Plane 升級不可 rollback：只能 Blue/Green 切換或重建 nodegroup
腳本 timeout ≠ 升級失敗：需主動用 describe-addon 確認狀態

Try It Fast¶

# === 完整升級流程 ===

# 1. 前置檢查（使用 flag 格式，非 positional arguments）
./upgrade-scripts/10_pre_upgrade_check.sh -c locust-eks -r ap-southeast-1 -t 1.33

# 2. Control Plane 升級（需兩次 y 確認，約 7 分鐘）
./upgrade-scripts/11_upgrade_eks_control_plane.sh -c locust-eks -v 1.33

# 3. Add-on 升級（建議直接用 OVERWRITE 避免 timeout）
for ADDON in vpc-cni coredns kube-proxy aws-ebs-csi-driver metrics-server amazon-cloudwatch-observability; do
  aws eks update-addon \
    --cluster-name locust-eks \
    --addon-name "$ADDON" \
    --addon-version $(aws eks describe-addon-versions \
      --kubernetes-version 1.33 \
      --addon-name "$ADDON" \
      --region ap-southeast-1 \
      --query 'addons[0].addonVersions[?compatibilities[?defaultVersion==`true`]].addonVersion | [0]' \
      --output text) \
    --region ap-southeast-1 \
    --resolve-conflicts OVERWRITE 2>/dev/null || true
done

# 4. 監控 Add-on 狀態
./upgrade-scripts/check_addon_status.sh locust-eks ap-southeast-1

# 5. 如果 Add-on 卡在 UPDATING，先檢查 aws-node CrashLoopBackOff
kubectl get pods -n kube-system -l k8s-app=aws-node -o wide
# 若發現 1/2 Ready，代表 grpc-health-probe :50051 失敗

# 6. 讓卡在問題節點的 coredns 重新排程
PROBLEM_NODE="ip-192-168-95-51.ap-southeast-1.compute.internal"
kubectl cordon "$PROBLEM_NODE"
kubectl get pods -n kube-system -l k8s-app=kube-dns -o wide | grep "$PROBLEM_NODE" | awk '{print $1}' | xargs kubectl delete pod -n kube-system
# 確認新 pod 在健康節點後
kubectl uncordon "$PROBLEM_NODE"

# 7. Node Group 升級（方法一：eksctl，可能失敗）
eksctl upgrade nodegroup \
  --cluster locust-eks \
  --name locust-ng-v3 \
  --region ap-southeast-1 \
  --kubernetes-version 1.33

# 7. Node Group 升級（方法二：直接 API，更可靠）
RELEASE_VERSION=$(aws eks describe-addon-versions \
  --kubernetes-version 1.33 --region ap-southeast-1 \
  --query 'addons[0].addonVersions[0].addonVersion' --output text 2>/dev/null || echo "1.33.8-20260304")
aws eks update-nodegroup-version \
  --cluster-name locust-eks \
  --nodegroup-name locust-ng-v3 \
  --region ap-southeast-1 \
  --kubernetes-version 1.33

# 8. 如果 eksctl nodegroup upgrade 失敗，查看 CloudFormation 事件
aws cloudformation describe-stack-events \
  --stack-name eksctl-locust-eks-nodegroup-locust-ng-v3 \
  --region ap-southeast-1 \
  --query 'StackEvents[?ResourceStatus==`UPDATE_FAILED`].[LogicalResourceId,ResourceStatusReason]' \
  --output table

# 9. 監控 ASG 活動（新節點是否成功加入）
ASG_NAME=$(aws eks describe-nodegroup \
  --cluster-name locust-eks --nodegroup-name locust-ng-v3 \
  --region ap-southeast-1 \
  --query 'nodegroup.resources.autoScalingGroups[0].name' --output text)
aws autoscaling describe-scaling-activities \
  --auto-scaling-group-name "$ASG_NAME" \
  --region ap-southeast-1 --max-items 10 \
  --query 'Activities[].[StartTime,StatusCode,Description]' --output table

Recommendation¶

Add-on 升級直接用 OVERWRITE：PRESERVE 在 ARM 架構（c7g.2xlarge）下容易 timeout（31分鐘），建議預設改用 --resolve-conflicts OVERWRITE
Add-on 升級後用腳本全面確認狀態：不只確認目標 add-on，要確認所有 add-on，因為 aws-ebs-csi-driver 可能出現意外的 UPDATE_FAILED
Add-on 卡在 UPDATING 時，先查 aws-node DaemonSet：立即執行 kubectl get pods -n kube-system -l k8s-app=aws-node -o wide，若有 ½ Ready 表示 CNI gRPC 服務問題
快速解決 coredns ContainerCreating：cordon 問題節點 → delete stuck pod → 等新 pod 在健康節點啟動 → uncordon
Node Group 升級優先用 aws eks update-nodegroup-version：比 eksctl 更直接透明，失敗時更易診斷
Node Group 升級失敗查 CloudFormation events：describe-stack-events --query ResourceStatus==UPDATE_FAILED 可直接看到失敗原因（如 NodeCreationFailure）
用 ASG activities 監控新節點：確認新節點是否成功 Launching 且未被立即 Terminating
aws-node 問題節點不需急於修復：若即將進行 Node Group Rolling Upgrade，問題節點會在升級過程中自然被替換
整體升級時間預估（ARM 叢集）：Pre-check 3分鐘 + Control Plane 7分鐘 + Add-on（含問題排查）60-180分鐘 + Node Group Rolling Upgrade 30-60分鐘

本文檔由 Semi-Brain 自動生成

Session ID: 7f62faa7-a87f-4880-845e-714dc32b3241

分析信心度: 98%