Named Templates and Helpers

In Lesson 1, you learned Go templating basics: variables, pipelines, conditionals, ranges. You can now write templates that branch on conditions and loop through data.

But you discovered a problem: You're repeating the same labels (app: myapp, version: 1.0, env: prod) in your Deployment, Service, and ConfigMap. That's not a templating problem—that's a code repetition problem. You need a way to define template fragments once and reuse them everywhere.

This lesson introduces named templates and the _helpers.tpl convention—the DRY principle for Helm charts. You'll define common patterns once (labels, selectors, image pull secrets, annotations) and include them wherever needed.

---

What You'll Learn

This lesson teaches you how to eliminate template duplication using Helm's named templates and helper conventions.

Prerequisites:

• Lesson 1 (Go templating: variables, pipelines, conditionals, ranges)
• Understand YAML indentation rules
• Familiarity with Kubernetes labels and selectors

Time Estimate: 45 minutes

---

1. Named Templates with define

In Lesson 1, every template you wrote was a full file that produced output. But templates can also define functions that output nothing on their own.

The define action creates a named template:

Key points:

• define starts a named template block
• chartname.labels is the template's name (convention: chart-name.component)
• Content between define and end is stored, not immediately output
• The block produces no output when defined

Output:

When you define a template, nothing appears. The template is registered in memory, waiting to be called.

---

2. The _helpers.tpl File Convention

Helm has a naming convention: Templates starting with _ (underscore) are not rendered as standalone manifests. They're utilities meant to be included elsewhere.

Create templates/_helpers.tpl:

Why _helpers.tpl?

• Convention recognized by all Helm users (like _config.scss in CSS)
• Prevents accidental rendering (underscore files are skipped)
• Centralizes reusable fragments
• One place to find all helpers

Output:

No files are created. _helpers.tpl is never rendered. It only provides functions for other templates to include.

---

3. Including Templates with include

Now you call a named template using include:

Syntax breakdown:

• include "myapp.labels" . calls the named template, passing . (current context)
• | nindent 4 pipes the output to nindent (indent and newline)
• nindent N indents output by N spaces, preserving YAML structure

Output:

---

4. Why include Replaces the Deprecated template

Helm originally provided template for calling named templates. template is now deprecated (removed in Helm 3.13+).

Why? The problem is output handling.

Problem with template:

template doesn't support pipes. You can't control indentation. Output becomes:

Notice: No indentation. YAML is broken.

Solution with include:

include returns a string that you can pipe to nindent. Output:

Properly indented. Valid YAML.

Output comparison:

template (broken indentation):

include (correct):

Key difference:

• template: Renders directly, no output control
• include: Returns string, composable with pipes

Always use include. Never use template for new code.

---

Checkpoint: Template Definition and Inclusion

Quick Reference:

Self-Check Questions:

1. What happens when you render a template file starting with _? Answer: Nothing—underscore files are not rendered as manifests.
2. Why does {{ template "myapp.labels" . }} break YAML indentation? Answer: template renders directly without supporting pipes, so you can't control indentation.
3. What does the . in {{ include "myapp.labels" . }} represent? Answer: The current context being passed to the named template (root context: .Chart, .Values, etc.).
4. Where should you define all your chart's helper templates? Answer: In templates/_helpers.tpl following Helm convention.

---

5. Scope Rules: What . Means Inside a Named Template

When you call a named template, you pass . as the current context. Inside the template, . refers to whatever you passed.

When you call:

Inside myapp.labels, . is the root context (.Chart, .Values, etc. all work).

Scope rule: Inside a named template, . refers to whatever you passed to include/template.

Common mistake:

Inside the range, . becomes each tag string. You can't access .Chart anymore.

To access both root context and loop value:

$ is a special variable: Always refers to root context, no matter how deep you nest.

---

6. Common Patterns

Pattern: Labels (Most Common)

Used in every Kubernetes manifest.

Pattern: Selectors

Used in Deployments, Services, StatefulSets.

Pattern: Image Pull Secrets (Conditional)

Only rendered if imagePullSecrets is defined.

Pattern: Annotations (with defaults)

Combines defaults with conditional fields.

---

7. Naming Conventions

The standard Helm convention is: chartname.component

Examples from real charts:

• postgresql.primary.fullname
• redis.fullname
• nginx.ingress.className

Your chart: myapp.labels, myapp.selector, myapp.imagePullSecrets

Why this pattern?

