Skip to content
Tutorials Center
My learning

Topics

Lesson 11 of 38 ยท Templates and Values

Values and Overrides: values.yaml, -f and --set

Learn how Helm merges values: chart defaults, values files, --set, --set-string and --set-file, the precedence order, list pitfalls and good values.yaml design.

Values are the inputs of a chart. A good chart exposes a clear set of values with safe defaults, and a good deployment overrides only what differs. This lesson explains where values come from, which source wins, how --set syntax works (including its traps with lists and types), and how to design a readable values.yaml.

Where values come from

Helm builds one big nested map called .Values by layering sources. Later sources override earlier ones:

  1. The chart's own values.yaml (the defaults).
  2. For a subchart, the values passed from its parent chart.
  3. Each -f / --values file, in the order given on the command line.
  4. --set, --set-string, --set-file and --set-json flags, in the order given.
flowchart LR
  A["values.yaml (chart defaults)"] --> B["-f base.yaml"]
  B --> C["-f prod.yaml"]
  C --> D["--set image.tag=2.8.1"]
  D --> E[".Values in templates"]

Each arrow means: this layer overrides the one before it, key by key.

Maps are merged deeply: you only name the keys you want to change. Everything else, including sibling keys, keeps the default. Lists and scalars are replaced: giving a list means giving the whole list.

A values file

YAML
# values-prod.yaml
replicaCount: 6
image:
  tag: "2.8.1"
resources:
  limits:
    memory: 512Mi
Terminal
helm install blog ./webapp -f values-prod.yaml
helm upgrade blog ./webapp -f values/base.yaml -f values/prod.yaml

image.repository is not mentioned in values-prod.yaml, so the chart default stays. Use as many files as you like: a common layout is base.yaml (shared), prod.yaml or staging.yaml (environment) and sometimes secrets.yaml (decrypted in CI, never committed in plain text).

The deep merge, in code

Here is the merge rule as a program. Experiment with lists to see them replaced rather than merged.

Python Stand-in: merging values layers

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Check the output: image.repository and cpu survived the merge, while ports is just [8080].

The --set flags

--set is great for one-off changes and values computed in a pipeline:

Terminal
helm install blog ./webapp \
  --set replicaCount=3 \
  --set image.tag=2.8.1 \
  --set ingress.enabled=true \
  --set 'ingress.hosts[0].host=blog.example.com' \
  --set 'nodeSelector.disktype=ssd' \
  --set 'tolerations[0].key=dedicated,tolerations[0].operator=Exists'

The rules, which the next stand-in implements:

Syntax Result
a.b=c {a: {b: "c"}}; dots create nesting
a[0]=x list with x at index 0
a={x,y} list [x, y] (use quotes in your shell)
a=1,b=2 two keys, comma separated
a=true, a=3, a=null coerced to boolean, integer, null
a=foo\,bar the comma is escaped and kept in the string
a\.b=c the key is literally a.b (needed for annotations such as kubernetes.io/foo)

Variants: --set-string forces strings (use for "true" or "1234" that must stay text), --set-file key=path reads a file's content into a value, and --set-json 'a={"b":1}' accepts JSON.

Python Stand-in: parsing --set expressions

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Two traps appear in the output. ingress.hosts[0].host=... builds a list, so any other entries of the default list are lost, and version=007 stays a string only because of the leading zero rule, while version=1234 would become a number: use --set-string when in doubt.

Why not set everything with --set?

  • It is invisible in review: nobody can see what --set flags a pipeline used last month.
  • Deep structures (lists of objects) are miserable to express.
  • Shell quoting differs between bash, PowerShell and CI systems.

Use values files for configuration, --set for the few dynamic inputs.

Designing a good values.yaml

  1. Document every key with a comment, and show an example for non-obvious ones. Tools such as helm-docs generate a README table from # -- comment lines.
  2. Use nested maps, not long flat names: image.repository and image.tag, not imageRepository. Group by component (web.replicas, worker.replicas).
  3. Prefer maps over lists where order does not matter. Maps merge by key and can be overridden one entry at a time (env.LOG_LEVEL=debug); lists must be replaced whole.
  4. Pick safe defaults so helm install works with no values at all.
  5. Add enabled toggles for optional components: ingress.enabled: false.
  6. Keep names stable. Renaming a key is a breaking change for everyone's override files; bump the chart's major version if you must.
  7. Expose escape hatches such as extraEnv, extraVolumes and podAnnotations so users do not need to fork the chart.
YAML
# Number of replicas. Ignored when autoscaling.enabled is true.
replicaCount: 2

image:
  # -- Image repository
  repository: registry.example.com/webapp
  # -- Image tag; defaults to the chart's appVersion when empty
  tag: ""

env:            # a map, so users can override one variable
  LOG_LEVEL: info

Never put real secrets (passwords, tokens) in values.yaml or in --set flags committed to Git. Values end up stored, in clear, inside the release Secret. Reference an existing Kubernetes Secret by name, or use an external secrets operator (see Secrets).

Inspecting what Helm received

Terminal
helm show values ./webapp                 # chart defaults
helm get values blog                      # user-supplied overrides
helm get values blog --all                # computed values
helm template blog ./webapp -f prod.yaml --set image.tag=9 | grep image:

The last command is a fast way to confirm that an override reached the manifest.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. values.yaml sets ports: [80, 443]. Your file sets ports: [8080]. What is the result?

    Lists are replaced, not merged; only maps merge deeply.
  2. 2. In which order do sources override each other, weakest to strongest?

    Defaults first, then each -f file in command-line order, then --set flags.
  3. 3. How do you set a value whose key contains dots, like kubernetes.io/ingress-class?

    An escaped dot is part of the key instead of a nesting separator.
  4. 4. You need the string "true" for a value, not the boolean. Which flag?

    --set coerces true/false/null/numbers; --set-string keeps text.
  5. 5. Which values layout is easiest to override per environment?

    Maps merge by key, so an environment can change one entry only.

Summary

  • Values layer as: chart defaults, then -f files in order, then --set flags; maps merge deeply, lists and scalars replace.
  • --set supports nesting with dots, [n] list indexes, {a,b} lists, escapes, and type coercion; use --set-string to keep text.
  • Keep configuration in reviewed values files; reserve --set for dynamic values.
  • Design values.yaml with documented, nested, stable keys and safe defaults; never store secrets in it.

Next: Built-in Objects: .Release, .Chart, .Values and More