Day 3: Values and Precedence
Goal: Combine values from
values.yaml,-fand--setsafely, avoid the list trap and know exactly which values apply on an upgrade. · Duration: approx. 60 min · Prerequisite: Day 2
Briefing
values.yamlis 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--setbeats every file. - Maps are merged, lists are replaced completely,
nulldeletes 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 .configExpected:
{"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 notesExpected:
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"; echoExpected:
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
doneExpected:
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"; echoExpected:
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
- Show all merged values of the release
notes. Target time: 10 s - Render the Deployment with 0 replicas and show only
.spec.replicas. Target time: 30 s - Show which values you had set in revision 5. Target time: 15 s
- Set
NOTES_FEATURE_TAGSto the stringtrueand 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 .configExpected (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 notesExpected:
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 notesExpected: 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"; echoExpected:
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 deployExpected:
== 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-ffrom left to right, then--setfrom left to right. - Why is
--reuse-valuesrisky? It takes over the old values together with the old chart defaults. New or changed defaults do not arrive;--reset-then-reuse-valuesis 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
--setonly 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 --allbefore 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).