Helm and Kustomize validation — lint, template, and build

Helm and Kustomize are the two templaters the Kubernetes ecosystem has converged on. Both turn sources into the YAML the API server eventually receives. Both produce that YAML through a render step that CI can invoke. The validation story differs because the source model differs: Helm’s source is a chart with values, and the render is template expansion; Kustomize’s source is a base plus patches, and the render is structural transformation. The CI commands reflect the difference, and the three tools — helm lint, helm template, kustomize build — compose with kubeconform to produce the validated render.

helm lint

helm lint reads the chart, the values, and the templates against a list of common mistakes. The check is source-time: the templates are parsed but not expanded with values, and the chart structure is checked against the chart best practices.

helm lint ./chart

The output is a list of [INFO] and [WARNING] lines, plus a summary:

[INFO] Chart.yaml: icon is recommended
[WARNING] templates/deployment.yaml: object name does not conform to Kubernetes naming conventions
1 chart(s) linted, 0 failed(s)

What helm lint catches:

• Chart structure. Missing Chart.yaml fields, malformed version strings, deprecated API versions.
• Template syntax. Go template errors that prevent expansion.
• Naming conventions. ServiceAccount names that exceed the 63-character limit, label keys that violate the optional prefix requirement.
• Common values issues. Missing required values, values that override immutable fields.

What helm lint does not catch:

• Render-time errors. A values.yaml that produces a syntactically valid template but a semantically broken manifest at expansion time.
• Schema errors. Unknown fields, missing required fields, type errors. These are caught by kubeconform, not by helm lint.

helm lint --strict upgrades warnings to failures; --with-subcharts extends the check to chart dependencies. The strict mode is the production default; the default mode is a debugging aid.

helm template

helm template renders the chart with values and emits the YAML on stdout. The render is what the API server will see if helm install is run. Adding --validate turns the render into a schema check by parsing each emitted document against the local Kubernetes API version:

helm template ./chart
helm template ./chart --validate

The --validate flag is the bridge between source-time and render-time validation. A chart that passes helm lint can still produce a render that fails --validate because the render references a field the schema does not accept. The failure is the API server’s contract enforced locally.

flowchart LR
    A["helm lint"] -->|chart structure| B["Source-time"]
    C["helm template --validate"] -->|render + schema| D["Render-time"]
    B --> E["CI pipeline"]
    D --> E
    E --> F["kubeconform"]
    F --> G["Pinned schema check"]

The composition is the point. helm lint is fast (sub-second on most charts) and catches the cheap class of error. helm template is slower (seconds) and catches the render-time class. kubeconform catches the schema class against a pinned Kubernetes version. The three checks together cover what neither covers alone.

kustomize build

kustomize build reads an overlay and emits the rendered YAML. The overlay is a directory containing a kustomization.yaml that lists the base and the patches; the build walks the resources, applies the patches, and produces a stream of YAML on stdout:

kustomize build overlays/prod

Unlike Helm, Kustomize does not have a separate lint command. The validation story is simpler:

• kustomize build succeeds. The overlay is structurally valid; the patches apply; the references resolve. A failure here is a structural error (a missing base, a malformed patch, a circular reference).
• kustomize build output is schema-valid. The render is structural YAML, but a field that does not exist in the target schema will pass kustomize build and fail kubeconform. The schema check is downstream.

The two checks compose:

kustomize build overlays/prod | kubeconform -strict -summary -kubernetes-version 1.36.0

The pipe is the contract: the render must succeed, and the rendered output must pass the pinned schema check. A failure in either fails the pipeline.

Source-time versus render-time

The three commands split into two classes:

The split is the operational discipline. Source-time checks are fast and cheap; render-time checks are slower and authoritative. Both are required; neither replaces the other.

Production discipline

1. Run helm lint --strict on every chart change. The strict flag promotes warnings to failures; the default is a debugging aid.
2. Run helm template --validate and pipe to kubeconform. The render-then-validate pipeline is what produces a checked artifact.
3. Pin the kubeconform version. Without -kubernetes-version, the schema check is against the tool’s bundled schema, not the target cluster.
4. Render Kustomize overlays and pipe to kubeconform. The overlay build is structural; the schema check is downstream.

Cross-course references

• Kubernetes for Production Sysadmins - Part X (Manifests) covers the Kustomize and Helm mechanics the validation assumes.
• Kubernetes for Production Sysadmins - Part XXXIII (Admission) covers OPA Gatekeeper and Kyverno, which check policy at admission time that the validation stage does not cover.
• This course, Part LII-02 (ManifestValidation) - the schema check kubeconform provides; this lesson renders into it.

Quiz