Rendering Model

Rendering Model defines how Helm processes templates and produces Kubernetes manifests by combining templates, values, and helpers into a fully rendered output before deployment. It is the conceptual framework that governs the transformation of chart templates into resource definitions based on input values, allowing Helm to generate dynamic, reusable configurations.

Core Concepts of the Rendering Model

Templates

Templates are files written using the Go template language, embedded within a Helm chart. They contain Kubernetes manifest definitions with placeholders and logic that Helm evaluates during rendering. Templates can include variables, control structures (such as if, range), and function calls. They serve as the blueprint for the final Kubernetes resource manifests.

Values

Values are the input parameters provided to the chart, typically defined in values.yaml or supplied via the command line. Values supply the dynamic data that templates use to customize the output. During rendering, Helm merges default values from the chart with user-supplied overrides to form a complete set of input data.

Helpers and Functions

Helm includes built-in functions and allows for custom helper templates defined in _helpers.tpl files. Helpers are reusable snippets that can be invoked within templates to avoid repetition and encapsulate common logic. Functions perform operations like string manipulation, arithmetic, and data structure handling, enabling complex logic inside templates.

Rendering Process

Loading and Parsing Templates

When Helm executes a render command (such as helm template or helm install), it first loads all template files from the chart. Each template is parsed as a Go template, preparing it for execution with the values and helpers.

Merging Values

Helm combines values from multiple sources in a specific order of precedence:

1. Chart default values.yaml
2. User-supplied values.yaml files
3. Direct command-line value overrides (--set)
4. Environment variables (if applicable)

This merged value set is passed as the context for template execution.

Executing Templates with Context

Templates are executed by applying the merged values and helper functions as context. The Go templating engine replaces placeholders with actual values, evaluates control statements, and processes helpers to produce a plain YAML manifest. This output is a valid Kubernetes resource definition ready for deployment.

Template Rendering Output

The rendered output is a concatenation of all processed templates, separated by document delimiters (---), forming a complete manifest file or stream. Helm does not modify this output further; it is the final representation of Kubernetes objects to be applied to a cluster.

Template Execution Context

The .Values Object

Within templates, .Values exposes the merged values, allowing access to user inputs and defaults. It is the primary data source for template customization.

The .Release Object

This object provides metadata about the current release, such as the release name, namespace, and revision number, enabling templates to adapt based on deployment context.

The .Chart Object

Contains information about the chart itself, like name, version, and description, useful for embedding metadata in rendered manifests.

The .Files Object

Allows templates to access files inside the chart package, enabling embedding of arbitrary files or configuration snippets.

Scope and Variable Context

Templates execute in a hierarchical scope where variables can be defined and overridden. This scoping enables encapsulation of logic and prevents conflicts between different template parts.

Rendering Model Behavior and Features

Deterministic Rendering

Given the same chart and values, the rendering process produces the same output manifest, ensuring reproducibility.

Conditional Logic

Templates can include conditional blocks that render resources only if certain criteria are met, facilitating flexible deployments.

Iteration and Loops

Helm supports looping over lists or maps in values, allowing dynamic generation of multiple resource instances based on input data.

Error Handling

Template execution can fail if required values are missing or expressions are invalid. Helm surfaces these errors to the user, preventing incomplete or invalid manifests.

Template Inheritance and Composition

Charts can include subcharts, each with their own templates and values. The rendering model merges these hierarchically, allowing complex application stacks to be deployed coherently.

Rendering Model Example

Given a template snippet:

apiVersion: v1
kind: ConfigMap
metadata:
  name: {{ .Release.Name }}-config
data:
  myvalue: {{ .Values.myvalue | quote }}

And values:

myvalue: hello

The rendering process replaces placeholders, producing:

apiVersion: v1
kind: ConfigMap
metadata:
  name: myrelease-config
data:
  myvalue: "hello"

where myrelease is the release name supplied by Helm.

Summary of Rendering Model Workflow

1. Load chart templates.
2. Merge values from all sources.
3. Execute templates with the merged context and helpers.
4. Produce fully rendered Kubernetes manifests.
5. Output manifests for deployment or inspection.

This rendering model allows Helm to provide powerful, flexible, and reusable Kubernetes configuration management by separating template logic from deployment data and producing deterministic manifests suitable for any Kubernetes cluster.