HelloWorld Helm Chart 教程

HelloWorld Helm Chart 是学习 Helm 的最佳入门示例。通过一个最小的 chart，你可以直观理解 Chart.yaml、values.yaml、templates 目录与 Go 模板语法，并亲自体验安装、升级、回滚与打包发布的完整流程。本教程以实操为核心，逐步拆解每个文件和命令的作用，提示常见陷阱与调试要点，帮助你快速把一个简单应用以可靠、可复用的 Chart 交付到 Kubernetes 集群。

为什么先做一个 HelloWorld Chart？

很多人一开始被 Helm 的概念和命令洪流淹没。如果把 Helm 想成是“打包并发布 Kubernetes 应用”的工具，HelloWorld Chart 就像学缝纫先缝一个小口袋：小、明确、能看到全流程。通过一个简单例子，你可以把抽象的概念变成操作步骤，遇到问题也更容易定位。

先理解核心概念（像解释给菜鸟听）

Chart：什么是包？

Chart 就是应用的包，里面包含元信息（Chart.yaml）、默认配置（values.yaml）和模板（templates/）。把 Chart 想成一个软件包，部署时会把模板渲染成 Kubernetes 的 YAML（Manifest）。

Release：部署的实例

Release 是安装到集群中的一个实例。用同一个 Chart 可以创建多个 Release，每个 Release 可以有不同的 values 来定制行为。

Values：配置的入口

values.yaml 存放默认配置。安装时可以通过 –set 或 -f 覆盖。它的设计理念是把可变的东西从模板里抽出来，使 Chart 可复用。

模板：用 Go 模板填充变量

templates 中的文件用 Go 模板语法（双大括号）来引用 .Values、.Release、.Capabilities 等对象。模板支持逻辑判断、循环、函数调用，这让一个模板能适配多个场景。

HelloWorld Chart 的目录结构（实操视角）

通过 helm create hellochart 可以生成一个标准结构，下面是典型的最小化结构及说明：

一步步创建你的 HelloWorld Chart

下面从零开始，假设你已经在本地安装了 helm v3（>=3.0）并能访问一个 Kubernetes 集群（kubectl 已配置）。

1. 初始化 Chart

• 命令：helm create hello-world
• 这个命令会生成一个完整的示例 Chart。你可以删减成最小示例以便学习。

2. 看看 Chart.yaml

打开 Chart.yaml，典型字段：

• apiVersion: chart 的版本（v2）
• name: Chart 名称
• version: Chart 的版本（语义化）
• appVersion: 应用镜像对应的版本

示例：

apiVersion: v2
name: hello-world
description: A minimal Helm chart for Kubernetes
type: application
version: 0.1.0
appVersion: "1.0"

3. 编辑 values.yaml

把可以变动的部分放这里。例如：

replicaCount: 1
image:
  repository: nginx
  tag: "stable"
  pullPolicy: IfNotPresent
service:
  type: ClusterIP
  port: 80

实际生产中，values 会更复杂，比如资源限制、探针、环境变量、持久化卷等。

4. 模板入门：templates/deployment.yaml

最简的 Deployment 模板会引用 .Values 中的字段：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "hello-world.fullname" . }}
spec:
  replicas: {{ .Values.replicaCount }}
  selector:
    matchLabels:
      app: {{ include "hello-world.name" . }}
  template:
    metadata:
      labels:
        app: {{ include "hello-world.name" . }}
    spec:
      containers:
        - name: {{ include "hello-world.name" . }}
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
          ports:
            - containerPort: 80

重点是理解模板表达式如何将 values 填进最终 YAML。

常用模板函数和技巧（让模板更干净）

• include：把 _helpers.tpl 中的模板片段引入（例如 fullname、name）
• toYaml + indent/nindent：把 Map 转成 YAML 并缩进，常用于注入复杂字段
• required：强制某个值存在，否则安装失败
• default：给一个缺省值
• tpl：把 values 中的字符串当模板渲染（动态注入模板）

举个小例子：动态环境变量

env:
{{- with .Values.env }}
{{ toYaml . | indent 10 }}
{{- end }}

这样你可以在 values.yaml 写：

env:
  - name: GREETING
    value: "hello"

安装、升级、回滚与删除（实操命令）

• 安装：helm install my-hello ./hello-world -f prod-values.yaml
• 查看状态：helm status my-hello
• 列出 releases：helm list
• 升级：helm upgrade my-hello ./hello-world -f prod-values.yaml
• 回滚：helm rollback my-hello 1
• 卸载：helm uninstall my-hello

小提示：从一开始就给 release 加有意义的名字，会让后续日志、历史更好定位。

调试与排错（现实中最常遇到的几类问题）

刚开始操作时会常见几类问题，按步骤排查更高效。

问题一：模板渲染错误

• 命令：helm template ./hello-world -f values.yaml —— 这个命令会把模板渲染到标准输出，省去安装步骤便于调试。
• 如果模板语法报错，通常是引用了不存在的字段或函数调用错误。

问题二：Kubernetes 资源未就绪

• 查看 Pod：kubectl get pods、kubectl describe pod <pod>、kubectl logs <pod>
• 如果是镜像拉取失败，检查 image.tag、image.repository 和 imagePullSecrets。
• 如果是探针（liveness/readiness），可能探针配置不合理导致 Pod 一直重启或标记为未就绪。

问题三：Service 找不到 Pod

常见原因是 labels/selectors 不匹配。确保 Deployment template 的 labels 与 Service 的 selector 完全一致（拼写和命名都要一致）。

查看 Helm 相关信息

