Helm Sprig toString Function Guide

💡 Quick Answer: The Sprig toString function converts any value to its string representation: {{ .Values.port | toString }} converts the integer 8080 to the string "8080". Essential when Helm values are numbers but YAML fields require strings — like container ports in annotations or ConfigMap data.

The Problem

Helm values in values.yaml can be integers, booleans, or other types, but many Kubernetes fields (annotations, ConfigMap data, environment variables) require strings. Without explicit conversion, Helm renders numbers as 8080 instead of "8080", causing YAML parsing errors or unexpected behavior.

The Solution

Basic Syntax

# Convert integer to string
{{ .Values.port | toString }}
# Input: 8080 → Output: "8080"

# Convert boolean to string
{{ .Values.debug | toString }}
# Input: true → Output: "true"

# Convert float to string
{{ .Values.ratio | toString }}
# Input: 0.75 → Output: "0.75"

Common Use Cases

ConfigMap Data (Must Be Strings)

# values.yaml
config:
  port: 8080
  workers: 4
  debug: true

# templates/configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: {{ .Release.Name }}-config
data:
  PORT: {{ .Values.config.port | toString | quote }}
  WORKERS: {{ .Values.config.workers | toString | quote }}
  DEBUG: {{ .Values.config.debug | toString | quote }}

Annotations (Always Strings)

metadata:
  annotations:
    prometheus.io/port: {{ .Values.metrics.port | toString | quote }}
    app.kubernetes.io/version: {{ .Chart.AppVersion | toString | quote }}
    replicas: {{ .Values.replicaCount | toString | quote }}

Environment Variables

env:
  - name: SERVER_PORT
    value: {{ .Values.port | toString | quote }}
  - name: MAX_CONNECTIONS
    value: {{ .Values.maxConn | toString | quote }}
  - name: ENABLE_TLS
    value: {{ .Values.tls.enabled | toString | quote }}

toString vs Other Conversion Functions

Handling Nil Values

# If .Values.optional is nil, toString returns ""
{{ .Values.optional | toString }}
# Output: ""

# Use default to provide fallback BEFORE toString
{{ .Values.optional | default 3000 | toString }}
# Output: "3000"

Real-World Example: Ingress Annotations

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    nginx.ingress.kubernetes.io/proxy-body-size: {{ .Values.ingress.maxBodySize | toString | quote }}
    nginx.ingress.kubernetes.io/proxy-read-timeout: {{ .Values.ingress.readTimeout | toString | quote }}
    nginx.ingress.kubernetes.io/limit-rps: {{ .Values.ingress.rateLimit | toString | quote }}

# values.yaml
ingress:
  maxBodySize: 50  # Will become "50"
  readTimeout: 120  # Will become "120"
  rateLimit: 10  # Will become "10"

Common Issues

”cannot convert nil to string”

# Problem: value doesn't exist
{{ .Values.missing | toString }}

# Fix: always provide a default
{{ .Values.missing | default "" | toString }}

Double Quoting

# Wrong: toString + quote on a value that's already a string
# Produces: '"already-a-string"' (double quoted)

# Right: use quote OR toString, check the type
{{ if kindIs "string" .Values.port }}
  {{ .Values.port | quote }}
{{ else }}
  {{ .Values.port | toString | quote }}
{{ end }}

List to String

# toString on a list produces Go syntax: [a b c]
{{ .Values.tags | toString }}
# Output: "[tag1 tag2 tag3]"

# Better: use join for lists
{{ .Values.tags | join "," }}
# Output: "tag1,tag2,tag3"

toStrings — Convert Every List Item

toStrings (plural) is the list-aware sibling of toString: it converts each element of a list to a string and returns a list, rather than collapsing the list into Go’s bracket syntax.

# toStrings converts every item, keeps it a list
{{ list 1 2 3 | toStrings }}
# Output: ["1" "2" "3"]

# Useful before join when items are mixed/non-string types
{{ list 1 2 3 | toStrings | join "," }}
# Output: "1,2,3"

Best Practices

• Always toString before quote for numeric values in annotations
• Use default before toString — handle nil values gracefully
• Prefer join for lists — toString on lists produces ugly Go syntax
• Use toStrings when you need a list back — converts each item, keeps the list shape, instead of collapsing to Go’s [a b c] syntax
• Check types with kindIs — avoid double conversion
• Use toJson for complex objects — maps and nested structures

Key Takeaways

• toString converts integers, booleans, and floats to string representation
• Essential for ConfigMap data, annotations, and environment variables
• Always pair with quote for proper YAML output: | toString | quote
• Use default before toString to handle nil values
• For lists, prefer join over toString