3. Chart 目录结构：核心文件作用与规范

一个标准的 Helm Chart 遵循固定的目录布局。理解每个文件和目录的职责，是进行 Chart 开发、治理与运维的基础。本章将详细拆解 Chart 目录结构，并明确各核心文件的编写规范。

3.1 标准 Chart 目录全景

一个典型的 Chart 包（如 my-app-1.0.0.tgz）解压后，其内部目录结构如下所示。所有文件均位于以 Chart 名称命名的顶级目录下。

my-app/
├── Chart.yaml          # Chart 元数据定义文件（必需）
├── values.yaml         # 默认配置值文件（必需）
├── values.schema.json  # values.yaml 的 JSON Schema 校验文件（可选）
├── charts/             # 子 Chart 依赖目录（可选）
│   └── redis-17.3.0.tgz
├── templates/          # Kubernetes 资源模板目录（必需）
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── _helpers.tpl    # 模板辅助函数（可选）
│   └── tests/
│       └── test-connection.yaml
├── templates/NOTES.txt # 部署后的使用说明模板（可选）
├── README.md           # Chart 的说明文档（推荐）
├── LICENSE             # 许可证文件（可选）
└── .helmignore         # 打包时忽略的文件列表（可选）

3.2 核心文件作用与规范

下表详细列出了每个核心文件的作用、规范要求以及常见治理检查点。

3.3 文件依赖与数据流关系

下图展示了 Chart 在渲染过程中，各核心文件之间的数据流与依赖关系。理解此流程有助于定位配置问题。

3.4 关键文件编写规范详解

3.4.1 Chart.yaml：Chart 的身份证

Chart.yaml 是 Helm 识别一个 Chart 的首要文件。其内容必须遵循严格的格式和字段要求。

apiVersion: v2
name: my-app
description: A Helm chart for deploying my-app on Kubernetes
type: application

# Chart 版本，每次发布新 Chart 包时必须递增
version: 1.2.3

# 被部署应用的版本，可独立于 Chart 版本更新
appVersion: "3.0.0"

# 关键字，用于 helm search 索引
keywords:
  - web
  - application

# 维护者信息
maintainers:
  - name: DevOps Team
    email: devops@example.com

# 依赖声明
dependencies:
  - name: redis
    version: "~17.3.0"
    repository: "https://charts.bitnami.com/bitnami"
    condition: redis.enabled
    tags:
      - cache

3.4.2 values.yaml：配置的单一入口

values.yaml 是 Chart 与用户交互的核心界面。良好的 values.yaml 设计能极大降低使用复杂度。

# 全局配置
global:
  imageRegistry: ""

# 应用副本数
replicaCount: 3

# 镜像配置
image:
  repository: nginx
  tag: "1.25.3"
  pullPolicy: IfNotPresent

# 服务配置
service:
  type: ClusterIP
  port: 80

# 资源限制
resources:
  limits:
    cpu: 500m
    memory: 512Mi
  requests:
    cpu: 250m
    memory: 256Mi

# 是否启用 ingress
ingress:
  enabled: false
  className: ""
  hosts:
    - host: my-app.local
      paths:
        - path: /
          pathType: Prefix

# 子 Chart 控制
redis:
  enabled: true
  architecture: standalone

3.4.3 templates/ 目录：资源模板的规范

templates/ 目录下的每个文件都应遵循以下规范，以确保模板的可读性和可维护性。

{{- /* 文件头：声明 API 版本和资源类型 */ -}}
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "my-app.fullname" . }}
  labels:
    {{- include "my-app.labels" . | nindent 4 }}
spec:
  {{- /* 使用 values.yaml 中的配置 */}}
  replicas: {{ .Values.replicaCount }}
  selector:
    matchLabels:
      {{- include "my-app.selectorLabels" . | nindent 6 }}
  template:
    metadata:
      labels:
        {{- include "my-app.selectorLabels" . | nindent 8 }}
    spec:
      containers:
        - name: {{ .Chart.Name }}
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
          imagePullPolicy: {{ .Values.image.pullPolicy }}
          ports:
            - containerPort: {{ .Values.service.port }}

3.4.4 templates/NOTES.txt：部署后的用户手册

NOTES.txt 是 Helm 与用户交互的最后一个环节。一个优秀的 NOTES.txt 能显著提升用户体验。

Thank you for installing {{ .Chart.Name }}.

Your release is named {{ .Release.Name }}.

To access the application from outside the cluster, follow these steps:

1. Get the application URL by running these commands:
{{- if .Values.ingress.enabled }}
  http://{{ (index .Values.ingress.hosts 0).host }}{{ (index (index .Values.ingress.hosts 0).paths 0).path }}
{{- else if contains "NodePort" .Values.service.type }}
  export NODE_PORT=$(kubectl get --namespace {{ .Release.Namespace }} -o jsonpath="{.spec.ports[0].nodePort}" services {{ include "my-app.fullname" . }})
  export NODE_IP=$(kubectl get nodes --namespace {{ .Release.Namespace }} -o jsonpath="{.items[0].status.addresses[0].address}")
  echo http://$NODE_IP:$NODE_PORT
{{- else if contains "LoadBalancer" .Values.service.type }}
  NOTE: It may take a few minutes for the LoadBalancer IP to be available.
  export SERVICE_IP=$(kubectl get svc --namespace {{ .Release.Namespace }} {{ include "my-app.fullname" . }} --template "{{"{{ range (index .status.loadBalancer.ingress 0) }}{{.}}{{ end }}"}}")
  echo http://$SERVICE_IP:{{ .Values.service.port }}
{{- end }}

2. Default credentials (if applicable):
   Username: admin
   Password: {{ .Values.adminPassword | default "NOT SET - please set adminPassword" }}

3.5 目录结构治理检查清单

在 Chart 发布前，运维团队应使用以下清单进行自动化检查。

1. 必需文件完整性： 确认 Chart.yaml、values.yaml、templates/ 目录存在且非空。
2. YAML 语法校验： 使用 helm lint 检查所有 YAML 文件的语法正确性。
3. 模板渲染测试： 使用 helm template --debug 检查模板是否能正确渲染，且输出符合 K8s 资源规范。
4. 依赖完整性： 检查 Chart.lock 文件是否存在，且与 Chart.yaml 中的依赖声明一致。
5. 敏感信息扫描： 扫描 values.yaml 和 templates/ 中是否包含硬编码的密码、密钥或 。
6. NOTES.txt 可读性： 确认 NOTES.txt 模板语法正确，且不输出未定义的变量。