4. Chart.yaml 详解：核心字段定义与最佳实践

Chart.yaml 是 Helm Chart 的元数据清单文件，位于 Chart 根目录，Helm 客户端通过它识别 Chart 的身份、版本、依赖与约束。一个结构严谨的 Chart.yaml 是发布治理的起点，也是运维排查版本冲突、依赖断裂、升级回滚的第一入口。

核心原则：Chart.yaml 中的每一个字段都应被显式声明，避免依赖 Helm 默认值。生产环境必须保证 version 与 appVersion 语义化、可追溯、与制品仓库一致。

4.1 字段定义速查表

字段 类型 是否必填 说明
apiVersion string 是 Chart API 版本，v1（Helm 2）或 v2（Helm 3+）
name string 是 Chart 名称，必须符合 DNS-1123 子域名规范
version semver 是 Chart 自身的语义化版本，用于 Helm 发布与回滚
appVersion string 推荐 所部署应用的版本号，可与 Chart version 不同步
description string 推荐 Chart 功能简述，用于 helm search 展示
dependencies list 按需 子 Chart 依赖列表，定义名称、版本、仓库地址
type string 否 application（默认）或 library
icon string 否 Chart 图标 URL，用于 UI 展示
keywords list 否 搜索关键词，增强 Chart 可发现性
home string 否 项目主页 URL
sources list 否 源码仓库地址列表
maintainers list 推荐 维护者信息（name、email、url）

4.2 核心字段深度解析

4.2.1 apiVersion：Chart API 版本选择

Helm 3 强制使用 v2，Helm 2 使用 v1。当前所有新 Chart 必须声明 apiVersion: v2。v2 支持依赖管理、Library Chart、更严格的 schema 校验。

迁移警告：不要将 v1 Chart 直接修改 apiVersion 为 v2 来“升级”。v2 对依赖目录结构、values 类型校验有差异，必须使用 helm create 重建或通过 helm package 验证。

4.2.2 name：Chart 命名规范

  • 必须符合 DNS-1123 子域名：只包含小写字母、数字、连字符（-），首尾为字母数字。
  • 禁止使用下划线、大写字母、点号。
  • 建议命名与 Git 仓库目录名、OCI 制品仓库名保持一致。
  • 示例：nginx-ingress、prometheus-operator。

4.2.3 version 与 appVersion：双版本治理

这是 Chart.yaml 中最容易混淆的一对字段，也是发布治理的核心。

维度 version appVersion
代表对象 Chart 包本身的版本 Chart 所部署的上游应用版本
变更时机 Chart 模板、values、依赖变更时 上游应用发布新版本时
格式要求 严格 SemVer 2.0 自由字符串，推荐 SemVer
helm list 展示 REVISION 列 APP VERSION 列
回滚影响 helm rollback 基于此版本 仅标识，不影响回滚逻辑
最佳实践 每次 Chart 变更递增 与上游 release tag 对齐 
# 典型生产示例
apiVersion: v2
name: redis-cluster
version: 3.2.1          # Chart 版本，第 3 次大重构，第 2 次特性，第 1 次补丁
appVersion: 7.2.4       # Redis 上游版本
description: "Redis Cluster Helm Chart for production workloads"
治理建议：在 CI/CD 中，每次 Chart 模板变更自动递增 version 的 patch 位；上游应用升级时同步更新 appVersion 并重置 version 的 minor 位。例如：appVersion 从 7.2.4 升到 7.4.0，Chart version 从 3.2.1 升到 3.3.0。

4.2.4 description：搜索与发现

description 会被 helm search 和 Helm UI（如 Harbor、Artifact Hub）展示。建议控制在 1-2 句话，包含 Chart 名称、主要功能、适用场景。

# 好的描述
description: "NGINX Ingress Controller for Kubernetes, supporting SSL termination, canary deployments, and custom annotations"

# 差的描述
description: "nginx chart"

4.2.5 dependencies：依赖治理

dependencies 字段定义了当前 Chart 所依赖的子 Chart。Helm 3 通过 helm dependency update 将依赖下载到 charts/ 目录并生成 Chart.lock 文件。

dependencies:
  - name: common
    version: "2.x.x"
    repository: "https://charts.bitnami.com/bitnami"
    condition: common.enabled
    tags:
      - bitnami-common
  - name: postgresql
    version: "12.1.0"
    repository: "https://charts.bitnami.com/bitnami"
    alias: db
    import-values:
      - child: defaults
        parent: postgresqlDefaults
