Creating Library Charts

1. Defining Library Chart Type

Field	Value	Description
type	`library`	Must be set to `library` for library charts

Note: Library charts are designed to be included as dependencies in other charts and do not define any Kubernetes resources directly.

2. Creating Reusable Templates

Reusable templates in Helm charts allow you to define common structures that can be shared across multiple chart components. These templates are typically stored in the templates/ directory and can be included using the {{ include }} function.

Template	Description	Usage
_helpers.tpl	Defines helper templates that can be reused throughout the chart.	`{{ include "mychart.labels" . }}`

Example: Defining a Helper Template

{{- define "mychart.labels" -}}
app.kubernetes.io/name: {{ include "mychart.name" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
{{- end -}}

Example: Using a Helper Template

metadata:
  labels:
    {{- include "mychart.labels" . | nindent 4 }}

Note: Helper templates are defined in _helpers.tpl and must be enclosed in {{- define "template.name" -}} and {{- end -}} blocks.

Key Points

Helper templates provide a way to define reusable components.
Templates are defined in _helpers.tpl.
Use {{ include "template.name" . }} to reference templates.

Library charts in Helm allow you to define shared templates, values, and helpers that can be reused across multiple chart deployments. This promotes consistency and reduces duplication in your chart configurations.

Helper Type Description Usage Example

template functions

Helper Type	Description	Usage Example
template functions	Reusable template functions defined in `templates/_helpers.tpl`	`{{- define "mychart.labels" -}} app: {{ include "mychart.name" . }} version: {{ .Values.version }} {{- end -}}`
partial templates	Reusable template snippets that can be included in other templates	`{{- define "mychart.configmap" -}} apiVersion: v1 kind: ConfigMap metadata: name: {{ include "mychart.fullname" . }} data: config.yaml: \| {{ .Files.Get "config.yaml" \| indent 4 }} {{- end -}}`

Reusable template functions defined in templates/_helpers.tpl

{{- define "mychart.labels" -}}
app: {{ include "mychart.name" . }}
version: {{ .Values.version }}
{{- end -}}

partial templates

Reusable template snippets that can be included in other templates

{{- define "mychart.configmap" -}}
apiVersion: v1
kind: ConfigMap
metadata:
  name: {{ include "mychart.fullname" . }}
data:
  config.yaml: |
{{ .Files.Get "config.yaml" | indent 4 }}
{{- end -}}

Example: Defining a Common Label Helper

{{- define "mychart.labels" -}}
app: {{ include "mychart.name" . }}
version: {{ .Values.version }}
{{- end -}}

Example: Using a Shared ConfigMap Template

{{- define "mychart.configmap" -}}
apiVersion: v1
kind: ConfigMap
metadata:
  name: {{ include "mychart.fullname" . }}
data:
  config.yaml: |
{{ .Files.Get "config.yaml" | indent 4 }}
{{- end -}}

Note: When using library charts, ensure that the helper functions and templates are compatible with the chart consuming them. Version mismatches can lead to unexpected behavior or errors during deployment.

4. Using Library as Dependency

Field	Description	Example
dependencies	List of chart dependencies	`[ { "name": "mylib", "version": "1.0.0", "repository": "https://example.com/charts" } ]`

Example: Adding Library Dependency

dependencies:
- name: mylib
  version: 1.0.0
  repository: https://example.com/charts

Note: The library chart must be packaged and available in a chart repository or local path.

Workflow: Using Library Chart as Dependency

Add library chart to dependencies in Chart.yaml
Run helm dependency update to fetch dependencies
Use library templates in your chart's templates/ directory

5. Including Library Templates

Template Type	Description	Usage	Notes
library templates	Reusable template files that can be included in multiple chart components	`{{ include "mylib.chart" . }}`	Must be defined in `templates/_library.tpl`
partial templates	Reusable template snippets for specific components or logic	`{{ include "mylib.partial" . }}`	Can be included in any template using `{{ include }}`

Example: Including a Library Template

{{ include "mylib.chart" . }}

Example: Defining a Library Template

{{- define "mylib.chart" -}}
apiVersion: v1
kind: ConfigMap
metadata:
  name: {{ include "mylib.fullname" . }}
data:
  config.yaml: |
    key: value
{{- end -}}

Note: Library templates must be defined in templates/_library.tpl to be accessible via the {{ include }} function.

6. Versioning Library Charts

Version Type	Description	Usage	Notes
appVersion	Version of the application code	`"1.2.3"`	Used to track the application's version, not the chart itself
version	Chart version (semver)	`"1.0.0"`	Must follow semantic versioning (SemVer) rules
apiVersion	Chart API version	`"v2"`	Must be set to `v2` for Helm 3

Example: Chart.yaml versioning

apiVersion: v2
name: my-lib-chart
description: A library chart for common configurations
version: 2.1.0
appVersion: "1.5.0"

Note: When versioning library charts, ensure the version field is updated to reflect changes in chart structure or dependencies.

7. Documenting Library Usage

Field	Description	Example
annotations	Metadata annotations for the chart	`{"helm.sh/chart": "mylib-1.0.0"}`
apiVersion	API version of the chart	`v2`
appVersion	Version of the application being deployed	`1.2.3`
description	Short description of the chart	`A library chart for common Kubernetes resources`
home	Homepage URL for the chart	`https://example.com/mylib`
icon	URL to an icon image	`https://example.com/icon.png`
keywords	List of keywords for the chart	`["library", "common", "k8s"]`
maintainers	List of chart maintainers	`[{"name": "John Doe", "email": "john@example.com"}]`
name	Name of the chart	`mylib`
sources	List of source URLs for the chart	`["https://github.com/example/mylib"]`
version	Chart version (semantic versioning)	`1.0.0`

Example: Chart Metadata

apiVersion: v2
name: mylib
description: A library chart for common Kubernetes resources
version: 1.0.0
appVersion: 1.2.3
home: https://example.com/mylib
icon: https://example.com/icon.png
keywords:
  - library
  - common
  - k8s
maintainers:
  - name: John Doe
    email: john@example.com
sources:
  - https://github.com/example/mylib

Note: The appVersion field should reflect the version of the application that this chart deploys, not the chart version itself.

8. Organizing Library Templates

Template Type	Description	Usage	Best Practice
_helpers.tpl	Contains reusable template functions and macros	Used to define common logic across charts	Place in root of templates directory
_config.tpl	Defines configuration values and defaults	Used to centralize config settings	Use for environment-specific overrides
_values.tpl	Defines default values for chart configuration	Used to provide fallbacks for settings	Include in chart's values.yaml template

Example: Using _helpers.tpl for Reusable Functions

{{- define "mychart.labels" -}}
app: {{ include "mychart.name" . }}
version: {{ .Values.version }}
{{- end -}}

Note: Template files starting with _ are not rendered as Kubernetes resources but can be included in other templates.

Template Organization Guidelines

Use _helpers.tpl for shared logic and macros
Store configuration in _config.tpl
Define default values in _values.tpl
Keep templates modular and DRY (Don't Repeat Yourself)

9. Testing Library Templates

Example: Unit testing with Helm Test

apiVersion: v1
kind: Pod
metadata:
  name: test-pod
  annotations:
    "helm.sh/hook": test
spec:
  containers:
  - name: tester
    image: busybox
    command:
    - /bin/sh
    - -c
    - |
      echo "Testing chart template..."
      # Add test logic here
  restartPolicy: Never

Test Type	Description	Usage
Unit Tests	Validate individual template outputs	Use `helm test` command
Integration Tests	Test chart with real dependencies	Run in CI/CD pipeline

Note: Helm test hooks execute in the same namespace as the chart deployment.

Testing Best Practices

Use helm test to validate chart functionality
Include test hooks in templates/ directory
Test templates with various values to ensure flexibility

10. Publishing Library Charts

Property	Description	Example
name	Name of the library chart	`my-library-chart`
version	Version of the chart	`1.0.0`
apiVersion	API version of the chart	`v2`
description	Description of the chart	`A library chart for common templates`
type	Type of chart (library)	`library`

Example: Publishing a Library Chart

helm package my-library-chart
helm push my-library-chart-1.0.0.tgz oci://my-registry.com/charts

Note: Library charts are not meant to be deployed directly but can be used as dependencies in other charts.