📚 课程目录第4章编写第一个Helm Chart

4. 模板引擎入门：Go模板语法基础、模板函数、管道操作、条件判断与循环

Helm 的核心价值在于通过模板引擎将静态的 Kubernetes 资源清单转化为动态、可配置的部署描述。本章深入解析 Go 模板语法在 Helm 中的应用，涵盖变量插值、模板函数、管道操作、条件判断与循环控制，帮助您编写灵活且可维护的 Chart 模板。

学习目标：掌握 Go 模板的核心语法结构，理解 Helm 内置模板函数与管道操作符的协作方式，能够独立编写包含条件分支与循环逻辑的模板文件。

4.1 Go 模板语法基础

Helm 使用 Go 标准库 text/template 作为模板引擎，所有模板文件均位于 Chart 的 templates/ 目录下，文件扩展名通常为 .yaml 或 .tpl。模板语法通过双花括号 {{ }} 包裹表达式，用于输出变量、执行函数或控制逻辑。

4.1.1 变量插值与点号

在模板中，. 表示当前上下文（Scope）。顶层上下文通常指向 .Values 对象，即 values.yaml 中定义的所有配置项。通过 .Values.key 即可引用对应值。

# values.yaml
replicaCount: 3
image:
  repository: nginx
  tag: "1.25"

# templates/deployment.yaml 片段
spec:
  replicas: {{ .Values.replicaCount }}
  template:
    spec:
      containers:
        - name: {{ .Chart.Name }}
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"

  内置对象：除了 .Values，Helm 还提供 .Release（发布信息）、.Chart（Chart 元数据）、.Files（文件访问）、.Capabilities（集群能力）等内置对象，可在模板中直接使用。

4.1.2 空白控制

Go 模板默认会保留表达式前后的空白字符。Helm 提供了 {{- （去除左侧空白）和 -}}（去除右侧空白）语法，用于生成整洁的 YAML 输出。

# 未使用空白控制
env:
  - name: LOG_LEVEL
    value: {{ .Values.logLevel }}

# 使用空白控制（去除表达式前的换行与缩进）
env:
  - name: LOG_LEVEL
    value: {{- .Values.logLevel | quote }}

4.2 模板函数与管道操作

Helm 内置了超过 60 个模板函数，涵盖字符串处理、数学运算、类型转换、编码解码、文件路径操作等。函数通过管道操作符 | 串联，形成数据流处理链。

4.2.1 常用内置函数

函数名	功能描述	示例
`quote`	将值用双引号包裹	`{{ .Values.name \| quote }}`
`upper`	转换为大写	`{{ "hello" \| upper }}`
`default`	当值为空时提供默认值	`{{ .Values.port \| default 8080 }}`
`indent`	为多行字符串添加缩进	`{{ .Values.config \| indent 4 }}`
`nindent`	先换行再缩进	`{{ .Values.config \| nindent 4 }}`
`toYaml`	将对象转换为 YAML 格式	`{{ .Values.labels \| toYaml }}`
`fromYaml`	将 YAML 字符串解析为对象	`{{ .Values.rawYaml \| fromYaml }}`

4.2.2 管道操作链

管道操作符 | 将左侧表达式的输出作为右侧函数的输入，支持多级串联。这种风格使模板逻辑清晰且易于组合。

# 管道链示例：将值转为大写并加引号
{{ .Values.service.name | upper | quote }}

# 复杂管道：默认值 → 大写 → 缩进
{{ .Values.description | default "no description" | upper | indent 2 }}

# 结合 YAML 转换与缩进
{{ .Values.annotations | toYaml | indent 8 }}

注意：管道操作中，函数参数顺序为：管道左侧的值作为函数的最后一个参数。例如 indent 4 表示缩进 4 个空格，管道传入的值是待缩进的字符串。

4.3 条件判断

条件判断使用 if/else if/else/end 结构，根据布尔值或非空值决定是否渲染某段模板内容。Helm 将以下值视为 false：false、空字符串、数字 0、空列表、空字典、nil。

# 条件判断基础语法
{{ if .Values.ingress.enabled }}
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: {{ .Release.Name }}-ingress
spec:
  rules:
    - host: {{ .Values.ingress.host }}
      http:
        paths:
          - path: /
            pathType: Prefix
            backend:
              service:
                name: {{ .Release.Name }}-svc
                port:
                  number: {{ .Values.service.port }}
{{ end }}

# 多分支条件
{{ if eq .Values.environment "production" }}
replicas: 5
{{ else if eq .Values.environment "staging" }}
replicas: 3
{{ else }}
replicas: 1
{{ end }}

4.3.1 逻辑运算符

