ECR Image Tag Versioning in Jenkins Pipeline

概念概覽

ECR Tag 不可覆蓋行為

核心知識

ECR Tag 不可覆蓋行為

在 BuildPSWebImage-MakeWish.groovy 的實際驗證中確認：若 webImageVersion 版號未遞增，push 到 ECR 的同版號 tag（如 func-web-5）**不會覆蓋**已存在的 image。Deploy 時 K8s 拉到的仍是舊 image，即使 pipeline 執行成功也無效果。

雙 Tag 策略

// 同時 push 固定版號與 latest
docker.withRegistry(ecrRegistry) {
    img.push("func-web-${webImageVersion}")  // 固定版號：便於追蹤
    img.push("func-web-latest")              // latest：保底用，永遠指向最新
}

固定版號便於追蹤與 rollback，但需手動遞增；latest tag 永遠覆蓋，作為保底確保新 image 可被拉取。

實務注意

每次修改 inline Dockerfile 或 pipeline 邏輯後，必須同步遞增 webImageVersion 參數，否則 ECR 不會更新，debug 時會因為 deploy 到舊 image 而困惑。

經驗教訓

• 同版號 ECR tag 不覆蓋是常見的 debug 陷阱，修改 Dockerfile 後若版號未增，排查問題時會以為修正已部署實際卻沒有

• 雙 tag 策略（固定版號 + latest）是兼顧追蹤性與部署保底的實用模式

常見陷阱

• 同版號 ECR tag push 不覆蓋既有 image，排查時容易誤以為修正已生效

• 只依賴 latest tag 無法做 rollback，只依賴固定版號容易忘記遞增

最佳實踐

• 每次修改 Dockerfile 後遞增版號，確保 ECR tag 有效更新

• 同時維護固定版號 tag 與 latest tag，固定版號用於追蹤與 rollback，latest 用於保底

相關概念

• Docker K8s Init Script Permission Inheritance
• ECR Image Deployment Pattern

相關視角

以下頁面與本概念共享主題，但從不同角度切入。保留獨立視角同時提供交叉參考：

• Helm Annotation Special Character Escaping — 共享：jenkins / 獨特：annotation, escaping
• Jenkins Pipeline Silent Failure — 共享：jenkins / 獨特：ci-cd, exit-code

來源 Sessions

日期	Session	貢獻摘要

| 2026-04-10 | 2915f12c-2e40-49a6-9734-a50edf42bc3a | 確認同版號 ECR image tag 不會被自動覆蓋更新，以及 Jenkins Groovy pipeline 中同時維護固定版號與 latest tag 的雙 tag 策略 |

---

本概念頁面由 Semi-Brain Wiki 系統自動維護

最後更新: 2026-04-10