Helm Libraries

Helm Libraries are reusable Helm chart components packaged as library charts. They contain templates, helper functions, and chart metadata that do not deploy resources on their own but provide shared functionality and best practices for other Helm charts to consume. This modular approach promotes code reuse, consistency, and maintainability across multiple charts within an organization or project.

Purpose and Role of Helm Libraries

Helm Libraries serve as foundational building blocks that encapsulate common Kubernetes manifest patterns, helper templates, and utility functions. They allow chart developers to avoid duplication by centralizing reusable logic such as template snippets, predefined labels, annotations, or complex template functions. Instead of copying and pasting code between charts, developers can depend on a Helm Library chart and invoke its templates or functions.

Unlike standard Helm charts, library charts are never installed directly into a Kubernetes cluster. They are referenced as dependencies via the Chart.yaml file of a parent chart. When the parent chart is rendered, the templates and helpers from the library chart become available in the rendering context.

Structure and Contents of Helm Libraries

Chart Metadata

A Helm Library is identified by a special flag in its Chart.yaml file:

type: library

This differentiates it from application or infrastructure charts and instructs Helm to treat it as a non-installable package.

Templates and Helpers

The core content of Helm Libraries lies in the templates/ directory, which contains:

• Helper templates: Defined using the {{- define }} directive, these templates encapsulate reusable snippets of Kubernetes manifest code or logic, such as label templates, resource configuration fragments, or complex conditional logic.

  Example:

  {{- define "mychart.labels" -}}
  app.kubernetes.io/name: {{ .Chart.Name }}
  app.kubernetes.io/version: {{ .Chart.AppVersion }}
  {{- end }}
  

• Go template functions: These can be written directly in templates or through Sprig functions (a collection of utility functions Helm supports). Libraries often combine these functions with helper templates for sophisticated templating capabilities.

Values Schema and Defaults

While Helm Libraries can provide default values in a values.yaml file, they typically do not include user-configurable settings since they are not installed directly. Instead, values are passed from the parent chart that depends upon the library.

Absence of Kubernetes Resources

Library charts do not define Kubernetes resource manifests that result in creation or modification of cluster resources. Instead, they focus on reusable template fragments or functions that produce manifests when invoked by the parent chart.

Usage and Integration

Referencing Helm Libraries

Parent charts declare dependencies on Helm Libraries in their Chart.yaml:

dependencies:
  - name: my-library
    version: 1.0.0
    repository: "https://example.com/helm-charts"

Upon helm dependency update and rendering, the library's templates and helpers become accessible inside the parent chart's templates.

Accessing Library Templates and Helpers

Parent charts invoke library templates by referencing their fully-qualified name, which includes the library chart name as a prefix:

labels:
  {{- include "my-library.labels" . | nindent 4 }}

This allows the parent chart to reuse complex label definitions or other templated fragments without redefining them.

Benefits of Helm Libraries

• Code Reuse: Centralizes common templates and functions to avoid duplication.
• Consistency: Ensures uniformity of labels, annotations, resource definitions, and logic across multiple charts.
• Maintainability: Updates to library templates automatically propagate to all charts depending on that library.
• Modularity: Separates concerns by decoupling shared components from application-specific manifests.
• Testing and Validation: Libraries can be independently tested to ensure correctness of shared logic.

Limitations and Considerations

• Helm Libraries cannot be installed directly; they must be used as dependencies.
• Libraries should avoid including resources or manifests that expect to be installed independently.
• Careful versioning and dependency management are required to prevent breaking changes from propagating unexpectedly.
• Since libraries do not have independent values usage, all configuration must be passed through the parent chart’s values.

Summary of Key Components in Helm Libraries

Helm Libraries are essential for developing scalable and maintainable Helm chart ecosystems, enabling teams to share and enforce best practices and reduce duplication through reusable templating logic.