1. Namespacing: Prevents collisions with subchart helpers
2. Clarity: myapp.labels immediately shows purpose
3. Searchability: grep "myapp\." _helpers.tpl finds all your helpers
4. Consistency: Everyone following convention means predictable code

---

Checkpoint: Scope and Naming Conventions

Quick Reference:

Self-Check Questions:

1. Inside a {{ range .Values.tags }} loop within a named template, what does . refer to? Answer: Each individual tag value (the current iteration item), not the root context.
2. How do you access .Chart.Name inside a range loop in a named template? Answer: Use {{ $.Chart.Name }} where $ always refers to the root context.
3. What naming convention should you follow for helper templates? Answer: chartname.component (e.g., myapp.labels, postgresql.fullname).
4. Why prefix helper names with the chart name? Answer: Prevents namespace collisions with subchart helpers and improves searchability.

---

Common Mistakes

Before you start the exercises, avoid these frequent errors:

Mistake 1: Forgetting to Pass Context (.)

Wrong:

Why it fails: The template can't access .Chart, .Values, etc. without context.

Correct:

---

Mistake 2: Using Wrong Indentation Level

Wrong:

Why it fails: Labels are already at 4-space indent (under metadata:), but nindent 2 only indents 2 spaces.

Correct:

Rule: Count the spaces from the left margin to where the first key should appear.

---

Mistake 3: Using template Instead of include

Wrong:

Why it fails: Can't pipe to nindent, breaks YAML indentation.

Correct:

---

Mistake 4: Creating Helpers Without the Chart Name Prefix

Wrong:

Why it fails: If you use a subchart that also defines labels, they collide.

Correct:

---

Mistake 5: Losing Root Context in Nested Loops

Wrong:

Correct:

---

Exercises

Exercise 2.1: Create _helpers.tpl with Common Labels

Create templates/_helpers.tpl:

Verify it's not rendered:

Output:

No YAML with app: aiagent appears. The template is defined but not rendered.

---

Exercise 2.2: Include Labels in Multiple Manifests

Create templates/deployment.yaml:

Create templates/service.yaml:

Create templates/configmap.yaml:

Render:

Output:

Three manifests (Deployment, Service, ConfigMap) all include the same labels from your helper.

---

Exercise 2.3: Create Image Pull Secrets Helper with Conditional Logic

Update templates/_helpers.tpl:

Update values.yaml:

Use in templates/deployment.yaml:

Render:

Output:

Change values.yaml to imagePullSecrets: [] and render again:

Output:

The imagePullSecrets section is omitted.

---

Exercise 2.4: Demonstrate Why include Works Where template Fails

Create a test file using old template syntax:

Render:

Output (BROKEN):

YAML is invalid. Labels aren't indented under labels:.

Now use include:

Output (CORRECT):

Valid YAML, proper indentation.

---

Exercise 2.5: Refactor 3 Duplicate Sections into Single Include

You have three manifests with duplicate metadata.labels:

Before:

After:

Create helper in _helpers.tpl:

Use in all three:

Benefit: Change labels once in _helpers.tpl. All three manifests automatically use the new labels.

---

Try With AI

Setup

You've created a chart with separate Deployment, Service, and ConfigMap. Each has duplicate labels, annotations, and image pull secret handling. Your job is to refactor common patterns into _helpers.tpl and simplify your manifests.

Files to work with:

• templates/_helpers.tpl (create this)
• templates/deployment.yaml
• templates/service.yaml
• templates/configmap.yaml
• values.yaml

Part 1: Initial State (Current Duplications)

Show AI your current manifests:

Part 2: Helper Design

Based on AI's suggestions, ask:

Part 3: Validation

Ask AI to help you validate:

Part 4: Refinement

Show AI your refactored manifests:

Part 5: Final Check

Verify your work:

Compare the output:

• Do all labels appear with correct indentation?
• Do selectors only appear where needed?
• Are image pull secrets included/excluded based on values.yaml?

Check your helpers are used everywhere they should be:

Should show calls in deployment, service, configmap—not in _helpers.tpl definitions.

---

Reflect on Your Skill

You built a helm-chart skill in Lesson 0. Test and improve it based on what you learned.

Test Your Skill

Identify Gaps

Ask yourself:

• Did my skill create templates with proper naming (chartname.templatename)?
• Did it use include instead of deprecated template?
• Does it handle indentation correctly with nindent?
• Did it demonstrate passing context with the . parameter?

Improve Your Skill

If you found gaps: