Day 10: Library Charts
Goal: Move shared building blocks into a library chart
plattform, build a second service on it in 20 lines and evolve the library with proper versions. · Duration: approx. 60 min · Prerequisite: Day 9
Briefing
- A library chart (
type: library) contains onlydefineblocks. It creates no objects itself and cannot be installed. - An application chart includes it as a dependency and calls the
blocks with
include– in its own context, so with its own.Valuesand.Chart. - A change to the library hits every user on their next
dependency update. So version strictly by SemVer and move users over one at a time.
plattform (library) helper (20 lines) notes
├─ plattform.labels <──────── include ───────────────── include (Labels)
├─ plattform.*SecurityContext ──────── include (restricted)
├─ plattform.deployment <────── include
└─ plattform.service <────── include
Drill 1: The library chart plattform
# on prod
mkdir -p ~/helm/tag10 && cd ~/helm/charts
mkdir -p plattform/templates
cat > plattform/Chart.yaml <<'EOF'
# plattform/Chart.yaml – Stand Tag 10
apiVersion: v2
name: plattform
description: Gemeinsame Bausteine für alle Charts der Plattform
type: library
version: 0.1.0
EOF
cat > plattform/templates/_namen.tpl <<'EOF'
{{/* plattform/templates/_namen.tpl – Stand Tag 10 */}}
{{- define "plattform.name" -}}
{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
{{- end }}
{{- define "plattform.fullname" -}}
{{- if .Values.fullnameOverride }}
{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
{{- else if contains (include "plattform.name" .) .Release.Name }}
{{- .Release.Name | trunc 63 | trimSuffix "-" }}
{{- else }}
{{- printf "%s-%s" .Release.Name (include "plattform.name" .) | trunc 63
| trimSuffix "-" }}
{{- end }}
{{- end }}
{{- define "plattform.selectorLabels" -}}
app.kubernetes.io/name: {{ include "plattform.name" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
{{- end }}
{{- define "plattform.labels" -}}
{{ include "plattform.selectorLabels" . }}
app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
app.kubernetes.io/managed-by: {{ .Release.Service }}
helm.sh/chart: {{ printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" }}
{{- with .Values.team }}
team: {{ . | quote }}
{{- end }}
{{- end }}
EOF
cat > plattform/templates/_sicherheit.tpl <<'EOF'
{{/* plattform/templates/_sicherheit.tpl – Stand Tag 10 */}}
{{/* Pod Security Standard "restricted" */}}
{{- define "plattform.podSecurityContext" -}}
runAsNonRoot: true
seccompProfile:
type: RuntimeDefault
{{- end }}
{{- define "plattform.containerSecurityContext" -}}
allowPrivilegeEscalation: false
readOnlyRootFilesystem: true
capabilities:
drop: [ALL]
{{- end }}
EOF
cat > plattform/templates/_deployment.tpl <<'EOF'
{{/* plattform/templates/_deployment.tpl – Stand Tag 10 */}}
{{- define "plattform.deployment" -}}
apiVersion: apps/v1
kind: Deployment
metadata:
name: {{ include "plattform.fullname" . }}
labels:
{{- include "plattform.labels" . | nindent 4 }}
spec:
replicas: {{ .Values.replicaCount | default 1 }}
selector:
matchLabels:
{{- include "plattform.selectorLabels" . | nindent 6 }}
template:
metadata:
labels:
{{- include "plattform.labels" . | nindent 8 }}
spec:
securityContext:
{{- include "plattform.podSecurityContext" . | nindent 8 }}
containers:
- name: {{ .Chart.Name }}
image: "{{ .Values.image.repository }}:{{ .Values.image.tag
| default .Chart.AppVersion }}"
ports: [{name: http, containerPort: {{ .Values.port | default 8080 }}}]
securityContext:
{{- include "plattform.containerSecurityContext" . | nindent 12 }}
{{- with .Values.probePath }}
readinessProbe:
httpGet: {path: {{ . }}, port: http}
{{- end }}
resources:
{{- toYaml .Values.resources | nindent 12 }}
{{- end }}
EOF
cat > plattform/templates/_service.tpl <<'EOF'
{{/* plattform/templates/_service.tpl – Stand Tag 10 */}}
{{- define "plattform.service" -}}
apiVersion: v1
kind: Service
metadata:
name: {{ include "plattform.fullname" . }}
labels:
{{- include "plattform.labels" . | nindent 4 }}
spec:
selector:
{{- include "plattform.selectorLabels" . | nindent 4 }}
ports:
- name: http
port: 80
targetPort: http
{{- end }}
EOF
helm lint plattform | tail -1Expected:
1 chart(s) linted, 0 chart(s) failed
All files start with _: they contain only definitions.
The blocks use .Values and .Chart – which
values those are is decided only by the chart that calls them.
Save your progress? Sign up for free
Drill 2: Not installable
# on prod
helm template x ./plattform
helm install plattform ./plattform -n tag10 --create-namespace
kubectl get namespace tag10
helm package plattform -d ~/helm/tag10Expected:
Error: library charts are not installable
Error: INSTALLATION FAILED: library charts are not installable
Error from server (NotFound): namespaces "tag10" not found
Successfully packaged chart and saved it to: /home/ubuntu/helm/tag10/plattform-0.1.0.tgz
Even helm template refuses. Helm aborts so early that
--create-namespace does not create anything either.
Packaging and publishing, on the other hand, work – that is exactly what
a library is for.
Save your progress? Sign up for free
Drill 3: helper in 20 lines
# on prod
mkdir -p helper/templates
cat > helper/Chart.yaml <<'EOF'
# helper/Chart.yaml – Stand Tag 10
apiVersion: v2
name: helper
description: HTTP-Testdienst (go-httpbin) auf Basis von plattform
version: 0.1.0
appVersion: "2.26.0"
dependencies:
- name: plattform
version: "~0.1.0"
repository: file://../plattform
EOF
cat > helper/values.yaml <<'EOF'
# helper/values.yaml – Stand Tag 10
image:
repository: ghcr.io/mccutchen/go-httpbin
port: 8080
probePath: /status/200
resources:
requests: {cpu: 10m, memory: 16Mi}
limits: {memory: 64Mi}
EOF
echo '{{ include "plattform.deployment" . }}' > helper/templates/deployment.yaml
echo '{{ include "plattform.service" . }}' > helper/templates/service.yaml
cat helper/Chart.yaml helper/values.yaml helper/templates/* | wc -l
helm dependency update helper | tail -1
helm template helper ./helper -s templates/deployment.yaml \
| sed -n '/securityContext/,/readinessProbe/p'Expected:
20
Deleting outdated charts
securityContext:
runAsNonRoot: true
seccompProfile:
type: RuntimeDefault
containers:
- name: helper
image: "ghcr.io/mccutchen/go-httpbin:2.26.0"
ports: [{name: http, containerPort: 8080}]
securityContext:
allowPrivilegeEscalation: false
readOnlyRootFilesystem: true
capabilities:
drop: [ALL]
readinessProbe:
The container is called helper and the image has the tag
2.26.0, because .Chart inside the block is the
calling chart, not plattform. The block has one weakness:
replicaCount | default 1 turns a deliberately set 0 back
into 1 – the trap from Day 5. For helper that is fine; a
library for many teams checks with hasKey.
Save your progress? Sign up for free
Drill 4: Roll out helper and check restricted
# on prod
helm install helper ./helper -n notes --wait | grep STATUS
IP=$(kubectl -n notes get svc helper -o jsonpath='{.spec.clusterIP}')
curl -s $IP/get | jq -c '{url}'
kubectl label --dry-run=server --overwrite ns notes \
pod-security.kubernetes.io/enforce=restrictedExpected:
STATUS: deployed
{"url":"http://10.43.234.156/get"}
namespace/notes labeled (server dry run)
Warning: existing pods in namespace "notes" violate the new PodSecurity enforce level
"restricted:latest"
Warning: notes-57d48b9df5-fbdxz (and 2 other pods): allowPrivilegeEscalation != false,
unrestricted capabilities, runAsNonRoot != true, seccompProfile
On the k3s node you can reach ClusterIPs directly. The dry run with
--dry-run=server does not set the label, but it names every
Pod that would violate “restricted”: the two notes Pods and Postgres –
not helper.
Save your progress? Sign up for free
Drill 5: Switch notes to the library
First record the current state, then switch over and compare:
# on prod
helm template notes ./notes -f values/prod.yaml > ~/helm/tag10/vorher.yaml
cat >> notes/Chart.yaml <<'EOF'
- name: plattform
version: "~0.1.0"
repository: file://../plattform
EOF
sed -i 's/^version: .*/version: 0.9.0/; s/Tag 09/Tag 10/' notes/Chart.yaml
jq '.title = "notes – Stand Tag 10" | .properties.plattform = {"type": "object"}' \
notes/values.schema.json > /tmp/s.json && mv /tmp/s.json notes/values.schema.json
cat > notes/templates/_helpers.tpl <<'EOF'
{{/* notes/templates/_helpers.tpl – Stand Tag 10 */}}
{{/* Namen und Labels kommen jetzt aus dem Library Chart plattform */}}
{{- define "notes.name" -}}{{ include "plattform.name" . }}{{- end }}
{{- define "notes.fullname" -}}{{ include "plattform.fullname" . }}{{- end }}
{{- define "notes.selectorLabels" -}}
{{ include "plattform.selectorLabels" . }}{{- end }}
{{- define "notes.labels" -}}{{ include "plattform.labels" . }}{{- end }}
{{/* Image: Tag leer = appVersion aus Chart.yaml */}}
{{- define "notes.image" -}}
{{- $repo := required "image.repository fehlt" .Values.image.repository }}
{{- printf "%s:%s" $repo (.Values.image.tag | default .Chart.AppVersion) }}
{{- end }}
{{/* DB-Umgebung für Init-Container und notes-api; leer = Speicherbetrieb */}}
{{- define "notes.dbEnv" -}}
{{- $db := .Values.database }}
{{- $secret := coalesce $db.existingSecret .Values.global.dbSecret }}
{{- if $secret }}
{{- $host := $db.host }}
{{- if and (not $host) .Values.postgres.enabled }}
{{- $host = printf "%s-postgres" .Release.Name }}
{{- end }}
- name: NOTES_DB_PASSWORD
valueFrom:
secretKeyRef:
name: {{ $secret }}
key: {{ $db.passwordKey }}
- name: NOTES_DB_URL
value: {{ printf "postgres://%s:$(NOTES_DB_PASSWORD)@%s:%v/%s?%s" $db.user
(required "database.host fehlt" $host) $db.port $db.name "sslmode=disable"
| quote }}
{{- end }}
{{- end }}
EOF
cat > notes/templates/deployment.yaml <<'EOF'
{{/* notes/templates/deployment.yaml – Stand Tag 10 */}}
{{- $dbEnv := include "notes.dbEnv" . }}
apiVersion: apps/v1
kind: Deployment
metadata:
name: {{ include "notes.fullname" . }}
labels:
{{- include "notes.labels" . | nindent 4 }}
spec:
replicas: {{ hasKey .Values "replicaCount" | ternary .Values.replicaCount 2 }}
selector:
matchLabels:
{{- include "notes.selectorLabels" . | nindent 6 }}
template:
metadata:
labels:
{{- include "notes.labels" . | nindent 8 }}
annotations:
checksum/config: {{ include (print $.Template.BasePath "/config.yaml") .
| sha256sum }}
spec:
terminationGracePeriodSeconds: {{ durationSeconds .Values.shutdownTimeout }}
securityContext:
{{- include "plattform.podSecurityContext" . | nindent 8 }}
{{- if $dbEnv }}
initContainers:
- name: migrate
image: {{ include "notes.image" . | quote }}
args: ["migrate"]
securityContext:
{{- include "plattform.containerSecurityContext" . | nindent 12 }}
env:
{{- $dbEnv | nindent 12 }}
{{- end }}
containers:
- name: notes-api
image: {{ include "notes.image" . | quote }}
ports: [{name: http, containerPort: 8080}]
securityContext:
{{- include "plattform.containerSecurityContext" . | nindent 12 }}
env:
- name: NOTES_API_KEY
valueFrom:
secretKeyRef:
name: {{ required "apiKey.existingSecret fehlt"
.Values.apiKey.existingSecret }}
key: {{ .Values.apiKey.key }}
{{- with $dbEnv }}
{{- . | nindent 12 }}
{{- end }}
envFrom:
- configMapRef:
name: {{ include "notes.fullname" . }}-config
readinessProbe:
httpGet: {path: /healthz, port: http}
resources:
{{- toYaml .Values.resources | nindent 12 }}
{{- with .Values.nodeSelector }}
nodeSelector:
{{- toYaml . | nindent 8 }}
{{- end }}
EOF
helm dependency update notes | tail -1
helm template notes ./notes -f values/prod.yaml > ~/helm/tag10/nachher.yaml
diff ~/helm/tag10/vorher.yaml ~/helm/tag10/nachher.yaml | grep '^[<>]' | sort | uniq -cExpected (abridged):
Deleting outdated charts
1 < checksum/config: 4adc2ea403fb3f11d24bcb7e4537bb3054d4542f79565f4834…
1 < helm.sh/chart: notes-0.8.0
6 < helm.sh/chart: notes-0.8.0
1 < chart: "notes-0.8.0"
2 > drop: [ALL]
2 > allowPrivilegeEscalation: false
2 > capabilities:
2 > readOnlyRootFilesystem: true
2 > securityContext:
1 > type: RuntimeDefault
1 > checksum/config: 14a13835155b7e9bbe47d63eff93afc4c13f60c257b6c7f9fb…
1 > helm.sh/chart: notes-0.9.0
1 > runAsNonRoot: true
1 > seccompProfile:
1 > securityContext:
6 > helm.sh/chart: notes-0.9.0
1 > chart: "notes-0.9.0"
The new _helpers.tpl says in its German comments that
names and labels now come from the library chart plattform.
Names and selectors are identical; only the SecurityContexts are new.
Two things stand out: helm.sh/chart changes with every
chart version, and because the label is also in
config.yaml, the checksum from Day 7 changes – every new
chart version restarts the Pods, even without a configuration change.
Here that is intended (new SecurityContexts), but good to know.
# on prod
helm upgrade notes ./notes -n notes -f values/prod.yaml --wait | grep REVISION
sleep 20
kubectl label --dry-run=server --overwrite ns notes \
pod-security.kubernetes.io/enforce=restricted
curl -s -H 'Host: api.notes.lab' localhost/notes; echoExpected (ID abridged):
REVISION: 21
Warning: existing pods in namespace "notes" violate the new PodSecurity enforce level
"restricted:latest"
Warning: notes-postgres-0: allowPrivilegeEscalation != false, unrestricted capabilities,
runAsNonRoot != true, seccompProfile
namespace/notes labeled (server dry run)
[{"id":"e725da85-…","text":"in Postgres"}]
Only Postgres still violates “restricted” – the official image starts
as root and then switches user. notes-api runs fine with a read-only
filesystem, too. The sleep gives the old Pods time to
disappear: --wait waits for the new ones, not for the old
ones to finish.
Save your progress? Sign up for free
Drill 6: Versioning the library
plattform gets an additional label and becomes 0.2.0.
Only helper follows.
# on prod
git add -A
git commit -qm "Tag 10: Library Chart plattform 0.1.0, helper, notes 0.9.0"
sed -i 's/^version: 0.1.0/version: 0.2.0/; s/Tag 10/Tag 10 (0.2.0)/' \
plattform/Chart.yaml
L='app.kubernetes.io/part-of: plattform'
sed -i "/^app.kubernetes.io\/managed-by/a $L" plattform/templates/_namen.tpl
sed -i 's/version: "~0.1.0"/version: "~0.2.0"/; s/^version: 0.1.0/version: 0.2.0/' \
helper/Chart.yaml
helm dependency update helper | tail -1
helm upgrade helper ./helper -n notes --wait | grep REVISION
kubectl -n notes get deploy helper \
-o jsonpath='{.metadata.labels.app\.kubernetes\.io/part-of}{"\n"}'
helm dependency update notes 2>&1 | tail -1
ls helper/charts notes/chartsExpected:
Deleting outdated charts
REVISION: 2
plattform
Error: can't get a valid version for 1 subchart(s): "plattform" (repository
"file://../plattform", version "~0.1.0"). Make sure a matching chart version exists
in the repo, or change the version constraint in Chart.yaml
helper/charts:
plattform-0.2.0.tgz
notes/charts:
plattform-0.1.0.tgz
postgres-0.1.0.tgz
helper carries the new label, notes stays
on 0.1.0 – but only because the old .tgz is still in
notes/charts/. A file:// repo only knows the
version that is currently in the folder; your Git ignores
.tgz files. A fresh clone could no longer build
notes. Real versioning needs a repository with all versions
– from Day 15 on, the OCI registry.
# on prod
git add -A && git commit -qm "Tag 10: plattform 0.2.0, helper 0.2.0 zieht nach"Save your progress? Sign up for free
Exercise: Speed Drills
- Which chart type is
plattform? Target time: 15 s - Which plattform version is in
helper, which innotes? Target time: 20 s - Make
helperreturn status code 418. Target time: 30 s - Show the Pod SecurityContext of the running Deployment
notes. Target time: 20 s
Solution
# on prod
cd ~/helm/charts
yq .type plattform/Chart.yaml
ls helper/charts notes/charts
IP=$(kubectl -n notes get svc helper -o jsonpath='{.spec.clusterIP}')
curl -s -o /dev/null -w '%{http_code}\n' $IP/status/418
kubectl -n notes get deploy notes -o jsonpath='{.spec.template.spec.securityContext}'Expected:
library
helper/charts:
plattform-0.2.0.tgz
notes/charts:
plattform-0.1.0.tgz
postgres-0.1.0.tgz
418
{"runAsNonRoot":true,"seccompProfile":{"type":"RuntimeDefault"}}
Save your progress? Sign up for free
Checkpoint
# on prod
helm list -n notesExpected: helper revision 2
(helper-0.2.0) and notes revision 21
(notes-0.9.0), both deployed.
# on prod
helm install x ~/helm/charts/plattform -n notesExpected:
Error: INSTALLATION FAILED: library charts are not installable
# on prod
kubectl -n notes get podsExpected: helper, two
notes Pods and notes-postgres-0, all
1/1 Running.
Challenge
In tag10, build a chart web with
nginxinc/nginx-unprivileged:1.31.7-alpine on top of
plattform and install it in a namespace that enforces
“restricted”. The Pod will crash. Find the reason and fix it in a copy
of the library (0.3.0).
Hint: readOnlyRootFilesystem – nginx
wants to write to /tmp.
Solution
# on prod
cd ~/helm/tag10 && mkdir -p web/templates
cat > web/Chart.yaml <<'EOF'
apiVersion: v2
name: web
version: 0.1.0
appVersion: "1.31.7-alpine"
dependencies:
- name: plattform
version: "~0.2.0"
repository: file://../../charts/plattform
EOF
cat > web/values.yaml <<'EOF'
image:
repository: docker.io/nginxinc/nginx-unprivileged
probePath: /
resources:
limits: {memory: 32Mi}
EOF
echo '{{ include "plattform.deployment" . }}' > web/templates/deployment.yaml
helm dependency update web | tail -1
kubectl create namespace tag10
kubectl label ns tag10 pod-security.kubernetes.io/enforce=restricted
helm install web ./web -n tag10 --wait --timeout 40s
kubectl -n tag10 logs deploy/web --tail 1Expected:
Deleting outdated charts
namespace/tag10 created
namespace/tag10 labeled
Error: INSTALLATION FAILED: resource Deployment/tag10/web not ready. status: InProgress,
message: Available: 0/1
context deadline exceeded
nginx: [emerg] mkdir() "/tmp/proxy_temp" failed (30: Read-only file system)
The library gets a switch tmpDir that mounts an
emptyDir at /tmp:
# on prod
cp -r ~/helm/charts/plattform .
sed -i 's/^version: 0.2.0/version: 0.3.0/' plattform/Chart.yaml
cat > plattform/templates/_deployment.tpl <<'EOF'
{{/* plattform/templates/_deployment.tpl – Stand Tag 10 (0.3.0, Challenge) */}}
{{- define "plattform.deployment" -}}
apiVersion: apps/v1
kind: Deployment
metadata:
name: {{ include "plattform.fullname" . }}
labels:
{{- include "plattform.labels" . | nindent 4 }}
spec:
replicas: {{ .Values.replicaCount | default 1 }}
selector:
matchLabels:
{{- include "plattform.selectorLabels" . | nindent 6 }}
template:
metadata:
labels:
{{- include "plattform.labels" . | nindent 8 }}
spec:
securityContext:
{{- include "plattform.podSecurityContext" . | nindent 8 }}
containers:
- name: {{ .Chart.Name }}
image: "{{ .Values.image.repository }}:{{ .Values.image.tag
| default .Chart.AppVersion }}"
ports: [{name: http, containerPort: {{ .Values.port | default 8080 }}}]
securityContext:
{{- include "plattform.containerSecurityContext" . | nindent 12 }}
{{- with .Values.probePath }}
readinessProbe:
httpGet: {path: {{ . }}, port: http}
{{- end }}
resources:
{{- toYaml .Values.resources | nindent 12 }}
{{- if .Values.tmpDir }}
volumeMounts:
- {name: tmp, mountPath: /tmp}
{{- end }}
{{- if .Values.tmpDir }}
volumes:
- {name: tmp, emptyDir: {sizeLimit: 64Mi}}
{{- end }}
{{- end }}
EOF
sed -i 's|"~0.2.0"|"~0.3.0"|; s|file://../../charts/plattform|file://../plattform|' \
web/Chart.yaml
echo 'tmpDir: true' >> web/values.yaml
helm dependency update web | tail -1
helm upgrade web ./web -n tag10 --wait --timeout 60s | grep REVISION
kubectl -n tag10 exec deploy/web -- wget -qO- 127.0.0.1:8080 \
| grep -o '<title>.*</title>'Expected:
Deleting outdated charts
REVISION: 2
<title>Welcome to nginx!</title>
The Pod now runs under “restricted” with a read-only root filesystem;
only /tmp is writable. With localhost instead
of 127.0.0.1, wget reported
Connection refused in the lab – when in doubt, use the IPv4
address.
Save your progress? Sign up for free
Cleanup
# on prod
helm uninstall web -n tag10
kubectl delete namespace tag10Expected:
release "web" uninstalled
namespace "tag10" deleted
Interview Note
- What is a library chart? A chart with
type: librarythat contains only named templates. It cannot be installed and creates objects only throughincludein the chart that uses it. - When is it worth it? When many charts share the same patterns – labels, SecurityContexts, Deployments. For two charts the effort rarely pays off.
- How do you roll out a change to the library? Publish a new
SemVer version, move users over one at a time via version range and
Chart.lock, and check beforehand with ahelm templatediff.
Enterprise Note
- Platform teams ship library and policies together: the library produces “restricted”-compliant Pods, Pod Security Admission or Kyverno enforce it.
- Every new library version changes the rendered manifests of many teams. An automatic diff of all user charts in CI catches surprises.
- Libraries live in a registry with immutable versions (Day 15);
file://is only good for local development. - Too much logic in the library makes charts unreadable. What has proven itself: labels, names, SecurityContexts and simple standard objects – special cases stay in the chart.