Kubernetes emptyDir Runtime Dependency Anti-Pattern¶
概念概覽
emptyDir Volume 生命週期陷阱¶
核心知識¶
emptyDir Volume 生命週期陷阱¶
emptyDir volume 的內容在 pod 重啟或重新調度後**完全消失**。若容器啟動腳本依賴從外網下載依賴（如 Maven Central），在私有 EKS cluster 中下載會靜默失敗——只印 WARN 繼續 sleep，不會導致 pod crash，讓人誤以為正常運作。
失效鏈條（完整證據鏈）¶
- Pod 啟動 → curl 嘗試從 Maven Central 下載 JAR → 網路政策封鎖 → 靜默失敗（只有 WARN）
- JAR 不在 emptyDir → classpath 不完整
- kafka-topics.sh 呼叫時拋出
ConfigException: Invalid value ... Class could not be found - 手動
kubectl cp修復 → pod 重啟後問題再次出現（Build #236 佐證）
診斷訊號¶
Invalid value ... Class could not be found→ JAR 不在 classpath，**不是**設定值錯誤- CLASSPATH 環境變數為空 → Bitnami Kafka image 可能用目錄掃描（
/opt/bitnami/kafka/libs/）而非 CLASSPATH 變數載入 JAR
修復優先序¶
立即: kubectl cp JAR 進 pod（臨時）
短期: 將 JAR 打入 Docker image（最可靠）
中期: init container + 私有 artifact repo (Nexus/S3)
長期: 建立 EKS private cluster artifact mirror 機制
經驗教訓¶
-
在私有 EKS cluster 中，任何依賴外網 runtime 下載的機制都是不可靠的，且失敗是靜默的
-
emptyDir volume 的生命週期等同於 pod 生命週期，不能用來持久化需要跨重啟存活的依賴
-
kubectl cp 是有效的應急手段，但本質上只是短暫的，pod 重啟後必定失效
-
腳本執行成功（exit code 0）不等於修復有效，需驗證各步驟的實際效果（如 CLASSPATH 是否真的生效）
常見陷阱¶
-
容器啟動時 curl 失敗只印 WARN，pod 仍然 Running，容易誤以為依賴已就緒
-
CLASSPATH 環境變數 patch 對 Bitnami Kafka image 可能無效，因其使用目錄掃描機制
-
只看自動化腳本的 exit code，沒有驗證 kafka-topics.sh 實際能否成功執行
最佳實踐¶
-
將外部依賴（JAR、binary）打入 Docker image，消除 runtime 下載需求
-
私有 cluster 需建立 artifact mirror（S3/Nexus），讓 init container 從內網取得依賴
-
ConfigException 'Class could not be found' 應優先排查 classpath，而非設定值本身
相關概念¶
- eks-network-policy----dangling---
- jenkins-msk-iam-auth-debug----dangling---
- MSK IAM Auth JAR Classpath 管理
來源 Sessions¶
| 日期 | Session | 貢獻摘要 |
|---|---|---|
| 2026-03-25 | a8e3a9b9-80d0-4bdd-b09d-be69ab423f5d | 完整記錄了 emptyDir volume + 外網 runtime 下載依賴在私有 EKS cluster 的失敗生命週期，並透過 Build #236 再次失敗提供了可觀察的驗證事實。 |