Part 3: Advanced Templates and Values

Series Navigation: ← Part 2: Creating Your First Chart | Back to Series Overview | Part 4: Chart Dependencies and Repositories →

Introduction

In Part 2, we built a functional Helm Chart with basic templating. Now it's time to level up. In my experience, the real power of Helm emerges when you master advanced templating techniques—conditional logic, loops, complex value manipulation, and reusable template functions.

This article covers the templating patterns I use daily when building Charts for complex TypeScript applications. These techniques have saved me countless hours and prevented numerous deployment errors.

Template Functions and Pipelines

Helm uses Go's template language with Sprig functions. Understanding pipelines is crucial for writing clean templates.

Basic Pipelines

Pipelines pass values from left to right:

# Basic usage
{{ .Values.image.repository }}

# With function
{{ .Values.name | upper }}

# Multiple functions (pipelines)
{{ .Values.name | upper | quote }}

# Trim and quote
{{ .Values.description | trim | quote }}

Common Template Functions

Here are functions I use most often:

String Functions:

# Convert to uppercase
{{ .Values.env | upper }}  # PRODUCTION

# Convert to lowercase
{{ .Values.env | lower }}  # production

# Trim whitespace
{{ .Values.name | trim }}

# Trim specific characters
{{ .Values.path | trimSuffix "/" }}

# Replace strings
{{ .Values.url | replace "http://" "https://" }}

# Add quotes (essential for strings in YAML)
{{ .Values.message | quote }}  # "Hello World"

# Repeat string
{{ "=" | repeat 10 }}  # ==========

# Substring
{{ .Values.version | substr 0 3 }}  # "1.2" from "1.2.3"

# String contains
{{ if contains "prod" .Values.environment }}

Default Values:

# Use default if value is empty
{{ .Values.replicas | default 2 }}

# Use first non-empty value
{{ .Values.tag | default .Chart.AppVersion }}

# Complex default
{{ .Values.service.port | default 80 }}

Type Conversion:

# Convert to integer
{{ .Values.port | int }}

# Convert to string
{{ .Values.replicas | toString }}

# Convert to float
{{ .Values.ratio | float64 }}

Encoding:

# Base64 encode
{{ .Values.secret | b64enc }}

# Base64 decode
{{ .Values.encoded | b64dec }}

# URL encoding
{{ .Values.param | urlquery }}

Real-World Example: Dynamic Labels

Here's how I build dynamic labels in my TypeScript app deployments:

metadata:
  labels:
    app.kubernetes.io/name: {{ include "typescript-api.name" . }}
    app.kubernetes.io/instance: {{ .Release.Name }}
    app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
    app.kubernetes.io/component: {{ .Values.component | default "api" }}
    app.kubernetes.io/part-of: {{ .Values.systemName | default "microservices" }}
    app.kubernetes.io/managed-by: {{ .Release.Service }}
    environment: {{ .Values.environment | default "production" | lower }}
    team: {{ .Values.team | default "platform" | trim }}

Conditional Logic

Conditional logic allows charts to adapt to different scenarios.

If/Else Statements

Basic conditional structure:

{{- if .Values.ingress.enabled }}
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: {{ include "typescript-api.fullname" . }}
# ... rest of ingress config
{{- end }}

With else:

{{- if eq .Values.environment "production" }}
replicas: 3
{{- else }}
replicas: 1
{{- end }}

With else if:

{{- if eq .Values.service.type "LoadBalancer" }}
  # LoadBalancer specific config
{{- else if eq .Values.service.type "NodePort" }}
  # NodePort specific config
{{- else }}
  # ClusterIP default config
{{- end }}

Comparison Operators

# Equal
{{- if eq .Values.env "production" }}

# Not equal
{{- if ne .Values.env "development" }}

# Less than
{{- if lt .Values.replicas 3 }}

# Less than or equal
{{- if le .Values.replicas 5 }}

# Greater than
{{- if gt .Values.replicas 10 }}

# Greater than or equal
{{- if ge .Values.replicas 5 }}

# Logical AND
{{- if and .Values.ingress.enabled .Values.tls.enabled }}

# Logical OR
{{- if or .Values.cache.enabled .Values.queue.enabled }}

# NOT
{{- if not .Values.debug }}

