2. Helm 基础回顾：Chart 结构解析、模板引擎语法、内置对象与函数、Values 文件的优先级与合并规则

在深入网络拓扑数据注入之前，必须牢固掌握 Helm 的核心基础。本章将系统回顾 Chart 的标准目录结构、Go 模板引擎的核心语法、内置对象与函数，以及 Values 文件的优先级与合并规则。这些知识是后续实现动态注入的基石。

2.1 Chart 标准目录结构解析

一个标准的 Helm Chart 遵循固定的目录布局。理解每个文件和目录的职责，是编写可维护 Chart 的第一步。

2.2 模板引擎语法核心

Helm 使用 Go 标准库 text/template 作为模板引擎，并扩展了 sprig 函数库。模板语法以双花括号 {{ }} 作为定界符。

2.2.1 基本指令

• 输出值： {{ .Values.replicaCount }} —— 从 Values 对象中读取 replicaCount 字段。
• 注释： {{/* 这是一段注释 */}} —— 注释不会出现在渲染结果中。
• 管道与函数： {{ .Values.image.tag | default "latest" | quote }} —— 使用 default 和 quote 函数处理值。
• 条件判断： {{ if .Values.service.enabled }} ... {{ end }} —— 根据布尔值控制输出。
• 循环迭代： {{ range .Values.ports }} ... {{ end }} —— 遍历列表或字典。
• 变量赋值： {{ $name := .Values.appName }} —— 在模板内定义局部变量。

2.2.2 控制结构示例

{{- /* 条件判断：仅当 enabled 为 true 时创建 Service */ -}}
{{- if .Values.service.enabled }}
apiVersion: v1
kind: Service
metadata:
  name: {{ .Values.service.name | default "my-svc" }}
spec:
  type: {{ .Values.service.type }}
  ports:
    {{- range .Values.service.ports }}
    - port: {{ .port }}
      targetPort: {{ .targetPort }}
      protocol: {{ .protocol | default "TCP" }}
    {{- end }}
{{- end }}

2.3 内置对象与函数

Helm 模板引擎提供了丰富的内置对象，用于访问 Chart 元数据、Values 值、Release 信息以及集群环境变量。

2.3.1 常用内置函数

• 字符串处理： quote, upper, lower, trim, nospace, replace
• 默认值： default "fallback" .Value —— 当 Value 为空时使用默认值
• 类型转换： int, float64, toString, toJson
• 集合操作： has, uniq, merge, keys, values
• 流程控制： fail "错误信息" —— 主动终止渲染并报错
• 网络拓扑专用： fromJson —— 将 JSON 字符串解析为对象，便于处理动态拓扑数据

{{- /* 使用 fromJson 解析外部注入的拓扑 JSON */ -}}
{{- $topology := .Values.networkTopology | default "{}" | fromJson -}}
{{- range $node := $topology.nodes }}
- name: {{ $node.name }}
  ip: {{ $node.ip }}
  weight: {{ $node.weight | default 1 | int }}
{{- end }}

2.4 Values 文件的优先级与合并规则

Helm 支持从多个来源注入 Values，并按照严格的优先级进行合并。理解这一规则对于网络拓扑数据的动态注入至关重要。

2.4.1 优先级顺序（从高到低）

1. --set 命令行参数 —— 最高优先级，直接覆盖任何文件中的值。
2. --set-string / --set-json —— 强制字符串或 JSON 格式覆盖。
3. 用户自定义 Values 文件 —— 通过 -f 或 --values 指定，后指定的文件优先级更高。
4. 父 Chart 的 Values —— 当存在子 Chart 依赖时，父 Chart 的 Values 会传递给子 Chart。
5. Chart 自带的 values.yaml —— 最低优先级，作为默认值。

2.4.2 合并规则示例

2.5 实践：网络拓扑 Values 注入策略

基于上述优先级规则，在网络拓扑数据传输优化场景中，推荐采用以下分层注入策略：

• 基础拓扑结构 定义在 values.yaml 中，包含默认节点、链路和权重。
• 环境特定覆盖 通过 -f prod-values.yaml 提供生产环境的节点 IP、带宽限制等参数。
• 动态运行时注入 使用 --set-json 注入从外部系统（如服务网格控制面）实时获取的拓扑变更。
• 全局共享配置 通过父 Chart 的 .Values.global 传递跨 Chart 共享的网络参数（如集群 CIDR、DNS 后缀）。

# 示例：动态注入拓扑节点
helm upgrade --install network-optimizer ./chart \
  --set-json 'networkTopology.nodes=[{"name":"node-a","ip":"10.0.1.10","weight":3},{"name":"node-b","ip":"10.0.2.20","weight":5}]'