Introduction
Validating Helm chart content is not one command. It is a layered process: lint the chart structure, render templates with realistic values, validate the rendered Kubernetes manifests, and, if needed, enforce policy checks before installation. The mistake teams make is stopping after helm lint and assuming the chart is production-safe.
Start With helm lint
helm lint checks chart structure, template issues, and some obvious mistakes.
This is the fastest first pass. It can catch problems such as:
It is useful, but it is not a complete validation strategy because it does not prove the rendered manifests are valid for your target cluster.
Render the Templates With Realistic Values
A chart that passes lint can still render invalid YAML or invalid Kubernetes resources for a specific values file. Render the chart exactly as your deployment pipeline would.
helm template my-release ./my-chart -f values.yaml
For deeper debugging, add --debug.
helm template my-release ./my-chart -f values.yaml --debug
This step matters because many Helm problems only appear after conditionals, loops, and value substitutions are evaluated.
Validate the Rendered Manifests
Once the chart is rendered, validate the output as Kubernetes YAML rather than as Helm templates.
A common pattern is piping the output into a manifest validator such as kubeconform.
helm template my-release ./my-chart -f values.yaml \
| kubeconform -strict -summary ``` This catches schema-level issues in the final manifests, such as invalid fields, wrong types, or resources that do not match the expected Kubernetes API schema. That is a much stronger check than linting the chart alone. ## Add a Values Schema Helm supports `values.schema.json`, which lets you validate chart values before or during rendering. This is one of the most effective ways to prevent bad input from reaching your templates. A minimal example: ```json { "$schema": "https://json-schema.org/draft-07/schema#", "type": "object", "properties": { "replicaCount": { "type": "integer", "minimum": 1 }, "image": { "type": "object", "properties": { "repository": { "type": "string" }, "tag": { "type": "string" } }, "required": ["repository", "tag"] } }, "required": ["replicaCount", "image"] } ``` With that schema in place, Helm can reject bad values earlier, which is much easier to debug than broken templates downstream. ## Use Dry Runs Against a Cluster When Needed Some errors depend on the actual cluster API or installed custom resources. In that case, validate with a dry run that talks to the cluster. ```bash helm install my-release ./my-chart -f values.yaml --dry-run --debug ``` That helps you catch issues involving API discovery, release rendering, and cluster-specific behavior. It is especially useful when the chart depends on CRDs or cluster capabilities that local linting cannot simulate fully. ## Validate Behavior With Tests Static validation is important, but it does not tell you whether the release behaves correctly after installation. For that, combine chart validation with tests. Helm supports chart tests after installation: ```bash helm test my-release ``` Those tests are useful for release behavior, but they are not a substitute for content validation before install. Think of them as a later stage in the pipeline. Many teams also use template-focused unit testing tools to assert that rendering produces the expected resources under different values files. ## Add Policy Checks for Security and Standards Schema validation confirms the manifests are shaped correctly. It does not confirm they meet your organization's rules. Examples of policy questions: - do all containers set resource requests and limits - are privileged containers forbidden - are only approved registries allowed - are labels and annotations present These checks belong in policy tooling after template rendering. That is where you move from "is this valid Kubernetes" to "is this acceptable in our platform". ## A Practical CI Sequence A strong CI pipeline for charts often looks like this: 1. run `helm lint` 2. render with one or more realistic values files 3. validate rendered manifests with a schema tool 4. run policy checks on the rendered YAML 5. optionally perform a dry-run install in a test cluster This layered approach catches different classes of errors at the right stage. ## Validate Dependencies Too If your chart uses dependencies, validation is incomplete unless those dependency versions are also pinned and rendered consistently. Keep the dependency lock file current and run validation after dependencies are updated. A chart that validates without fresh dependency resolution can still fail in CI or deployment if transitive templates changed. ## Common Pitfalls Stopping after `helm lint` and assuming the rendered manifests must therefore be valid. Testing only with default values while production uses several environment-specific overrides. Skipping `values.schema.json`, which leaves bad values to fail later inside templates. Using dry-run output alone without schema or policy validation of the rendered manifests. Ignoring dependency changes when validating chart behavior. ## Summary - Helm chart validation should include linting, rendering, manifest validation, and often policy checks. - '`helm lint` is a first pass, not the whole answer.' - '`helm template` with real values is the core step for understanding what the chart actually produces.' - '`values.schema.json` catches bad inputs earlier and makes charts easier to maintain.' - Strong pipelines validate both chart structure and the final Kubernetes resources the chart renders.