Practical Example: Environment-Specific Configuration

This is a pattern I use frequently for TypeScript applications:

apiVersion: v1
kind: ConfigMap
metadata:
  name: {{ include "typescript-api.fullname" . }}-config
data:
  NODE_ENV: {{ .Values.environment | quote }}
  
  {{- if eq .Values.environment "production" }}
  LOG_LEVEL: "warn"
  ENABLE_METRICS: "true"
  CACHE_TTL: "3600"
  {{- else if eq .Values.environment "staging" }}
  LOG_LEVEL: "info"
  ENABLE_METRICS: "true"
  CACHE_TTL: "1800"
  {{- else }}
  LOG_LEVEL: "debug"
  ENABLE_METRICS: "false"
  CACHE_TTL: "300"
  {{- end }}
  
  {{- if .Values.features.authentication }}
  AUTH_ENABLED: "true"
  AUTH_PROVIDER: {{ .Values.auth.provider | quote }}
  {{- end }}
  
  {{- if and .Values.database.enabled (ne .Values.environment "development") }}
  DB_POOL_SIZE: {{ .Values.database.poolSize | quote }}
  DB_TIMEOUT: {{ .Values.database.timeout | quote }}
  {{- end }}

Loops and Ranges

Loops iterate over lists and maps, essential for dynamic configurations.

Range Over Lists

# Simple list iteration
env:
{{- range .Values.additionalEnvVars }}
  - name: {{ .name }}
    value: {{ .value | quote }}
{{- end }}

values.yaml:

additionalEnvVars:
  - name: API_KEY
    value: "abc123"
  - name: REGION
    value: "us-west-2"
  - name: TIMEOUT
    value: "30"

Range Over Maps

# Iterating over a map
data:
{{- range $key, $value := .Values.config }}
  {{ $key }}: {{ $value | quote }}
{{- end }}

values.yaml:

config:
  APP_NAME: "typescript-api"
  MAX_CONNECTIONS: "100"
  FEATURE_A: "enabled"
  FEATURE_B: "disabled"

Range with Index

# With index
{{- range $index, $item := .Values.hosts }}
  - host{{ add $index 1 }}: {{ $item }}
{{- end }}

Practical Example: Multiple Ingress Hosts

This pattern handles multiple domains for a TypeScript API:

{{- if .Values.ingress.enabled }}
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: {{ include "typescript-api.fullname" . }}
  annotations:
    {{- range $key, $value := .Values.ingress.annotations }}
    {{ $key }}: {{ $value | quote }}
    {{- end }}
spec:
  ingressClassName: {{ .Values.ingress.className }}
  {{- if .Values.ingress.tls }}
  tls:
  {{- range .Values.ingress.tls }}
    - hosts:
      {{- range .hosts }}
        - {{ . | quote }}
      {{- end }}
      secretName: {{ .secretName }}
  {{- end }}
  {{- end }}
  rules:
  {{- range .Values.ingress.hosts }}
    - host: {{ .host | quote }}
      http:
        paths:
        {{- range .paths }}
          - path: {{ .path }}
            pathType: {{ .pathType }}
            backend:
              service:
                name: {{ include "typescript-api.fullname" $ }}
                port:
                  number: {{ $.Values.service.port }}
        {{- end }}
  {{- end }}
{{- end }}

Named Templates and Includes

Named templates (also called partials) make charts maintainable and DRY.

Defining Named Templates

In _helpers.tpl:

