容器与云原生 / 系统课时
Helm 模板与变量
Helm 模板与变量
Helm 模板把一组 Kubernetes 清单变成可参数化的 Chart:Values 提供数据,模板函数负责格式化,条件和循环决定资源片段是否生成。掌握这条渲染链路后,就能用同一套模板安全适配不同环境,而不是复制多份 YAML。
学习目标
- 理解
.Values、内置对象与模板函数在渲染阶段的职责 - 使用条件、循环和常用函数生成可复用的 Kubernetes 资源
- 通过
helm template在安装前检查最终清单和变量覆盖结果
从 Values 到最终清单
Helm 不会把 values.yaml 直接提交给 Kubernetes。它先合并 Chart 默认值、额外 values 文件与命令行 --set 等覆盖项,再把结果注入模板上下文,最后渲染成普通 Kubernetes YAML。同名配置发生冲突时,显式传入的覆盖值优先于 Chart 默认值。

常用入口是 .Values,而 .Release.Name、.Chart.Name、.Capabilities 等属于 Helm 注入的内置对象。模板函数用于把值转换成合适的 YAML,例如 default 提供缺省值,quote 强制字符串化,toYaml 配合 nindent 输出嵌套结构。
用条件和循环组织一个主模板
下面给出可渲染的最小 Chart。values.yaml 保存镜像、副本数、环境变量和可选注解;Deployment 模板同时演示变量读取、函数、条件与循环。
# Chart.yaml
apiVersion: v2
name: web-chart
version: 0.1.0
appVersion: "1.0.0"该文件定义 Chart 元信息,保存为 web-chart/Chart.yaml 后即可被 Helm 识别。
# values.yaml
replicaCount: 2
image:
repository: nginx
tag: "1.27"
podAnnotations: {}
env:
APP_MODE: production
LOG_LEVEL: info保存为 web-chart/values.yaml。这些值只参与模板渲染,不会单独创建 Kubernetes 资源。
# templates/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
name: {{ .Release.Name }}-web
spec:
replicas: {{ .Values.replicaCount }}
selector:
matchLabels:
app: {{ .Release.Name }}-web
template:
metadata:
labels:
app: {{ .Release.Name }}-web
{{- with .Values.podAnnotations }}
annotations:
{{- toYaml . | nindent 8 }}
{{- end }}
spec:
containers:
- name: web
image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
imagePullPolicy: {{ .Values.image.pullPolicy | default "IfNotPresent" }}
env:
{{- range $name, $value := .Values.env }}
- name: {{ $name }}
value: {{ $value | quote }}
{{- end }}with 只在 podAnnotations 非空时生成 annotations,避免输出无意义的空节点;range 遍历键值对生成多个环境变量;管道把左侧结果传给右侧函数。nindent 8 会先换行再缩进 8 个空格,使 toYaml 的多行结果落在正确层级。
在安装前渲染并覆盖变量
使用 helm template 可以只渲染、不创建集群资源。下面把镜像标签临时改为 1.28,并只输出 Deployment 模板。
helm template demo ./web-chart --set image.tag=1.28 --show-only templates/deployment.yaml预期输出的关键内容如下。环境变量顺序不应作为业务逻辑依赖,实际输出还可能带有 Helm 生成的 Source 注释。
apiVersion: apps/v1
kind: Deployment
metadata:
name: demo-web
spec:
replicas: 2
selector:
matchLabels:
app: demo-web
template:
metadata:
labels:
app: demo-web
spec:
containers:
- name: web
image: "nginx:1.28"
imagePullPolicy: IfNotPresent
env:
- name: APP_MODE
value: "production"
- name: LOG_LEVEL
value: "info"如果需要覆盖较多配置,优先使用独立 values 文件,而不是堆叠大量 --set。环境文件更容易审查、版本控制和复现,而 --set 更适合少量临时覆盖。
把模板逻辑控制在可维护范围
模板应负责“组装清单”,而不是承载复杂业务逻辑。必须存在的值可用 required 提前失败;可选对象适合用 with;集合适合用 range。同一段名称、标签或注解被多处复用时,应抽到命名模板并通过 include 调用。
调试时先看渲染结果,再看 Kubernetes 行为:模板报错说明 Helm 无法完成渲染;YAML 结构错误通常是缩进或类型问题;资源被 API Server 拒绝则进入 Kubernetes 资源校验阶段。分清这三层,比直接反复安装更容易定位根因。