Skip to content
Hands-on IT IT Drills

Day 3: Values and Precedence

Goal: Combine values from values.yaml, -f and --set safely, avoid the list trap and know exactly which values apply on an upgrade. · Duration: approx. 60 min · Prerequisite: Day 2

Briefing

  • values.yaml is the default configuration and the documentation of your chart.
  • Precedence from weak to strong: values.yaml < -f (left to right) < --set (left to right). Whoever speaks last wins – but --set beats every file.
  • Maps are merged, lists are replaced completely, null deletes a default.
  • On an upgrade, a flag decides whether old values live on. Without a flag it depends on whether you pass any values at all.
 values.yaml ──> -f dev.yaml ──> -f geheim.yaml ──> --set a=1 ──> --set a=2
 (weak)                                                           (strong)

Drill 1: values.yaml as documentation

The chart gets values. Every value has a comment – # -- is the convention that tools like helm-docs read.

# on prod
mkdir -p ~/helm/tag03 && cd ~/helm/charts
cat > notes/values.yaml <<'EOF'
# notes/values.yaml – Stand Tag 03

# -- Anzahl der notes-api-Pods
replicaCount: 2

image:
  # -- Image ohne Tag
  repository: ghcr.io/thomaszachmann/notes-api
  # -- Tag des Images
  tag: "0.7.1"

# -- API-Key (nur Labor! Ab Tag 8 aus einem Secret)
apiKey: lab-key-123

# -- Zusätzliche Umgebungsvariablen als Liste
env:
  - name: NOTES_LOG_LEVEL
    value: info
  - name: NOTES_PAGE_SIZE
    value: "20"

service:
  # -- Port des Service
  port: 80
EOF
cat > notes/templates/deployment.yaml <<'EOF'
# notes/templates/deployment.yaml – Stand Tag 03
apiVersion: apps/v1
kind: Deployment
metadata:
  name: notes-api
  labels: {app.kubernetes.io/name: notes-api}
spec:
  replicas: {{ .Values.replicaCount }}
  selector:
    matchLabels: {app.kubernetes.io/name: notes-api}
  template:
    metadata:
      labels: {app.kubernetes.io/name: notes-api}
    spec:
      containers:
        - name: notes-api
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
          ports: [{name: http, containerPort: 8080}]
          env:
            - name: NOTES_API_KEY
              value: {{ .Values.apiKey | quote }}
            {{- with .Values.env }}
            {{- toYaml . | nindent 12 }}
            {{- end }}
          readinessProbe:
            httpGet: {path: /healthz, port: http}
EOF
sed -i 's/Stand Tag 02/Stand Tag 03/' notes/templates/service.yaml
sed -i 's/port: 80,/port: {{ .Values.service.port }},/' notes/templates/service.yaml
sed -i 's/^version: .*/version: 0.2.0/; s/Tag 02/Tag 03/' notes/Chart.yaml
helm template notes ./notes -s templates/deployment.yaml | sed -n '/env:/,/readiness/p'

The # -- comments stay German, like all comments in chart files. In order: “number of notes-api Pods”, “image without tag”, “image tag”, “API key (lab only! From Day 8 from a Secret)”, “additional environment variables as a list”, “port of the Service”.

Expected:

          env:
            - name: NOTES_API_KEY
              value: "lab-key-123"
            - name: NOTES_LOG_LEVEL
              value: info
            - name: NOTES_PAGE_SIZE
              value: "20"
          readinessProbe:

{{ .Values.replicaCount }} fetches a value; you learn with, toYaml and nindent in more detail on Days 4 and 5. Today only one thing counts: what ends up in the YAML?

Save your progress? Sign up for free

Drill 2: Who wins?

# on prod
cd ~/helm/tag03
printf 'replicaCount: 1\n' > a.yaml
printf 'replicaCount: 3\n' > b.yaml
C=~/helm/charts/notes
helm template notes $C -s templates/deployment.yaml | yq '.spec.replicas'
helm template notes $C -s templates/deployment.yaml -f a.yaml | yq '.spec.replicas'
helm template notes $C -s templates/deployment.yaml -f a.yaml -f b.yaml \
  | yq '.spec.replicas'
