Working with Named Templates

1. Defining Named Templates

Named templates in Helm are reusable template fragments that can be defined once and referenced multiple times within a chart. They are defined in the templates/ directory using the {{ define }} action.

Template Definition	Description	Example
Template Name	Name of the template, must be unique within the chart	`{{ define "mychart.labels" }}`
Template Content	Content to be rendered when the template is called	`{{- range $key, $val := .Values.labels }} {{ $key }}={{ $val }} {{- end }}`

Example: Defining a Named Template

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

Note: Template names follow the pattern <chart-name>.<template-name> to avoid naming conflicts.

2. Including Templates

Template	Type	Usage	Notes
.Include	`template`	`{{ include "mychart.templates.configmap" . }}`	Include a named template from the current chart
.Include with values	`template`	`{{ include "mychart.templates.configmap" (dict "key" "value") }}`	Pass values to the included template

Example: Including a ConfigMap Template

{{- define "mychart.templates.configmap" -}}
apiVersion: v1
kind: ConfigMap
metadata:
  name: {{ include "mychart.fullname" . }}
data:
  config.yaml: |
    key1: {{ .Values.config.key1 }}
{{- end -}}
{{- include "mychart.templates.configmap" . -}}

Example: Including with Custom Values

{{- define "mychart.templates.configmap" -}}
apiVersion: v1
kind: ConfigMap
metadata:
  name: {{ include "mychart.fullname" . }}
data:
  config.yaml: |
    key1: {{ .Values.config.key1 }}
    key2: {{ .Values.config.key2 }}
{{- end -}}
{{- include "mychart.templates.configmap" (dict "Values" .Values "key2" "customValue") -}}

3. Using Template Directive

Directive	Description	Usage
template	Used to include a named template from the current context or parent scope.	`{{ template "myTemplate" . }}`

Example: Using template directive

apiVersion: v1
kind: ConfigMap
metadata:
  name: {{ template "fullname" . }}
data:
  config.yaml: |
    server:
      port: {{ .Values.server.port }}

Note: The template directive allows for reusing named templates defined in the same chart or imported from subcharts.

4. Creating Partial Templates

Partial templates in Helm are reusable template fragments that can be included in other templates using the {{ include }} function. They are useful for organizing complex templates and promoting reuse.

Template File	Description	Usage
_helpers.tpl	Standard location for partial templates in Helm charts	Use `{{ include "mychart.partialName" . }}`

Example: Defining a Partial Template

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

Example: Using a Partial Template

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

Note: Partial templates must be defined in a file named _helpers.tpl or another file with the _ prefix to avoid being rendered as a Kubernetes resource.

Warning: Avoid circular includes when using {{ include }} to prevent infinite loops during template rendering.

5. Passing Scope to Templates

Parameter	Type	Description
.Values	Object	Values passed to the chart from values.yaml or --set
.Chart	Object	Chart metadata (name, version, etc.)
.Files	Object	Access to files in the chart
.Capabilities	Object	Kubernetes version and features supported
.Release	Object	Release information (name, namespace, status)
.Template	Object	Template context (name, basepath)

Example: Using .Values in a Template

{{- range .Values.ingress.hosts }}
host: {{ .host }}
{{- end }}

Example: Accessing Chart Metadata

Chart Name: {{ .Chart.Name }}
Chart Version: {{ .Chart.Version }}

Note: The .Values scope is the most commonly used and allows templates to dynamically adjust based on configuration values.

6. Defining Common Labels

Label Key	Value Example	Description
app.kubernetes.io/name	`"myapp"`	Application name, used for identifying the application
app.kubernetes.io/version	`"1.2.3"`	Version of the application
app.kubernetes.io/instance	`"myapp-production"`	Unique name identifying the instance of an application
app.kubernetes.io/part-of	`"myproject"`	Name of a higher-level application this one is part of
app.kubernetes.io/managed-by	`"helm"`	Tool being used to manage the operation of an application

Example: Defining Common Labels in a Template

