Skip to content
Hands-on IT IT Drills

Day 2: Your Own Chart – Structure and Chart.yaml

Goal: Create the chart notes by hand, package it and install it as the release notes – 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.txt is shown after the installation.
  • version is the SemVer version of the chart, appVersion that of the app. They are independent.
  • Today still without values: the manifests are finished YAML; only NOTES.txt already uses the built-in objects .Chart and .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 demo

Save 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 notes

Expected:

==> 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.yaml

Expected:

# 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).
EOF

Expected:

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 %1

Expected (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.yaml

Expected:

[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/x

Expected:

== "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/charts

Expected:

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

  1. Show which files are in the package notes-0.1.0.tgz. Target time: 10 s
  2. Show the chart and app version of the installed release. Target time: 20 s
  3. Render only the Deployment. Target time: 15 s
  4. 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 notes

Expected (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 notes

Expected:

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-api

Expected: READY 2/2.

# on prod
helm lint notes | tail -1

Expected: 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.yaml

Expected:

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 --oneline

Expected:

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.tpl for? Files starting with _ produce no manifest; they only hold named templates. All other files in templates/ 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? version belongs to the chart and determines the package; appVersion describes the app and often serves as the default image tag.

Enterprise Note

  • Make helm lint a mandatory step in CI – helm package alone lets errors like appVersion: 2.10 through.
  • A published chart version is immutable. Every change, even to the README, gets a new version (Day 18 checks this with ct lint).
  • Maintain kubeVersion honestly: 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 --starter instead of letting every team start from the nginx example.