Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 38 ยท Templates and Values

Built-in Objects: .Release, .Chart, .Capabilities, .Files and .Template

Know every object Helm gives your templates: .Values, .Release, .Chart, .Capabilities, .Template, .Files and .Subcharts, with examples and a runnable model.

Besides your own values, Helm injects a set of objects into every template. They tell the template who it is deployed as (the release), which chart it belongs to, what the cluster supports and which extra files the chart carries. This lesson lists them all, with the fields you will actually use.

Overview

flowchart TB
  D(("." top-level context)) --> V[".Values"]
  D --> R[".Release"]
  D --> C[".Chart"]
  D --> K[".Capabilities"]
  D --> T[".Template"]
  D --> F[".Files"]
  D --> S[".Subcharts"]

Seven top-level objects. Names start with a capital letter because they come from Helm itself.

.Release

Information about the release being installed or upgraded.

Field Meaning
.Release.Name The release name (blog)
.Release.Namespace The target namespace
.Release.Revision Revision number; 1 on install
.Release.IsInstall true when this operation is an install
.Release.IsUpgrade true for an upgrade or rollback
.Release.Service Always Helm
YAML
metadata:
  name: {{ .Release.Name }}-config
  namespace: {{ .Release.Namespace }}
  labels:
    app.kubernetes.io/managed-by: {{ .Release.Service }}
    app.kubernetes.io/instance: {{ .Release.Name }}

.Release.IsInstall lets a template do something only once, for example generate a random initial password on install and leave it alone on upgrades (combined with lookup, see tpl, lookup and Other Advanced Functions).

When you run helm template, there is no cluster operation, so IsInstall is true and Namespace is default unless you pass --namespace.

.Chart

The contents of Chart.yaml, with each key capitalized:

Field From
.Chart.Name name
.Chart.Version version
.Chart.AppVersion appVersion
.Chart.Description description
.Chart.Type type
.Chart.Annotations annotations (a map)
.Chart.Maintainers, .Chart.Keywords, .Chart.Sources lists

The common pairing is the image tag defaulting to the app version:

YAML
image: "{{ .Values.image.repository }}:{{ .Values.image.tag | default .Chart.AppVersion }}"

and a label that records the chart that produced an object: helm.sh/chart: {{ .Chart.Name }}-{{ .Chart.Version }}. Because labels cannot contain + (allowed in SemVer build metadata), the scaffold replaces it: {{ printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" }}.

.Capabilities

What the target cluster and the Helm client support. This allows one chart to work on old and new clusters.

Field Meaning
.Capabilities.KubeVersion.Version Full version, such as v1.31.2
.Capabilities.KubeVersion.Major / .Minor Components as strings
.Capabilities.APIVersions.Has "networking.k8s.io/v1" True if the cluster serves that API group version
.Capabilities.APIVersions.Has "batch/v1/CronJob" Checks a specific kind
.Capabilities.HelmVersion.Version The Helm client version
YAML
{{- if .Capabilities.APIVersions.Has "autoscaling/v2" }}
apiVersion: autoscaling/v2
{{- else }}
apiVersion: autoscaling/v2beta2
{{- end }}
kind: HorizontalPodAutoscaler

Use these checks sparingly; a chart that supports a modern range of Kubernetes versions (kubeVersion in Chart.yaml) usually does not need them. With helm template, Helm cannot ask a cluster, so it uses defaults for a recent Kubernetes. Pass --kube-version 1.28.0 and --api-versions networking.k8s.io/v1 to test other combinations in CI.

.Template

Information about the file currently being rendered.

  • .Template.Name: the path, such as webapp/templates/deployment.yaml.
  • .Template.BasePath: the templates directory, webapp/templates.

It is mostly used to compute a checksum of a sibling template so that pods restart when a ConfigMap changes:

YAML
spec:
  template:
    metadata:
      annotations:
        checksum/config: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }}

Pay attention to $.Template: inside a range or with the dot changes meaning, while $ always points to the top-level context (see Control Flow).

.Files

Access to files in the chart that are not templates (anything outside templates/, except a few that Helm excludes such as Chart.yaml, values.yaml, charts/ and files matched by .helmignore).

Call Returns
.Files.Get "config/app.ini" File content as a string
.Files.GetBytes "logo.png" Content as bytes
.Files.Glob "config/*.yaml" A map of files matching the pattern
.Files.Lines "config/hosts.txt" A list of lines
.Files.AsConfig The matched files as YAML for a ConfigMap data
.Files.AsSecrets The same, base64 encoded, for a Secret
YAML
apiVersion: v1
kind: ConfigMap
metadata:
  name: {{ include "webapp.fullname" . }}-files
data:
  {{- (.Files.Glob "config/*").AsConfig | nindent 2 }}

Files go into the release record, so keep them small and never include secrets. Paths use forward slashes everywhere.

.Subcharts and .Values

.Subcharts.redis gives access to a dependency's own scope (its .Values, .Chart and so on), which parent charts rarely need. .Values is the merged map from the previous lesson and is by far the most used object.

A model of the context

The stand-in builds the same kind of context as Helm and evaluates the version and API checks a template might make. It helps to see that .Release and friends are just data.

Python Stand-in: building the template context

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.

Files as ConfigMap data

.Files is easiest to understand with an example: every file matching a pattern becomes a key of a ConfigMap.

Python Stand-in: .Files.Glob and AsConfig

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 real AsConfig produces the same name: "content" pairs, keyed by the base file name.

Use helm template --debug and add a temporary {{ . | toYaml }} or {{ .Release | toYaml }} to dump an object while learning; remove it before you commit.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which object holds the name of the release?

    .Chart.Name is the chart; .Release.Name is the installed release.
  2. 2. How do you check whether the cluster serves autoscaling/v2?

    APIVersions.Has reports whether the API group version is available.
  3. 3. Which object reads a non-template file packaged in the chart?

    .Files.Get, .Glob, .Lines and AsConfig read chart files.
  4. 4. What is .Release.IsInstall during helm upgrade?

    An upgrade (or rollback) sets IsUpgrade; IsInstall is only true on install.

Summary

  • Seven top-level objects: .Values, .Release, .Chart, .Capabilities, .Template, .Files, .Subcharts.
  • .Release identifies the installation; .Chart mirrors Chart.yaml with capitalized keys.
  • .Capabilities adapts templates to the cluster; test other versions with helm template --kube-version and --api-versions.
  • .Files embeds chart files, .Template.BasePath supports config checksum annotations, and $ always means the top-level context.

Next: Control Flow: if, with, range and Variables