4. 资源映射模型：Helm values.yaml 到 Kubernetes 资源对象的映射机制

Helm 的核心能力之一是将用户提供的配置数据（values.yaml）与预定义的模板（templates/ 目录下的 Go 模板文件）结合，最终生成一组结构化的 Kubernetes 资源对象（YAML/JSON）。这一过程被称为 资源映射。理解映射机制是编写可维护、可复用的 Helm Chart 的基础。

4.1 映射流程概览

从 values.yaml 到 Kubernetes 资源对象，Helm 内部经历了三个关键阶段：

1. 值注入：Helm 将 values.yaml、用户通过 --set 传入的值以及子 Chart 的值合并为一个全局的 .Values 对象。
2. 模板渲染：Go 模板引擎遍历 templates/ 目录下的每个文件，使用 .Values 对象替换模板中的占位符和逻辑控制语句。
3. 对象生成：渲染后的纯 YAML 字符串被 Helm 解析为 Kubernetes 资源对象，并发送给 API Server。

4.2 核心映射机制：模板函数与作用域

映射的核心是 Go 模板语法。以下是最常用的映射模式：

4.3 资源映射的典型结构

一个标准的 Helm Chart 模板文件（如 deployment.yaml）通常包含以下映射结构：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "myapp.fullname" . }}
  labels:
    {{- include "myapp.labels" . | nindent 4 }}
spec:
  replicas: {{ .Values.replicaCount }}
  selector:
    matchLabels:
      {{- include "myapp.selectorLabels" . | nindent 6 }}
  template:
    metadata:
      labels:
        {{- include "myapp.selectorLabels" . | nindent 8 }}
    spec:
      containers:
        - name: {{ .Chart.Name }}
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"
          ports:
            - containerPort: {{ .Values.service.port }}
          env:
            {{- toYaml .Values.env | nindent 12 }}

4.4 映射中的类型转换与函数

Helm 模板提供了一系列内置函数，用于在映射过程中处理数据类型：

• toYaml：将复杂结构（如列表、字典）转换为缩进的 YAML 字符串，常用于注入 env、volumes 等字段。
• quote / squote：将值用双引号或单引号包裹，确保 YAML 解析器正确处理字符串类型。
• int / float64：强制类型转换，用于需要数值类型的字段（如 replicas）。
• nindent：在值前添加指定数量的空格并换行，用于保持 YAML 缩进层级。

4.5 映射案例：从 values.yaml 到 Deployment

以下是一个完整的映射案例，展示 values.yaml 如何驱动一个 Deployment 对象的生成：

values.yaml 输入：

replicaCount: 2
image:
  repository: nginx
  tag: "1.25"
service:
  port: 80
env:
  - name: NGINX_HOST
    value: example.com
  - name: NGINX_PORT
    value: "80"
resources:
  limits:
    cpu: 500m
    memory: 256Mi
  requests:
    cpu: 250m
    memory: 128Mi

模板渲染后的 Deployment 输出：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp-release
  labels:
    app.kubernetes.io/name: myapp
    app.kubernetes.io/instance: myapp-release
spec:
  replicas: 2
  selector:
    matchLabels:
      app.kubernetes.io/name: myapp
      app.kubernetes.io/instance: myapp-release
  template:
    metadata:
      labels:
        app.kubernetes.io/name: myapp
        app.kubernetes.io/instance: myapp-release
    spec:
      containers:
        - name: myapp
          image: "nginx:1.25"
          ports:
            - containerPort: 80
          env:
            - name: NGINX_HOST
              value: example.com
            - name: NGINX_PORT
              value: "80"
          resources:
            limits:
              cpu: 500m
              memory: 256Mi
            requests:
              cpu: 250m
              memory: 128Mi

4.6 映射中的全局对象与命名模板

除了 .Values，Helm 还提供了其他全局对象用于映射：

命名模板（通过 define 和 template 定义）是映射机制的重要扩展，用于封装重复的标签、名称生成逻辑，保持模板 DRY（Don't Repeat Yourself）。

{{- define "myapp.labels" -}}
app.kubernetes.io/name: {{ .Chart.Name }}
app.kubernetes.io/instance: {{ .Release.Name }}
{{- end -}}

4.7 映射中的依赖与子 Chart

当 Chart 包含子 Chart（通过 dependencies 定义）时，映射机制会引入作用域隔离：

• 子 Chart 的 values.yaml 默认只影响自身模板。
• 父 Chart 可以通过 子Chart名称: 键在 values.yaml 中覆盖子 Chart 的值。
• 子 Chart 通过 .Values.global 访问父 Chart 定义的全局变量。

# 父 Chart 的 values.yaml
global:
  commonLabel: "my-app"
mysql:
  image:
    tag: "8.0"  # 覆盖子 Chart mysql 的 image.tag