Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 38 ยท Dependencies and Hooks

Library Charts and Shared Templates

Build a Helm library chart with type: library, share named templates and helpers, avoid name collisions, and call them with include, with a runnable template-sharing stand-in.

If you maintain ten microservices, you will write the same Deployment, labels block and probe settings ten times. Copy-paste works until someone fixes a bug in one copy. A library chart is Helm's answer: a chart that installs nothing by itself and only provides named templates that other charts call.

What makes a chart a library

Set type: library in Chart.yaml:

YAML
apiVersion: v2
name: svc-lib
description: Shared templates for our microservices
type: library
version: 1.4.0

A library chart differs from the default type: application in two ways: you cannot helm install it, and Helm does not render any file in its templates/ that does not start with an underscore. Everything useful is a named template declared with define, normally stored in files like _labels.tpl and _deployment.tpl. The leading underscore tells Helm "this file produces no manifest on its own".

Writing shared helpers

Named templates use define and are called with include. Prefix every name with the chart name, because named templates are global to the whole release:

YAML
{{/* templates/_labels.tpl */}}
{{- define "svc-lib.labels" -}}
app.kubernetes.io/name: {{ .Chart.Name }}
app.kubernetes.io/instance: {{ .Release.Name }}
app.kubernetes.io/managed-by: {{ .Release.Service }}
{{- end -}}

{{- define "svc-lib.fullname" -}}
{{- printf "%s-%s" .Release.Name .Chart.Name | trunc 63 | trimSuffix "-" -}}
{{- end -}}

A whole resource can be a template too. The library below produces a Service from a few values:

YAML
{{/* templates/_service.tpl */}}
{{- define "svc-lib.service" -}}
apiVersion: v1
kind: Service
metadata:
  name: {{ include "svc-lib.fullname" . }}
  labels:
    {{- include "svc-lib.labels" . | nindent 4 }}
spec:
  type: {{ .Values.service.type | default "ClusterIP" }}
  ports:
    - port: {{ .Values.service.port | default 80 }}
      targetPort: http
  selector:
    app.kubernetes.io/instance: {{ .Release.Name }}
{{- end -}}

Using the library in an application chart

An application declares the library as a normal dependency, then runs helm dependency update:

YAML
# Chart.yaml of the application
dependencies:
  - name: svc-lib
    version: "~1.4.0"
    repository: "file://../svc-lib"

Its own templates shrink to one-liners:

YAML
# templates/service.yaml
{{ include "svc-lib.service" . }}

The . you pass is the context. Because the library template reads .Chart.Name and .Values.service, it sees the application's chart name and values, not its own. That is why library helpers feel like functions that take the whole chart as an argument.

Each application keeps only what is special about it: its values.yaml, an extra ConfigMap, a custom probe. A fix to svc-lib ships to every service on the next dependency bump.

Passing a custom context

Sometimes you want a helper to take explicit arguments instead of the root context. Build a dictionary with dict and pass it:

YAML
{{- define "svc-lib.envvars" -}}
{{- range $name, $value := .vars }}
- name: {{ $name }}
  value: {{ $value | quote }}
{{- end }}
{{- end -}}
YAML
env:
  {{- include "svc-lib.envvars" (dict "vars" .Values.env "root" .) | nindent 2 }}

Inside the helper, .vars is the map and .root is the original top-level context when you need .Release or .Chart.

A stand-in for define and include

Helm's engine is Go's text/template, which the site cannot run. The stand-in below keeps the idea honest with Python: a registry of named templates, an include function that renders one with a context, and a naive {{ path }} substitution. It is a teaching model, not Helm.

Python Stand-in: named templates shared by two charts

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The same library renders different output for each application, because the context differs. (Real Helm indents the included labels with nindent; the stand-in skips that detail.)

Versioning a library

A library is an API. Treat it like one:

  • Use semantic versioning: renaming or removing a named template is a major bump.
  • Keep helper names stable and document the values each helper reads.
  • Applications should depend with ~ ranges so a minor library bump cannot surprise them.
  • Add unit tests to the library's own repository (see Helm unit tests), using a small example application chart as the fixture.

Common mistakes

  1. Unprefixed names. define "labels" in two charts overwrites silently. Always use chartname.helper.
  2. Forgetting underscores. A library file without _ and without define tries to render and fails.
  3. Relying on library defaults for values. The library cannot ship a values.yaml that applies; document values in a README and use default in the template.
  4. Calling include with the wrong context. Passing .Values instead of . makes .Release disappear.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does type: library in Chart.yaml do?

    Library charts expose helpers through define and cannot be installed on their own.
  2. 2. Why should named templates be prefixed with the chart name?

    Templates from the parent and all subcharts live in one namespace.
  3. 3. What is passed as the dot (.) when an application calls include "svc-lib.service" .

    The helper renders against whatever context you pass, normally the root context of the calling chart.
  4. 4. Why do library template files start with an underscore?

    Files beginning with _ are skipped as manifests and used for helpers.

Summary

  • A library chart (type: library) ships named templates, not manifests.
  • Applications depend on it, call helpers with include, and pass the context they want rendered.
  • Prefix names, version the library like an API, and keep helper inputs documented.

Next: Helm Hooks