Helm Annotation Special Character Escaping¶
概念概覽
問題根因¶
核心知識¶
問題根因¶
當 annotation key 含有 / 或 .（如 ps.version/server），透過 Jenkins Groovy 呼叫 shell 再呼叫 helm --set 時，會經歷三層轉義：
- Groovy string 轉義
- Shell 轉義
- Helm 解析轉義
最終 Helm 將 ps\.version/server 中 / 後的部分解析為 nested object 結構，造成 json: cannot unmarshal object into Go struct field ... of type string。
解法優先順序¶
最穩定：writeFile 生成 values.yaml → -f values.yaml 傳入
次選： --set-string（避免型別問題，但特殊字符仍需轉義）
避免： 含特殊字符 key 使用 --set（三層轉義極易出錯）
驗證方式¶
部署前用 helm template --dry-run 渲染輸出並 grep annotation，確認 key/value 正確解析，避免等到實際部署才發現 unmarshal 錯誤。
經驗教訓¶
-
含
/、.的 annotation key 不應直接用 --set 在 Pipeline 中傳遞 -
build log 中 unmarshal 錯誤的直接原因是 Helm 將 key 解析為 object 而非 string
-
writeFile 動態生成 values yaml 是 Jenkins Pipeline 中最穩定的做法
常見陷阱¶
-
Groovy 中對
\.的轉義在 shell 展開後仍可能讓 Helm 誤判結構 -
--set-string 只解決型別問題，不解決特殊字符結構解析問題
最佳實踐¶
-
含特殊字符的 annotation key 統一改用 writeFile 生成 values yaml
-
每次 Helm 部署前加 dry-run 步驟並 grep 關鍵欄位做 smoke check
相關概念¶
- EKS NoExecute Taint Toleration Scheduling
- Istio Gateway Helm Chart Volume Mount Path
- jenkins-pipeline----dangling-------dangling---
相關視角¶
以下頁面與本概念共享主題，但從不同角度切入。保留獨立視角同時提供交叉參考：
- Jenkins Pipeline Silent Failure — 共享：
groovy,jenkins,pipeline/ 獨特：ci-cd,exit-code - ECR Image Tag Versioning in Jenkins Pipeline — 共享：
jenkins/ 獨特：deployment,ecr - Jenkins Pipeline kubectl exec Target — 共享：
jenkins,pipeline/ 獨特：automation,ci-cd
來源 Sessions¶
| 日期 | Session | 貢獻摘要 |
|---|---|---|
| 2026-04-08 | 4704b57e-d74e-48ab-811d-8bf398552c49 | 記錄 Groovy→Shell→Helm 三層轉義導致含 / 或 . 的 annotation key unmarshal 失敗的根因與解法 |