4. Chart 包结构：Chart.yaml、values.yaml、templates 目录、charts 依赖、NOTES.txt、helpers.tpl

一个标准的 Helm Chart 包遵循固定的目录与文件约定。理解这些核心构件是编写可维护、可复用的 Kubernetes 应用描述文件的基础。本章逐一拆解 Chart 包的六大组成部分，并说明它们在资源模型适配中的角色。

4.1 Chart 包顶层结构一览

执行 helm create mychart 后生成的标准骨架如下：

mychart/
├── Chart.yaml          # Chart 元数据定义
├── values.yaml         # 默认配置值
├── charts/             # 子 Chart 依赖（手动或 helm dependency 管理）
├── templates/          # Go 模板 + Kubernetes 资源清单
│   ├── NOTES.txt       # 安装后的使用提示
│   ├── _helpers.tpl    # 模板辅助函数（命名模板）
│   ├── deployment.yaml
│   ├── service.yaml
│   └── ...
└── .helmignore         # 打包时忽略的文件模式

4.2 Chart.yaml — Chart 的身份证

Chart.yaml 是每个 Chart 必须存在的元数据文件。Helm 通过它识别 Chart 的名称、版本、API 兼容性以及依赖声明。

4.3 values.yaml — 配置的默认值锚点

values.yaml 是 Chart 的默认配置入口。它定义了模板渲染时使用的变量初始值，用户可通过 --set 或自定义 values 文件覆盖。

# values.yaml 典型结构
replicaCount: 3

image:
  repository: nginx
  tag: "1.25"
  pullPolicy: IfNotPresent

service:
  type: ClusterIP
  port: 80

resources:
  limits:
    cpu: 500m
    memory: 512Mi
  requests:
    cpu: 250m
    memory: 256Mi

ingress:
  enabled: false
  host: myapp.example.com

4.4 templates 目录 — 资源模板的核心战场

templates/ 目录存放所有 Kubernetes 资源清单的 Go 模板文件。Helm 会递归渲染该目录下所有 .yaml、.tpl、.txt 文件，并将结果发送给 Kubernetes API。

模板文件的核心语法要素：

• 模板指令：{{ .Values.replicaCount }} 引用 values 值
• 管道函数：{{ .Values.name | default "default-name" | quote }}
• 流程控制：if/else、range、with
• 命名模板调用：{{ include "mychart.labels" . }}
• 内置对象：.Values、.Release、.Chart、.Files、.Capabilities

{{- /* templates/deployment.yaml 示例片段 */ -}}
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "mychart.fullname" . }}
  labels:
    {{- include "mychart.labels" . | nindent 4 }}
spec:
  replicas: {{ .Values.replicaCount }}
  selector:
    matchLabels:
      {{- include "mychart.selectorLabels" . | nindent 6 }}
  template:
    metadata:
      labels:
        {{- include "mychart.selectorLabels" . | nindent 8 }}
    spec:
      containers:
        - name: {{ .Chart.Name }}
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
          ports:
            - containerPort: {{ .Values.service.port }}

4.5 charts 依赖 — 子 Chart 管理

charts/ 目录存放 Chart 的依赖子 Chart。依赖关系在 Chart.yaml 的 dependencies 字段中声明，通过 helm dependency update 下载。

# Chart.yaml 中的依赖声明
dependencies:
  - name: redis
    version: "17.3.0"
    repository: "https://charts.bitnami.com/bitnami"
    condition: redis.enabled
    tags:
      - cache
  - name: postgresql
    version: "12.1.0"
    repository: "https://charts.bitnami.com/bitnami"
    condition: postgresql.enabled

4.6 NOTES.txt — 安装后的用户指引

NOTES.txt 是一个特殊的模板文件，在 helm install 或 helm upgrade 成功后自动渲染并输出给用户。它通常包含：

• 应用访问地址（Service IP、Ingress 域名）
• 默认凭据（用户名/密码）及获取方式
• 后续操作步骤（如数据库迁移命令）
• 故障排查提示

{{- /* templates/NOTES.txt 示例 */ -}}
1. Get the application URL by running these commands:
{{- if .Values.ingress.enabled }}
  http://{{ .Values.ingress.host }}/
{{- else }}
  export POD_NAME=$(kubectl get pods --namespace {{ .Release.Namespace }} -l "app.kubernetes.io/name={{ include "mychart.name" . }},app.kubernetes.io/instance={{ .Release.Name }}" -o jsonpath="{.items[0].metadata.name}")
  echo "Visit http://127.0.0.1:8080 to use your application"
  kubectl --namespace {{ .Release.Namespace }} port-forward $POD_NAME 8080:{{ .Values.service.port }}
{{- end }}

2. Default credentials:
   Username: admin
   Password: {{ .Values.adminPassword | default "changeme" }}

4.7 _helpers.tpl — 命名模板的复用工厂

_helpers.tpl 是约定俗成的命名模板文件（文件名以下划线开头，不会生成 Kubernetes 资源）。它定义可复用的模板片段，通过 define 和 include 机制在多个模板间共享。

{{- /* _helpers.tpl 典型内容 */ -}}
{{- define "mychart.name" -}}
{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
{{- end }}

{{- define "mychart.fullname" -}}
{{- if .Values.fullnameOverride }}
{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
{{- else }}
{{- $name := default .Chart.Name .Values.nameOverride }}
{{- if contains $name .Release.Name }}
{{- .Release.Name | trunc 63 | trimSuffix "-" }}
{{- else }}
{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
{{- end }}
{{- end }}
{{- end }}

{{- define "mychart.labels" -}}
helm.sh/chart: {{ include "mychart.name" . }}-{{ .Chart.Version | replace "+" "_" }}
{{ include "mychart.selectorLabels" . }}
{{- if .Chart.AppVersion }}
app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
{{- end }}
app.kubernetes.io/managed-by: {{ .Release.Service }}
{{- end }}

{{- define "mychart.selectorLabels" -}}
app.kubernetes.io/name: {{ include "mychart.name" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
{{- end }}

4.8 六大组件在资源模型适配中的协作关系