Understanding the Chart Context in Helm Templates

If you’ve worked with Helm templates, you may have noticed the . (dot) being passed into helpers, like {{ include "common.names.fullname" . }}. But what exactly is this .? What does it contain, and how does it work?

Let’s dive deeper into Helm’s chart context and explore how it helps render templates effectively.

What is the Chart Context (.)?

In Helm, the . represents the chart context, a powerful object that encapsulates all the data and metadata about the chart, release, and Kubernetes cluster.

Think of it as a container that provides:

• Chart-specific details (e.g., name, version).
• Configurable values (from values.yaml or CLI overrides).
• Release information (e.g., name, namespace).
• Kubernetes cluster capabilities.

Helm automatically passes this chart context to all templates and helpers, making it the foundation of Helm’s templating system.

What Does the Chart Context Contain?

Here’s a breakdown of the key components available in the chart context:

1. Chart metadata (.Chart)

• Metadata from the Chart.yaml file.
• Includes information like the chart name, version, and application version.

Example:

Chart:
  name: demo-app
  version: 0.1.0
  appVersion: "1.16.0"

2. Values (.Values)

• All configurable values defined in values.yaml, merged with any overrides passed via the command line or parent charts.
• This is where user-specific configurations live.

Example:

Values:
  replicaCount: 2
  image:
    repository: nginx
    tag: "1.16.0"
  commonLabels:
    environment: production
    team: backend

3. Release Information (.Release)

• Metadata about the current release (created during helm install or helm upgrade).
• Useful for generating resource names and labels.

Example:

Release:
  Name: release-name
  Namespace: default
  Service: Helm

4. Cluster Capabilities (.Capabilities)

• Provides details about the Kubernetes cluster’s supported API versions.
• Allows templates to conditionally render resources based on cluster features.

Example:

Capabilities:
  KubeVersion: 1.21.1
  APIVersions:
    - "v1"
    - "apps/v1"

5. Files (.Files)

• Access to non-template files in the chart, such as additional configuration files or secrets.

Example:

Files.Get "config.json"

6. Templates and Helpers

The chart context allows access to defined helper functions, like common.names.fullname, and can pass data into them.

Using the Chart Context (.) in Helpers

Let’s see how the chart context is used in a template. Suppose we’re using the helper common.names.fullname to generate consistent resource names. Here’s what it looks like:

name: {{ include "common.names.fullname" . }}

In this example:

• . is passed into the helper common.names.fullname.
• The helper can access everything in the chart context: .Chart, .Values, .Release, etc.

Enhancing Helpers with dict

Sometimes, the entire chart context (.) isn’t enough for specific use cases. That’s where dict comes in, allowing you to pass a custom map of inputs to a helper.

What Is ‘dict’?

• dict creates a map of key-value pairs that you can pass to a helper.
• This is useful when you want to provide additional inputs along with the chart context.

Example: Using dict for Custom Inputs

Calling the Helper:

labels:
  {{ include "common.labels.standard" (dict "context" . "customLabels" .Values.commonLabels) | nindent 4 }}

What Happens Here:

• context: Passes the entire chart context (.) to the helper.
• customLabels: Passes user-defined labels from values.yaml.

Inside the helper:

{{- define "common.labels.standard" -}}
{{- if and (hasKey . "customLabels") (hasKey . "context") -}}
  app.kubernetes.io/name: {{ include "common.names.name" .context }}
  app.kubernetes.io/instance: {{ .context.Release.Name }}
  {{- range $key, $value := .customLabels }}
  {{ $key }}: {{ $value }}
  {{- end }}
{{- end -}}
{{- end -}}

This helper:

• Checks if customLabels and context exist.
• Adds standard labels (like app.kubernetes.io/name) from the chart context.
• Adds custom labels (like environment: production) from customLabels.

What does the Output Look Like?

Input (values.yaml):

commonLabels:
  environment: production
  team: backend

Rendered Output:

metadata:
  labels:
    app.kubernetes.io/name: my-app
    app.kubernetes.io/instance: my-release
    environment: production
    team: backend

Keypoints to understand

1. Inputs Passed to the Helper:
   - context: The full Helm chart context (e.g., .).
   - commonLabels: A dictionary of custom labels defined in values.yaml.
2. Standard Labels: These are predefined by the common library to ensure consistency, such as:
   - app.kubernetes.io/name
- app.kubernetes.io/instance
3. Custom Labels: Users can add their own labels to resources by specifying them in values.yaml.

What If context or customLabels Is Missing?

If:

• context is missing: Standard labels cannot be generated.
• customLabels is missing: Only the standard labels will be generated.

For example, if commonLabels is not defined, the output will look like this:

metadata:
  labels:
    app.kubernetes.io/name: my-app
    app.kubernetes.io/instance: my-release

This ensures the chart still works even if no custom labels are provided.

Debugging Tip

If you’re unsure about what is being passed to the helper, you can add debug lines like this:

{{ printf "DEBUG: Chart = %v\n" .Chart | nindent 4 }}
{{ printf "DEBUG: Values = %v\n" .Values | nindent 4 }}
{{ printf "DEBUG: commonLabels = %v\n" .Values.commonLabels | nindent 4 }}
{{ printf "DEBUG: Capabilities = %v\n" .Capabilities | nindent 4 }}

For example, you might integrate these debug statements into your deployment template to inspect what is being passed:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "common.names.fullname" . }}
  labels:
  {{ include "common.labels.standard" (dict "context" . "customLabels" .Values.commonLabels) | nindent 4 }}
  {{ printf "DEBUG: commonLabels = %v\n" .Values.commonLabels | nindent 4 }}
  {{ printf "DEBUG: Chart = %v\n" .Chart | nindent 4 }}

This will help you understand the actual inputs being passed when the chart is rendered.

Running Helm Debugging:

helm template -s templates/deployment.yaml . --debug

Example Output:

vagrant@demo-app-1$ helm template -s templates/deployment.yaml . --debug
install.go:222: [debug] Original chart version: ""
install.go:239: [debug] CHART PATH: /vagrant/learning-helm-chart/demo-app-1

---
# Source: demo-app-1/templates/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: release-name-demo-app-1
  labels:

    app.kubernetes.io/instance: release-name
    app.kubernetes.io/managed-by: Helm
    app.kubernetes.io/name: demo-app-1
    app.kubernetes.io/version: 1.16.0
    environment: production
    helm.sh/chart: demo-app-1-0.1.0
    team: backend

    DEBUG: commonLabels = map[environment:production team:backend]
    DEBUG: Chart = {{demo-app-1  [] 0.1.0 A Helm chart for Kubernetes [] []  v2   1.16.0 false map[]  [0xc000482870] application} true}

Conclusion

The chart context (.) is the heart of Helm’s templating system, holding everything needed to render resources. By combining it with custom inputs using dict, you can extend the flexibility and reusability of your helpers, ensuring your templates are both powerful and maintainable.

For more details, refer to Helm’s Built-in Objects Documentation.