{{/*
Generate standard labels
*/}}
{{- define "typescript-api.labels" -}}
app.kubernetes.io/name: {{ include "typescript-api.name" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
app.kubernetes.io/managed-by: {{ .Release.Service }}
{{- end }}

{{/*
Generate selector labels
*/}}
{{- define "typescript-api.selectorLabels" -}}
app.kubernetes.io/name: {{ include "typescript-api.name" . }}
app.kubernetes.io/instance: {{ .Release.Name }}
{{- end }}

{{/*
Generate environment variables from values
*/}}
{{- define "typescript-api.env" -}}
- name: NODE_ENV
  value: {{ .Values.environment | quote }}
- name: PORT
  value: {{ .Values.service.targetPort | quote }}
- name: APP_VERSION
  value: {{ .Chart.AppVersion | quote }}
{{- if .Values.redis.enabled }}
- name: REDIS_HOST
  value: {{ include "typescript-api.redis.host" . }}
- name: REDIS_PORT
  value: {{ .Values.redis.port | quote }}
{{- end }}
{{- if .Values.database.enabled }}
- name: DB_HOST
  value: {{ .Values.database.host | quote }}
- name: DB_PORT
  value: {{ .Values.database.port | quote }}
- name: DB_NAME
  value: {{ .Values.database.name | quote }}
{{- end }}
{{- end }}

{{/*
Generate resource limits
*/}}
{{- define "typescript-api.resources" -}}
{{- if .Values.resources }}
resources:
  {{- if .Values.resources.limits }}
  limits:
    {{- if .Values.resources.limits.cpu }}
    cpu: {{ .Values.resources.limits.cpu }}
    {{- end }}
    {{- if .Values.resources.limits.memory }}
    memory: {{ .Values.resources.limits.memory }}
    {{- end }}
  {{- end }}
  {{- if .Values.resources.requests }}
  requests:
    {{- if .Values.resources.requests.cpu }}
    cpu: {{ .Values.resources.requests.cpu }}
    {{- end }}
    {{- if .Values.resources.requests.memory }}
    memory: {{ .Values.resources.requests.memory }}
    {{- end }}
  {{- end }}
{{- end }}
{{- end }}

Using Named Templates

# Include template and indent output
metadata:
  labels:
    {{- include "typescript-api.labels" . | nindent 4 }}

# In Deployment selector
selector:
  matchLabels:
    {{- include "typescript-api.selectorLabels" . | nindent 6 }}

# Environment variables
env:
{{- include "typescript-api.env" . | nindent 2 }}

# Resources
{{- include "typescript-api.resources" . | nindent 10 }}

Template vs Include

template: Inserts template without indentation control
include: Returns string that can be piped (e.g., for nindent)

Always use include with nindent for proper YAML formatting:

# Good - properly indented
metadata:
  labels:
    {{- include "typescript-api.labels" . | nindent 4 }}

# Bad - incorrect indentation
metadata:
  labels:
    {{- template "typescript-api.labels" . }}

Complex Values Manipulation

Merging Values

Combining multiple value sources:

{{- $defaults := .Values.defaultConfig }}
{{- $custom := .Values.customConfig }}
{{- $merged := merge $custom $defaults }}

data:
{{- range $key, $value := $merged }}
  {{ $key }}: {{ $value | quote }}
{{- end }}

Working with Lists

# Check if list contains value
{{- if has "production" .Values.environments }}

# Get list length
{{- if gt (len .Values.hosts) 0 }}

# Append to list
{{- $list := append .Values.domains "example.com" }}

# Concatenate lists
{{- $combined := concat .Values.listA .Values.listB }}

# Get first item
{{- first .Values.items }}

# Get last item
{{- last .Values.items }}

# Remove duplicates
{{- $unique := uniq .Values.items }}

Working with Dictionaries

# Create dictionary
{{- $dict := dict "key1" "value1" "key2" "value2" }}

# Set value
{{- $_ := set $dict "key3" "value3" }}

# Get value
{{- $value := get $dict "key1" }}

# Check if key exists
{{- if hasKey $dict "key1" }}

# Delete key
{{- $_ := unset $dict "key2" }}

# Get all keys
{{- $keys := keys $dict }}

# Pick specific keys
{{- $subset := pick $dict "key1" "key3" }}

# Omit specific keys
{{- $filtered := omit $dict "key2" }}

Advanced Practical Examples

Multi-Environment TypeScript API Configuration

values.yaml:

environments:
  development:
    replicas: 1
    resources:
      limits:
        cpu: 100m
        memory: 128Mi
      requests:
        cpu: 50m
        memory: 64Mi
    config:
      LOG_LEVEL: debug
      ENABLE_PROFILING: "true"
      CACHE_ENABLED: "false"
  
  staging:
    replicas: 2
    resources:
      limits:
        cpu: 200m
        memory: 256Mi
      requests:
        cpu: 100m
        memory: 128Mi
    config:
      LOG_LEVEL: info
      ENABLE_PROFILING: "false"
      CACHE_ENABLED: "true"
  
  production:
    replicas: 3
    resources:
      limits:
        cpu: 500m
        memory: 512Mi
      requests:
        cpu: 200m
        memory: 256Mi
    config:
      LOG_LEVEL: warn
      ENABLE_PROFILING: "false"
      CACHE_ENABLED: "true"

# Active environment
activeEnvironment: production

deployment.yaml:

{{- $env := index .Values.environments .Values.activeEnvironment }}
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "typescript-api.fullname" . }}
spec:
  replicas: {{ $env.replicas }}
  template:
    spec:
      containers:
      - name: {{ .Chart.Name }}
        resources:
          {{- toYaml $env.resources | nindent 10 }}
        env:
        {{- range $key, $value := $env.config }}
        - name: {{ $key }}
          value: {{ $value | quote }}
        {{- end }}
        - name: ENVIRONMENT
          value: {{ .Values.activeEnvironment | quote }}

