Day 2: Your Own Chart – Structure and Chart.yaml
Goal: Create the chart
notesby hand, package it and install it as the releasenotes– and know which file goes where and which version means what. · Duration: approx. 45 min · Prerequisite: Day 1
Briefing
- A chart is a folder with fixed names:
Chart.yaml(ID card),values.yaml(default values, from Day 3),templates/(gets rendered),charts/(subcharts). - Everything in
templates/gets rendered – except files that start with_.NOTES.txtis shown after the installation. versionis the SemVer version of the chart,appVersionthat of the app. They are independent.- Today still without values: the manifests are finished YAML; only
NOTES.txtalready uses the built-in objects.Chartand.Release. Values come on Day 3.
notes/
├── Chart.yaml name, version 0.1.0, appVersion "0.7.1", kubeVersion
├── .helmignore what stays out of the package
├── README.md
└── templates/
├── NOTES.txt text after install/upgrade
├── deployment.yaml
└── service.yaml
Drill 1: Look at helm create and throw it away
helm create produces a skeleton with everything charts
usually have. For learning, it is too much – you look at it once.
# on prod
mkdir -p ~/helm/tag02 && cd ~/helm/tag02
helm create demo
tree -a demo
cat demo/templates/*.yaml demo/templates/_helpers.tpl demo/values.yaml | wc -l
helm template demo ./demo | grep '^kind:'Expected:
Creating demo
demo
├── .helmignore
├── Chart.yaml
├── charts
├── templates
│ ├── NOTES.txt
│ ├── _helpers.tpl
│ ├── deployment.yaml
│ ├── hpa.yaml
│ ├── httproute.yaml
│ ├── ingress.yaml
│ ├── service.yaml
│ ├── serviceaccount.yaml
│ └── tests
│ └── test-connection.yaml
└── values.yaml
4 directories, 12 files
442
kind: ServiceAccount
kind: Service
kind: Deployment
kind: Pod
442 lines for an nginx. New in Helm 4 is httproute.yaml
for the Gateway API. The kind: Pod is a test hook. You
build each of these pieces yourself over the next days – then you
understand it.
# on prod
rm -rf demoSave your progress? Sign up for free
Drill 2: Chart.yaml by hand
The chart lives in the git repo from Day 0.
# on prod
mkdir -p ~/helm/charts/notes/templates && cd ~/helm/charts
cat > notes/Chart.yaml <<'EOF'
# notes/Chart.yaml – Stand Tag 02
apiVersion: v2
name: notes
description: Notiz-API mit PostgreSQL – Übungschart aus „Helm Charts zum Anfassen“
type: application
version: 0.1.0
appVersion: "0.7.1"
kubeVersion: ">=1.33.0-0"
maintainers:
- name: Helm Lab
email: [email protected]
EOF
helm lint notes
helm show chart notesExpected:
==> Linting notes
[INFO] Chart.yaml: icon is recommended
[INFO] values.yaml: file does not exist
1 chart(s) linted, 0 chart(s) failed
apiVersion: v2
appVersion: 0.7.1
description: Notiz-API mit PostgreSQL – Übungschart aus „Helm Charts zum Anfassen“
kubeVersion: '>=1.33.0-0'
maintainers:
- email: [email protected]
name: Helm Lab
name: notes
type: application
version: 0.1.0
The description reads “notes API with PostgreSQL – practice chart from ‘Helm Charts zum Anfassen’” (the German edition of this book).
| Field | Meaning |
|---|---|
apiVersion: v2 |
Chart format of Helm 3 and 4 |
type |
application or library (Day 10) |
version |
Chart version, SemVer, goes up with every change to the chart |
kubeVersion |
Which Kubernetes versions the chart supports |
The -0 in >=1.33.0-0 also lets
pre-release versions through, as reported by managed clusters
(v1.36.4-gke.1043002). Build suffixes like
+k3s1 do no harm anyway.
Save your progress? Sign up for free
Drill 3: The first templates
Still finished YAML without placeholders. Without
NOTES_DB_URL, notes-api stores in memory – the database
comes on Day 9. Today you write the API key straight in; from Day 8 on
it comes from a Secret.
# on prod
cat > notes/templates/deployment.yaml <<'EOF'
# notes/templates/deployment.yaml – Stand Tag 02
apiVersion: apps/v1
kind: Deployment
metadata:
name: notes-api
labels: {app.kubernetes.io/name: notes-api}
spec:
replicas: 2
selector:
matchLabels: {app.kubernetes.io/name: notes-api}
template:
metadata:
labels: {app.kubernetes.io/name: notes-api}
spec:
containers:
- name: notes-api
image: ghcr.io/thomaszachmann/notes-api:0.7.1
ports: [{name: http, containerPort: 8080}]
env:
- {name: NOTES_API_KEY, value: lab-key-123}
readinessProbe:
httpGet: {path: /healthz, port: http}
EOF
cat > notes/templates/service.yaml <<'EOF'
# notes/templates/service.yaml – Stand Tag 02
apiVersion: v1
kind: Service
metadata:
name: notes-api
labels: {app.kubernetes.io/name: notes-api}
spec:
selector: {app.kubernetes.io/name: notes-api}
ports: [{name: http, port: 80, targetPort: http}]
EOF
helm template notes ./notes | grep -E '^(# Source|kind)'
helm template notes ./notes -s templates/service.yamlExpected:
# Source: notes/templates/service.yaml
kind: Service
# Source: notes/templates/deployment.yaml
kind: Deployment
---
# Source: notes/templates/service.yaml
# notes/templates/service.yaml – Stand Tag 02
apiVersion: v1
kind: Service
metadata:
name: notes-api
labels: {app.kubernetes.io/name: notes-api}
spec:
selector: {app.kubernetes.io/name: notes-api}
ports: [{name: http, port: 80, targetPort: http}]
Helm sorts by kind: the Service comes before the Deployment, no
matter what the files are called. # Source: shows which
file a document comes from. -s (--show-only)
shows just one file – your measuring instrument for the rest of the
book.
Save your progress? Sign up for free
Drill 4: Folder rules
What happens to files that do not look like a manifest?
# on prod
cat > notes/templates/_entwurf.yaml <<'EOF'
apiVersion: v1
kind: ConfigMap
metadata: {name: entwurf}
EOF
echo "Hier kommt später die Doku hin." > notes/templates/liesmich.txt
helm template notes ./notes | grep '^kind:'Expected:
Error: YAML parse error on notes/templates/liesmich.txt: error unmarshaling JSON: while
decoding JSON: json: cannot unmarshal string into Go value of type util.SimpleHead
Use --debug flag to render out invalid YAML
(entwurf means “draft”, liesmich.txt is
“readme.txt”, and its text says “the docs go here later”.) The file
extension does not matter: Helm renders every file in
templates/ and expects a Kubernetes object. The ConfigMap
in _entwurf.yaml, on the other hand, never shows up – the
underscore means “building blocks only”. Docs belong in
README.md next to Chart.yaml.
# on prod
rm notes/templates/liesmich.txt
helm template notes ./notes | grep '^kind:'
cat > notes/templates/NOTES.txt <<'EOF'
{{- /* notes/templates/NOTES.txt – Stand Tag 02 */ -}}
notes {{ .Chart.AppVersion }} ist als Release {{ .Release.Name }} installiert.
Test: kubectl -n {{ .Release.Namespace }} port-forward svc/notes-api 8080:80
EOF
cat > notes/README.md <<'EOF'
# notes
Übungschart aus „Helm Charts zum Anfassen“. Werte siehe values.yaml (ab Tag 3).
EOFExpected:
kind: Service
kind: Deployment
NOTES.txt is the only exception: it gets rendered, but
it is not sent to the cluster; it is printed after install
and upgrade. Its text says “notes
<version> is installed as release
<name>”. The README says “practice chart from …; for
values see values.yaml (from Day 3)”.
Save your progress? Sign up for free
Drill 5: .helmignore, package and release
# on prod
mkdir -p notes/entwurf && echo "alte Idee" > notes/entwurf/idee.txt
cat > notes/.helmignore <<'EOF'
# notes/.helmignore – Stand Tag 02
.git/
*.swp
*~
entwurf/
EOF
helm package notes -d ~/helm/tag02
tar -tzf ~/helm/tag02/notes-0.1.0.tgz
helm show chart ~/helm/tag02/notes-0.1.0.tgz | grep -E '^(name|version|appVersion)'Expected:
Successfully packaged chart and saved it to: /home/ubuntu/helm/tag02/notes-0.1.0.tgz
notes/Chart.yaml
notes/templates/NOTES.txt
notes/templates/_entwurf.yaml
notes/templates/deployment.yaml
notes/templates/service.yaml
notes/.helmignore
notes/README.md
appVersion: 0.7.1
name: notes
version: 0.1.0
(alte Idee / idee.txt: “old idea”.)
entwurf/ is missing from the package,
_entwurf.yaml is in it – it sits in templates/
and is not ignored, but it creates no object. The file name
notes-0.1.0.tgz comes from name and
version. Now the release that will accompany you through
the book:
# on prod
helm install notes ~/helm/tag02/notes-0.1.0.tgz -n notes --create-namespace \
--wait --timeout 3m
kubectl -n notes port-forward svc/notes-api 8080:80 >/dev/null 2>&1 &
sleep 3
curl -s localhost:8080/healthz
curl -s -X POST -H 'X-API-Key: lab-key-123' -H 'Content-Type: application/json' \
-d '{"text":"Tag 2"}' localhost:8080/notes
kill %1Expected (abridged):
NAME: notes
NAMESPACE: notes
STATUS: deployed
REVISION: 1
DESCRIPTION: Install complete
NOTES:
notes 0.7.1 ist als Release notes installiert.
Test: kubectl -n notes port-forward svc/notes-api 8080:80
ok
{"id":"a48b87ce-b86e-4d34-a50a-5ca6ffd1731b","text":"Tag 2"}
The note lives only in the memory of one of the two Pods. That changes with the database on Day 9.
Save your progress? Sign up for free
Drill 6: Versions that are not versions
YAML guesses types. What becomes of appVersion: 2.10
without quotes?
# on prod
sed -i 's/^appVersion: "0.7.1"/appVersion: 2.10/' notes/Chart.yaml
helm lint notes | grep ERROR
helm show chart notes | grep appVersion
helm package notes -d /tmp/x | tail -1
sed -i 's/^appVersion: 2.10/appVersion: "0.7.1"/' notes/Chart.yamlExpected:
[ERROR] Chart.yaml: appVersion should be of type string but it's of type float64
appVersion: "2.1"
Successfully packaged chart and saved it to: /tmp/x/notes-0.1.0.tgz
2.10 turns into the number 2.1. helm lint reports an
error, helm package packages it anyway.
version is similarly lax:
# on prod
for v in '"0.1"' 'v0.1.0' 'eins' '1.0.0+build.7'; do
sed -i "s/^version: .*/version: $v/" notes/Chart.yaml
echo "== $v"; helm package notes -d /tmp/x 2>&1 | tail -1
done
sed -i 's/^version: .*/version: 0.1.0/' notes/Chart.yaml
rm -rf /tmp/xExpected:
== "0.1"
Successfully packaged chart and saved it to: /tmp/x/notes-0.1.tgz
== v0.1.0
Successfully packaged chart and saved it to: /tmp/x/notes-v0.1.0.tgz
== eins
Error: validation: chart.metadata.version "eins" is invalid
== 1.0.0+build.7
Successfully packaged chart and saved it to: /tmp/x/notes-1.0.0+build.7.tgz
Only complete nonsense (eins is German for “one”) fails.
"0.1" only gives a warning in helm lint
(not a valid SemVerV2), v0.1.0 not even that.
Stick to MAJOR.MINOR.PATCH anyway: patch for bug fixes,
minor for new options, major when users have to adjust their values. You
will meet the +build suffix again on Day 15.
Save your progress? Sign up for free
Drill 7: Chart v3 – just a glance
Helm 4 ships an experimental chart format
apiVersion: v3.
# on prod
cd ~/helm/tag02
helm create v3demo --chart-api-version v3
HELM_EXPERIMENTAL_CHART_V3=1 helm create v3demo --chart-api-version v3
grep '^apiVersion' v3demo/Chart.yaml
HELM_EXPERIMENTAL_CHART_V3=1 helm template x ./v3demo
rm -rf v3demo
cd ~/helm/chartsExpected:
Creating v3demo
Error: this feature has been marked as experimental and is not enabled by default.
Please set HELM_EXPERIMENTAL_CHART_V3=1 in your environment to use this feature
Creating v3demo
apiVersion: v3
Error: invalid chart apiVersion
In Helm 4.3.2 a v3 chart can only be created, not rendered or
installed – not even with the variable set. For everything in this book
and in practice, use apiVersion: v2; existing charts run
unchanged under Helm 4.
Save your progress? Sign up for free
Exercise: Speed Drills
- Show which files are in the package
notes-0.1.0.tgz. Target time: 10 s - Show the chart and app version of the installed release. Target time: 20 s
- Render only the Deployment. Target time: 15 s
- Show the release’s NOTES again. Target time: 10 s
Solution
# on prod
tar -tzf ~/helm/tag02/notes-0.1.0.tgz
helm get metadata notes -n notes | grep -E '^(VERSION|APP_VERSION)'
helm template notes ./notes -s templates/deployment.yaml
helm get notes notes -n notesExpected (abridged):
notes/Chart.yaml
...
VERSION: 0.1.0
APP_VERSION: 0.7.1
# Source: notes/templates/deployment.yaml
...
NOTES:
notes 0.7.1 ist als Release notes installiert.
Save your progress? Sign up for free
Checkpoint
# on prod
helm list -n notesExpected:
NAME NAMESPACE REVISION UPDATED STATUS CHART APP VERSION
notes notes 1 ... deployed notes-0.1.0 0.7.1
# on prod
kubectl -n notes get deploy notes-apiExpected: READY 2/2.
# on prod
helm lint notes | tail -1Expected:
1 chart(s) linted, 0 chart(s) failed
Challenge
What happens when kubeVersion excludes your cluster? Set
>=1.38.0-0 and try helm lint,
helm template and an upgrade with
--dry-run=server. Get helm template to render
anyway.
Hint: helm template does not know your
cluster and assumes a built-in Kubernetes version.
Solution
# on prod
sed -i 's/^kubeVersion: .*/kubeVersion: ">=1.38.0-0"/' notes/Chart.yaml
helm lint notes | tail -1
helm template notes ./notes > /dev/null
helm upgrade notes ./notes -n notes --dry-run=server 2>&1 | head -1
helm template notes ./notes --kube-version 1.38.0 | grep -c '^kind:'
sed -i 's/^kubeVersion: .*/kubeVersion: ">=1.33.0-0"/' notes/Chart.yamlExpected:
1 chart(s) linted, 0 chart(s) failed
Error: chart requires kubeVersion: >=1.38.0-0 which is incompatible with Kubernetes
v1.37.0
Error: UPGRADE FAILED: chart requires kubeVersion: >=1.38.0-0 which is incompatible
with Kubernetes v1.37.2+k3s1
2
helm lint does not check kubeVersion.
Without a cluster, helm template assumes v1.37.0 – the
version Helm 4.3 was built with. With --kube-version you
set it yourself. The upgrade asks the real cluster. Day 4 goes deeper
into CI and cluster seeing different versions.
Save your progress? Sign up for free
Cleanup
The draft and the experiments go, the current state goes into the git repo.
# on prod
cd ~/helm/charts
rm -r notes/templates/_entwurf.yaml notes/entwurf
git add notes
git commit -qm "Tag 02: notes 0.1.0 ohne Templates"
git log --onelineExpected:
beabaab Tag 02: notes 0.1.0 ohne Templates
eeb85c7 Tag 00: leeres Chart-Repo
(The commit message means “Day 02: notes 0.1.0 without templates” –
that is, the manifests have no placeholders yet. NOTES.txt
already uses .Chart and .Release.)
Interview Note
- What is the underscore in
_helpers.tplfor? Files starting with_produce no manifest; they only hold named templates. All other files intemplates/get rendered and must result in Kubernetes objects. - When do you bump which part of the chart version? At least patch for every change to the chart, minor for new options, major when users have to adjust something.
- version or appVersion?
versionbelongs to the chart and determines the package;appVersiondescribes the app and often serves as the default image tag.
Enterprise Note
- Make
helm linta mandatory step in CI –helm packagealone lets errors likeappVersion: 2.10through. - A published chart version is immutable. Every change, even to the
README, gets a new version (Day 18 checks this with
ct lint). - Maintain
kubeVersionhonestly: it is the only barrier that protects users from a chart for a Kubernetes version that is too old or too new. - Provide your own skeletons via
helm create --starterinstead of letting every team start from the nginx example.