Skip to content
Hands-on IT IT Drills

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 only define blocks. 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 .Values and .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 -1

Expected:

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/tag10

Expected:

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=restricted

Expected:

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

Expected (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; echo

Expected (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/charts

Expected:

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

  1. Which chart type is plattform? Target time: 15 s
  2. Which plattform version is in helper, which in notes? Target time: 20 s
  3. Make helper return status code 418. Target time: 30 s
  4. 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 notes

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

Expected: Error: INSTALLATION FAILED: library charts are not installable

# on prod
kubectl -n notes get pods

Expected: 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 1

Expected:

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 tag10

Expected:

release "web" uninstalled
namespace "tag10" deleted

Interview Note

  • What is a library chart? A chart with type: library that contains only named templates. It cannot be installed and creates objects only through include in 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 a helm template diff.

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.