Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 38 ยท Testing and Security

Linting and Debugging Helm Templates

Catch chart mistakes before the cluster does with helm lint, helm template, --dry-run and --debug, read common errors, and validate rendered YAML, with runnable stand-ins.

Most Helm problems are not Kubernetes problems. They are template problems: a misplaced indent, a value that is missing, a list rendered as a string. The good news is that Helm can show you everything it would send to the cluster without sending anything. A disciplined chart author renders and checks early and often.

helm lint

Terminal
helm lint ./webapp
helm lint ./webapp -f values-prod.yaml --strict
helm lint ./webapp --with-subcharts

lint runs a set of checks on the chart: a valid Chart.yaml, parsable YAML, templates that render with the default values, a values file that matches values.schema.json if present, and best-practice warnings. The output has three severities:

  • [INFO] suggestions, such as a missing icon.
  • [WARNING] things that are probably wrong but still render.
  • [ERROR] the chart cannot be installed.

Add --strict so warnings fail the command, which is what you want in CI. Lint checks against the default values unless you pass -f, so lint once per environment values file.

What lint does not do: validate the rendered manifests against the Kubernetes API. A Deployment with replica: 3 (instead of replicas) lints fine, because the YAML is valid.

helm template

helm template renders the chart locally and prints the manifests. It never contacts a cluster by default:

Terminal
helm template shop ./webapp -f values-prod.yaml
helm template shop ./webapp --set replicaCount=5 --show-only templates/deployment.yaml
helm template shop ./webapp --namespace prod --include-crds > rendered.yaml

--show-only limits output to one template file, handy for large charts. --validate additionally asks the cluster whether the rendered resources are valid. Everything printed is plain YAML, so you can pipe it to other tools:

Terminal
helm template shop ./webapp | kubeconform -strict -summary -

A schema validator such as kubeconform or kubeval checks resources against the Kubernetes OpenAPI schemas offline. This catches the replica typo that lint misses.

--dry-run and --debug

Terminal
helm install shop ./webapp --dry-run=client --debug
helm upgrade shop ./webapp --dry-run=server -f prod.yaml
Mode What it does
--dry-run=client Renders only, no cluster calls (like template, with release metadata)
--dry-run=server Sends the resources to the API server for validation without persisting them
--debug Prints the computed values and, on error, the failing template text

--dry-run=server is the closest to the real thing: admission webhooks and schema validation run, but nothing is saved. It needs cluster access, so use it in a pre-deploy CI job rather than on every commit.

Reading a template error

Errors carry a file and line. Learn the common shapes:

TEXT
Error: template: webapp/templates/deployment.yaml:14:28: executing "webapp/templates/deployment.yaml"
at <.Values.image.tag>: nil pointer evaluating interface {}.tag

Meaning: .Values.image is missing, so .tag on it is a nil pointer. Fix: add image: to values.yaml, or guard with default/with.

TEXT
Error: YAML parse error on webapp/templates/service.yaml: error converting YAML to JSON:
yaml: line 9: did not find expected key

Meaning: the rendered YAML is invalid, almost always an indent problem (indent vs nindent) or a missing newline.

TEXT
Error: UPGRADE FAILED: another operation (install/upgrade/rollback) is in progress

Meaning: a previous operation was interrupted and the release is stuck in a pending state; check helm history and roll back.

The stand-in: a tiny template linter

Helm's engine cannot run here, but you can practice the thinking. The stand-in renders {{ .Values.x.y }} placeholders, reports undefined values the way helm lint --strict reports missing keys, and checks that the result is valid-looking YAML structure.

Python Stand-in: render, find missing values, check indentation

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Real Helm renders a missing map key as <no value> in strings and as an error for nil pointer access, which is why the first output line shows the placeholder. The habit to take away: render, then look at the output.

A debugging workflow

  1. helm lint --strict for structure.
  2. helm template ... --show-only <file> for the manifest you are changing.
  3. Add {{ toYaml .Values | nindent 2 }} or {{ printf "%#v" .Values.image }} temporarily to inspect a value (remove it afterwards).
  4. Pipe through a schema validator.
  5. helm install --dry-run=server --debug against a test cluster.
  6. helm diff upgrade to preview changes against a running release.
Python Stand-in: structural checks CI would run

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Mistakes to avoid

  • Trusting lint alone. Lint passes broken manifests; add schema validation.
  • Debugging against the cluster first. Render locally; it is faster and safer.
  • Leaving --debug secrets in CI logs. Rendered output can contain Secret values; mask them.

When the error line number does not match your file, the cause is often a named template (include) or a subchart. Render the subchart alone with helm template ./charts/redis to find it.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. What does helm lint NOT verify?

    Lint checks the chart; a separate schema validator or a server dry run checks the Kubernetes objects.
  2. 2. Which option validates resources against the API server without saving them?

    Server-side dry run runs admission and validation but persists nothing.
  3. 3. What does --show-only templates/deployment.yaml do?

    It limits the rendered output to the named template.

Summary

  • Render locally first: helm lint --strict, then helm template, then a schema validator.
  • Use --dry-run=server --debug for cluster-aware validation.
  • Read errors by file:line; nil pointers mean a missing value, YAML parse errors mean indentation.
  • Lint does not validate Kubernetes object schemas.

Next: Testing Charts with helm test and unittest