Skip to content

Lesson 29 ยท 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