跳轉到

MSK IAM Auth JAR Classpath 管理

概念概覽

Kafka client 連接 AWS MSK（IAM 認證）時，aws-msk-iam-auth JAR 必須存在於 container 的 classpath 中。此頁面涵蓋 Bitnami Kafka image 的 JAR 載入機制、CLASSPATH 環境變數 patch 的已知異常、image 升級時 JAR 遺失導致的 rolling update 間歇性失敗模式，以及透過 Dockerfile 固定 JAR 的永久修法與驗證流程。

核心知識

JAR 部署需求

AWS MSK 使用 IAM 認證時，Kafka client container 必須在 classpath 中包含 aws-msk-iam-auth JAR：

  • Bitnami Kafka image 預設路徑：/opt/bitnami/kafka/libs/aws-msk-iam-auth-2.3.2-all.jar（約 14MB）
  • 缺少時的錯誤訊息：IAMClientCallbackHandler could not be found（或 ConfigException: Class could not be found）
  • Dockerfile 加入方式： 
    COPY aws-msk-iam-auth-*.jar /opt/bitnami/kafka/libs/

Bitnami Image 的 JAR 載入機制

Bitnami Kafka image 的 JAR 載入有兩種可能模式，需確認實際行為：

  • 目錄掃描：自動掃描 /opt/bitnami/kafka/libs/ 下所有 JAR → 若是此模式，CLASSPATH 環境變數 patch 無意義
  • CLASSPATH 環境變數：依賴明確設定的 CLASSPATH → 若是此模式，需調查 patch 為何未生效

CLASSPATH Patch 已知異常

透過 kubectl patch deployment 注入 CLASSPATH 後，kubectl exec 確認顯示為空。可能原因：

  1. Bitnami image 啟動腳本覆蓋或不使用 CLASSPATH 環境變數
  2. patch 的環境變數格式不正確
  3. 容器使用的 shell 設定優先於 Kubernetes 注入的環境變數

結論：不應依賴 CLASSPATH 環境變數 patch，應直接將 JAR 打入 Docker image。

Rolling Update 期間的間歇性失敗模式

image 升級時容易遺漏此 JAR，因 K8s rolling update 特性會出現「部分 Pod 成功、部分失敗」的間歇性問題：

舊 Pod（含 JAR）→ kafka-topics.sh exec 成功
新 Pod（rollout 後，JAR 遺失）→ IAMClientCallbackHandler not found

這種間歇性成功極容易誤導排查方向（例如：某次 snapshot 測試成功，實際上是打到舊 Pod）。

診斷指令

# 確認 JAR 是否存在於 container
kubectl exec <pod> -- ls /opt/bitnami/kafka/libs/ | grep msk

# 確認 CLASSPATH 環境變數（Bitnami image 中通常為空）
kubectl exec <pod> -- env | grep CLASSPATH

# 實際連線測試（唯一能確認修復有效的方式）
kubectl exec <pod> -- kafka-topics.sh \
  --bootstrap-server <msk-endpoint> \
  --list \
  --command-config /opt/bitnami/kafka/config/client.properties

驗證流程

維護 verify-kafka.sh 腳本，每次 image 更新後執行，輸出 ALL CHECKS PASSED 才算完成。CI build 階段也應加入 JAR 存在性驗證步驟，防止升級時意外遺漏。

經驗教訓

  • JAR 上傳成功或 ls 確認存在，不等於 Kafka client 能正常使用——必須執行 kafka-topics.sh 實際連線 MSK 才能確認修復有效

  • MSK IAM auth 問題的第一排查步驟：確認 JAR 是否在 container 的 /opt/bitnami/kafka/libs/ 目錄下

  • 間歇性成功（舊 Pod 正常、新 Pod 失敗）是 rolling update 期間 JAR 遺失的典型症狀，不可用單次成功推斷問題已解決

  • image 升級後必須立即執行 verify 腳本，不能靠過去的成功記錄推斷新 image 也正常

  • Bitnami Kafka image 的 JAR 載入機制需要確認，不能假設 CLASSPATH 環境變數一定有效

常見陷阱

  • CLASSPATH 環境變數 patch 在 Bitnami image 中可能無效，image 啟動腳本可能覆蓋該變數，需確認 JAR 載入機制

  • ConfigException 'Class could not be found' 容易誤判為設定值錯誤，實際上是 classpath / JAR 遺失問題

  • rolling update 期間新舊 Pod 並存，導致間歇性成功，容易誤判問題已修復——需確認所有新 Pod 皆正常

  • ImagePullBackOff 的失敗 Pod 不會自動清除，需手動刪除讓 controller 重新 reconcile

最佳實踐

  • kafka-client Dockerfile 明確加入 COPY aws-msk-iam-auth-*.jar /opt/bitnami/kafka/libs/，是最可靠的永久修法

  • JAR 版本固定在 Dockerfile 中（如 aws-msk-iam-auth-2.3.2-all.jar），避免版本漂移

  • CI build 階段加入 JAR 存在性驗證步驟，防止 image 升級時意外遺漏

  • 每次 image 更新後執行 verify-kafka.sh，確認輸出 ALL CHECKS PASSED

  • 修復後必須執行端對端測試（kafka-topics.sh 實際連線 MSK），而不只是確認 JAR 存在

相關概念

來源 Sessions

日期 Session 貢獻摘要

| - | a8e3a9b9-80d0-4bdd-b09d-be69ab423f5d | 融合自原始頁面 msk-iam-auth-jar-classpath |

| - | e9680a7b-7572-4a2f-949b-d4d7c75a4e96 | 融合自原始頁面 msk-iam-auth-jar-dependency |

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

最後更新: 2026-04-11