Skip to content

How Helm merges values files

Helm builds one values object from the chart defaults, then each -f file, then --set. Nested maps are combined. Lists are not. A null in a later file deletes the key. That is the whole merge, and it surprises people who expected array items to union by name.

The order

A chart ships values.yaml. Installs and upgrades then apply user files in flag order: -f a.yaml -f b.yaml means b wins where the two disagree. --set and --set-string are applied after the files. Subcharts have their own values under the subchart key, plus a merge with the parent’s overrides for that key. ConfigKit’s Merge Helm values files online page models the two-file case: a base mapping and an override mapping, both parsed as YAML in the browser. It does not load a chart, evaluate templates, or send values to a cluster.

Maps merge. Lists replace.

When both sides have a map at the same path, Helm walks the keys. Keys only in the base stay. Keys only in the override are added. Keys in both are merged again if both values are maps, or replaced if either side is a scalar or a list.

# base
image:
  repository: nginx
  tag: "1.25"
env:
  - name: LOG
    value: info

# override
image:
  tag: "1.26"
env:
  - name: LOG
    value: debug

After the merge, image.repository is still nginx and image.tag is 1.26. env is not a union of two items. It is the override list alone: one entry, LOG=debug. If the base had a second variable, it is gone. This is how Helm’s coalesce works. To change one item, copy the full list into the override and edit the line you care about.

null deletes the key

In Helm 3, an override of drop: null removes drop from the merged object. That is how you turn off a default block without copying every sibling key. ConfigKit deletes the key and lists it as removed. Some older notes about coalesce left the base value when the override was null; do not rely on that if you are on Helm 3.

# override
ingress:
  enabled: null

If you meant “set enabled to false,” write false. null means “this key should not exist.” Templates that check if .Values.ingress.enabled treat missing and false differently when they use hasKey or index into a nested map that no longer exists. Read the chart before deleting a whole subtree.

--set is not a values file

--set image.tag=1.26 is parsed with Helm’s dotted-path syntax, not YAML. A comma starts the next assignment. Nested commas inside a string need escaping. --set-file reads a file into a string key. None of that is “merge two YAML documents.” If a CI job mixes -f and --set, the set flags still win last. The two-file merger on this site will not reproduce a command line you have not pasted as YAML.

--reuse-values and a live release

helm upgrade --reuse-values starts from the values that were computed for the last release, then applies new flags. That object includes previous --set and may not match the chart’s values.yaml plus your git overrides. Dumping helm get values and merging it with a new file is closer to that story. The browser tool does not talk to Tiller-less Helm, the cluster, or the chart archive. It is a helm values.yaml validator only in the sense that each side must be a YAML mapping. Unknown keys are kept. Invalid YAML is not repaired.

Comments and aliases

The merged document is rebuilt from values. Comments in either file are dropped. YAML aliases are expanded up to a limit, then lost as source text. If the comment is the reason you kept two files, put the note in git next to the override, not in a key you expect to survive stringify. See Why YAML to JSON loses comments (and what to do) for the same rebuild rule in another conversion.

Checking a merge here

Paste chart defaults on the left and the environment file on the right. The merged YAML appears below. Notices list each added, removed, and changed path. Use that list to catch an accidental list replace. Then run a real helm template in CI with the same two files. The browser merge is for inspecting the object. The chart templates are what you ship.

FAQ

Does Helm deep-merge lists in values.yaml?
No. A list in a later values file replaces the list at that key. To change one item, repeat the whole list.
What does a null override do in Helm 3?
null removes the key from the merged map. Older coalesce behavior could leave the base value; ConfigKit follows the delete rule and says so in the diff.
Is merging two files the same as helm upgrade --reuse-values?
No. --reuse-values starts from the last release’s computed values. A two-file merge on this site does not talk to a cluster or a chart.

Related: Merge Helm values files online, JSON and YAML diff, YAML validator.