Helm YAML 模板语法详解（values.yaml + templates）

Helm 的 YAML 语法基于 Kubernetes 的 YAML 配置文件，但在此基础上引入了 Go Template 模板语法，使得配置更灵活、参数化程度更高。以下是对 Helm 的 YAML 文件结构和语法的详细介绍。

一、Helm YAML 文件分类

Helm Chart 中的 YAML 文件主要分为两类：

文件	说明
values.yaml	参数默认值，供模板引用
templates/*.yaml	Kubernetes 配置模板，使用 Go Template 语法生成

两者结合，即能复用 Kubernetes 通用配置，如：安装 nginx 集群，又能实现一些个性化配置。

---

二、values.yaml 的语法（配置参数）

这个文件结构就是普通的 YAML，没有模板语法，通常定义变量供模板使用。

📌 示例：

replicaCount: 3

image:
  repository: nginx
  tag: "1.24"
  pullPolicy: IfNotPresent

service:
  type: ClusterIP
  port: 80

resources:
  limits:
    cpu: 100m
    memory: 128Mi

---

三、templates/*.yaml 中的模板语法（Go Template）

在 templates/ 下的 YAML 文件中，可以使用 Go Template 语法，主要有以下几类写法：

---

✅ 1. 变量引用

replicas: {{ .Values.replicaCount }}

• .Values 代表 values.yaml 中的变量
• 支持多层嵌套，例如：

image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"

---

✅ 2. 内置对象

对象名	说明
.Release.Name	当前 release 名称
.Chart.Name	Chart 名称
.Values	values.yaml 中的变量值
.Capabilities	当前 Kubernetes 能力信息
.Files	引用其他文件（如 config 文件）

---

✅ 3. 条件判断（if, else, end）

{{- if .Values.service.enabled }}
apiVersion: v1
kind: Service
...
{{- end }}

{{- if .Values.image.pullSecrets }}
imagePullSecrets:
  - name: {{ .Values.image.pullSecrets }}
{{- else }}
imagePullSecrets: []
{{- end }}

---

✅ 4. 循环（range）

适用于列表或字典遍历。

env:
{{- range $key, $val := .Values.env }}
  - name: {{ $key }}
    value: "{{ $val }}"
{{- end }}

---

✅ 5. 模板注释

{{/* 这是一个注释，不会渲染出来 */}}

---

✅ 6. 默认值 (default 函数)

replicas: {{ .Values.replicaCount | default 1 }}

如果 .Values.replicaCount 未设置，则使用默认值 1。

---

✅ 7. include 与 define（模块化模板）

可以将某些通用片段提取为可复用函数：

# _helpers.tpl
{{- define "mychart.fullname" -}}
{{ .Release.Name }}-{{ .Chart.Name }}
{{- end }}

# deployment.yaml
name: {{ include "mychart.fullname" . }}

---

✅ 8. 格式控制（- 用于去除空格）

{{- if ... }}  # 左侧无空格
{{ ... -}}     # 右侧无空格

---

四、实战例子：Deployment 模板

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "mychart.fullname" . }}
spec:
  replicas: {{ .Values.replicaCount }}
  selector:
    matchLabels:
      app: {{ include "mychart.name" . }}
  template:
    metadata:
      labels:
        app: {{ include "mychart.name" . }}
    spec:
      containers:
        - name: {{ .Chart.Name }}
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
          ports:
            - containerPort: {{ .Values.service.port }}

---

五、调试推荐命令

命令	说明
helm template	渲染模板但不部署
helm lint	语法检查
helm install --dry-run --debug	预览安装并输出调试信息

---

六、YAML 模板技巧总结

场景	模板技巧
字符拼接	{{ print "a" .Values.xxx }} 或 include
默认值处理	`{{ .Values.key
控制缩进	配合 nindent, indent, trim
文件读取	{{ .Files.Get "files/config.conf" }}
标签自动生成	提取公共标签逻辑封装到 _helpers.tpl

---

七、学习资源推荐

类型	名称
官方文档	https://helm.sh/docs
中文教程	https://helm.sh/zh/docs/
可视化工具	Kubeapps, Monokle, Lens
Chart 示例	Bitnami Charts: https://bitnami.com/stacks/helm