Dynamic Feature Flags

values.yaml:

features:
  authentication:
    enabled: true
    config:
      provider: "oauth2"
      timeout: 30
  
  caching:
    enabled: true
    config:
      backend: "redis"
      ttl: 3600
  
  metrics:
    enabled: true
    config:
      exporter: "prometheus"
      port: 9090
  
  tracing:
    enabled: false
    config:
      provider: "jaeger"
      endpoint: "http://jaeger:14268"

configmap.yaml:

apiVersion: v1
kind: ConfigMap
metadata:
  name: {{ include "typescript-api.fullname" . }}-features
data:
  features.json: |
    {
      {{- $features := list }}
      {{- range $name, $config := .Values.features }}
      {{- if $config.enabled }}
      {{- $features = append $features (printf "\"%s\": %s" $name ($config.config | toJson)) }}
      {{- end }}
      {{- end }}
      {{- $features | join ",\n      " | nindent 6 }}
    }

Dynamic Service Ports

values.yaml:

service:
  type: ClusterIP
  ports:
    - name: http
      port: 80
      targetPort: 3000
      protocol: TCP
    - name: metrics
      port: 9090
      targetPort: 9090
      protocol: TCP
    - name: health
      port: 8080
      targetPort: 8080
      protocol: TCP

service.yaml:

apiVersion: v1
kind: Service
metadata:
  name: {{ include "typescript-api.fullname" . }}
spec:
  type: {{ .Values.service.type }}
  ports:
  {{- range .Values.service.ports }}
    - name: {{ .name }}
      port: {{ .port }}
      targetPort: {{ .targetPort }}
      protocol: {{ .protocol }}
      {{- if and (eq $.Values.service.type "NodePort") .nodePort }}
      nodePort: {{ .nodePort }}
      {{- end }}
  {{- end }}
  selector:
    {{- include "typescript-api.selectorLabels" . | nindent 4 }}

Template Variables and Scope

Understanding variable scope prevents common errors.

Local Variables

{{- $releaseName := .Release.Name }}
{{- $chartName := .Chart.Name }}
{{- $fullName := include "typescript-api.fullname" . }}

metadata:
  name: {{ $fullName }}
  labels:
    release: {{ $releaseName }}
    chart: {{ $chartName }}

Variables in Ranges

Inside range loops, . changes context:

# $ holds root context
{{- range .Values.services }}
apiVersion: v1
kind: Service
metadata:
  name: {{ include "typescript-api.fullname" $ }}-{{ .name }}
  labels:
    {{- include "typescript-api.labels" $ | nindent 4 }}
    service: {{ .name }}
spec:
  type: {{ .type }}
  ports:
    - port: {{ .port }}
      targetPort: {{ .targetPort }}
  selector:
    {{- include "typescript-api.selectorLabels" $ | nindent 4 }}
    component: {{ .name }}
---
{{- end }}

Notice $ is used to access root values inside the range.

With Blocks

with changes scope to a specific value:

{{- with .Values.ingress }}
{{- if .enabled }}
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: {{ include "typescript-api.fullname" $ }}
  {{- with .annotations }}
  annotations:
    {{- toYaml . | nindent 4 }}
  {{- end }}
spec:
  ingressClassName: {{ .className }}
  # ... more config
{{- end }}
{{- end }}

Template Comments and Formatting

Comments

{{/* This is a comment - won't appear in output */}}

