📚 课程目录第4章 Values参数基础

4. Values 参数基础：定义方式、默认值、用户自定义值、--set 命令行传参、--values 文件传参

Helm 的 Values 系统是 Chart 配置化的核心机制。它通过分层定义、合并与覆盖的规则，让用户无需修改 Chart 源码即可灵活定制部署参数。理解 Values 的定义方式、默认值机制以及多种传参方法，是掌握 Helm 资源模型映射的第一步。

4.1 Values 的定义方式与默认值

每个 Chart 在 values.yaml 文件中声明其所有可配置参数的默认值。这些默认值构成了 Chart 的“出厂设置”，当用户不提供任何自定义值时，Helm 直接使用这些默认值渲染模板。

定义位置	文件/方式	优先级	说明
Chart 内置默认值	`values.yaml`	最低（基础层）	Chart 开发者预设的默认配置，所有用户自定义值都基于此层覆盖
父 Chart 默认值	父 Chart 的 `values.yaml`	次低	当 Chart 作为子 Chart 被依赖时，父 Chart 可提供默认值
用户自定义文件	`-f values-custom.yaml`	高	用户通过 `--values` 或 `-f` 指定的 YAML 文件
命令行传参	`--set key=value`	最高	直接覆盖同名参数，支持复杂表达式

  关键原则：Helm 使用“后加载覆盖前加载”的合并策略。多个 --values 文件按顺序合并，--set 参数最后应用，因此 --set 拥有最高优先级。

4.2 默认值文件结构示例

以下是一个典型 values.yaml 的片段，展示了层级结构与常见数据类型：

# values.yaml — Chart 默认值
replicaCount: 3

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

service:
  type: ClusterIP
  port: 80

ingress:
  enabled: false
  className: ""
  annotations: {}
  hosts:
    - host: chart-example.local
      paths:
        - path: /
          pathType: Prefix

resources:
  limits:
    cpu: 500m
    memory: 512Mi
  requests:
    cpu: 250m
    memory: 256Mi

nodeSelector: {}
tolerations: []
affinity: {}

最佳实践：Chart 开发者应在 values.yaml 中为每个参数添加注释，说明用途、数据类型和可选值。这不仅是文档，也是 IDE 自动补全和校验的基础。

4.3 用户自定义值：--values 文件传参

用户通过 --values（或简写 -f）指定一个或多个 YAML 文件来覆盖默认值。Helm 会将这些文件与 Chart 内置的 values.yaml 进行深度合并。

单文件传参：

helm install my-release ./mychart --values my-values.yaml

多文件传参（后文件覆盖前文件）：

helm install my-release ./mychart \
  -f base-values.yaml \
  -f staging-overrides.yaml \
  -f production-overrides.yaml

假设 my-values.yaml 内容如下：

# my-values.yaml — 用户自定义覆盖
replicaCount: 5
image:
  tag: "1.26.0"
service:
  type: LoadBalancer

合并后，replicaCount 变为 5，image.tag 变为 1.26.0，service.type 变为 LoadBalancer，而 resources、ingress 等未覆盖的参数仍使用 Chart 默认值。

4.4 --set 命令行传参

--set 参数允许在命令行直接指定键值对，适合临时覆盖或 CI/CD 流水线中动态传参。语法规则如下：

场景	命令行示例	说明
简单键值	`--set replicaCount=3`	直接覆盖顶层标量
嵌套键	`--set image.tag=1.26.0`	使用点号分隔层级路径
列表元素	`--set service.ports[0].port=80`	使用数组索引访问列表元素
复杂对象	`--set resources.limits.cpu=1`	逐层指定嵌套对象的值
多个参数	`--set a=1,b=2`	逗号分隔多个键值对
JSON 字符串	`--set 'nodeSelector={kubernetes.io/os: linux}'`	使用花括号表示内联对象

注意：--set 参数的值会被 Helm 解析为 YAML 类型。例如 --set enabled=true 会解析为布尔值 true，而非字符串 "true"。如果确实需要字符串，应使用 --set-string 或加引号。

4.5 Values 分层合并流程

下图展示了 Helm 在安装或升级时，如何将多个 Values 来源按优先级合并为最终的 .Values 对象：

4.6 多文件与 --set 混合使用示例

实际部署中，经常需要组合使用 --values 和 --set。以下是一个典型的生产环境部署命令：

helm upgrade --install production-release ./mychart \
  --values values.yaml \
  --values values-production.yaml \
  --set image.tag=1.26.0 \
  --set replicaCount=10 \
  --set 'ingress.annotations.nginx\.ingress\.kubernetes\.io/rewrite-target=/'

  合并结果分析：
  values.yaml 提供基础默认值（如 service.type: ClusterIP）
values-production.yaml 覆盖环境级参数（如 resources.limits.cpu: 2）
--set image.tag=1.26.0 覆盖镜像标签
--set replicaCount=10 覆盖副本数
--set ingress.annotations... 使用转义点号设置带特殊字符的 annotation 键

4.7 特殊场景：--set 的转义与类型控制

场景	命令示例	说明
键名包含点号	`--set 'ingress.annotations.nginx\.ingress\.kubernetes\.io/rewrite-target=/'`	使用反斜杠转义点号，避免被解析为层级分隔符
强制字符串类型	`--set-string version=1.0`	防止 `1.0` 被解析为浮点数 `1.0`
强制整数类型	`--set-int port=8080`	确保值被解析为整数而非字符串
列表整体赋值	`--set tolerations={key:value,effect:NoSchedule}`	使用花括号表示列表或对象
空值/删除键	`--set ingress.annotations=null`	将值设为 `null` 可删除该键（需模板支持）

调试技巧：使用 helm get values <release-name> 可以查看已部署 release 的最终合并 Values。使用 helm template --dry-run 配合 --values 和 --set 可以在安装前预览渲染结果。

4.8 Values 参数映射到模板的典型模式

在模板文件中，通过 .Values 对象访问所有合并后的参数。以下是一个 Deployment 模板中引用 Values 的典型模式：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "mychart.fullname" . }}
spec:
  replicas: {{ .Values.replicaCount }}
  selector:
    matchLabels:
      app: {{ include "mychart.name" . }}
  template:
    metadata:
      labels:
        app: {{ include "mychart.name" . }}
    spec:
      containers:
        - name: {{ .Chart.Name }}
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
          imagePullPolicy: {{ .Values.image.pullPolicy }}
          ports:
            - containerPort: {{ .Values.service.port }}
          resources:
            {{- toYaml .Values.resources | nindent 12 }}

这种映射模式确保了模板与 Values 之间的松耦合：修改 values.yaml 或通过 --set 传参即可改变部署行为，而无需修改模板代码。