helm template notes $C -s templates/deployment.yaml -f b.yaml -f a.yaml \
  | yq '.spec.replicas'
helm template notes $C -s templates/deployment.yaml -f b.yaml --set replicaCount=4 \
  -f a.yaml | yq '.spec.replicas'
helm template notes $C -s templates/deployment.yaml --set replicaCount=4 \
  --set replicaCount=5 | yq '.spec.replicas'

Expected:

2
1
3
1
4
5

Among files, the rightmost wins. --set wins against every file – even one that comes further right on the command line. Among several --set, the rightmost wins again.

Save your progress? Sign up for free

Drill 3: The siblings of –set

Which type do you get? A dry run prints the release as JSON; .config holds your values:

# on prod
printf 'Zeile 1\nZeile 2\n' > motd.txt
helm install x $C --dry-run=client -o json --set a=1 --set b=true --set c=0.7.10 \
  --set d=1.20 --set e=null | jq -c .config
helm install x $C --dry-run=client -o json --set-string a=1,b=true | jq -c .config
helm install x $C --dry-run=client -o json --set hosts=a.example.com,b.example.com
helm install x $C --dry-run=client -o json \
  --set-literal hosts=a.example.com,b.example.com | jq -c .config
helm install x $C --dry-run=client -o json --set 'hosts={a.example.com,b.example.com}' \
  | jq -c .config
helm install x $C --dry-run=client -o json \
  --set-json 'resources={"limits":{"memory":"128Mi"}}' | jq -c .config
helm install x $C --dry-run=client -o json --set-file motd=motd.txt | jq -c .config

Expected:

{"a":1,"b":true,"c":"0.7.10","d":"1.20","e":null}
{"a":"1","b":"true"}
Error: INSTALLATION FAILED: failed parsing --set data: key "com" has no value
{"hosts":"a.example.com,b.example.com"}
{"hosts":["a.example.com","b.example.com"]}
{"resources":{"limits":{"memory":"128Mi"}}}
{"motd":"Zeile 1\nZeile 2\n"}

(Zeile is German for “line”.)

Flag Effect
--set integers, true/false and null are recognised, everything else is a string
--set-string always a string
--set-literal the whole text is the value; comma and dot have no special meaning
--set-json / --set-file value as JSON, or from the content of a file

Contrary to what is often claimed, --set does not turn 1.20 into a number – only whole numbers are converted. With --set, the comma separates assignments; you write a list with {…}.

Save your progress? Sign up for free

Drill 4: The list trap

Paths also work into lists: env[0].value. What happens to the rest of the list?

# on prod
Q='.spec.template.spec.containers[0].env'
helm template notes $C -s templates/deployment.yaml --set 'env[0].value=debug' \
  | yq -o json -I0 "$Q"
printf 'env:\n  - name: NOTES_FEATURE_TAGS\n    value: "on"\n' > dev-liste.yaml
helm template notes $C -s templates/deployment.yaml -f dev-liste.yaml \
  | yq -o json -I0 "$Q"

Expected:

[{"name":"NOTES_API_KEY","value":"lab-key-123"},{"value":"debug"}]
[{"name":"NOTES_API_KEY","value":"lab-key-123"},
{"name":"NOTES_FEATURE_TAGS","value":"on"}]

Both times the list from values.yaml is gone. --set 'env[0].value=debug' does not change the first element; it builds a new list whose first element has only value – without name, Kubernetes would reject the Deployment. The file replaces the list completely. Configuration that users should be able to extend belongs in a map:

# on prod
cat > $C/values.yaml <<'EOF'
# notes/values.yaml – Stand Tag 03

# -- Anzahl der notes-api-Pods
replicaCount: 2

