Helm 模板语法与 values.yaml

「Helm 模板到底怎么写？」——Go 模板引擎 + Sprig 函数，让 YAML 动起来。

Helm 的核心能力是模板化。你写一份 Chart，通过 values.yaml 和命令行参数注入不同的值，生成不同的 Kubernetes 资源。这个过程的背后，是 Go 模板引擎在驱动。

Go 模板基础

Helm 使用 Go 的 text/template 包作为模板引擎。模板以 {{ }} 包裹表达式。

yaml

# 基础语法
&#123;&#123; .Values.name &#125;&#125;          # 引用 Values 中的 name
&#123;&#123; .Release.Name &#125;&#125;         # 内置对象 Release 的 Name
&#123;&#123; .Chart.Version &#125;&#125;        # Chart 元数据

# 条件渲染
&#123;&#123;- if .Values.replicaCount &#125;&#125;
replicas: &#123;&#123; .Values.replicaCount &#125;&#125;
&#123;&#123;- end &#125;&#125;

# 注释
&#123;&#123;/* 这是一个注释，不会在输出中出现 */&#125;&#125;

注意 {{- 后面的短横线会自动去掉前方的空白，结束标签前的 - 会去掉后方空白，这是 Helm 模板对齐的常用技巧。

values.yaml 结构

values.yaml 是 Chart 的默认配置入口：

yaml

# values.yaml
replicaCount: 1

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

service:
  type: ClusterIP
  port: 80

ingress:
  enabled: true
  className: "nginx"
  annotations:
    kubernetes.io/ingress.class: nginx
  hosts:
    - host: myapp.example.com
      paths:
        - path: /
          pathType: Prefix

resources:
  limits:
    cpu: 100m
    memory: 128Mi
  requests:
    cpu: 50m
    memory: 64Mi

autoscaling:
  enabled: false
  minReplicas: 1
  maxReplicas: 10
  targetCPUUtilizationPercentage: 80

values 的覆盖优先级

Helm 支持多层 values，优先级从高到低：

bash

# 1. 最高：命令行 -f 指定的文件
helm install -f myvalues.yaml myrelease ./chart

# 2. 命令行 --set 参数
helm install --set replicaCount=3 myrelease ./chart

# 3. 当前目录的 values.yaml
# 4. Chart 内部的 values.yaml（最低）

bash

# 常见 set 用法
--set name=value              # 简单值
--set foo={a,b,c}            # 数组
--set foo=bar,baz=qux        # 多个值
--set foo[key]=value         # 字典
--set-json foo='{"a":1}'     # JSON 格式
--set-file foo=path/file     # 文件内容作为值

模板函数

Helm 内置了 100+ 模板函数，来自 Sprig 库。

字符串函数

yaml

# values.yaml
appName: my-app
version: v1.0.0
fullName: "&#123;&#123; .Values.appName &#125;&#125;-&#123;&#123; .Release.Name &#125;&#125;"

# upper / lower / title
appName: &#123;&#123; upper .Values.appName &#125;&#125;        # MY-APP
version: &#123;&#123; lower .Values.version &#125;&#125;        # v1.0.0

# quote / squote（加引号）
name: &#123;&#123; quote .Values.appName &#125;&#125;           # "my-app"
name: &#123;&#123; squote .Values.appName &#125;&#125;         # 'my-app'

# replace（替换）
imageTag: &#123;&#123; replace "v" "" .Values.version &#125;&#125;  # 1.0.0

# substr（截取）
shortVersion: &#123;&#123; substr 0 3 .Values.version &#125;&#125;   # v1.

逻辑与比较函数

yaml

# eq / ne / gt / lt / ge / le（等于/不等于/大于/小于/大于等于/小于等于）
&#123;&#123;- if eq .Values.replicaCount 1 &#125;&#125;
  # 单副本场景的特殊配置
&#123;&#123;- else if gt .Values.replicaCount 1 &#125;&#125;
  # 多副本场景
&#123;&#123;- end &#125;&#125;

# and / or / not（逻辑运算）
&#123;&#123;- if and .Values.ingress.enabled .Values.ingress.tls.enabled &#125;&#125;
  # 同时满足多个条件
&#123;&#123;- end &#125;&#125;

集合函数

yaml

# list（创建列表）
&#123;&#123;- $items := list "a" "b" "c" &#125;&#125;

# first / last / rest（取列表元素）
firstItem: &#123;&#123; first $items &#125;&#125;       # a
lastItem: &#123;&#123; last $items &#125;&#125;         # c

# has（检查是否包含）
hasA: &#123;&#123; has "a" $items &#125;&#125;          # true

# compact（去除空值）
cleanList: &#123;&#123; compact (list "a" "" "b" nil) | toJson &#125;&#125;

# merge（合并字典）
&#123;&#123;- $merged := merge (dict "key1" "val1") (dict "key2" "val2") &#125;&#125;

类型转换函数

yaml

# toString / toInt / toFloat64
count: &#123;&#123; .Values.count | toInt &#125;&#125;

# toYaml（将对象输出为 YAML 格式）
&#123;&#123; .Values.config | toYaml &#125;&#125;

# toJson / toJsonPretty
&#123;&#123; .Values.data | toJson &#125;&#125;

# default（默认值）
imageTag: &#123;&#123; .Values.image.tag | default "latest" &#125;&#125;

# required（必填值，缺失则报错）
clusterName: &#123;&#123; required "cluster.name is required" .Values.cluster.name &#125;&#125;

模板控制结构

if/else

yaml

&#123;&#123;- if .Values.ingress.enabled &#125;&#125;
---
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: &#123;&#123; include "mychart.fullname" . &#125;&#125;
  annotations:
    &#123;&#123;- range $key, $value := .Values.ingress.annotations &#125;&#125;
    &#123;&#123; $key &#125;&#125;: &#123;&#123; $value | quote &#125;&#125;
    &#123;&#123;- end &#125;&#125;
spec:
  ingressClassName: &#123;&#123; .Values.ingress.className &#125;&#125;
  rules:
  &#123;&#123;- range .Values.ingress.hosts &#125;&#125;
    - host: &#123;&#123; .host | quote &#125;&#125;
      http:
        paths:
        &#123;&#123;- range .paths &#125;&#125;
          - path: &#123;&#123; .path &#125;&#125;
            pathType: &#123;&#123; .pathType &#125;&#125;
            backend:
              service:
                name: &#123;&#123; $.Release.Name &#125;&#125;
                port:
                  number: 80
        &#123;&#123;- end &#125;&#125;
  &#123;&#123;- end &#125;&#125;
&#123;&#123;- end &#125;&#125;

range（循环）

yaml

# 遍历列表
env:
&#123;&#123;- range .Values.env &#125;&#125;
  - name: &#123;&#123; .name &#125;&#125;
    value: &#123;&#123; .value | quote &#125;&#125;
&#123;&#123;- end &#125;&#125;

# 遍历字典
annotations:
&#123;&#123;- range $key, $value := .Values.podAnnotations &#125;&#125;
  &#123;&#123; $key &#125;&#125;: &#123;&#123; $value | quote &#125;&#125;
&#123;&#123;- end &#125;&#125;

# 使用 index 访问列表元素
firstEnv: &#123;&#123; index .Values.env 0 "name" &#125;&#125;

with（修改作用域）

with 用于切换当前作用域（.）：

yaml

&#123;&#123;- with .Values.image &#125;&#125;
image: &#123;&#123; .repository &#125;&#125;:&#123;&#123; .tag &#125;&#125;
imagePullPolicy: &#123;&#123; .pullPolicy &#125;&#125;
&#123;&#123;- end &#125;&#125;
# with 块外，. 恢复到上级作用域

define 与 include

define 定义命名模板，include 引入并执行：

yaml

# _helpers.tpl（约定俗成的辅助模板文件）
&#123;&#123;- define "mychart.labels" -&#125;&#125;
app.kubernetes.io/name: &#123;&#123; .Chart.Name &#125;&#125;
app.kubernetes.io/version: &#123;&#123; .Chart.Version &#125;&#125;
app.kubernetes.io/managed-by: &#123;&#123; .Release.Service &#125;&#125;
&#123;&#123;- end &#125;&#125;

# 在任意资源中引用
metadata:
  labels:
    &#123;&#123;- include "mychart.labels" . | nindent 4 &#125;&#125;

include 会输出模板内容并保留缩进；template（旧写法）功能类似但不支持管道。

命名模板最佳实践

约定将辅助模板放在 templates/_helpers.tpl 中：

templates/
├── Chart.yaml
├── values.yaml
├── _helpers.tpl          # 辅助模板（推荐）
├── _labels.tpl           # 按功能分离
├── _common.tpl           # 
├── deployment.yaml
├── service.yaml
├── ingress.yaml
└── NOTES.txt             # 安装后提示信息

yaml

# _helpers.tpl
&#123;&#123;/*
Expand the name of the chart.
*/&#125;&#125;
&#123;&#123;- define "mychart.name" -&#125;&#125;
&#123;&#123;- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" &#125;&#125;
&#123;&#123;- end &#125;&#125;

&#123;&#123;/*
Create a default fully qualified app name.
*/&#125;&#125;
&#123;&#123;- define "mychart.fullname" -&#125;&#125;
&#123;&#123;- if .Values.fullnameOverride &#125;&#125;
&#123;&#123;- .Values.fullnameOverride | trunc 63 | trimSuffix "-" &#125;&#125;
&#123;&#123;- else &#125;&#125;
&#123;&#123;- $name := default .Chart.Name .Values.nameOverride &#125;&#125;
&#123;&#123;- if contains $name .Release.Name &#125;&#125;
&#123;&#123;- .Release.Name | trunc 63 | trimSuffix "-" &#125;&#125;
&#123;&#123;- else &#125;&#125;
&#123;&#123;- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" &#125;&#125;
&#123;&#123;- end &#125;&#125;
&#123;&#123;- end &#125;&#125;
&#123;&#123;- end &#125;&#125;

&#123;&#123;/*
Create chart name and version as used by the chart label.
*/&#125;&#125;
&#123;&#123;- define "mychart.chart" -&#125;&#125;
&#123;&#123;- printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" &#125;&#125;
&#123;&#123;- end &#125;&#125;

&#123;&#123;/*
Common labels
*/&#125;&#125;
&#123;&#123;- define "mychart.commonLabels" -&#125;&#125;
app.kubernetes.io/name: &#123;&#123; include "mychart.name" . &#125;&#125;
app.kubernetes.io/instance: &#123;&#123; .Release.Name &#125;&#125;
app.kubernetes.io/version: &#123;&#123; .Chart.AppVersion | default .Chart.Version &#125;&#125;
app.kubernetes.io/managed-by: &#123;&#123; .Release.Service &#125;&#125;
&#123;&#123;- end &#125;&#125;

常见模板场景

条件生成资源

yaml

&#123;&#123;- if .Values.persistence.enabled &#125;&#125;
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: &#123;&#123; include "mychart.fullname" . &#125;&#125;
spec:
  accessModes:
    - &#123;&#123; .Values.persistence.accessMode &#125;&#125;
  resources:
    requests:
      storage: &#123;&#123; .Values.persistence.size &#125;&#125;
&#123;&#123;- end &#125;&#125;

使用 lookup 获取集群资源

yaml

# 检查是否存在同名 Secret（lookup 返回空 map 表示不存在）
&#123;&#123;- $secret := lookup "v1" "Secret" .Release.Namespace "my-secret" &#125;&#125;
&#123;&#123;- if not $secret &#125;&#125;
---
apiVersion: v1
kind: Secret
metadata:
  name: my-secret
type: Opaque
data:
  password: &#123;&#123; .Values.password | b64enc &#125;&#125;
&#123;&#123;- end &#125;&#125;

处理多环境配置

yaml

# 方式一：通过环境名称切换
&#123;&#123;- if eq .Values.environment "production" &#125;&#125;
resources:
  limits:
    memory: 2Gi
    cpu: 1000m
&#123;&#123;- else &#125;&#125;
resources:
  limits:
    memory: 512Mi
    cpu: 500m
&#123;&#123;- end &#125;&#125;

# 方式二：独立的 values 文件
# values-dev.yaml / values-prod.yaml
# helm install -f values-prod.yaml myrelease ./chart

NOTES.txt 模板

安装后显示自定义提示信息：

yaml

# templates/NOTES.txt
Thank you for installing &#123;&#123; .Chart.Name &#125;&#125;.

Your release is named &#123;&#123; .Release.Name &#125;&#125;.

To learn more about the release, try:

  $ helm status &#123;&#123; .Release.Name &#125;&#125;
  $ helm get all &#123;&#123; .Release.Name &#125;&#125;

To access the application:
&#123;&#123;- if .Values.service.type "NodePort" &#125;&#125;
  $ export NODE_PORT=$(kubectl get -n &#123;&#123; .Release.Namespace &#125;&#125; -o jsonpath="{.spec.ports[0].nodePort}" services &#123;&#123; include "mychart.fullname" . &#125;&#125;)
  $ kubectl port-forward -n &#123;&#123; .Release.Namespace &#125;&#125; svc/&#123;&#123; include "mychart.fullname" . &#125;&#125; &#123;&#123; .Values.service.port &#125;&#125;:$NODE_PORT
&#123;&#123;- else &#125;&#125;
  $ kubectl port-forward -n &#123;&#123; .Release.Namespace &#125;&#125; svc/&#123;&#123; include "mychart.fullname" . &#125;&#125; &#123;&#123; .Values.service.port &#125;&#125;:8080
&#123;&#123;- end &#125;&#125;

调试模板

bash

# 渲染模板（不安装）
helm template myrelease ./chart
helm template myrelease ./chart --set replicaCount=3

# 本地调试（dry-run + 连到集群验证）
helm install --dry-run --debug myrelease ./chart

# 验证 Chart 语法
helm lint ./chart

# 在集群上模拟安装（不实际创建资源）
helm upgrade --install --dry-run --debug myrelease ./chart

面试追问方向

Helm 模板中的 . 作用域是什么？ —— . 是当前的作用域对象，可以是 Release、Values、Chart、Files 等内置对象，在 with 和 range 中会切换作用域。
Helm 模板如何实现「空值不渲染」？ —— {{- if .Values.foo }} 配合 {{- end }} 的短横线语法，或者使用 default 函数。
lookup 函数的限制是什么？ —— lookup 只在 helm template 和 --dry-run 时使用时会返回空（因为没有真实连接集群），生产环境中使用需谨慎。

"Helm 模板的精髓在于『一份 Chart，多种形态』。通过 values 的不同组合，同一套模板可以适应开发、测试、生产多个环境。"

Helm 模板语法与 values.yaml ​

Go 模板基础 ​

values.yaml 结构 ​

values 的覆盖优先级 ​

模板函数 ​

字符串函数 ​

逻辑与比较函数 ​

集合函数 ​

类型转换函数 ​

模板控制结构 ​

if/else ​

range（循环） ​

with（修改作用域） ​

define 与 include ​

命名模板最佳实践 ​

常见模板场景 ​

条件生成资源 ​

使用 lookup 获取集群资源 ​

处理多环境配置 ​

NOTES.txt 模板 ​

调试模板 ​

面试追问方向 ​

Helm 模板语法与 values.yaml

Go 模板基础

values.yaml 结构

values 的覆盖优先级

模板函数

字符串函数

逻辑与比较函数

集合函数

类型转换函数

模板控制结构

if/else

range（循环）

with（修改作用域）

define 与 include

命名模板最佳实践

常见模板场景

条件生成资源

使用 lookup 获取集群资源

处理多环境配置

NOTES.txt 模板

调试模板

面试追问方向