{{- /* 
Multi-line comment
Still won't appear in output
*/}}

Whitespace Control

Control whitespace with -:

# Remove whitespace before
{{- .Values.name }}

# Remove whitespace after
{{ .Values.name -}}

# Remove whitespace before and after
{{- .Values.name -}}

This is crucial for clean YAML output:

# Without whitespace control - bad
{{ if .Values.enabled }}
enabled: true
{{ end }}

# Output has blank lines

# With whitespace control - good
{{- if .Values.enabled }}
enabled: true
{{- end }}

# Output is clean

Debugging Templates

Debug Output

# Print value for debugging
{{ .Values | toYaml }}

# Print specific value
{{ printf "Debug: %v" .Values.replicas }}

# Fail template rendering with message
{{ fail "Custom error message" }}

# Required value (fails if empty)
{{ required "image.repository is required" .Values.image.repository }}

Testing Templates

# Render template to see output
helm template my-release ./chart

# Render specific template
helm template my-release ./chart -s templates/deployment.yaml

# With debug output
helm template my-release ./chart --debug

# With custom values
helm template my-release ./chart --set replicas=5 --debug

What's Next?

We've covered advanced templating that handles complex scenarios. In Part 4, we'll explore:

Managing chart dependencies
Working with subcharts
Creating and hosting chart repositories
Consuming charts from Artifact Hub
Chart versioning strategies
Library charts for shared templates

Series Navigation: ← Part 2: Creating Your First Chart | Back to Series Overview | Part 4: Chart Dependencies and Repositories →

Key Takeaways

✅ Pipelines chain functions for powerful value transformations
✅ Conditional logic enables environment-specific configurations
✅ Range loops handle dynamic lists and maps efficiently
✅ Named templates promote DRY principles and maintainability
✅ Always use include with nindent for proper YAML formatting
✅ Understand variable scope, especially in loops and with blocks
✅ Whitespace control with - produces clean YAML output
✅ Debug templates with helm template and --debug flag

PreviousPart 2: Creating Your First Chart NextPart 4: Chart Dependencies and Repositories

Last updated 12 days ago

hashtagIntroduction

hashtagTemplate Functions and Pipelines

hashtagBasic Pipelines

hashtagCommon Template Functions

hashtagReal-World Example: Dynamic Labels

hashtagConditional Logic

hashtagIf/Else Statements

hashtagComparison Operators

hashtagPractical Example: Environment-Specific Configuration

hashtagLoops and Ranges

hashtagRange Over Lists

hashtagRange Over Maps

hashtagRange with Index

hashtagPractical Example: Multiple Ingress Hosts

hashtagNamed Templates and Includes

hashtagDefining Named Templates

hashtagUsing Named Templates

hashtagTemplate vs Include

hashtagComplex Values Manipulation

hashtagMerging Values

hashtagWorking with Lists

hashtagWorking with Dictionaries

hashtagAdvanced Practical Examples

hashtagMulti-Environment TypeScript API Configuration

hashtagDynamic Feature Flags

hashtagDynamic Service Ports

hashtagTemplate Variables and Scope

hashtagLocal Variables

hashtagVariables in Ranges

hashtagWith Blocks

hashtagTemplate Comments and Formatting

hashtagComments

hashtagWhitespace Control

hashtagDebugging Templates

hashtagDebug Output

hashtagTesting Templates

hashtagWhat's Next?

hashtagKey Takeaways

Introduction

Template Functions and Pipelines

Basic Pipelines

Common Template Functions

Real-World Example: Dynamic Labels

Conditional Logic

If/Else Statements

Comparison Operators

Practical Example: Environment-Specific Configuration

Loops and Ranges

Range Over Lists

Range Over Maps

Range with Index

Practical Example: Multiple Ingress Hosts

Named Templates and Includes

Defining Named Templates

Using Named Templates

Template vs Include

Complex Values Manipulation

Merging Values

Working with Lists

Working with Dictionaries

Advanced Practical Examples

Multi-Environment TypeScript API Configuration

Dynamic Feature Flags

Dynamic Service Ports

Template Variables and Scope

Local Variables

Variables in Ranges

With Blocks

Template Comments and Formatting

Comments

Whitespace Control

Debugging Templates

Debug Output

Testing Templates

What's Next?

Key Takeaways