运算符	说明	示例
`eq`	等于	`{{ if eq .Values.region "us-east" }}`
`ne`	不等于	`{{ if ne .Values.region "cn-north" }}`
`lt`	小于	`{{ if lt .Values.replicas 3 }}`
`gt`	大于	`{{ if gt .Values.replicas 5 }}`
`and`	逻辑与	`{{ if and .Values.monitoring.enabled .Values.monitoring.prometheus }}`
`or`	逻辑或	`{{ if or .Values.debug .Values.trace }}`
`not`	逻辑非	`{{ if not .Values.production }}`

4.4 循环控制

Helm 使用 range 关键字遍历数组、切片或字典。循环体内通过 . 访问当前迭代元素，支持 else 分支处理空集合。

4.4.1 遍历列表

# values.yaml
ports:
  - name: http
    containerPort: 80
  - name: https
    containerPort: 443

# templates/deployment.yaml 片段
ports:
{{- range .Values.ports }}
  - name: {{ .name }}
    containerPort: {{ .containerPort }}
{{- end }}

4.4.2 遍历字典

# values.yaml
labels:
  app: myapp
  tier: frontend
  env: production

# 遍历字典，获取 key 和 value
{{- range $key, $value := .Values.labels }}
  {{ $key }}: {{ $value }}
{{- end }}

4.4.3 循环中的索引与变量

在 range 中可以使用 $index 获取当前索引（从 0 开始），也可以将迭代值赋给自定义变量。

# 带索引的遍历
{{- range $index, $port := .Values.ports }}
  # 索引: {{ $index }}, 端口名: {{ $port.name }}
{{- end }}

# 空集合处理
{{- range .Values.optionalConfigs }}
  {{ . }}
{{- else }}
  # 当 optionalConfigs 为空时渲染此部分
  config: default
{{- end }}

4.5 模板引擎工作流程

以下 SVG 图展示了 Helm 模板引擎从读取 values 到生成最终 Kubernetes 清单的完整数据流与逻辑处理路径。

4.6 条件与循环综合示例

以下是一个完整的 Deployment 模板片段，综合运用了变量插值、管道函数、条件判断和循环控制，展示了实际 Chart 开发中的典型模式。

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ .Release.Name }}-{{ .Values.component }}
  labels:
    app: {{ .Chart.Name }}
    release: {{ .Release.Name }}
    {{- if .Values.labels }}
    {{- .Values.labels | toYaml | nindent 4 }}
    {{- end }}
spec:
  replicas: {{ .Values.replicaCount | default 1 }}
  selector:
    matchLabels:
      app: {{ .Chart.Name }}
  template:
    metadata:
      labels:
        app: {{ .Chart.Name }}
        release: {{ .Release.Name }}
    spec:
      containers:
        - name: {{ .Chart.Name }}
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default "latest" }}"
          ports:
          {{- range .Values.service.ports }}
            - containerPort: {{ .port }}
              name: {{ .name }}
          {{- end }}
          env:
          {{- range $key, $value := .Values.env }}
            - name: {{ $key | upper }}
              value: {{ $value | quote }}
          {{- end }}
          {{- if .Values.resources }}
          resources:
            {{- .Values.resources | toYaml | nindent 12 }}
          {{- end }}
      {{- if .Values.nodeSelector }}
      nodeSelector:
        {{- .Values.nodeSelector | toYaml | nindent 8 }}
      {{- end }}

最佳实践：在模板中尽量使用 default 函数为关键字段提供回退值，避免因 values 缺失导致渲染失败。同时，合理使用 nindent 保持 YAML 缩进结构清晰。

4.7 模板调试技巧

Helm 提供了多个命令用于调试模板渲染结果，帮助定位语法错误或逻辑问题。

命令	用途	示例
`helm template`	在本地渲染模板并输出 YAML，不实际安装	`helm template my-release ./mychart`
`helm lint`	检查 Chart 语法和模板错误	`helm lint ./mychart`
`helm install --dry-run`	模拟安装，显示渲染后的清单	`helm install my-release ./mychart --dry-run`
`helm get manifest`	查看已安装 Release 的最终清单	`helm get manifest my-release`

常见错误：模板中未闭合的 {{ end }}、错误的缩进层级、引用不存在的 values 键、管道函数参数顺序错误，是初学者最容易遇到的问题。建议每次修改模板后先执行 helm lint 和 helm template 验证。

4.8 模板函数与管道操作关系图

以下 SVG 图展示了模板函数与管道操作之间的数据流转关系，帮助理解函数组合与管道链的协作模式。

4.9 本章小结

Go 模板语法：使用 {{ }} 进行变量插值，. 表示当前上下文，支持空白控制 {{- -}}。
模板函数：Helm 内置 60+ 函数，涵盖字符串、数学、类型转换、YAML 处理等场景。
管道操作：通过 | 串联函数，形成数据流处理链，提升模板可读性。
条件判断：if/else/end 结构配合逻辑运算符 eq、ne、and、or 实现分支渲染。
循环控制：range 遍历列表和字典，支持索引访问与空集合处理。
调试工具：helm template、helm lint、--dry-run 是模板开发的三大利器。