📚 课程目录第4章 Helm Chart基础

4. Helm Chart 基础：Chart 结构、模板语法、Values 文件、依赖管理

Helm Chart 是 Kubernetes 应用的打包格式，本质是一个按约定组织的文件集合。理解 Chart 的内部结构、模板渲染机制、Values 注入方式以及依赖管理，是开发网络拓扑感知调度器插件的前提。本章从这四个维度展开，为后续编写调度器 Helm Chart 奠定基础。

4.1 Chart 标准目录结构

一个标准的 Helm Chart 目录遵循以下约定，每个文件和目录都有明确的职责：

路径 / 文件	是否必须	作用说明
`Chart.yaml`	是	Chart 元数据：名称、版本、API 版本、描述、关键字等
`values.yaml`	是	默认配置值，供模板引用，用户可覆盖
`templates/`	是	存放 Go 模板文件，渲染后生成 Kubernetes 资源清单
`charts/`	否	子 Chart 或依赖 Chart 的存放目录
`crds/`	否	自定义资源定义（CRD），在模板渲染前安装
`templates/NOTES.txt`	否	安装成功后向用户显示的说明文本
`templates/_helpers.tpl`	否	模板辅助函数定义，可被其他模板引用

  调度器插件场景提示： 网络拓扑感知调度器通常需要注册 MutatingWebhookConfiguration 或 ValidatingWebhookConfiguration，这些资源应放在 templates/ 目录下；如果涉及自定义调度器 CRD，则必须放在 crds/ 目录，避免模板渲染顺序问题。

4.2 模板语法核心

Helm 使用 Go 模板引擎（text/template）配合 Sprig 函数库进行资源渲染。以下是最常用的模板语法元素：

4.2.1 基本指令

语法	说明	示例
`{{ .Values.key }}`	引用 values.yaml 中的值	`replicas: {{ .Values.replicaCount }}`
`{{ .Release.Name }}`	内置对象，当前 Release 名称	`name: {{ .Release.Name }}-scheduler`
`{{ .Chart.Name }}`	内置对象，Chart 名称	`app.kubernetes.io/name: {{ .Chart.Name }}`
`{{- if condition -}} ... {{- end -}}`	条件判断，`-` 用于消除空白	`{{- if .Values.webhook.enabled }} ... {{- end }}`
`{{- range $i, $v := .Values.nodes -}} ... {{- end -}}`	循环遍历列表或字典	`{{- range .Values.topologyZones }} ... {{- end }}`
`{{ .Values.nested.key \| default "fallback" }}`	管道函数，提供默认值	`port: {{ .Values.service.port \| default 80 }}`

4.2.2 辅助模板与命名模板

在 _helpers.tpl 中定义可复用的命名模板，避免重复代码：

{{- /* 定义命名模板：生成完整的资源名称 */ -}}
{{- define "scheduler.fullname" -}}
{{- printf "%s-%s" .Release.Name .Chart.Name | trunc 63 | trimSuffix "-" -}}
{{- end -}}

{{- /* 定义命名模板：通用标签 */ -}}
{{- define "scheduler.labels" -}}
app.kubernetes.io/name: {{ .Chart.Name }}
app.kubernetes.io/instance: {{ .Release.Name }}
app.kubernetes.io/version: {{ .Chart.AppVersion }}
{{- end -}}

在 deployment.yaml 中引用：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "scheduler.fullname" . }}
  labels:
    {{- include "scheduler.labels" . | nindent 4 }}
spec:
  replicas: {{ .Values.replicaCount }}

💡 调度器开发技巧： 网络拓扑感知调度器通常需要注入多个环境变量（如节点拓扑标签、网络延迟阈值）。建议在 _helpers.tpl 中定义 scheduler.envVars 命名模板，集中管理环境变量配置，便于维护和测试。

4.3 Values 文件与值注入机制

values.yaml 是 Chart 的默认配置入口。Helm 支持多层值覆盖，优先级从低到高依次为：

Chart 内置 values.yaml —— 最低优先级，作为默认值
父 Chart 的 values.yaml —— 当 Chart 作为子 Chart 时生效
用户提供的 -f 文件 —— 可指定多个 YAML 文件，后覆盖前
命令行 --set 参数 —— 最高优先级，直接覆盖特定键

以下是一个面向网络拓扑调度器的 values.yaml 示例：

# 调度器基础配置
replicaCount: 2
image:
  repository: myregistry/scheduler-plugin
  tag: "1.0.0"
  pullPolicy: IfNotPresent

# 网络拓扑感知配置
topology:
  enabled: true
  zoneLabel: "topology.kubernetes.io/zone"
  latencyThresholdMs: 10
  bandwidthThresholdMbps: 1000

# Webhook 配置（用于动态更新拓扑信息）
webhook:
  enabled: true
  port: 9443
  certManager:
    enabled: false

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

⚠️ 常见陷阱： 当使用 --set 设置嵌套值时，必须使用逗号分隔路径，例如 --set topology.latencyThresholdMs=5。如果值包含特殊字符（如逗号、括号），建议使用 --set-json 或 -f 文件方式注入。

4.4 依赖管理

当调度器插件依赖其他 Chart（如 cert-manager、prometheus-operator）时，需要在 Chart.yaml 中声明依赖关系。

4.4.1 声明依赖

在 Chart.yaml 的 dependencies 字段中定义：

apiVersion: v2
name: network-aware-scheduler
version: 0.1.0
appVersion: "1.0"
description: "网络拓扑感知调度器插件"

dependencies:
  - name: cert-manager
    version: "~1.12.0"
    repository: "https://charts.jetstack.io"
    condition: webhook.certManager.enabled
    alias: cert-manager
  - name: prometheus
    version: "~15.0.0"
    repository: "https://prometheus-community.github.io/helm-charts"
    condition: monitoring.enabled

4.4.2 依赖管理命令

命令	作用
`helm dependency update`	根据 Chart.yaml 下载依赖到 charts/ 目录，并生成 Chart.lock 锁定版本
`helm dependency build`	从 Chart.lock 重建依赖，确保版本一致性
`helm dependency list`	列出当前 Chart 的所有依赖及其状态

4.4.3 子 Chart 值覆盖

父 Chart 可以通过 values.yaml 中的嵌套键覆盖子 Chart 的配置：

# 父 Chart values.yaml
cert-manager:
  installCRDs: true
  replicaCount: 1

monitoring:
  enabled: false

  🔗 调度器依赖实践： 网络拓扑感知调度器通常依赖 cert-manager 管理 Webhook 证书。建议在 values.yaml 中通过 webhook.certManager.enabled 条件控制是否安装 cert-manager，避免强制依赖。同时，使用 alias 字段避免子 Chart 名称冲突。

4.5 本章小结

Chart 结构 遵循约定优于配置原则，templates/、values.yaml、Chart.yaml 是核心三要素。
模板语法 以 Go 模板为基础，结合 Sprig 函数和命名模板机制，实现动态资源生成。
Values 文件 支持多层覆盖，合理组织 values 结构可提升 Chart 的可配置性和复用性。
依赖管理 通过 dependencies 字段声明，配合条件控制和别名机制，实现灵活的组合部署。