helm-debugging

Helm 调试与故障排除

有关诊断和修复 Helm 部署失败、模板错误及配置问题的全面指南。

何时使用此技能

在以下情况下使用此技能……	在以下情况下改用 ……
诊断模板渲染错误、值类型错误或 YAML 解析失败	如果 release 本身卡住（pending-install/upgrade）且需要回滚，请使用 helm-release-recovery
检查图表已部署但 Pod 崩溃或无法拉取镜像的原因	如果需要临时容器或节点级调试会话，请使用 kubectl-debugging
在部署前运行 helm lint、helm template 或 --dry-run 进行验证	从头编写或重组图表时，请使用 helm-chart-development

何时使用

在以下情况下自动使用此技能：

• 用户报告 Helm 部署失败或出错
• 用户提到调试、故障排除或修复 Helm 问题
• 出现模板渲染问题
• 值验证或类型错误
• 资源冲突或 API 错误
• 镜像拉取失败或 Pod 崩溃
• 用户需要检查已部署的资源

上下文安全（至关重要）

始终在所有 kubectl 和 helm 命令中明确指定 --context。切勿依赖当前上下文。

# CORRECT: Explicit context
kubectl --context=prod-cluster get pods -n prod
helm --kube-context=prod-cluster status myapp -n prod

# WRONG: Relying on current context
kubectl get pods -n prod  # Which cluster?

这可以防止意外操作错误的集群。

---

分层验证方法

始终按照以下顺序进行，以确保部署稳健：

# 1. LINT - Static analysis (local charts only)
helm lint ./mychart --strict

# 2. TEMPLATE - Render templates locally
helm template myapp ./mychart \
  --debug \
  --values values.yaml

# 3. DRY-RUN - Server-side validation
helm install myapp ./mychart \
  --namespace prod \
  --values values.yaml \
  --dry-run --debug

# 4. INSTALL - Actual deployment
helm install myapp ./mychart \
  --namespace prod \
  --values values.yaml \
  --atomic --wait

# 5. TEST - Post-deployment validation (if chart has tests)
helm test myapp --namespace prod --logs

核心调试命令

模板渲染与检查

# Render all templates locally
helm template myapp ./mychart \
  --debug \
  --values values.yaml

# Render specific template file
helm template myapp ./mychart \
  --show-only templates/deployment.yaml \
  --values values.yaml

# Render with debug output (shows computed values)
helm template myapp ./mychart \
  --debug \
  --values values.yaml \
  2>&1 | less

# Validate against Kubernetes API (dry-run)
helm install myapp ./mychart \
  --namespace prod \
  --values values.yaml \
  --dry-run \
  --debug

检查已部署的资源

# Get deployed manifest (actual YAML in cluster)
helm get manifest myapp --namespace prod

# Get deployed values (what was actually used)
helm get values myapp --namespace prod

# Get ALL values (including defaults)
helm get values myapp --namespace prod --all

# Get release status with resources
helm status myapp --namespace prod --show-resources

# Get everything about a release
helm get all myapp --namespace prod

图表验证

# Lint chart structure and templates
helm lint ./mychart

# Lint with strict mode (treats warnings as errors)
helm lint ./mychart --strict

# Lint with specific values
helm lint ./mychart --values values.yaml --strict

# Validate chart against Kubernetes API
helm install myapp ./mychart \
  --dry-run --validate --namespace prod

详细调试

# Enable Helm debug logging
helm install myapp ./mychart \
  --namespace prod \
  --debug \
  --dry-run

# Enable Kubernetes client logging
helm install myapp ./mychart \
  --namespace prod \
  --v=6  # Verbosity level 0-9

常见故障场景

场景	症状	快速修复
YAML 解析错误	error converting YAML to JSON	检查缩进，并使用 {{- ... }} 删除空白
模板渲染错误	nil pointer evaluating interface	添加默认值：{{ .Values.key | default "value" }}
值类型错误	cannot unmarshal string into Go value of type int	在模板中使用 {{ .Values.port | int }}
资源已存在	resource that already exists	卸载冲突的 release：helm uninstall，或接管该资源
镜像拉取失败	ImagePullBackOff	修正镜像名称/标签，并创建拉取密钥
未找到 CRD	no matches for kind	先安装 CRD：kubectl apply -f crds/
超时	timed out waiting for the condition	增加 --timeout，检查就绪探针
Hook 失败	pre-upgrade hooks failed	删除失败的 hook Job，并使用 --no-hooks 重试

有关每种故障场景的详细调试步骤、修复方法和示例，请参阅 REFERENCE.md。

Agentic 优化

上下文	命令
Release 状态（JSON）	helm status <release> -n <ns> -o json
所有值（JSON）	helm get values <release> -n <ns> --all -o json
Pod 状态（精简）	kubectl get pods -n <ns> -l app.kubernetes.io/instance=<release> -o wide
事件（排序后）	kubectl get events -n <ns> --sort-by='.lastTimestamp' -o json
渲染并验证	helm template <release> ./chart --debug 2>&1 | head -100

相关技能

• Helm Release 管理 - 安装、升级和卸载操作
• Helm Values 管理 - 高级配置管理
• Helm Release 恢复 - 回滚和恢复策略
• Kubernetes 操作 - 管理和调试 K8s 资源
• ArgoCD CLI 登录 - 使用 ArgoCD 进行 GitOps 调试

参考资料

• Helm 调试文档
• Helm 故障排除指南
• Kubernetes 调试
• 模板函数参考