CI/CD / 系统课时
看懂 Chart.yaml 与目录结构
看懂 Chart.yaml 与目录结构
拿到一个 Helm Chart 时,先不要急着修改模板。识别 Chart.yaml、values.yaml、templates 与 charts 的职责,才能判断元数据、参数、资源模板和依赖分别应该改在哪里,并避免把环境配置硬编码进模板。
学习目标
- 识别标准 Chart 中核心文件和目录的职责
- 理解
Chart.yaml、Values 与模板渲染之间的关系 - 能用 Helm 命令检查一个 Chart 的结构与基本有效性
一个 Chart 由什么组成
可以把 Chart 理解为一份可参数化的 Kubernetes 应用包。最常见的结构如下:
myapp/
Chart.yaml
values.yaml
templates/
deployment.yaml
service.yaml
_helpers.tpl
charts/这是结构示例,不是可执行命令。其中 Chart.yaml 描述 Chart 自身,values.yaml 提供默认参数,templates 保存待渲染的 Kubernetes 模板,charts 保存依赖 Chart。

Chart.yaml 不负责保存 Deployment 的副本数或镜像地址,它描述的是这个 Chart 本身。一个最小的 Helm 3 应用 Chart 可以写成:
apiVersion: v2
name: myapp
description: A Helm chart for myapp
type: application
version: 0.1.0
appVersion: "1.0.0"这里的 version 是 Chart 包版本,修改 Chart 内容并准备发布新包时通常需要递增;appVersion 是被部署应用的版本信息,两者不是同一个版本号。apiVersion: v2 表示 Helm 3 使用的 Chart API。
配置文件的生效行为是:Helm 读取这些元数据来识别和打包 Chart。可以通过后面的 helm lint 验证基本格式。
templates 与 values.yaml 怎样协作
templates 中保存最终 Kubernetes YAML 的模板,而不是某个环境已经写死的资源清单。例如 Deployment 可以从 Values 读取副本数:
apiVersion: apps/v1
kind: Deployment
metadata:
name: {{ .Release.Name }}-myapp
spec:
replicas: {{ .Values.replicaCount }}这是片段示例,依赖完整 Deployment 中的 selector、Pod template 等上下文。对应的 values.yaml 可以提供默认值:
replicaCount: 2渲染时,.Values.replicaCount 会被替换为 2。因此模板负责资源结构,Values 负责可变参数;环境差异通常应该进入 Values,而不是复制多份几乎相同的 Deployment 模板。
templates/_helpers.tpl 常用于定义可复用的命名、标签等模板片段。以下划线开头的模板文件不会直接渲染成 Kubernetes 资源,可以由其他模板通过 Helm 模板函数引用。
charts 目录放什么
当当前 Chart 依赖 Redis、数据库或其他子 Chart 时,依赖包可能出现在 charts 目录。Helm 3 通常在 Chart.yaml 的 dependencies 中声明依赖,再使用 helm dependency update 或 helm dependency build 准备依赖,而不是手工维护目录里的压缩包。
因此排查一个陌生 Chart 时,可以先判断问题属于哪一层:Chart 身份和依赖声明看 Chart.yaml,默认参数看 values.yaml,资源生成逻辑看 templates,已准备的依赖包看 charts。
用 Helm 检查 Chart
假设当前目录存在完整的 myapp Chart,可以先执行静态检查:
helm lint ./myapp预期输出
==> Linting ./myapp
1 chart(s) linted, 0 chart(s) failed实际提示数量可能随 Chart 内容变化,但成功时应看到失败数量为 0。随后可以用 helm template 在不连接 Kubernetes 集群的情况下观察渲染结果:
helm template demo ./myapp预期结果
# Source: myapp/templates/...
apiVersion: ...
kind: ...
metadata:
...实际资源内容和 # Source 路径由 Chart 中的模板决定。检查目录结构的目的不是记住文件名,而是建立修改边界:元数据、默认参数、资源模板和依赖各有位置。边界清晰后,后续增加环境 Values 或接入 GitOps 时才不需要反复重构 Chart。