2. Values 文件基础结构：YAML 语法回顾、Values 文件的默认层级、必填字段与可选字段的设计原则
在 Helm 网络拓扑性能调优中，Values 文件是 Chart 的“配置接口”。一个结构清晰、层级合理的 values.yaml 能大幅降低运维心智负担，避免因字段缺失或类型错误导致的部署失败。本节从 YAML 语法基础出发，逐步拆解 Values 文件的默认层级设计，并给出必填字段与可选字段的工程化设计原则。
2.1 YAML 语法快速回顾
YAML（YAML Ain’t Markup Language）是 Helm 默认的配置描述语言。以下是在 Values 文件中高频使用的语法要点：
| 语法特性 | 示例 | 说明 |
|---|---|---|
| 键值对 | replicaCount: 3 |
冒号后必须跟一个空格 |
| 字符串 | name: "my-app" |
可加引号，也可不加（无歧义时） |
| 数字 | port: 8080 |
不加引号，否则会被当作字符串 |
| 布尔值 | enabled: true |
小写 true/false，不加引号 |
| 列表 | dnsServers: |
短横线 + 空格，缩进对齐 |
| 嵌套映射 | network: |
缩进 2 空格，层级清晰 |
| 多行字符串 | config: | |
竖线保留换行，> 折叠换行 |
常见陷阱：YAML 对缩进极其敏感。Helm 在解析 values.yaml 时，禁止使用 Tab 缩进，必须统一使用 2 个空格。缩进不一致会导致
yaml: line X: did not find expected key 错误。
2.2 Values 文件的默认层级结构
一个面向网络拓扑性能调优的 Values 文件，通常包含以下四个核心层级。每个层级对应一个独立的配置关注点：
- 全局层（global）：跨 Chart 共享的配置，如集群名称、全局标签、镜像仓库地址。
- 应用层（app）：业务容器自身的配置，如副本数、资源限制、环境变量。
- 网络层（network）：网络拓扑相关的参数，如 MTU、CNI 插件、Service 类型、Ingress 配置。
- 性能调优层（performance）：内核参数、连接池大小、缓冲区设置、QoS 策略。
设计原则：层级深度建议不超过 4 层。过深的嵌套会导致模板中
.Values.xxx.yyy.zzz 路径过长，降低可读性。当层级超过 4 层时，考虑将子配置拆分为独立的子 Chart 或使用 --set 覆盖。
2.3 必填字段与可选字段的设计原则
在 Helm Chart 开发中，区分必填字段（required）与可选字段（optional）是保证 Chart 健壮性的关键。以下是在网络拓扑性能调优场景下的设计原则：
2.3.1 必填字段（Required Fields）
必填字段是 Chart 正常运行所不可或缺的参数。如果缺失，Chart 应拒绝部署并给出明确错误提示。典型场景包括：
- 网络接口名称：如
network.interfaceName，缺少则无法绑定网络策略。 - Service 端口映射：如
network.service.ports，缺少则服务不可达。 - MTU 值：如
network.mtu，在性能调优中必须显式指定。 - 集群 CIDR：如
network.clusterCIDR，用于路由规则生成。
实现方式：在模板中使用
{{ required "network.interfaceName is required" .Values.network.interfaceName }}。这会在 values.yaml 中缺失该字段时，直接终止 Helm 安装并打印错误信息。
2.3.2 可选字段（Optional Fields）
可选字段提供默认值，用户可根据实际环境覆盖。设计时需遵循以下原则：
- 提供合理的默认值：默认值应适用于大多数场景，如
performance.connectionPoolSize: 100。 - 使用
default函数：在模板中通过{{ default 1500 .Values.network.mtu }}安全取值。 - 避免空值陷阱：如果可选字段的默认值为空字符串或 0，需在模板中做空值判断。
- 分组注释：在 values.yaml 中为每个可选字段添加注释，说明其作用、取值范围和性能影响。
2.3.3 必填 vs 可选：决策矩阵
| 判断维度 | 必填字段 | 可选字段 |
|---|---|---|
| 缺失后果 | Chart 无法启动或产生错误路由 | 使用默认值，功能降级但可运行 |
| 用户心智负担 | 高（必须提供） | 低（可跳过） |
| 测试覆盖要求 | 必须测试缺失场景 | 测试默认值场景即可 |
| 变更风险 | 高（需版本升级通知） | 低（可平滑调整） |
| 典型示例 | network.clusterCIDR |
performance.bufferSize |
2.4 实战：一个网络拓扑 Values 文件示例
以下是一个融合了必填与可选字段的 values.yaml 片段，展示了层级结构与字段设计的具体落地：
# 全局配置
global:
clusterName: "production-cluster"
environment: "prod"
# 应用配置
app:
name: "network-probe"
replicaCount: 3
image:
repository: "myregistry/network-probe"
tag: "1.2.0"
pullPolicy: "IfNotPresent"
# 网络拓扑配置
network:
# 必填：集群 CIDR，用于路由规则生成
clusterCIDR: "10.100.0.0/16"
# 必填：主网络接口名称
interfaceName: "eth0"
# 可选：MTU 值，默认 1500
mtu: 1500
# 可选：Service 类型，默认 ClusterIP
serviceType: "ClusterIP"
service:
ports:
- name: "http"
port: 8080
targetPort: 8080
# 可选：Ingress 配置，默认不启用
ingress:
enabled: false
host: "probe.example.com"
# 性能调优配置
performance:
# 可选：连接池大小，默认 100
connectionPoolSize: 200
# 可选：内核网络缓冲区大小（字节），默认 65536
bufferSize: 131072
# 可选：是否启用 TCP 快速打开，默认 false
tcpFastOpen: false
最佳实践：在 values.yaml 中，必填字段不设置默认值，仅保留键名和注释；可选字段必须提供默认值，并在注释中标注取值范围。这样用户在阅读 values.yaml 时，一眼就能识别哪些参数必须修改。
2.5 本章小结
- YAML 语法是 Values 文件的基础，注意缩进、类型和引号规则。
- Values 文件默认层级建议分为 global、app、network、performance 四层，深度不超过 4 层。
- 必填字段使用
required函数，缺失即报错；可选字段使用default函数，提供合理默认值。 - 在 values.yaml 中通过注释和默认值的有无，直观区分必填与可选字段，降低用户使用门槛。