容器与云原生 / 系统课时

Helm 模板与变量

Helm 模板与变量

Helm 模板把一组 Kubernetes 清单变成可参数化的 Chart:Values 提供数据,模板函数负责格式化,条件和循环决定资源片段是否生成。掌握这条渲染链路后,就能用同一套模板安全适配不同环境,而不是复制多份 YAML。

学习目标

  • 理解 .Values、内置对象与模板函数在渲染阶段的职责
  • 使用条件、循环和常用函数生成可复用的 Kubernetes 资源
  • 通过 helm template 在安装前检查最终清单和变量覆盖结果

从 Values 到最终清单

Helm 不会把 values.yaml 直接提交给 Kubernetes。它先合并 Chart 默认值、额外 values 文件与命令行 --set 等覆盖项,再把结果注入模板上下文,最后渲染成普通 Kubernetes YAML。同名配置发生冲突时,显式传入的覆盖值优先于 Chart 默认值。

Helm Values 合并与模板渲染链路

常用入口是 .Values,而 .Release.Name、.Chart.Name、.Capabilities 等属于 Helm 注入的内置对象。模板函数用于把值转换成合适的 YAML,例如 default 提供缺省值,quote 强制字符串化,toYaml 配合 nindent 输出嵌套结构。

用条件和循环组织一个主模板

下面给出可渲染的最小 Chart。values.yaml 保存镜像、副本数、环境变量和可选注解;Deployment 模板同时演示变量读取、函数、条件与循环。

yaml
# Chart.yaml
apiVersion: v2
name: web-chart
version: 0.1.0
appVersion: "1.0.0"

该文件定义 Chart 元信息,保存为 web-chart/Chart.yaml 后即可被 Helm 识别。

yaml
# values.yaml
replicaCount: 2

image:
  repository: nginx
  tag: "1.27"

podAnnotations: {}

env:
  APP_MODE: production
  LOG_LEVEL: info

保存为 web-chart/values.yaml。这些值只参与模板渲染,不会单独创建 Kubernetes 资源。

yaml
# 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 模板。

bash
helm template demo ./web-chart --set image.tag=1.28 --show-only templates/deployment.yaml

预期输出的关键内容如下。环境变量顺序不应作为业务逻辑依赖,实际输出还可能带有 Helm 生成的 Source 注释。

yaml
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 资源校验阶段。分清这三层,比直接反复安装更容易定位根因。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

Helm 模板与变量

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通