metadata:
  labels:
    app.kubernetes.io/name: {{ .Values.appName }}
    app.kubernetes.io/version: {{ .Values.version }}
    app.kubernetes.io/instance: {{ .Release.Name }}
    app.kubernetes.io/part-of: {{ .Values.projectName }}
    app.kubernetes.io/managed-by: {{ .Release.Service }}

Note: These labels follow the Kubernetes common labels specification for better integration and observability.

7. Creating Selector Templates

Template Type	Description	Usage	Notes
helm.tpl	Template file for selector logic	`{{ include "myapp.selector" . }}`	Used to define label selectors for deployments
selector.name	Selector name for labels	`{{ .Values.selector.name }}`	Must match app name in deployment
selector.matchLabels	Map of label keys and values	`{{ .Values.selector.matchLabels }}`	Used for pod selection in services

Example: Selector Template

selector:
  matchLabels:
    app.kubernetes.io/name: {{ .Values.name }}
    app.kubernetes.io/instance: {{ .Release.Name }}

Note: Selector templates must align with the labels used in deployments to ensure proper pod selection.

8. Building Image Strings

Property	Description	Example
image.repository	Repository name for the Docker image	`nginx`
image.tag	Tag of the Docker image	`1.21.6`
image.pullPolicy	Policy for pulling the image	`IfNotPresent`

Example: Building Image String

image:
  repository: nginx
  tag: 1.21.6
  pullPolicy: IfNotPresent

Note: The full image string is constructed as {{ .Values.image.repository }}:{{ .Values.image.tag }} in templates.

9. Generating Resource Names

Property	Description	Example
name	Name of the resource	`my-app`
fullname	Full name combining release name and chart name	`my-release-my-app`
nameOverride	Override the name of the chart	`custom-app`
fullnameOverride	Override the full name of the resource	`my-release-custom-app`

Example: Using name and fullname in templates

apiVersion: v1
kind: Service
metadata:
  name: {{ include "my-chart.fullname" . }}
spec:
  selector:
    app: {{ include "my-chart.name" . }}

Note: The fullname template function combines the release name and chart name to ensure uniqueness across releases.

10. Reusing Template Logic

Template	Type	Description
.Release.Name	Variable	Name of the Helm release
.Release.Namespace	Variable	Namespace where the release is installed
.Release.Revision	Variable	Revision number of the release (1 for first install)
.Release.IsInstall	Variable	True if this is an install operation
.Release.IsUpgrade	Variable	True if this is an upgrade operation
.Values	Variable	Values provided to the chart during installation
.Chart	Variable	Metadata about the chart (name, version, etc.)
.Files	Variable	Access to files within the chart (e.g., .Files.Get)

Example: Using Release Variables

apiVersion: v1
kind: ConfigMap
metadata:
  name: {{ .Release.Name }}-config
data:
  namespace: {{ .Release.Namespace }}
  revision: {{ .Release.Revision }}

Example: Conditional Logic with Release Variables

{{- if .Release.IsInstall }}
apiVersion: v1
kind: ConfigMap
metadata:
  name: {{ .Release.Name }}-install-config
{{- else if .Release.IsUpgrade }}
apiVersion: v1
kind: ConfigMap
metadata:
  name: {{ .Release.Name }}-upgrade-config
{{- end }}

11. Using Template Inheritance

Helm's template inheritance allows you to define a base template and extend it in child templates, promoting reuse and reducing duplication.

Feature	Description	Usage
partial	Renders a named template from the current context	`{{ include "mytemplate" . }}`
block	Defines a named block that can be overridden in child templates	`{{ define "myblock" }}...{{ end }}`
override	Replaces a block defined in a parent template	`{{ define "myblock" }}...{{ end }}`

Example: Base Template with Block

{{ define "base-template" }}
<div class="container">
  {{ block "content" . }}{{ end }}
</div>
{{ end }}

Example: Child Template Extending Base

{{ define "my-template" }}
{{ include "base-template" . }}
{{- define "content" }}
  <h1>{{ .Values.title }}</h1>
  <p>{{ .Values.description }}</p>
{{ end }}
{{ end }}