Profundizando en las plantillas de Helm

Introducción

Las plantillas de Helm son manifiestos de Kubernetes enriquecidos con el lenguaje de plantillas text/template de Go. Se encuentran en el directorio templates/ del chart y Helm las renderiza usando los valores de values.yaml y cualquier sobrescritura del usuario. Entenderlas es clave para escribir charts mantenibles y reutilizables.

Conceptos básicos de plantillas

Una plantilla de Deployment mínima:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ .Release.Name }}-app
  labels:
    app: {{ .Chart.Name }}
spec:
  replicas: {{ .Values.replicaCount }}
  selector:
    matchLabels:
      app: {{ .Chart.Name }}
  template:
    metadata:
      labels:
        app: {{ .Chart.Name }}
    spec:
      containers:
        - name: {{ .Chart.Name }}
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"

Objetos integrados

Objeto	Descripción
`.Release`	Info del release actual: `.Release.Name`, `.Release.Namespace`
`.Chart`	Contenido de `Chart.yaml`: `.Chart.Name`, `.Chart.Version`
`.Values`	Valores combinados de `values.yaml` y sobrescrituras del usuario
`.Files`	Acceso a archivos no-plantilla incluidos en el chart

Funciones de plantilla

Helm incluye la librería Sprig de Go con más de 60 funciones:

# Valor por defecto cuando está vacío
image: {{ .Values.image | default "nginx:latest" }}

# Entrecomillar una cadena de forma segura
annotation: {{ .Values.description | quote }}

# Convertir a mayúsculas
name: {{ .Values.name | upper }}

# Formatear cadenas
fullname: {{ printf "%s-%s" .Release.Name .Chart.Name }}

# Indentar un bloque multi-línea (crítico para YAML anidado)
resources:
  {{- toYaml .Values.resources | nindent 2 }}

Condicionales

spec:
  {{- if .Values.resources }}
  resources:
    {{- toYaml .Values.resources | nindent 4 }}
  {{- end }}
  {{- if .Values.nodeSelector }}
  nodeSelector:
    {{- toYaml .Values.nodeSelector | nindent 4 }}
  {{- else }}
  nodeSelector: {}
  {{- end }}

El - en {{- elimina espacios en blanco al inicio; -}} los elimina al final. Esto es esencial para producir YAML limpio.

Bucles con range

Iterar sobre una lista:

env:
{{- range .Values.envVars }}
  - name: {{ .name }}
    value: {{ .value | quote }}
{{- end }}

Iterar sobre un mapa:

annotations:
{{- range $key, $val := .Values.annotations }}
  {{ $key }}: {{ $val | quote }}
{{- end }}

Plantillas con nombre

Las plantillas con nombre evitan la repetición entre archivos. Por convención viven en _helpers.tpl (el prefijo _ evita que Helm renderice el archivo como un manifiesto):

{{/* _helpers.tpl */}}
{{- define "myapp.labels" -}}
helm.sh/chart: {{ .Chart.Name }}-{{ .Chart.Version }}
app.kubernetes.io/name: {{ .Chart.Name }}
app.kubernetes.io/instance: {{ .Release.Name }}
app.kubernetes.io/managed-by: {{ .Release.Service }}
{{- end }}

Úselas en otras plantillas con include:

metadata:
  labels:
    {{- include "myapp.labels" . | nindent 4 }}

Prefiera siempre include sobre la acción template integrada, ya que include devuelve una cadena que puede pasarse a funciones como nindent.

Depuración de plantillas

Renderice las plantillas localmente sin desplegar en el clúster:

# Renderizar todas las plantillas
helm template my-release ./my-chart

# Renderizar con valores personalizados
helm template my-release ./my-chart -f custom-values.yaml

# Validar y hacer lint
helm lint ./my-chart

Para inspeccionar un objeto renderizado durante el desarrollo, vuélquelo temporalmente a YAML:

{{- toYaml .Values | nindent 0 }}

Si deseas apoyarme, invítame un café.