helm-template-development

name	helm-template-development
description	This skill should be used when making changes to `charts/*/templates/` or `charts/*/values.yaml` which are the underlying kubernetes resource templates and configurations used to generate resources in a helm release.

Helm Template Development

Overview

Many examples of helm templates on the internet are not well-suited for production use and vary by quality greatly. This skill brings strong opinions about quality and maintainability of helm templates and how to test them.

YAML Best Practices

For YAML best practices, consult the yaml-development skill which generally applies to helm templates. Do note that helm templates are not strictly valid YAML files and helm template rules supercede normal YAML rules.

Linting scope

• charts/*/templates/** is excluded from check-yaml and yamllint (Go template syntax is not valid YAML).
• charts/*/values.yaml, Chart.yaml, and examples/*.values.yaml are linted by yamllint with the repo's default config — write them as valid YAML. The __mainSection: helm-docs sentinel pattern is explicitly allowed (see yaml-development).
• charts/*/pre-rendered/** is excluded globally as generated output.

Helm Values Best Practices

Helm values (values.yaml) are the main inputs for a user to configure a chart.

We use values.yaml as the source of truth for our configuration and also where we document all parameters that are exposed to a chart's README.md.

README.md Generation from values.yaml

We use helm-docs to generate README.md (and the docsite values reference page) from each chart's values.yaml plus a README.md.gotmpl template.

helm-docs is pinned via the tool directive in go.mod and invoked through Make: make charts/<chart>/README.md regenerates the chart README, and make helm-docs regenerates all helm-docs outputs (chart README + docsite reference).

The pre-commit hook in .pre-commit-config.yaml reruns the same Make targets when any of the source files change, so the generated outputs stay in sync with values.yaml.

Annotation conventions

• # -- <description> directly above a key documents that key.
• # @notationType -- (sectionstart) <section title> starts a new section automatically. This is a feature that is not present in helm-docs but we implemented within tools/chartlib/helm-docs-lib.gotmpl to allow for better organization of the generated documentation.
• # @default -- <override> overrides the auto-rendered default (useful when the literal default is {} / [] or large/complex).
• # @raw lets a description carry multi-line raw markdown.

Section prose within values.yaml. It generally needs a @raw annotation. See references/values.example.yaml and references/readme.example.md for the conventions in practice.

Helm Template Best Practices

Helpers ("Named Templates")

Helper functions (canonically named "named templates", but that is confusing with general use of "template") are methodic snippets which can be reused across templates.

These should be defined inside of _*.tpl files.

Helpers in Markdown

When writing markdown referencing helpers / named templates, use handlebars for code blocks. This is closest to go templating syntax supported in Github's highlighting engine (highlight.js).

```handlebars
{{- define "mychart.helpername" -}}
  {{/* helper implementation */}}
{{- end -}}

Testing Helm Charts

Consult references/testing.md for implementation details and best practices for testing.

Unit tests should be written and updated as templates are updated.

Snapshot tests should be generally updated as part of feature changes, but do require careful reviews on the changesets to ensure that the changes are expected and correct.

Helm unittests are safe to run locally, do not require a live Kubernetes cluster, and do run quite quickly, so they should be run frequently during development.

Installing Helm Unittest Plugin

Helm unittest is a BDD plugin for writing and testing helm unit tests.

helm plugin install https://github.com/helm-unittest/helm-unittest

See notes in references/testing.md## Installing Helm Unittest Plugin about workarounds for installation issues and verifying installation.

Unit Test Layout

Helm unittest does not support recursive directories by default, so prefer to place all unit tests in a single flat directory within charts/*/tests/ (sibling to the templates/ directory) using the default *_test.yaml pattern. Prefer to use one unit test file per resource template.