GeekIt

Helm命令速查

仓库管理、安装升级回滚、状态调试、模板语法、钩子依赖、OCI 推送与故障排查等 135 条命令

共 135 条命令 · 10 类场景 · 点击右侧图标可复制

命令 / 语法说明复制
helm version查看客户端版本与 Git 提交信息
helm version --short只输出版本号,适合脚本判断
helm env查看 Helm 环境变量、配置目录与缓存路径
helm repo add bitnami https://charts.bitnami.com/bitnami添加官方或第三方 Chart 仓库
helm repo add private https://charts.example.com --username user --password 密码添加需要认证的私有仓库
helm repo list列出已添加的仓库
helm repo update更新仓库索引,安装前建议先执行
helm repo remove bitnami移除仓库
helm repo index . --url https://charts.example.com为本地目录生成本地仓库索引文件
helm search repo nginx在已添加的仓库中搜索 Chart
helm search hub nginx在 Artifact Hub 上搜索(需外网)
helm search repo nginx --versions列出 Chart 的全部可用版本
helm show chart bitnami/nginx查看 Chart 元信息(版本、依赖、关键字)
helm show values bitnami/nginx查看可配置项,安装前必看
helm show readme bitnami/nginx查看 Chart 的 README 说明
helm pull bitnami/nginx --version 15.0.0 --untar下载并解压 Chart,便于本地改模板
命令 / 语法说明复制
helm install my-nginx bitnami/nginx -n web --create-namespace安装 Chart 到指定命名空间(不存在则创建)
helm install my-app ./mychart -f values-prod.yaml用本地 Chart 与自定义 values 安装
helm install my-app ./mychart --set image.tag=v1.2.3 --set replicaCount=3覆盖少量参数,多个用逗号分隔
helm install my-app ./mychart --set-string image.tag=1.20强制按字符串解析,避免版本号被转成数字
helm install my-app ./mychart --set-file config=./app.conf把文件内容作为值传入
helm install my-app ./mychart --dry-run --debug只渲染不提交,检查最终清单
helm install my-app ./mychart --atomic --timeout 5m --wait等待资源就绪,失败自动回滚
helm upgrade my-app ./mychart -f values-prod.yaml升级发布,未指定的值会按新 values 计算
helm upgrade --install my-app ./mychart -f values.yaml不存在则安装、存在则升级,CI 中最常用
helm upgrade my-app ./mychart --reuse-values沿用上一次的值,仅合并本次变更
helm upgrade my-app ./mychart --reset-values丢弃旧值,完全以当前 values 为准
helm upgrade my-app ./mychart --history-max 10限制保留的历史版本数,避免 Secret 堆积
helm rollback my-app 1回滚到指定修订版本
helm rollback my-app 0回滚到上一个版本
helm history my-app查看修订历史与状态、描述
helm uninstall my-app -n web卸载发布并删除其资源
helm uninstall my-app --keep-history保留历史记录,便于回滚或审计
helm list -A查看所有命名空间的发布
命令 / 语法说明复制
helm list -n web查看指定命名空间的发布列表
helm list -A --all包括已失败或已卸载(保留历史)的记录
helm status my-app -n web查看发布状态、资源与 NOTES
helm get values my-app查看当前生效的用户自定义值
helm get values my-app --all包含 Chart 默认值与计算后的全部值
helm get manifest my-app查看实际提交给集群的 YAML 清单
helm get all my-app一次性输出 values、manifest、hooks 与 notes
helm get notes my-app查看 Chart 的安装说明
helm get hooks my-app查看钩子资源执行情况
helm template my-app ./mychart -f values.yaml本地渲染模板,不连接集群即可检查输出
helm template my-app ./mychart --debug渲染失败时输出更多上下文
helm lint ./mychart检查 Chart 结构与模板语法
helm lint ./mychart --strict严格模式,警告也视为失败,适合 CI
helm test my-app执行 Chart 中定义的 test 钩子
helm test my-app --logs测试失败时输出 Pod 日志
命令 / 语法说明复制
helm create mychart生成标准 Chart 骨架(Chart.yaml、values.yaml、templates/)
tree mychart查看 Chart 目录结构
helm package mychart打包为 tgz,用于分发或推送仓库
helm package mychart --version 1.2.3 --app-version 2.0.0指定 Chart 版本与应用版本
helm package mychart -d ./dist指定输出目录
helm package mychart --sign --key mykey --keyring ~/.gnupg/secring.gpg签名打包,配合 verify 校验完整性
helm verify mychart-1.2.3.tgz校验 Chart 签名
CHART VERSION 与 APP VERSION 的区别前者是打包版本,后者是被部署应用版本,升级判断只认前者
.helmignore 排除不需要打包的文件类似 .gitignore,避免把测试脚本打进包
helm plugin list查看已安装插件(diff、secrets 等)
helm plugin install https://github.com/databus23/helm-diff安装 diff 插件,升级前对比变更
命令 / 语法说明复制
{{ .Values.replicaCount }}引用 values.yaml 中的值
{{ .Release.Name }} 与 {{ .Release.Namespace }}发布名与命名空间,用于资源命名
{{ .Release.IsInstall }} 与 {{ .Release.IsUpgrade }}判断当前是安装还是升级
{{ .Chart.Name }} 与 {{ .Chart.Version }} 与 {{ .Chart.AppVersion }}引用 Chart 元信息
{{ .Files.Get "config/app.conf" }}读取 Chart 内的文件内容
{{ .Capabilities.KubeVersion }}获取集群版本,用于版本兼容判断
{{ include "mychart.fullname" . }}调用 _helpers.tpl 中定义的模板
{{ template "mychart.labels" . }}引入模板片段(不支持管道处理)
{{- if .Values.ingress.enabled }} ... {{- end }}条件渲染,{{- 用于裁剪左侧空白
{{- range .Values.env }} - name: {{ .name }} {{- end }}遍历列表渲染
{{- with .Values.resources }} ... {{- end }}切换上下文,简化深层字段引用
{{ toYaml .Values.resources | nindent 12 }}把结构体转 YAML 并缩进,最常用组合
{{ default "info" .Values.logLevel }}值为空时使用默认值
{{ required "image.tag 必须填写" .Values.image.tag }}必填校验,缺失时渲染直接失败
{{ .Values.image.tag | quote }}加引号,避免 1.20 被解析为浮点数
{{ .Values | toJson }}调试时打印全部值
{{- define "mychart.labels" -}} ... {{- end }}在 _helpers.tpl 中定义可复用片段
命令 / 语法说明复制
helm.sh/hook: pre-install安装前执行,常用于建库、初始化配置
helm.sh/hook: post-install安装后执行,如数据初始化 Job
helm.sh/hook: pre-upgrade 与 post-upgrade升级前后执行迁移脚本
helm.sh/hook: pre-delete 与 post-delete卸载前后执行清理
helm.sh/hook: testhelm test 时会执行该钩子
helm.sh/hook-weight: "-5"同类型钩子按权重顺序执行,数字小的先跑
helm.sh/hook-delete-policy: before-hook-creation重建前删除旧钩子资源,避免 Job 名称冲突
helm.sh/hook-delete-policy: hook-succeeded成功后自动删除钩子资源
helm get hooks my-app查看钩子执行结果,失败时第一时间看这里
helm install my-app ./chart --atomic钩子失败时自动回滚整个发布
钩子资源不会随 helm uninstall 自动清理(除指定 delete-policy)长期使用需关注残留 Job 与 ConfigMap
NOTES.txt安装完成后在终端输出的使用说明,内容支持模板
命令 / 语法说明复制
dependencies: [{ name: redis, version: 17.x.x, repository: https://charts.bitnami.com/bitnami }]在 Chart.yaml 中声明依赖
helm dependency update ./mychart拉取依赖并生成 Chart.lock(最常用)
helm dependency build ./mychart严格按 Chart.lock 还原依赖,CI 中更可复现
helm dependency list ./mychart查看依赖状态,MISSING 表示未下载
condition: redis.enabled通过父 Chart 的值控制子 Chart 是否启用
tags: [cache]按标签批量启用或禁用依赖
redis.auth.password: xxx父 Chart 中按子 Chart 名做层级覆盖
global: { imageRegistry: registry.example.com }global 值对所有子 Chart 可见
alias: cache同一 Chart 引入多次时用别名区分
import-values: [child: exports.data]把子 Chart 的值导入父级
--set redis.enabled=false安装时临时禁用某个依赖
命令 / 语法说明复制
helm registry login harbor.example.com -u admin -p 密码登录 OCI 仓库(Harbor、ECR 等)
helm push mychart-1.2.3.tgz oci://harbor.example.com/library推送 Chart 到 OCI 仓库
helm install my-app oci://harbor.example.com/library/mychart --version 1.2.3直接从 OCI 仓库安装
helm pull oci://harbor.example.com/library/mychart --version 1.2.3 --untar从 OCI 仓库下载 Chart
helm show values oci://harbor.example.com/library/mychart查看远端 Chart 的默认值
helm registry logout harbor.example.com退出登录,清理凭据
helm push mychart.tgz oci://127.0.0.1:5000/charts --plain-http本地测试用 HTTP 仓库(生产必须 HTTPS)
helm lint ./chart && helm template app ./chart -f values.yaml流水线中的基础校验组合
helm upgrade --install app ./chart --dry-run --debug在 CI 中预演,避免带错误上生产
helm package ./chart -d ./dist && helm push ./dist/*.tgz oci://...打包并推送的完整发布链路
命令 / 语法说明复制
HELM_NAMESPACE=web helm list用环境变量指定默认命名空间
HELM_KUBECONTEXT=prod helm list指定 kubeconfig 上下文,避免误操作集群
helm install app ./chart --kube-context prod命令行显式指定集群上下文
helm list --failed只看失败的发布
helm list --pending只看处于 pending 状态的发布(常见于卡住的操作)
Error: another operation (install/upgrade/rollback) is in progress有未完成的操作:等待、回滚,或删除对应 release Secret
kubectl get secret -n web -l owner=helm查看 release 记录存储(Secret 版本号即修订号)
Error: rendered manifests contain a resource that already exists资源已存在且无 Helm 标注:改名、加注解或先删除旧资源
Error: found in Chart.yaml, but missing in charts/ directory依赖未下载,执行 helm dependency update
Error: chart requires kubeVersion集群版本低于 Chart 要求,核对 kubeVersion 与实际版本
UPGRADE FAILED: timed out waiting for the condition--wait 超时:看 Pod 事件与就绪探针,或用 --atomic 自动回滚
helm history app 看失败版本的 description 字段描述中常有具体错误摘要
helm uninstall app --no-hooks跳过钩子卸载,钩子本身故障时使用
kubectl describe secret -n web sh.helm.release.v1.app.v1直接查看 release 数据(内容为 base64+gzip)
命令 / 语法说明复制
helm upgrade --install --atomic --wait --timeout 10m生产发布标准参数组合:失败自动回滚
values.yaml / values-dev.yaml / values-prod.yaml 分层管理公共值放基础文件,环境差异用 -f 叠加
helm diff upgrade app ./chart -f values-prod.yaml升级前对比集群实际差异(需 helm-diff 插件)
helm secrets enc secrets.yaml用 helm-secrets 插件加密敏感值,避免明文入库
避免在生产使用 --force会删除重建资源,可能造成数据丢失与中断
--set 只用于简单标量,复杂结构用 -f 文件命令行转义易出错,也难审计
为 Chart 固定版本号,不要用 latest保证不同环境与时间点可复现
helm lint --strict 加入 CI 强制卡点提前发现模板与 Chart 结构问题
release 记录会占用 Secret,设置 --history-max默认保留 10 个版本,长期不升级也要定期清理
用 RBAC 限制谁能操作哪些命名空间的 releaseHelm 权限等同于提交任意 YAML 的权限
Chart 中的镜像使用固定 digest 或精确 tag避免滚动更新拉到意外版本

运维常用组合

安装前检查helm show values repo/chart → helm template app ./chart -f values.yaml → helm install --dry-run --debug
生产发布helm upgrade --install app ./chart -f values-prod.yaml --atomic --wait --timeout 10m
发布失败处置helm history app → kubectl describe/logs → helm rollback app <rev>
Chart 发布到仓库helm package ./chart -d ./dist → helm push ./dist/*.tgz oci://harbor.example.com/library
排查清单差异helm get manifest app → helm diff upgrade app ./chart -f values-prod.yaml
CI 校验卡点helm lint --strict ./chart → helm dependency build ./chart → helm template app ./chart

常见问题排查

1. 升级报 another operation in progress

上一次操作未正常结束:先 helm history 确认状态,必要时删除对应的 release Secret 或回滚

2. 安装成功但 Pod 起不来

helm 只负责提交资源:用 kubectl describe/logs 看镜像拉取、探针与资源配额

3. values 覆盖不生效

层级写错是主因:子 Chart 用 <chart>.key,结构体用 --set a.b=c,复杂结构改用 -f

4. 模板渲染结果异常

用 helm template --debug 查看渲染输出与错误行号,注意 {{- 裁剪导致的空行问题

5. 依赖总是缺失

CI 用 helm dependency build 而非 update,并把 Chart.lock 一起提交

6. 回滚后配置仍是新的

回滚基于历史修订,若 values 在外部被改动需重新升级;用 helm get values 核对

共 135 条 Helm 命令 · 示例发布名 my-app 与命名空间 web 请替换为实际环境

关于Helm命令速查

在线 Helm 命令速查手册,按版本与仓库管理、安装升级与回滚、查看状态与调试、Chart 开发与打包、模板语法与内置对象、钩子与生命周期、依赖与子 Chart、OCI 仓库与流水线集成、环境与故障排查、最佳实践与安全等 10 类场景整理 130+ 条常用命令与模板写法,每条附中文说明与可直接复制的写法,支持关键词搜索、分类折叠和一键复制,打开网页即可查阅。涵盖 helm version 与 env、repo add 与 repo update 与 repo index、search repo/hub --versions、show chart/values/readme、pull --untar、install 与 --create-namespace、-f values.yaml 与 --set 与 --set-string 与 --set-file、--dry-run --debug、--atomic --wait --timeout、upgrade 与 --install 与 --reuse-values 与 --reset-values 与 --history-max、rollback 指定版本与 0、history、uninstall 与 --keep-history、list -A --all、status、get values 与 --all 与 get manifest 与 get all 与 get hooks、template 与 --debug、lint 与 --strict、test 与 --logs、create 与 package --version/--app-version 与 --sign 与 verify、Chart.yaml 的 dependencies 与 condition 与 tags 与 alias 与 import-values 与 global、helm dependency update/build/list、模板中的 .Values 与 .Release 与 .Chart 与 .Files 与 .Capabilities 与 include 与 template 与 define、{{- 空白裁剪、if/range/with、toYaml 与 nindent、default 与 required 与 quote 与 toJson、helm.sh/hook 的 pre-install/post-install/pre-upgrade/post-upgrade/pre-delete/post-delete/test 与 hook-weight 与 hook-delete-policy 与 NOTES.txt、helm registry login/push/pull/logout 与 oci:// 安装与 --plain-http、HELM_NAMESPACE 与 HELM_KUBECONTEXT 与 --kube-context、--failed 与 --pending、another operation in progress 与 rendered manifests contain a resource that already exists 与 missing in charts directory 与 UPGRADE FAILED 排查、helm-diff 与 helm-secrets 插件与 RBAC 实践。适用于 Helm Chart 开发与发布、Kubernetes 应用部署升级回滚、多环境 values 管理、私有 OCI 仓库集成与 CI/CD 流水线卡点,以及运维与 DevOps 面试复习。

核心能力

  • 涵盖 helm version 与 env、repo add 与 repo update 与 repo index、search repo/hub --versions、show chart/values/readme、pull --untar、install 与 --create-namespace、-f values.yaml 与 --set 与 --set-string 与 --set-file、--dry-run --debug、--atomic --wait --timeout、upgrade 与 --install 与 --reuse-values 与 --reset-values 与 --history-max、rollback 指定版本与 0、history、uninstall 与 --keep-history、list -A --all、status、get values 与 --all 与 get manifest 与 get all 与 get hooks、template 与 --debug、lint 与 --strict、test 与 --logs、create 与 package --version/--app-version 与 --sign 与 verify、Chart.yaml 的 dependencies 与 condition 与 tags 与 alias 与 import-values 与 global、helm dependency update/build/list、模板中的 .Values 与 .Release 与 .Chart 与 .Files 与 .Capabilities 与 include 与 template 与 define、{{- 空白裁剪、if/range/with、toYaml 与 nindent、default 与 required 与 quote 与 toJson、helm.sh/hook 的 pre-install/post-install/pre-upgrade/post-upgrade/pre-delete/post-delete/test 与 hook-weight 与 hook-delete-policy 与 NOTES.txt、helm registry login/push/pull/logout 与 oci:// 安装与 --plain-http、HELM_NAMESPACE 与 HELM_KUBECONTEXT 与 --kube-context、--failed 与 --pending、another operation in progress 与 rendered manifests contain a resource that already exists 与 missing in charts directory 与 UPGRADE FAILED 排查、helm-diff 与 helm-secrets 插件与 RBAC 实践

适用场景

适用于 Helm Chart 开发与发布、Kubernetes 应用部署升级回滚、多环境 values 管理、私有 OCI 仓库集成与 CI/CD 流水线卡点,以及运维与 DevOps 面试复习。Helm命令速查全程在浏览器中完成,无需安装插件,可放心用于日常办公与排障。

常见问题

Helm命令速查是免费的吗?需要注册或安装吗?
Helm命令速查完全免费,无需注册、无需下载安装任何软件,用浏览器打开网页即可直接使用,也不限制使用次数。
Helm命令速查支持哪些功能?
涵盖 helm version 与 env、repo add 与 repo update 与 repo index、search repo/hub --versions、show chart/values/readme、pull --untar、install 与 --create-namespace、-f values.yaml 与 --set 与 --set-string 与 --set-file、--dry-run --debug、--atomic --wait --timeout、upgrade 与 --install 与 --reuse-values 与 --reset-values 与 --history-max、rollback 指定版本与 0、history、uninstall 与 --keep-history、list -A --all、status、get values 与 --all 与 get manifest 与 get all 与 get hooks、template 与 --debug、lint 与 --strict、test 与 --logs、create 与 package --version/--app-version 与 --sign 与 verify、Chart.yaml 的 dependencies 与 condition 与 tags 与 alias 与 import-values 与 global、helm dependency update/build/list、模板中的 .Values 与 .Release 与 .Chart 与 .Files 与 .Capabilities 与 include 与 template 与 define、{{- 空白裁剪、if/range/with、toYaml 与 nindent、default 与 required 与 quote 与 toJson、helm.sh/hook 的 pre-install/post-install/pre-upgrade/post-upgrade/pre-delete/post-delete/test 与 hook-weight 与 hook-delete-policy 与 NOTES.txt、helm registry login/push/pull/logout 与 oci:// 安装与 --plain-http、HELM_NAMESPACE 与 HELM_KUBECONTEXT 与 --kube-context、--failed 与 --pending、another operation in progress 与 rendered manifests contain a resource that already exists 与 missing in charts directory 与 UPGRADE FAILED 排查、helm-diff 与 helm-secrets 插件与 RBAC 实践。
Helm命令速查适合哪些场景使用?
适用于 Helm Chart 开发与发布、Kubernetes 应用部署升级回滚、多环境 values 管理、私有 OCI 仓库集成与 CI/CD 流水线卡点,以及运维与 DevOps 面试复习。