Helm中_stateful-set.yaml使用include及checksum/config配置问题

一、解决include生成secret checksum无效的问题 #

针对你在_stateful-set.yaml注解中使用include生成secret checksum失效的情况，按以下步骤排查修复：

1. 确认上下文传递
   主statefulset.yaml引入_stateful-set.yaml时，必须完整传递Helm上下文（.），否则子模板无法获取正确的变量和模板引用：

   # 主statefulset.yaml中引入子模板的正确写法
   {{ include "_stateful-set.yaml" . }}
   

2. 修正include引用方式
   根据你的secret文件结构选择对应写法：

   • 如果secret.yaml是templates目录下的完整资源文件（未用define包裹），直接引用文件名生成checksum：

     # _stateful-set.yaml中的注解部分
     annotations:
       checksum/secret: {{ include "secret.yaml" . | sha256sum }}
     

   • 如果secret.yaml是用define定义的模板片段（比如定义了apache-template.secret模板），则引用模板名称：

     # _stateful-set.yaml中的注解部分
     annotations:
       checksum/secret: {{ include "apache-template.secret" . | sha256sum }}
     

3. 排查语法错误
   运行helm lint apache-template检查模板语法，重点看是否存在：

   • 管道符|前后的空格缺失
   • 模板引用名称拼写错误
   • 上下文变量未正确传递导致的渲染失败

二、模板仓库有效性验证 #

你的apache-template结构符合Helm Chart规范，只要满足以下条件，即可正常在Helm仓库中使用：

1. Chart.yaml必填字段齐全
   确保Chart.yaml包含apiVersion（推荐v2）、name、version三个核心字段，示例：

   apiVersion: v2
   name: apache-template
   version: 0.1.0
   description: Apache StatefulSet Template Chart
   

2. 模板文件命名合规

   • 下划线开头的文件（如_stateful-set.yaml）会被Helm识别为局部模板，不会直接渲染为K8s资源，需通过主模板（如statefulset.yaml）引入，这是符合规范的写法。
   • 所有模板文件需放在templates目录下，无嵌套目录或命名冲突。

3. 本地验证通过
   执行以下命令确认模板无问题：

   # 检查语法
   helm lint apache-template
   # 模拟安装，验证渲染结果
   helm install --dry-run test ./apache-template
   

   以上命令无报错的话，即可将Chart打包后推送到Helm仓库，正常供用户拉取安装。

内容的提问来源于stack exchange，提问作者unbox-us