image:
  # -- Image ohne Tag
  repository: ghcr.io/thomaszachmann/notes-api
  # -- Tag des Images
  tag: "0.7.1"

# -- API-Key (nur Labor! Ab Tag 8 aus einem Secret)
apiKey: lab-key-123

# -- Zusätzliche Umgebungsvariablen: Name -> Wert (Map, damit -f ergänzen kann)
env:
  NOTES_LOG_LEVEL: info
  NOTES_PAGE_SIZE: "20"

service:
  # -- Port des Service
  port: 80
EOF
cat > $C/templates/deployment.yaml <<'EOF'
# notes/templates/deployment.yaml – Stand Tag 03
apiVersion: apps/v1
kind: Deployment
metadata:
  name: notes-api
  labels: {app.kubernetes.io/name: notes-api}
spec:
  replicas: {{ .Values.replicaCount }}
  selector:
    matchLabels: {app.kubernetes.io/name: notes-api}
  template:
    metadata:
      labels: {app.kubernetes.io/name: notes-api}
    spec:
      containers:
        - name: notes-api
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
          ports: [{name: http, containerPort: 8080}]
          env:
            - name: NOTES_API_KEY
              value: {{ .Values.apiKey | quote }}
            {{- range $name, $value := .Values.env }}
            - name: {{ $name }}
              value: {{ $value | quote }}
            {{- end }}
          readinessProbe:
            httpGet: {path: /healthz, port: http}
EOF
printf 'env:\n  NOTES_FEATURE_TAGS: "on"\n' > dev-map.yaml
helm template notes $C -s templates/deployment.yaml -f dev-map.yaml \
  | yq -o json -I0 "$Q"
helm template notes $C -s templates/deployment.yaml --set env.NOTES_LOG_LEVEL=debug \
  | yq -o json -I0 "$Q"

The new env comment reads “additional environment variables: name -> value (a map, so that -f can add to it)”.

Expected:

[{"name":"NOTES_API_KEY","value":"lab-key-123"},
{"name":"NOTES_FEATURE_TAGS","value":"on"},{"name":"NOTES_LOG_LEVEL","value":"info"},
{"name":"NOTES_PAGE_SIZE","value":"20"}]
[{"name":"NOTES_API_KEY","value":"lab-key-123"},
{"name":"NOTES_LOG_LEVEL","value":"debug"},{"name":"NOTES_PAGE_SIZE","value":"20"}]

The file adds, --set changes exactly one entry. range over a map runs in alphabetical order – the output stays stable (Day 5).

Save your progress? Sign up for free

Drill 5: null deletes a default

# on prod
helm template notes $C -s templates/deployment.yaml --set env.NOTES_PAGE_SIZE=null \
  | yq -o json -I0 "$Q"
printf 'env:\n  NOTES_PAGE_SIZE: null\n' > ohne-page.yaml
helm template notes $C -s templates/deployment.yaml -f ohne-page.yaml \
  | yq -o json -I0 "$Q"

Expected:

[{"name":"NOTES_API_KEY","value":"lab-key-123"},
{"name":"NOTES_LOG_LEVEL","value":"info"}]
[{"name":"NOTES_API_KEY","value":"lab-key-123"},
{"name":"NOTES_LOG_LEVEL","value":"info"}]

null removes the key from the result – not “empty”, but gone. That is how a user switches off a default without changing the chart.

Save your progress? Sign up for free

Drill 6: Values per environment

Same chart, same version, different values. The files live in the repo next to the chart, not inside it – they belong to operations, not to the package.

# on prod
cd ~/helm/charts && mkdir -p values
cat > values/dev.yaml <<'EOF'
# values/dev.yaml – Stand Tag 03
replicaCount: 1
env:
  NOTES_LOG_LEVEL: debug
  NOTES_FEATURE_TAGS: "on"
EOF
cat > values/prod.yaml <<'EOF'
# values/prod.yaml – Stand Tag 03
replicaCount: 2
env:
  NOTES_LOG_LEVEL: warn