子字段 说明 最佳实践
name 依赖 Chart 名称 与上游 Chart.yaml 的 name 一致
version 依赖版本范围 使用 SemVer 范围（如 1.x、>=2.0.0 <3.0.0）
repository Chart 仓库 URL 或 OCI 地址 优先使用 OCI 仓库（oci://）
condition 条件控制，值为 values 中的布尔路径 用于按环境开关依赖
tags 标签分组，可批量启用/禁用 避免与 condition 冲突
alias 依赖别名，避免同名冲突 当依赖多个同名 Chart 时必填
import-values 子 Chart values 导入父 Chart 谨慎使用，增加隐式耦合
依赖治理红线：
  • 永远不要手动修改 charts/ 目录下的依赖 Chart，必须通过 helm dependency update 管理。
  • Chart.lock 必须提交到 Git，确保可重现构建。
  • 避免使用 latest 或空版本范围，锁定主版本号（如 2.x）。

4.3 Chart.yaml 字段关系图

Chart.yaml 核心字段关系与治理层级 Chart.yaml apiVersion + name version + appVersion description + keywords maintainers dependencies type (application/library) icon + home + sources name + version repository condition + tags alias + import-values 治理要点 1. version 与 appVersion 必须分离管理，CI/CD 自动递增 version 2. dependencies 使用 SemVer 范围锁定主版本，Chart.lock 提交 Git 3. apiVersion 固定 v2，name 遵守 DNS-1123 规范 4. maintainers 字段必填，用于告警通知与负责人追溯

4.4 生产级 Chart.yaml 完整示例

apiVersion: v2
name: platform-gateway
version: 1.4.2
appVersion: 3.2.0
description: "Platform API Gateway based on Kong, with OAuth2, rate limiting, and observability integration"
type: application
keywords:
  - gateway
  - kong
  - api-management
  - platform
home: https://github.com/example/platform-gateway
sources:
  - https://github.com/example/platform-gateway
  - https://github.com/example/platform-common
icon: https://example.com/icons/gateway.png
maintainers:
  - name: "Platform Team"
    email: "platform@example.com"
    url: "https://platform.example.com"
  - name: "Alice Zhang"
    email: "alice@example.com"
dependencies:
  - name: kong
    version: "2.36.x"
    repository: "https://charts.konghq.com"
    condition: kong.enabled
  - name: postgresql
    version: "12.x"
    repository: "oci://registry-1.docker.io/bitnamicharts"
    alias: kong-db
    tags:
      - database
  - name: redis
    version: "18.x"
    repository: "oci://registry-1.docker.io/bitnamicharts"
    condition: redis.enabled
    tags:
      - cache
  - name: common
    version: "2.x"
    repository: "https://charts.bitnami.com/bitnami"
    tags:
      - platform-common
运维清单检查项：
  • ☐ version 是否使用 SemVer 且与 Git tag 一致？
  • ☐ appVersion 是否与上游应用 release 版本对齐？
  • ☐ dependencies 中是否所有 repository 可访问且版本范围合理？
  • ☐ Chart.lock 是否已生成并提交？
  • ☐ maintainers 是否包含当前负责人的有效邮箱？
  • ☐ apiVersion 是否为 v2？

4.5 常见错误与避坑指南

错误场景 后果 正确做法
version 使用 latest 或 1.0 helm list 无法区分版本，回滚失效 严格使用 SemVer：1.0.0
appVersion 与 version 同步递增 Chart 模板未变更却升级版本，造成冗余发布 分离管理，仅上游变更时更新 appVersion
dependencies 中 repository 使用 file:// 相对路径 CI/CD 环境路径不一致导致依赖解析失败 使用 HTTPS 或 OCI 仓库地址
name 包含大写字母或下划线 helm install 报错，K8s 资源命名冲突 全小写 + 连字符
缺少 maintainers 字段 故障时无法定位负责人 至少填写一个维护者邮箱
手动修改 charts/ 目录下的依赖 helm dependency update 覆盖修改，版本不一致 通过 dependency 声明 + update 管理

4.6 版本治理策略对比

version 与 appVersion 治理策略对比 策略 A：同步递增（不推荐） • version 与 appVersion 始终相同 • 每次上游升级，Chart 版本也递增 • 问题：模板未变也产生新 Chart 版本 • 问题：无法区分“模板修复”与“应用升级” • 后果：Chart 仓库膨胀，回滚粒度粗糙 示例：version 3.2.1 → appVersion 3.2.1 策略 B：分离治理（推荐） • version 仅 Chart 模板/values 变更时递增 • appVersion 仅上游应用发布时更新 • 模板修复：version 1.2.1 → 1.2.2 • 应用升级：appVersion 7.2.4 → 7.4.0 • 优势：精确回滚，版本可追溯 示例：version 1.2.2 + appVersion 7.4.0

4.7 本章小结

  • Chart.yaml 是 Helm Chart 的身份证，每个字段都有明确的治理含义。
  • version 与 appVersion 必须分离管理，这是发布治理的第一道防线。
  • dependencies 使用 SemVer 范围 + Chart.lock 锁定，确保可重现构建。
  • 生产环境必须填写 maintainers、description、keywords，提升可运维性。
  • 所有字段的变更都应通过 CI/CD 自动化，避免人工修改导致版本混乱。
← 上一章 📖 返回目录 下一章 →