容器与云原生 / 系统课时
Helm Chart 结构
Helm Chart 结构
本课用一个最小可渲染 Chart 拆解 Helm 的目录、元数据、默认值、模板和依赖关系。完成后,你能从文件结构判断每个配置的职责,并用 helm lint 与 helm template 验证 Chart 是否可交付。
学习目标
- 识别
Chart.yaml、values.yaml、templates/与charts/的职责 - 理解 values 如何进入模板并生成 Kubernetes 清单
- 能够创建、渲染并检查一个最小 Chart
Chart 如何组织应用
Chart 是一组按约定目录组织的文件,用来描述一套相关的 Kubernetes 资源。Chart.yaml 定义包的身份与版本,values.yaml 提供默认配置,templates/ 保存 Go 模板,charts/ 保存已下载的子 Chart,crds/ 可放置需要先安装的 CRD。Helm 将模板与 values 合并后生成普通 Kubernetes 清单。:contentReference[oaicite:0]{index=0}
不要把 Chart、Release 和渲染结果混为一谈:Chart 是可复用的软件包;Release 是某个 Chart 在指定命名空间中的一次已命名安装;渲染结果是提交给 Kubernetes API 的资源清单。

构建一个最小 Chart
下面的主示例直接创建一个只包含 Deployment 的 Chart。模板使用 .Release.Name、.Chart.Name 和 .Values,因此同一份 Chart 可以用不同发布名和参数重复安装。
mkdir -p demo-app/templates
cat > demo-app/Chart.yaml <<'EOF'
apiVersion: v2
name: demo-app
description: Minimal Helm chart for a web workload
type: application
version: 0.1.0
appVersion: "1.0.0"
EOF
cat > demo-app/values.yaml <<'EOF'
replicaCount: 2
image:
repository: nginx
tag: "1.27-alpine"
EOF
cat > demo-app/templates/deployment.yaml <<'EOF'
apiVersion: apps/v1
kind: Deployment
metadata:
name: {{ .Release.Name }}-{{ .Chart.Name }}
spec:
replicas: {{ .Values.replicaCount }}
selector:
matchLabels:
app: {{ .Release.Name }}-{{ .Chart.Name }}
template:
metadata:
labels:
app: {{ .Release.Name }}-{{ .Chart.Name }}
spec:
containers:
- name: web
image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
ports:
- containerPort: 80
EOF
helm lint ./demo-app
helm template demo ./demo-app | grep -E '^(kind:| name:| replicas:)'预期输出(提示行可能随 Helm 版本略有差异):
==> Linting ./demo-app
1 chart(s) linted, 0 chart(s) failed
kind: Deployment
name: demo-demo-app
replicas: 2helm lint 检查 Chart 结构和常见错误,helm template 在本地渲染清单但不写入集群。只要渲染结果仍是合法 Kubernetes YAML,模板内部如何复用变量并不会改变 API Server 的处理方式。
values 与模板如何配合
模板读取 .Values 中的数据,Chart 默认值来自 values.yaml;安装或升级时传入的 -f 文件与 --set 参数可以覆盖默认值。适合跨环境变化的副本数、镜像、端口和资源限制应放入 values,固定的资源种类与字段骨架保留在模板中。:contentReference[oaicite:1]{index=1}
模板还可读取 .Chart、.Release、.Capabilities 和 .Template。其中 .Release.Name 适合生成发布级名称,.Chart.Version 表示 Chart 包版本,.Values 才是用户配置入口。不要在模板中硬编码环境名称、密钥或集群地址。
依赖与边界
父 Chart 可在 Chart.yaml 的 dependencies 中声明子 Chart;依赖下载后通常进入 charts/,锁定结果记录在 Chart.lock。下面是片段示例,只有同级目录确实存在 common Chart 时才可执行依赖更新。:contentReference[oaicite:2]{index=2}
dependencies:
- name: common
version: "1.0.0"
repository: "file://../common"
condition: common.enabledcondition 允许通过 values 开关依赖。声明依赖后,应运行 helm dependency update ./demo-app 生成或刷新依赖包,再重新执行 helm lint 和 helm template。子 Chart 默认不能直接读取父 Chart 的任意值,跨 Chart 共享配置应使用约定的全局值或显式导入,避免形成隐式耦合。
常见检查顺序
先检查 Chart.yaml 的 apiVersion、name 和 version,再确认模板引用的每个 values 路径都存在,最后渲染并检查资源名称、标签选择器和命名空间。若 helm lint 成功但安装失败,问题通常已经从“Chart 结构”转移到集群权限、资源冲突或 Kubernetes API 校验。