Skip to content

Helm Debugger

CI Docs

Debug Helm charts by tracing values.yaml through _helpers.tpl into the rendered manifests.

Overview

This project lets you debug Helm charts and answer how your values.yaml options change across _helpers.tpl functions and eventually make it into the final rendered manifests.

The debugger makes use of Delve because Go's text/template library processes entire files at a time, making it difficult to track down individual operations without introspecting a running process.

State of the project

This is still pretty experimental / proof of concept.

Quick start

The recommended way to run this project is the pinned Docker image, which provides every tool at a known version:

docker run --rm --cap-add=SYS_PTRACE --security-opt seccomp=unconfined \
  -v "$PWD:/workspace" -w /workspace \
  ghcr.io/jessesimpson36/helm-debugger:latest --mode model --helm-path helm \
  --chart test --values image.tag \
  --extra-command-args '--show-only templates/deployment.yaml'

Continue with Getting started for requirements, the deterministic toolchain, and building from source.

What it produces

For a query, the debugger reports the execution flow that produced a line, the relevant values the flow reads, and the write buffer (the rendered output). For example, asking why serviceAccountName renders a particular value returns:

test/templates/deployment.yaml:30
          serviceAccountName: {{ include "test.serviceAccountName" . }}
  test/templates/_helpers.tpl:57
    in test.serviceAccountName
      {{- if .Values.serviceAccount.create }}
  test/templates/_helpers.tpl:58
    in test.serviceAccountName
      {{- default (include "test.fullname" .) .values.serviceAccount.name }}
  ...

See Understanding output for a full walk-through.

Where to go next

Support

If this project is useful to you, consider buying me a coffee:

Support me on Ko-fi

See Support this project for other ways to help.