Values and Overrides

Layering values files and --set overrides, managing per-environment configuration cleanly, and validating inputs with values.schema.json.

Overview

One chart, many environments

Values are Helm's configuration layer: the mechanism that lets one chart serve many environments and use cases without duplicating templates. Layering, precedence and a clean multi-environment structure are core to effective Helm use.

Values merge, they do not replace

When you pass several -f files, Helm deep-merges them left to right into a single values map. The base values.yaml defines safe defaults for every environment, and environment files contain only what differs.

> [!TIP] Small environment files reduce drift and make diffs between environments meaningful.

Precedence

1 (lowest) — Chart defaults (values.yaml)
2 — Parent chart values for sub-charts
3 — -f files, left to right
4 (highest) — CLI --set flags

The standard CI/CD pattern:

In CI/CD the command is: -f values.yaml -f values-${ENV}.yaml with --set image.tag=${BUILD_SHA} to pin the exact image at deploy time.

Schema validation

values.schema.json (JSON Schema draft-07) is a feature many charts omit but all public charts should use.

> [!IMPORTANT] For platform teams distributing internal charts, schema validation prevents "wrong values applied to the wrong environment" incidents that are otherwise hard to detect.

Key concepts

Values precedence order: Lowest to highest: chart values.yaml defaults, sub-chart parent values, -f files (left-to-right), --set flags. The rightmost source wins on conflicts. Values from all sources are deep-merged, not replaced wholesale.
--set vs -f: --set is for point overrides at deploy time (image tag, replica count). -f is for structured environment files. Avoid using --set for complex nested structures — use --set-json or -f. Store --set values in the release Secret, but they are easy to lose track of when inspecting deployments.
helm get values vs helm get values --all: helm get values shows only user-supplied overrides (not chart defaults). helm get values --all shows the complete merged values including chart defaults. Use --all when debugging to see the full effective configuration.
Deep merge semantics: When multiple -f files are merged, nested maps are merged recursively. A staging values file can set image.tag without affecting image.repository from the base values.yaml. Only conflicting leaf values are overwritten.
values.schema.json: JSON Schema (draft-07) file at chart root. Validated on install, upgrade, lint, and template. Enforces types, required fields, enums, patterns, and numeric ranges. Shifts errors from runtime Pod failures to install-time validation errors.

When to use it

Designing the configuration surface for a new chart: decide what belongs in values.yaml vs what gets hardcoded
Setting up multi-environment deploys: one chart, three values files (dev/staging/prod)
Debugging a release with unexpected behavior: helm get values to see what is actually configured
Adding input validation to a chart: values.schema.json for type checking, required fields, and enum constraints

Interview questions

How would you structure values files for a service deployed to dev, staging, and production?
How do you handle secrets in Helm values without committing them to Git?
Describe how values.schema.json improves chart reliability.
How do you debug a release where the running behavior does not match your expected values?
What is the difference between --set, --set-string, --set-json, and --set-file?