3. Helm 基础：Chart 结构解析、模板引擎语法、Values 文件设计原则

在构建故障域隔离演练平台的门户看板集成之前，必须掌握 Helm 的核心基础。Helm Chart 是 Kubernetes 应用的打包单元，其目录结构、模板语法和 Values 设计直接决定了看板组件的可配置性、可复用性和故障隔离能力。本节将系统解析 Chart 的骨架、模板引擎的核心语法以及 Values 文件的设计原则，为后续的看板集成演练打下坚实基础。

3.1 Chart 标准目录结构解析

一个标准的 Helm Chart 遵循固定的目录布局。理解每个文件和目录的职责，是编写可维护 Chart 的第一步。下表列出了核心组件及其在故障域隔离场景中的典型用途。

下图展示了 Helm Chart 的标准目录结构，以及各组件在看板集成中的角色映射。

3.2 模板引擎语法核心

Helm 使用 Go 模板引擎扩展 Kubernetes 资源清单。模板语法以双花括号 {{ }} 为标记，支持变量引用、管道函数、流程控制和作用域管理。在看板集成中，模板语法用于将 Values 中的配置动态注入到 Deployment、ConfigMap 等资源中。

3.2.1 变量引用与内置对象

模板中最基本的操作是引用 Values 中的值。Helm 提供了多个内置对象，最常用的是 .Values、.Release 和 .Chart。

# values.yaml
dashboard:
  replicaCount: 2
  image:
    repository: "myregistry/dashboard"
    tag: "v1.0.0"
  faultDomain: "az-1"

# templates/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ .Release.Name }}-dashboard
  labels:
    app: dashboard
    fault-domain: {{ .Values.dashboard.faultDomain }}
spec:
  replicas: {{ .Values.dashboard.replicaCount }}
  template:
    spec:
      containers:
        - name: dashboard
          image: "{{ .Values.dashboard.image.repository }}:{{ .Values.dashboard.image.tag }}"

3.2.2 管道函数与流程控制

模板引擎支持丰富的管道函数和流程控制语句，用于处理默认值、字符串转换和条件渲染。下表列出了看板集成中最常用的语法元素。

# 条件渲染示例：根据故障域启用不同的数据源
{{- if eq .Values.dashboard.faultDomain "az-1" }}
dataSources:
  - name: "primary-metrics"
    url: "http://prometheus-az1:9090"
{{- else if eq .Values.dashboard.faultDomain "az-2" }}
dataSources:
  - name: "secondary-metrics"
    url: "http://prometheus-az2:9090"
{{- else }}
dataSources:
  - name: "default-metrics"
    url: "http://prometheus-default:9090"
{{- end }}

3.2.3 模板函数与作用域

Helm 内置了超过 60 个模板函数，并支持通过 _helpers.tpl 定义自定义函数。作用域控制是模板编写的难点，使用 $ 可以引用根作用域，避免在 range 或 with 块中丢失上下文。

# _helpers.tpl 定义自定义标签函数
{{- define "dashboard.labels" -}}
app: {{ .Chart.Name }}
release: {{ .Release.Name }}
fault-domain: {{ .Values.dashboard.faultDomain }}
{{- end -}}

# deployment.yaml 中引用
metadata:
  labels:
    {{- include "dashboard.labels" . | nindent 4 }}

3.3 Values 文件设计原则

Values 文件是 Chart 的配置接口，其设计质量直接影响看板组件的可配置性和故障域隔离能力。良好的 Values 设计应遵循以下原则。

3.3.1 分层结构与类型安全

Values 应使用分层结构组织配置项，避免扁平化命名空间。同时，应明确每个字段的类型和默认值，便于模板进行类型判断。

3.3.2 故障域隔离专用 Values 设计

在看板集成场景中，Values 文件需要专门设计故障域相关的配置项，以便在不同故障域中部署时只需修改少量参数。

# values.yaml — 看板集成专用设计
# 全局配置
global:
  environment: "production"
  faultDomain: "default"          # 当前部署的故障域

# 看板核心配置
dashboard:
  enabled: true
  replicaCount: 2
  title: "故障域演练看板"
  port: 8080

  # 数据源配置（按故障域区分）
  dataSources:
    - name: "prometheus"
      url: "http://prometheus-{{ .Values.global.faultDomain }}:9090"
    - name: "elasticsearch"
      url: "http://elasticsearch-{{ .Values.global.faultDomain }}:9200"

  # 看板 UI 配置
  ui:
    theme: "dark"
    refreshInterval: 30           # 自动刷新间隔（秒）
    showFaultDomainBadge: true    # 是否显示故障域标签

  # 故障域演练专用配置
  faultSimulation:
    enabled: false                # 是否启用故障模拟
    latencyMs: 0                  # 模拟延迟（毫秒）
    errorRate: 0.0                # 模拟错误率（0.0 ~ 1.0）

# 网络配置
ingress:
  enabled: true
  host: "dashboard.{{ .Values.global.faultDomain }}.example.com"
  annotations:
    nginx.ingress.kubernetes.io/rewrite-target: "/"

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

3.3.3 Values 覆盖策略

在实际部署中，不同故障域需要不同的 Values 覆盖。Helm 支持通过多个 -f 参数叠加 Values 文件，后加载的文件会覆盖先加载的同名配置。

# 基础 Values 文件（所有故障域共享）
helm install my-dashboard ./dashboard-chart -f values.yaml

# 故障域 az-1 专用覆盖
helm upgrade my-dashboard ./dashboard-chart \
  -f values.yaml \
  -f values-az1.yaml

# 故障域 az-2 专用覆盖
helm upgrade my-dashboard ./dashboard-chart \
  -f values.yaml \
  -f values-az2.yaml

# values-az1.yaml 示例
global:
  faultDomain: "az-1"
dashboard:
  dataSources:
    - name: "prometheus"
      url: "http://prometheus-az1:9090"
ingress:
  host: "dashboard.az1.example.com"

下图展示了 Values 文件分层覆盖的流程，以及如何通过不同的覆盖文件实现故障域隔离。

3.4 本章小结

• Chart 结构：标准目录包含 Chart.yaml、values.yaml、templates/ 等核心组件，charts/ 用于管理依赖。
• 模板语法：使用 {{ }} 引用变量，通过 default、if/else、range 等实现动态渲染，注意作用域控制。
• Values 设计：采用分层结构、类型明确、默认值完备、注释完整；针对故障域隔离，将 faultDomain 置于 global 层级，并通过多文件覆盖实现差异化部署。