EOF
helm upgrade notes ./notes -n notes -f values/prod.yaml --wait | grep REVISION
helm get values notes -n notes

Expected:

REVISION: 2
USER-SUPPLIED VALUES:
env:
  NOTES_LOG_LEVEL: warn
replicaCount: 2

Save your progress? Sign up for free

Drill 7: Values on upgrade

What happens to prod.yaml if on the next upgrade you just quickly change the replicas? And what if you pass nothing at all?

# on prod
J='{.spec.replicas} {range .spec.template.spec.containers[0].env[*]}'
J="$J{.name}={.value} {end}"
helm upgrade notes ./notes -n notes --set replicaCount=3 --wait | grep REVISION
helm get values notes -n notes
helm upgrade notes ./notes -n notes --wait | grep REVISION
helm get values notes -n notes
kubectl -n notes get deploy notes-api -o jsonpath="$J"; echo

Expected:

REVISION: 3
USER-SUPPLIED VALUES:
replicaCount: 3
REVISION: 4
USER-SUPPLIED VALUES:
replicaCount: 3
3 NOTES_API_KEY=lab-key-123 NOTES_LOG_LEVEL=info NOTES_PAGE_SIZE=20

Revision 3: as soon as you pass any value, Helm computes chart defaults plus that value – warn from prod.yaml is gone. Revision 4: if you pass no value at all, Helm takes over the values of the last deployed revision. So the rule “without a flag only the defaults apply” is only half true.

Now the three flags. For this you restore the state and change a default in the chart: page size 50 instead of 20, version 0.2.1.

# on prod
helm upgrade notes ./notes -n notes -f values/prod.yaml --set replicaCount=3 --wait \
  | grep REVISION
sed -i 's/^version: 0.2.0/version: 0.2.1/' notes/Chart.yaml
sed -i 's/NOTES_PAGE_SIZE: "20"/NOTES_PAGE_SIZE: "50"/' notes/values.yaml
for f in --reuse-values --reset-then-reuse-values --reset-values; do
  helm upgrade notes ./notes -n notes $f --wait > /dev/null
  echo "$f"; kubectl -n notes get deploy notes-api -o jsonpath="$J"; echo
done

Expected:

REVISION: 5
--reuse-values
3 NOTES_API_KEY=lab-key-123 NOTES_LOG_LEVEL=warn NOTES_PAGE_SIZE=20
--reset-then-reuse-values
3 NOTES_API_KEY=lab-key-123 NOTES_LOG_LEVEL=warn NOTES_PAGE_SIZE=50
--reset-values
2 NOTES_API_KEY=lab-key-123 NOTES_LOG_LEVEL=info NOTES_PAGE_SIZE=50
Flag Result
--reuse-values old values and old defaults – the new default 50 is missing
--reset-then-reuse-values new defaults, with your old values on top
--reset-values only the new defaults; your values are gone

--reuse-values is the trap: it takes the merged values of the old chart. A new or changed default never arrives. The safest approach remains: pass all values from files on every upgrade.

# on prod
helm upgrade notes ./notes -n notes -f values/prod.yaml --wait | grep REVISION
kubectl -n notes get deploy notes-api -o jsonpath="$J"; echo

Expected:

REVISION: 9
2 NOTES_API_KEY=lab-key-123 NOTES_LOG_LEVEL=warn NOTES_PAGE_SIZE=50

Save your progress? Sign up for free

Exercise: Speed Drills

  1. Show all merged values of the release notes. Target time: 10 s
  2. Render the Deployment with 0 replicas and show only .spec.replicas. Target time: 30 s
  3. Show which values you had set in revision 5. Target time: 15 s
  4. Set NOTES_FEATURE_TAGS to the string true and prove the type. Target time: 45 s

Solution

# on prod
helm get values notes -n notes --all
helm template notes ./notes -s templates/deployment.yaml --set replicaCount=0 \
  | yq .spec.replicas
