Helm Library Charts: Reusable Templates for Microservice Deployments

Problem: Repeating Boilerplate Across Microservices

In a typical Kubernetes‑centric microservice architecture, each service ships its own Helm chart. Every chart contains the same set of labels, probes, security contexts, and monitoring resources. This duplication inflates the codebase, increases the chance of drift, and makes onboarding new services slower.

Thesis: Use Helm Library Charts to Share Templates Without Creating Releases

Helm 3 introduced library charts (type: library in Chart.yaml). They bundle reusable templates and helpers but never produce Kubernetes objects on their own. By declaring a library chart as a dependency, application teams can import templates into their own charts, keeping the "DRY" principle intact while still generating a single release per service.

How Library Charts Work

• Definition: A library chart contains only templates in templates/ and optional values.yaml for documentation. It cannot have crds/, hooks/, or any resource files.
• Dependency Declaration: In the consumer chart’s Chart.yaml, add a dependency entry:

  dependencies:
    - name: mylib
      version: 1.2.3
      repository: file://../mylib
  

  This pulls the library into charts/mylib-1.2.3.tgz during helm dependency update.
• Template Import: Inside a consumer template, call a library helper:

  {{ include "mylib.labels" . | indent 8 }}

  The library’s templates/_helpers.tpl defines mylib.labels and receives the consumer’s context (.Values, .Release, etc.).
• OCI Support: From Helm 3.7+, library charts can be stored in OCI registries. Push with helm chart save <name> oci://registry.example.com/mylib:v1.0.0 and pull in the consumer with the same OCI URL.

Concrete Example: Shared Label Template

1. Create a library chart:

   helm create mylib
   # Edit Chart.yaml
   # type: library
   # Add a helper
   mkdir -p mylib/templates
   cat > mylib/templates/_helpers.tpl <<'EOF'
   {{/*  Shared labels  */}}
   {{- define "mylib.labels" -}}
   {{- $labels := dict "app.kubernetes.io/name" .Chart.Name "app.kubernetes.io/instance" .Release.Name -}}
   {{- if .Values.global.labels }}
   {{- $labels = merge $labels .Values.global.labels -}}
   {{- end -}}
   {{- $labels | toYaml -}}
   {{- end -}}
   EOF
   

2. Create a consumer chart:

   helm create mysvc
   # Edit Chart.yaml
   # Add dependency
   cat >> mysvc/Chart.yaml <<'EOF'
   dependencies:
     - name: mylib
       version: 1.0.0
       repository: file://../mylib
   EOF
   

3. Render the chart:

   helm dependency update mysvc
   helm template mysvc --output-dir rendered
   # Inspect rendered/deployment.yaml for the labels section
   

   Expected check: the output contains a metadata.labels block identical to the library helper.
4. OCI push (optional):

   helm chart save mylib oci://registry.example.com/mylib:v1.0.0
   helm chart push oci://registry.example.com/mylib:v1.0.0
   # In consumer
   cat >> mysvc/Chart.yaml <<'EOF'
   dependencies:
     - name: mylib
       version: v1.0.0
       repository: oci://registry.example.com/mylib
   EOF
   helm dependency update mysvc
   

Trade‑offs & Limitations

• No Conditional Inclusion: All templates in a library are loaded every time the consumer renders. Keep the library focused on reusable helpers; avoid templates that should be optional.
• Debugging Difficulty: Template errors point to the library’s file paths. When debugging, remember that the line numbers refer to the library, not the consumer.
• Values Separation: values.yaml in a library is for documentation only. Consumers must pass needed values explicitly or use a .Values.global namespace.
• OCI Compatibility: Requires Helm 3.7+ and a registry that implements the OCI Distribution Spec. Older CI pipelines may need upgrades.

Actionable Take‑away

If you have multiple microservices that share common templating logic, create a library chart once and treat it as a shared dependency. Pin the library version in each consumer to avoid accidental drift, and use OCI for central distribution if your environment supports it. This keeps your charts lightweight, avoids duplicate releases, and enforces a single source of truth for shared configuration.