4. Chart 模板语法入门：Go 模板基础、内置对象与函数管道

Helm Chart 的核心价值在于通过模板引擎将静态 YAML 转化为可参数化、可复用的动态配置。本章将系统讲解 Go 模板语法在 Helm 中的实际应用，涵盖模板基础、四大内置对象（.Values、.Release、.Chart、.Files）以及模板函数与管道的使用模式。

4.1 Go 模板基础：从变量到控制结构

Helm 使用 Go 标准库 text/template 作为模板引擎，所有模板文件均以 {{ }} 作为动作分隔符。以下是最常用的基础语法元素：

语法	说明	示例
{{ . }}	当前上下文对象	{{ . }} 输出整个作用域
{{ .Values.key }}	访问 Values 中的字段	{{ .Values.replicaCount }}
{{- }}	修剪左侧空白	{{- .Values.name }}
{{ -}}	修剪右侧空白	{{ .Values.name -}}
{{ if / else / end }}	条件判断	{{ if .Values.enabled }}...{{ end }}
{{ range }}	遍历列表或字典	{{ range .Values.ports }}...{{ end }}
{{ with }}	限定作用域	{{ with .Values.db }}...{{ end }}
{{ define / template }}	定义和引用命名模板	{{ define "my.name" }}{{ .name }}{{ end }}

{{- /* 示例：带空白控制的 Deployment 模板片段 */ -}}
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ .Values.name | default "my-app" | quote }}
spec:
  replicas: {{ .Values.replicaCount | default 1 }}
  selector:
    matchLabels:
      app: {{ .Values.name }}
  template:
    metadata:
      labels:
        app: {{ .Values.name }}
    spec:
      containers:
        - name: {{ .Values.name }}
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
          ports:
{{- range .Values.ports }}
            - containerPort: {{ . }}
{{- end }}

4.2 四大内置对象详解

Helm 在模板渲染时注入四个顶级内置对象，它们构成了模板数据源的核心。理解每个对象的用途和访问方式，是编写高质量 Chart 的前提。

4.2.1 .Values：用户配置的入口

.Values 对象代表用户在 values.yaml 中定义的配置，以及通过 --set、--values 传入的覆盖值。它是模板中最常使用的对象。

• 层级访问： .Values.global.imageRegistry 或 .Values.service.port
• 默认值： 使用 default 函数提供回退值：{{ .Values.replicas | default 3 }}
• 类型安全： Values 支持字符串、数字、布尔、列表、字典等类型，模板中可直接使用 eq、and、or 等比较操作
• 全局值： 子 Chart 可通过 .Values.global 访问父 Chart 传递的全局配置

4.2.2 .Release：发布元数据

.Release 对象提供当前 Helm Release 的运行时信息，常用于生成唯一名称、命名空间隔离等场景。

字段	类型	说明	示例值
.Release.Name	string	Release 名称	my-app-prod
.Release.Namespace	string	目标 Kubernetes 命名空间	production
.Release.Revision	int	当前修订版本号（从 1 递增）	3
.Release.IsUpgrade	bool	是否为升级操作	true
.Release.IsInstall	bool	是否为首次安装	false
.Release.Service	string	管理该 Release 的服务（通常为 Helm）	Helm

{{- /* 使用 Release 对象生成唯一资源名称 */ -}}
apiVersion: v1
kind: ConfigMap
metadata:
  name: {{ .Release.Name }}-config
  namespace: {{ .Release.Namespace }}
data:
  release-info: |
    Name: {{ .Release.Name }}
    Revision: {{ .Release.Revision }}
    IsUpgrade: {{ .Release.IsUpgrade }}

4.2.3 .Chart：Chart 元数据

.Chart 对象对应 Chart.yaml 文件中的内容，提供 Chart 自身的描述信息。

字段	说明	Chart.yaml 对应字段
.Chart.Name	Chart 名称	name
.Chart.Version	Chart 版本号	version
.Chart.AppVersion	应用版本号	appVersion
.Chart.Description	Chart 描述	description
.Chart.Keywords	关键词列表	keywords
.Chart.Home	项目主页 URL	home
.Chart.Sources	源码地址列表	sources

4.2.4 .Files：文件系统访问

.Files 对象允许模板读取 Chart 包内的非模板文件（如配置文件、证书、脚本等），但不能访问 templates/ 目录下的文件。