helm get values notes -n notes --revision 5
helm install x ./notes --dry-run=client -o json \
  --set-string env.NOTES_FEATURE_TAGS=true | jq -c .config

Expected (abridged):

COMPUTED VALUES:
apiKey: lab-key-123
env:
  NOTES_LOG_LEVEL: warn
  NOTES_PAGE_SIZE: "50"
...
0
USER-SUPPLIED VALUES:
env:
  NOTES_LOG_LEVEL: warn
replicaCount: 3
{"env":{"NOTES_FEATURE_TAGS":"true"}}

Save your progress? Sign up for free

Checkpoint

# on prod
helm list -n notes

Expected:

NAME   NAMESPACE  REVISION  UPDATED  STATUS    CHART        APP VERSION
notes  notes      9         ...      deployed  notes-0.2.1  0.7.1
# on prod
helm get values notes -n notes

Expected: exactly the content of values/prod.yaml (NOTES_LOG_LEVEL: warn, replicaCount: 2).

# on prod
kubectl -n notes get deploy notes-api -o jsonpath="$J"; echo

Expected: 2 NOTES_API_KEY=lab-key-123 NOTES_LOG_LEVEL=warn NOTES_PAGE_SIZE=50 ($J comes from Drill 7; in a new shell, run the two J= lines first).

Challenge

Add an environment staging (2 replicas, log level from the chart, feature NOTES_FEATURE_TAGS on). Render all three environments in a loop showing replicas and environment variables, and install dev as release notes-dev in tag03.

Hint: A for loop over the environment names and yq with two expressions.

Solution

# on prod
cat > values/staging.yaml <<'EOF'
# values/staging.yaml – Stand Tag 03
replicaCount: 2
env:
  NOTES_FEATURE_TAGS: "on"
EOF
for env in dev staging prod; do echo "== $env"; helm template notes ./notes \
  -f values/$env.yaml -s templates/deployment.yaml | yq '.spec.replicas,
  (.spec.template.spec.containers[0].env[] | .name + "=" + .value)' \
  | grep -v API_KEY; done
helm install notes-dev ./notes -n tag03 --create-namespace -f values/dev.yaml \
  --wait | grep STATUS
kubectl -n tag03 get deploy

Expected:

== dev
1
NOTES_FEATURE_TAGS=on
NOTES_LOG_LEVEL=debug
NOTES_PAGE_SIZE=50
== staging
2
NOTES_FEATURE_TAGS=on
NOTES_LOG_LEVEL=info
NOTES_PAGE_SIZE=50
== prod
2
NOTES_LOG_LEVEL=warn
NOTES_PAGE_SIZE=50
STATUS: deployed
NAME        READY   UP-TO-DATE   AVAILABLE   AGE
notes-api   1/1     1            1           3s

The same chart version moves through all stages; only the values change. In CI you render every environment and check it (Day 17).

Save your progress? Sign up for free

Cleanup

# on prod
helm uninstall notes-dev -n tag03
kubectl delete namespace tag03
git add -A
git commit -qm "Tag 03: Values, Werte-Dateien pro Umgebung, notes 0.2.1"

Expected:

release "notes-dev" uninstalled
namespace "tag03" deleted

Interview Note

  • In which order do values apply? The chart’s values.yaml, then values from the parent chart (Day 9), then -f from left to right, then --set from left to right.
  • Why is --reuse-values risky? It takes over the old values together with the old chart defaults. New or changed defaults do not arrive; --reset-then-reuse-values is the better choice.
  • How do you make configuration extensible? Maps instead of lists, because Helm merges maps and replaces lists.

Enterprise Note

  • Keep values files per environment in Git and pass all of them on every upgrade. Use --set only for what CI generates, such as an image tag.
  • Secrets never belong in these files – not even in values.yaml, like the lab API key here (Days 8, 16).
  • Save helm get values --all before every manual intervention: it is the only record of which values a release is currently running with.
  • GitOps tools always compute with all values from the repo and avoid the upgrade traps of manual upgrades (Day 18).