📚 课程目录第2章 Values基础语法

2. Values 基础语法：YAML 基础、数据类型与注释规范

Helm Values 文件本质上是遵循 YAML 1.2 规范的配置文件。掌握 YAML 基础语法、数据类型及注释规范，是编写可复用、可维护的 Values 文件的前提。本章将系统讲解这些核心要素，并通过实例演示如何在实际 Chart 中应用。

2.1 YAML 基础：缩进、键值对与结构

YAML（YAML Ain't Markup Language）是一种以数据为中心的序列化格式，其核心规则包括：

缩进：使用空格表示层级关系，禁止使用 Tab。通常使用 2 个空格作为一级缩进。
键值对：格式为 key: value，冒号后必须跟一个空格。
注释：以 # 开头，可位于行首或行尾。
文件扩展名：通常使用 .yaml 或 .yml。

  💡 最佳实践：在 Helm 项目中，Values 文件统一使用 .yaml 扩展名，并保持缩进风格一致。推荐使用支持 YAML 语法检查的编辑器（如 VS Code + YAML 插件）以避免缩进错误。

以下是一个符合规范的 YAML 结构示例：

# 顶层键
global:
  # 二级键
  registry: docker.io
  tag: "1.0.0"

# 另一个顶层键
service:
  port: 8080
  type: ClusterIP

2.2 数据类型详解

YAML 支持多种数据类型，在 Helm Values 中常用的有五种：字符串、数字、布尔值、列表和字典。下表总结了它们的语法规则与典型用途：

数据类型	YAML 语法示例	Helm 模板引用方式	典型场景
字符串	`name: my-app` `message: "hello world"`	`{{ .Values.name }}`	镜像名称、标签、环境变量值
数字	`replicas: 3` `port: 8080`	`{{ .Values.replicas }}`	副本数、端口号、资源限制
布尔值	`enabled: true` `debug: false`	`{{ .Values.enabled }}`	功能开关、调试模式、TLS 启用
列表	`hosts: - example.com - api.example.com`	`{{ range .Values.hosts }} {{ . }} {{ end }}`	域名列表、白名单、环境变量数组
字典	`labels: app: nginx env: prod`	`{{ .Values.labels.app }}`	标签、注解、资源配额、配置映射

2.2.1 字符串的特殊处理

在 Helm Values 中，字符串可以不加引号，但以下情况必须使用引号包裹：

包含特殊字符（如 :、#、!）时：message: "value: with colon"
以数字开头但需要作为字符串处理时：version: "1.2.3"
包含布尔值关键字但需要作为字符串时：flag: "true"
多行字符串使用 |（保留换行）或 >（折叠换行）：

multiline_pipe: |
  第一行
  第二行
  第三行

multiline_fold: >
  第一行
  第二行
  第三行

2.2.2 数字与布尔值的陷阱

⚠️ 常见陷阱：YAML 会将 yes、no、on、off 自动解析为布尔值。在 Helm Values 中，如果希望这些词作为字符串，必须加引号：flag: "yes"。同样，0123 会被解析为八进制数字 83，而非字符串 "0123"。

2.3 注释规范

良好的注释是 Values 文件可维护性的关键。Helm 社区推荐以下注释规范：

注释类型	格式	示例
行内注释	`# 注释内容`	`replicas: 3 # 生产环境建议至少 3 个副本`
块注释	多行 `#`	`# 此配置用于生产环境 # 请勿在开发环境使用`
参数说明注释	在参数上方单独行	`# 镜像拉取策略，可选值：Always/IfNotPresent/Never pullPolicy: IfNotPresent`
分组注释	用 `##` 或 `===` 分隔	`## ============ 网络配置 ============`

📌 专业建议：在大型 Chart 中，建议为每个顶层参数添加注释，说明其用途、默认值、可选值及依赖关系。这有助于团队成员快速理解配置意图，也便于自动生成文档。

2.4 数据类型在 Helm 模板中的实际应用

以下是一个完整的 values.yaml 示例，展示了各种数据类型的组合使用：

# ============ 全局配置 ============
global:
  # 镜像仓库地址
  registry: docker.io
  # 环境标签
  environment: production

# ============ 应用配置 ============
replicaCount: 3
image:
  repository: nginx
  tag: "1.25.0"
  pullPolicy: IfNotPresent

# 功能开关
features:
  monitoring: true
  tracing: false
  debug: "no"  # 使用引号避免被解析为布尔值

# 服务端口列表
ports:
  - name: http
    containerPort: 80
  - name: https
    containerPort: 443

# 资源限制
resources:
  requests:
    memory: "256Mi"
    cpu: "250m"
  limits:
    memory: "512Mi"
    cpu: "500m"

# 环境变量（字典形式）
env:
  LOG_LEVEL: info
  CACHE_TTL: "3600"

2.5 数据类型与模板渲染的关系

下面的 SVG 图展示了 Helm 模板引擎如何解析 Values 文件中的不同数据类型，并将其注入到 Kubernetes 资源模板中：

2.6 数据类型转换与模板函数

Helm 模板提供了一系列函数用于数据类型转换，这在处理 Values 参数时非常实用：

函数	作用	示例
`quote`	将值转为带引号的字符串	`{{ .Values.replicas \| quote }}` → `"3"`
`int`	将值转为整数	`{{ "8080" \| int }}` → `8080`
`bool`	将字符串转为布尔值	`{{ "true" \| bool }}` → `true`
`toString`	将值转为字符串	`{{ 42 \| toString }}` → `"42"`
`default`	为空时提供默认值	`{{ .Values.port \| default 8080 }}`

  🔧 实战技巧：在模板中引用 Values 参数时，建议使用 default 函数为关键参数提供回退值，避免因 Values 文件缺失导致渲染失败。例如：replicas: {{ .Values.replicaCount | default 1 }}

2.7 注释的最佳实践

高质量的 Values 文件注释应遵循以下原则：

描述意图而非实现：注释应说明“为什么”，而非“是什么”。例如：# 生产环境需要至少 3 个副本以保证高可用 优于 # 副本数为 3
标注可选值范围：对于枚举型参数，列出所有可选值：# 存储类型：ssd / hdd / premium
标记依赖关系：当某个参数依赖其他参数时，在注释中说明：# 当 features.monitoring 为 true 时生效
使用分组注释：用 ## 或 === 分隔不同配置模块，提高可读性
避免冗余注释：不要为显而易见的参数添加注释，如 port: 8080 # 端口号

以下是一个符合最佳实践的 Values 文件片段：

## ============ 高可用配置 ============
# 副本数量，生产环境建议 3 以上
replicaCount: 3

# 更新策略，可选值：RollingUpdate / Recreate
updateStrategy: RollingUpdate

## ============ 监控配置 ============
# 启用 Prometheus 指标采集
# 需要先部署 prometheus-operator
metrics:
  enabled: true
  # 指标采集路径，默认 /metrics
  path: /metrics

2.8 本章小结

掌握 YAML 基础语法和数据类型是编写 Helm Values 文件的基石。核心要点包括：

YAML 使用空格缩进表示层级，禁止使用 Tab
五种基本数据类型：字符串、数字、布尔值、列表、字典
字符串在特定场景下必须加引号，避免类型误解析
注释应描述意图、标注可选值、标记依赖关系
模板函数可用于数据类型转换和提供默认值