ShowDocs
搜索文章Ctrl K

外观

← 返回Kubernetes列表
知识专题

Helm 基础与进阶 ​

用户常见的 “heml” 正确拼写为 Helm。Helm 用 Chart 描述 Kubernetes 应用，用 Release 表示一次命名安装实例。

一、版本口径 ​

截至 2026-08-12（Asia/Shanghai），官方 GitHub Releases 标记的最新稳定版本是 v4.2.3，发布于 2026-07-09；Helm 4 是当前稳定主线。v4.2.3 发布说明曾把 v4.2.4 计划在 2026-08-12 发布，但核对时它尚未成为 Latest，因此本文不把计划版本当成已发布版本。

本文以 Helm 4.2 为主。Helm 3 用户迁移前应阅读 Helm 4 Overview 和变更说明；Chart 多数保持兼容，但 CLI、插件、SDK 和默认行为可能不同。始终先运行 helm version 与 helm <command> --help。

二、概念与安装 ​

概念含义
Chart包含模板、默认值和元数据的可版本化应用包
ReleaseChart 在指定命名空间的一次安装实例
Values渲染模板时的配置输入
Revision安装、升级或回滚形成的历史修订
Repository / OCIChart 的 HTTP 或 OCI 分发方式

官方建议从 Release 下载二进制，验证 SHA256 和签名后安装。以 Linux AMD64 为例：

bash
HELM_VERSION=v4.2.3
curl -fLO "https://get.helm.sh/helm-${HELM_VERSION}-linux-amd64.tar.gz"
curl -fLO "https://get.helm.sh/helm-${HELM_VERSION}-linux-amd64.tar.gz.sha256sum"
sha256sum -c "helm-${HELM_VERSION}-linux-amd64.tar.gz.sha256sum"
tar -tzf "helm-${HELM_VERSION}-linux-amd64.tar.gz"
tar -xzf "helm-${HELM_VERSION}-linux-amd64.tar.gz"
./linux-amd64/helm version
sudo install -m 0755 ./linux-amd64/helm /usr/local/bin/helm

签名和维护者公钥以官方安装文档为准。生产环境不要未经审查执行 curl ... | bash。

bash
helm version
helm env
kubectl config current-context
kubectl config view --minify
helm --kube-context <context> list -n <namespace>

Helm 使用 kubeconfig 访问集群；kubeconfig 可能含凭据，应设为 chmod 600 且禁止提交到 Git。

三、仓库与 Chart 检查 ​

bash
helm repo list
helm repo add <repo> https://<trusted-repository>/charts
helm repo update
helm search repo <repo>/<chart> --versions
helm search hub <keyword>
helm show chart <repo>/<chart> --version <chart-version>
helm show values <repo>/<chart> --version <chart-version>
helm show readme <repo>/<chart> --version <chart-version>
helm show crds <repo>/<chart> --version <chart-version>

搜索结果不等于安全审查。生产必须固定 Chart 版本，并检查维护者、源仓库、依赖、镜像、权限、CRD、安全公告与供应链证据。

四、Values 与安全输入 ​

常见优先级从低到高为：Chart 默认 values.yaml、依次传入的 -f 文件、命令行 --set*；准确合并行为以当前版本文档为准。

bash
helm upgrade --install <release> <chart> -n <namespace> \
  -f values-common.yaml -f values-production.yaml \
  --set image.tag=<version> --set-string externalId='<string>'
helm show values <chart> --version <chart-version>
helm get values <release> -n <namespace> --all

--set-file 可读取文件内容，--set-json 是否可用以本机帮助为准。命令行值会进入历史、进程参数或 Release 元数据；不要用 --set password=... 传秘密，应使用组织批准的秘密管理方式。

五、Release 全生命周期 ​

先预览，再安装并等待：

bash
helm install <release> <repo>/<chart> \
  --version <chart-version> -n <namespace> --create-namespace \
  -f <values-file> --dry-run --hide-secret
helm install <release> <repo>/<chart> \
  --version <chart-version> -n <namespace> --create-namespace \
  -f <values-file> --wait --timeout 10m

查询、测试和检查内容：

bash
helm list -n <namespace>
helm status <release> -n <namespace>
helm history <release> -n <namespace>
helm test <release> -n <namespace> --logs --timeout 10m
helm get values <release> -n <namespace> --all
helm get manifest <release> -n <namespace>
helm get hooks <release> -n <namespace>

升级并验证：

bash
helm upgrade --install <release> <chart> \
  --version <chart-version> -n <namespace> --create-namespace \
  -f <values-file> --wait --timeout 10m
helm status <release> -n <namespace>
kubectl -n <namespace> get pods
kubectl -n <namespace> get events --sort-by=.metadata.creationTimestamp

生产应由完整、版本化的 values 文件驱动。--reuse-values 可能携带历史遗留值；--reset-values 和事务性参数的准确语义以 helm upgrade --help 为准。

回滚与卸载：

bash
helm history <release> -n <namespace>
helm rollback <release> <revision> -n <namespace> --wait --timeout 10m
helm get manifest <release> -n <namespace>
helm uninstall <release> -n <namespace> --dry-run
helm uninstall <release> -n <namespace> --wait --timeout 10m

回滚和卸载边界

回滚不能自动逆转数据库迁移、外部 API、Hook 副作用或持久卷数据。卸载时 CRD、保留资源、PVC 和外部资源可能保留，其他数据资源也可能被删除；执行前逐项确认清单、备份和恢复方案。