• 读取文件内容： {{ .Files.Get "config/app.conf" }}
• 读取文件列表： {{ .Files.Glob "config/*.yaml" }}
• 读取 ConfigMap 友好格式： {{ .Files.GetConfigMap "config/app.conf" }}（自动处理换行和缩进）
• 文件大小限制： 默认单个文件不超过 1MB，可通过 --files-max-size 调整

{{- /* 使用 .Files 注入配置文件到 ConfigMap */ -}}
apiVersion: v1
kind: ConfigMap
metadata:
  name: {{ .Release.Name }}-app-config
data:
  app.conf: |
{{ .Files.Get "config/app.conf" | indent 4 }}
  nginx.conf: |
{{ .Files.Get "config/nginx.conf" | indent 4 }}

4.3 模板函数与管道：数据转换的艺术

Helm 内置了超过 60 个模板函数，涵盖字符串处理、数学运算、类型转换、编码解码、日期格式化等场景。函数通过管道（|）串联，形成数据流式处理链。

4.3.1 常用内置函数分类

类别	函数	示例
字符串	quote、upper、lower、trim、replace	{{ .Values.name | upper | quote }}
默认值	default	{{ .Values.port | default 8080 }}
类型转换	int、float64、toString、toJson	{{ .Values.replicas | int }}
列表操作	first、last、uniq、join	{{ .Values.hosts | join "," }}
字典操作	keys、values、merge、hasKey	{{ .Values.labels | keys | join "," }}
编码	b64enc、b64dec、fromYaml、toYaml	{{ .Values.secret | b64enc }}
比较	eq、ne、lt、gt、and、or	{{ if eq .Values.env "prod" }}...{{ end }}
正则	regexMatch、regexReplaceAll	{{ regexReplaceAll "old" .Values.name "new" }}

4.3.2 管道链式处理

管道（|）将前一个函数的输出作为后一个函数的输入，形成从左到右的数据处理流。这是 Helm 模板中最具表达力的特性。

{{- /* 管道链式处理示例 */ -}}
{{- /* 原始值：.Values.image.tag = "v1.0.0-beta" */ -}}
{{- /* 目标：转换为大写并添加引号 */ -}}
{{ .Values.image.tag | upper | quote }}
{{- /* 输出："V1.0.0-BETA" */ -}}

{{- /* 更复杂的链：默认值 → 编码 → 缩进 */ -}}
{{ .Values.secretKey | default "default-secret" | b64enc | indent 4 }}

{{- /* 结合 range 和管道处理列表 */ -}}
{{- range .Values.hosts }}
  - {{ . | lower | quote }}
{{- end }}

4.3.3 自定义模板函数（命名模板）

当内置函数无法满足需求时，可以通过 define 创建可复用的命名模板，并在 _helpers.tpl 中集中管理。

{{- /* _helpers.tpl 中定义自定义函数 */ -}}
{{- define "myapp.fullname" -}}
{{- printf "%s-%s" .Release.Name .Chart.Name | trunc 63 | trimSuffix "-" -}}
{{- end -}}

{{- define "myapp.labels" -}}
app.kubernetes.io/name: {{ .Chart.Name }}
app.kubernetes.io/instance: {{ .Release.Name }}
app.kubernetes.io/version: {{ .Chart.AppVersion }}
app.kubernetes.io/managed-by: {{ .Release.Service }}
{{- end -}}

{{- /* 在模板中引用 */ -}}
metadata:
  name: {{ include "myapp.fullname" . }}
  labels:
{{ include "myapp.labels" . | indent 4 }}

4.4 内置对象与函数协作流程图

下图展示了 Helm 模板渲染时，四大内置对象与模板函数、管道之间的数据流关系：

4.5 模板语法避坑指南

常见错误	错误示例	正确做法
忘记传递上下文	{{ include "myapp.fullname" }}	{{ include "myapp.fullname" . }}
未使用空白控制导致 YAML 格式错误	{{ range .Values.items }}{{ . }}{{ end }}	{{- range .Values.items }}{{ . }}{{- end }}
访问不存在的嵌套字段	.Values.nested.key（nested 为 nil）	{{ (.Values.nested).key | default "" }}
整数与字符串比较	{{ if eq .Values.port "8080" }}	{{ if eq (.Values.port | int) 8080 }}
在 range 中丢失父作用域	{{ range .Values.items }}{{ .Values.global.key }}{{ end }}	{{ range .Values.items }}{{ $.Values.global.key }}{{ end }}