3. Chart 结构详解

Helm Chart 是 Kubernetes 应用的打包格式，其目录结构、元数据文件、模板引擎和依赖管理共同构成了 Helm 的资源模型基础。理解 Chart 的每一层结构，是编写可维护、可参数化 Helm 包的前提。

3.1 标准 Chart 目录结构

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

3.2 Chart.yaml 文件

Chart.yaml 是 Chart 的“身份证”，Helm 通过它识别 Chart 的身份、版本和依赖关系。以下是一个标准示例：

apiVersion: v2
name: mychart
description: A Helm chart for Kubernetes
type: application
version: 0.1.0
appVersion: "1.16.0"
kubeVersion: ">=1.19.0-0"
keywords:
  - web
  - database
home: https://example.com
sources:
  - https://github.com/example/mychart
maintainers:
  - name: John Doe
    email: john@example.com
    url: https://example.com
dependencies:
  - name: postgresql
    version: "12.x.x"
    repository: "https://charts.bitnami.com/bitnami"
    condition: postgresql.enabled
    tags:
      - database
    alias: db
icon: https://example.com/icon.svg
annotations:
  category: Infrastructure

3.3 values.yaml 文件

values.yaml 是 Chart 的配置中心，定义了所有可被模板引用的默认参数。Helm 通过 .Values 对象在模板中访问这些值。

# values.yaml
replicaCount: 3

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

service:
  type: ClusterIP
  port: 80

ingress:
  enabled: false
  className: ""
  hosts:
    - host: chart-example.local
      paths:
        - path: /
          pathType: ImplementationSpecific

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

autoscaling:
  enabled: false
  minReplicas: 1
  maxReplicas: 10
  targetCPUUtilizationPercentage: 80

nodeSelector: {}

tolerations: []

affinity: {}

Values 的层级结构直接映射到模板中的访问路径：

• .Values.replicaCount → 3
• .Values.image.repository → nginx
• .Values.service.port → 80
• .Values.ingress.enabled → false

3.4 templates 目录

templates/ 目录存放 Go 模板文件，Helm 将 values.yaml 中的参数注入模板，渲染出最终的 Kubernetes 资源清单。模板文件使用 .yaml 或 .tpl 扩展名。

一个典型的 Deployment 模板示例：

# 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 }}"
          imagePullPolicy: {{ .Values.image.pullPolicy }}
          ports:
            - containerPort: {{ .Values.service.port }}
          resources:
            {{- toYaml .Values.resources | nindent 12 }}

模板中常用的内置对象：

3.5 charts 依赖目录

charts/ 目录用于存放子 Chart 依赖。当你在 Chart.yaml 的 dependencies 中声明依赖后，执行 helm dependency update 会将依赖 Chart 下载到此目录。

依赖管理的三种方式：

• 直接存放：手动将子 Chart 的 .tgz 包或目录放入 charts/
• 声明式管理：在 Chart.yaml 的 dependencies 中声明，通过 helm dep update 自动下载
• 条件依赖：使用 condition 和 tags 控制依赖是否启用

依赖声明示例：

# Chart.yaml 中的 dependencies 段
dependencies:
  - name: postgresql
    version: "12.x.x"
    repository: "https://charts.bitnami.com/bitnami"
    condition: postgresql.enabled
    tags:
      - database
    alias: db

对应的 values.yaml 控制：

# values.yaml
postgresql:
  enabled: true
  postgresqlDatabase: myapp
  postgresqlUsername: admin

3.6 Chart 结构全景图

下图展示了 Chart 各组件之间的数据流和依赖关系：

3.7 参数映射流程

下图展示了从 values.yaml 到最终 Kubernetes 资源的完整参数映射链路：

3.8 关键实践要点

• 目录命名一致性：Chart 目录名必须与 Chart.yaml 中的 name 字段完全一致，否则 Helm 会报错。
• 模板文件组织：按 Kubernetes 资源类型拆分模板文件（如 deployment.yaml、service.yaml、ingress.yaml），避免将所有资源写在一个大文件中。
• Values 层级扁平化：避免过深的嵌套层级（超过 3 层），否则会降低可读性。使用 --set 覆盖时，深层路径容易出错。
• 依赖版本锁定：执行 helm dependency update 后会生成 Chart.lock 文件，锁定所有依赖的精确版本，确保可重复构建。
• 忽略非必要文件：使用 .helmignore 排除 .git/、.DS_Store、测试文件等，减小 Chart 包体积。