Value Precedence

When the same key is set in several places, Helm merges them with a clear precedence order.

The same key can be defined in the chart, in override files, and on the command line. Helm merges them all, and the winner follows a fixed precedence order.

From lowest to highest priority

  1. The chart's own values.yaml (defaults).
  2. A parent chart's values (for subcharts).
  3. Values files passed with -f, in the order given (later beats earlier).
  4. --set and --set-string on the command line (highest).
SourcePriority
chart values.yamllowest
parent chart values (subcharts)low
-f values files (later wins)high
--set / --set-stringhighest

Example

Example · bash
# replicaCount is 1 in values.yaml, 3 in prod.yaml, 5 on the CLI.
# The final value is 5 because --set has the highest precedence.
helm upgrade my-web ./mychart \
  -f prod.yaml \
  --set replicaCount=5

# Confirm the computed values
helm get values my-web

When to use it

  • A developer understands that a --set flag passed at install time beats a -f values file, so they can pin a hotfix image tag in CI without editing any committed files.
  • A chart author documents the precedence order so operators know that subchart values are overridden by prefixing the subchart name in the parent's values.yaml.
  • A platform team enforces production settings by placing them in a values file loaded last in the -f chain, knowing later -f files win over earlier ones.

More examples

Precedence demonstration

Illustrates the full precedence stack: --set overrides the last -f file, which overrides chart defaults.

Example · bash
# Order from lowest to highest precedence:
# 1. chart defaults (values.yaml)
# 2. subchart values
# 3. -f values files (later files win)
# 4. --set / --set-string / --set-json (highest)
helm upgrade my-app ./chart \
  -f values.yaml \
  -f values-prod.yaml \
  --set image.tag=hotfix-123

Later -f file wins

Shows that when the same key exists in two -f files, the value from the last file in the list wins.

Example · bash
# values-base.yaml has: replicaCount: 2
# values-prod.yaml has: replicaCount: 10
# Result: replicaCount = 10 (prod wins)
helm install my-app ./chart \
  -f values-base.yaml \
  -f values-prod.yaml

Debug merged values

Uses --dry-run --debug to print the final merged values Helm would use, confirming precedence worked as expected.

Example · bash
helm install my-app ./chart \
  -f values-prod.yaml \
  --set replicaCount=3 \
  --dry-run --debug 2>&1 | grep -A 20 'USER-SUPPLIED VALUES'

Related

helm sethelm custom values

Discussion

  • Be the first to comment on this lesson.