• helm get manifest my-hello：查看 Helm 渲染并发送到 API Server 的 manifest。
• helm history my-hello：查看历史版本。
• helm get values my-hello：查看安装时使用的 values。

关于 CRD 和 crds/ 目录的注意事项

如果你的 Chart 需要安装自定义资源定义（CRD），把 CRD 文件放在 crds/ 目录中。Helm 在安装 Chart 时会先安装 crds/ 中的资源，但不会在卸载时删除这些 CRD，以避免意外删除用户数据。需要谨慎设计 CRD 生命周期。

Chart 的测试（helm test）

你可以在 templates 中提供测试 Job（带有 helm.sh/hook: test 标签），并使用 helm test release-name 来运行这些测试。测试 Job 的成功或失败会被 Helm 用来判断 test 是否通过，对 CI 很有用。

打包与发布 Chart

打包

使用 helm package ./hello-world 可以生成 hello-world-0.1.0.tgz。

生成索引（index.yaml）并发布仓库

• 本地生成索引：helm repo index . –url https://yourdomain/charts
• 简单方式：把 .tgz 和 index.yaml 放到一个静态服务器（如 GitHub Pages 或对象存储），然后通过 helm repo add 添加仓库。
• 企业场景通常使用 ChartMuseum 或 Harbor 的 Chart 仓库来托管和认证。

版本、语义化与兼容性

维护 Chart 时要同时管理 Chart 的版本（Chart.yaml: version）和应用版本（appVersion）。遵循语义化版本控制（SemVer）有助于用户判断兼容性。对于 Chart 的 breaking changes，应该增加 major 版本。

安全与签名

• 镜像安全：使用可信镜像、基于扫描的 CI 步骤（静态扫描、依赖检查）。
• 签名 Chart：可以使用 GPG 对打包的 Chart 进行签名（helm package –sign –key）来保证来源。
• values 中不要写明敏感信息（明文密码、密钥）。使用 Kubernetes Secrets 或外部密钥管理更安全。

进阶主题速览（知道它们存在就好，慢慢熟）

• hooks（pre-install、post-install、pre-upgrade 等）：用于在 Chart 生命周期特定时刻运行 Job 或其它资源。
• library charts：把可复用模板封装到库 chart 中，其他 chart 可以依赖它。
• dependencies：在 Chart.yaml 声明依赖子 chart，使用 helm dependency update 管理。
• values.schema.json：Helm 支持对 values 进行 JSON Schema 验证（从 v3.7 起更完善），可以在安装前验证用户输入。
• Chart 测试与 CI 集成：结合 helm lint、helm template、kubeconform/kubeval、kubectl apply –dry-run 或者 Kind 集群做集成测试。

在 CI/CD 中使用 HelloWorld Chart（示例思路）

典型步骤：

• 代码变更触发流水线。
• 构建并推镜像，生成镜像标签（例如基于 commit sha）。
• 更新 Chart 的 values（或使用 –set image.tag=sha）并运行 helm lint、helm template 校验模板。
• 在临时集群（Kind）上做集成测试：helm install，然后运行测试 Job，检查服务健康。
• 打包 Chart，生成索引并推送到 Chart 仓库（ChartMuseum、Harbor 或静态站点）。
• 在生产环境通过 CD 工具（Argo CD、Flux 或自建脚本）拉取并同步 Chart。

常见的设计建议（实务经验汇总）

• 把可变配置尽量放在 values 中，模板只做渲染逻辑。
• 避免在 values 中嵌套过深的结构（维护成本高），用合理的命名空间分组字段。
• 为重要字段使用 required，避免用户误操作导致部署失败。
• 使用 toYaml 和 nindent 来避免手写缩进错误。
• 把重复的模板片段放到 _helpers.tpl（或 library chart）中，减少复制粘贴。
• 保持 Chart 的向后兼容，升级时优先兼容老 values。

示例常见问题与快速解决清单

• Pod CrashLoopBackOff：查看 kubectl logs 与探针设置。
• ImagePullBackOff：检查 image 名称、标签、私有 registry 的凭证。
• Service 无法访问：检查 selector 与 pod labels 是否一致，Service 类型与端口是否正确。
• 安装失败报模板错误：用 helm template 本地渲染查语法和变量是否存在。
• 升级产生不期望的变更：使用 helm diff 插件或先用 helm template 对比差异。

小练习（边做边学）

如果你想马上上手，可以按下面的练习来实践：

1. 运行 helm create hello-world，删除不需要的模板，把 Deployment 和 Service 精简成最小版本。
2. 修改 values.yaml，改变镜像、副本数和 Service 类型，使用 helm template 验证渲染结果。
3. 在本地集群（Minikube 或 Kind）上安装：helm install myhello ./hello-world，观察 Pod、Service 的状态。
4. 引入一个可选的环境变量，通过 values 控制它是否注入，练习条件判断和 toYaml。
5. 打包 Chart 并在本地生成 index.yaml，搭建一个简单的静态仓库来测试 repo add 与 repo update。

参考资料（书名与工具，便于深入）

• 官方 Helm 文档（Helm 官方文档是权威参考）
• 书：Kubernetes Patterns、Managing Kubernetes 等（提供部署模式和实践）
• 工具：kubeval、kubeconform（YAML/CRD 校验），ChartMuseum（私有托管）

好了，手把手讲完这些常见点后，你应该能把 HelloWorld Chart 当作一把放大镜来看 Helm：每个文件、每条命令、每个失败案例都能被拆分、理解并改正。实践中多用 helm template、helm lint 和临时集群来验证，会比只看文档更快学会。愿你在下一次把一个小的 HelloWorld 进化成公司级的生产 Chart 时，能够稳稳把控变化和风险。