六、创建、渲染与校验 Chart ​

bash
helm create <chart-name>
helm dependency build <chart>
helm lint <chart> -f <values-file> --strict
helm template <release> <chart> -n <namespace> \
  -f <values-file> --debug > rendered.yaml
kubectl apply --dry-run=server -f rendered.yaml

rendered.yaml 可能包含 Secret 和内部配置，应使用受限临时目录、最小文件权限，并按数据处理规范及时清理。

典型结构包括 Chart.yaml、values.yaml、values.schema.json、templates/、charts/、crds/ 和 .helmignore。关键元数据：

yaml
apiVersion: v2
name: example
type: application
version: 0.1.0
appVersion: "1.0.0"
kubeVersion: ">=1.32.0-0"

version 是 Chart 的 SemVer；appVersion 是展示用应用版本；kubeVersion 应反映真实测试范围。若团队批准 helm-diff 插件，可用 helm diff upgrade 审查差异；插件会以当前用户权限执行代码，必须审查来源并固定版本。

七、模板基础与进阶 ​

yaml
metadata:
  name: {{ include "example.fullname" . }}
  labels:
    {{- include "example.labels" . | nindent 4 }}
spec:
  type: {{ default "ClusterIP" .Values.service.type }}
  ports:
    - port: {{ required "service.port is required" .Values.service.port }}

常用对象有 .Values、.Release、.Chart、.Capabilities、.Files 和 .Template。进阶要点：

  • include 调用命名模板；toYaml | nindent 输出嵌套 YAML。
  • with、range 会改变 .，根作用域保存在 $。
  • required、fail 和 values.schema.json 尽早拒绝无效输入。
  • tpl 会再次执行模板，只对可信输入使用。
  • lookup 依赖集群实时状态，会降低渲染可重复性，应谨慎使用。
bash
helm template <release> <chart> -f <values-file> \
  --show-only templates/<file.yaml> --debug

八、依赖、Hooks 与 CRD ​

yaml
dependencies:
  - name: postgresql
    version: "<pinned-chart-version>"
    repository: "https://<trusted-repository>/charts"
    condition: postgresql.enabled
bash
helm dependency list <chart>
helm dependency update <chart>  # 更新依赖和 Chart.lock
helm dependency build <chart>   # 按 Chart.lock 恢复依赖

CI/生产应提交 Chart.lock 并使用 dependency build。Hook Job 必须幂等、可重试并明确删除策略，其外部副作用不一定随回滚恢复。

crds/ 中的 CRD 在普通资源前安装，但不会作为普通模板升级，Helm 默认也不会在卸载时删除。CRD 升级需单独设计存储版本、转换和回滚；删除 CRD 可能级联删除全部自定义资源。

九、OCI、打包与插件 ​

bash
printf '%s' "$REGISTRY_PASSWORD" | \
  helm registry login <registry> \
  --username "$REGISTRY_USERNAME" --password-stdin
helm pull oci://<registry>/<namespace>/<chart> --version <chart-version>
helm package <chart-directory>
helm push <chart>-<version>.tgz oci://<registry>/<namespace>
helm verify <chart-package.tgz> --keyring <trusted-public-keyring>
helm registry logout <registry>

生产应固定版本或 digest，启用 Registry 最小权限、不可变标签、审计、签名/证明与漏洞扫描。签名只证明来源和完整性，不证明 Chart 没有漏洞。Helm 4 插件与 Helm 3 可能不兼容，插件也能读取 kubeconfig 和本地文件。

十、安全发布与排障 ​

  • 固定 Helm、kubectl、Chart、依赖和镜像版本；生产镜像优先使用 digest。
  • 使用非 root、禁止提权、只读根文件系统、最小 capabilities 和最小 RBAC。
  • 明确资源配额、探针、PDB、拓扑策略；Secret 不进入 values 仓库、NOTES、日志或命令行。
  • 渲染后执行 Kubernetes schema、准入和组织策略检查；CRD、权限、存储和迁移单独评审。
  • 同一 <context>/<namespace>/<release> 只运行一个发布流程，保存摘要、差异、revision 和回滚条件。

模板失败：

bash
helm lint <chart> -f <values-file> --strict
helm template <release> <chart> -f <values-file> --debug

安装、升级超时或状态为 pending-*：

bash
helm status <release> -n <namespace>
helm history <release> -n <namespace>
helm get hooks <release> -n <namespace>
kubectl -n <namespace> get pods,jobs
kubectl -n <namespace> get events --sort-by=.metadata.creationTimestamp

找到未 Ready 的资源或 Hook，再用 describe 和日志定位；不要盲目增大 timeout，也不要编辑或删除 sh.helm.release.v1.* 存储对象“解锁”。资源已存在时，不要直接补 Helm 所有权元数据强行接管，应设计并测试迁移、升级、回滚和卸载语义。

十一、发布前清单 ​

text
[ ] context、namespace、release 与版本已双重确认
[ ] 来源、权限、CRD、存储、镜像和供应链证据已审查
[ ] values 无明文秘密；依赖、lint、渲染、策略和服务端校验通过
[ ] 容量、探针、PDB、Hook、超时和数据库兼容性已验证
[ ] 差异、备份、回滚 revision、触发阈值、负责人和发布后验证明确

版本信息会变化。每次升级重新核对官方 Release、支持策略、变更说明和安全公告，不把本文核对日期当作永久结论。

继续阅读