La forma más rápida de aprender las plantillas de Helm es tomar manifiestos que ya entiendes y convertirlos en plantillas campo por campo. Esta guía parte de un Deployment, un Service y un ConfigMap planos, genera el andamiaje de un chart y sustituye los campos que deberían variar por valores.

Genera el andamiaje de un chart y despeja el ejemplo

helm create webapp
cd webapp
rm -rf templates/tests templates/hpa.yaml templates/ingress.yaml \
       templates/serviceaccount.yaml templates/_helpers.tpl

Los templates/deployment.yaml y templates/service.yaml generados son un ejemplo funcional, pero para aprender es más claro escribir los tuyos desde cero. Vacía su contenido (deja los archivos) y vacía values.yaml:

: > values.yaml

Añade tus propios manifiestos

Escribe primero YAML plano de Kubernetes, exactamente como lo harías sin Helm:

# templates/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-webapp
  labels:
    app: my-webapp
spec:
  replicas: 3
  selector:
    matchLabels:
      app: my-webapp
  template:
    metadata:
      labels:
        app: my-webapp
    spec:
      containers:
        - name: my-webapp
          image: myorg/webapp:1.0
          envFrom:
            - configMapRef:
                name: my-webapp-config
          ports:
            - containerPort: 8080

# templates/service.yaml
apiVersion: v1
kind: Service
metadata:
  name: my-webapp
spec:
  selector:
    app: my-webapp
  ports:
    - port: 80
      targetPort: 8080

# templates/configmap.yaml
apiVersion: v1
kind: ConfigMap
metadata:
  name: my-webapp-config
data:
  CUSTOM_HEADER: "this app was deployed with Helm"

Fíjate en que la misma cadena, my-webapp, se repite en el nombre, la etiqueta, el selector y la referencia del ConfigMap. Esa repetición es exactamente lo que hace que los manifiestos multi-entorno mantenidos a mano sean propensos a errores: renombra la aplicación una vez y tienes cuatro lugares que revisar.

Sustituye los valores repetidos por un valor de plantilla

Introduce un valor y haz referencia a él en todos los lugares donde aparece el nombre:

# values.yaml
appName: my-webapp

# templates/deployment.yaml (extracto)
metadata:
  name: {{ .Values.appName }}
  labels:
    app: {{ .Values.appName }}
spec:
  selector:
    matchLabels:
      app: {{ .Values.appName }}
  template:
    metadata:
      labels:
        app: {{ .Values.appName }}
    spec:
      containers:
        - name: {{ .Values.appName }}
          envFrom:
            - configMapRef:
                name: {{ .Values.appName }}-config

Haz lo mismo en service.yaml y configmap.yaml dondequiera que aparezca my-webapp. .Values se rellena desde values.yaml, así que un único cambio allí ahora renombra todos los recursos de forma coherente.

Convierte en plantilla la imagen y los datos del ConfigMap

Divide la imagen en sus propios valores para que la etiqueta pueda cambiar independientemente del repositorio:

# values.yaml (añadir)
image:
  repository: myorg/webapp
  tag: "1.0"

        - name: {{ .Values.appName }}
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"

Y el contenido del ConfigMap:

# values.yaml (añadir)
config:
  customHeader: "this app was deployed with Helm"

# templates/configmap.yaml
data:
  CUSTOM_HEADER: {{ .Values.config.customHeader | quote }}

El filtro | quote envuelve el valor entre comillas dobles, lo que importa cuando los valores específicos de cada entorno empiezan a contener espacios o caracteres especiales. Una buena regla para nombrar tus valores: refleja la propia estructura del manifiesto (config.customHeader corresponde al data.CUSTOM_HEADER de un ConfigMap), de modo que quien lea la plantilla pueda adivinar de dónde viene un valor.

Previsualiza antes de instalar

Dos comandos renderizan el chart sin tocar un clúster:

helm template ./webapp
helm install my-webapp ./webapp --dry-run --debug

helm template renderiza en local y no necesita ningún clúster. --dry-run --debug en install además valida contra la API del clúster sin persistir nada. Ejecuta uno de los dos tras cada cambio de plantilla; un error tipográfico en {{ .Values.appname }} (mayúsculas/minúsculas incorrectas) se renderiza en silencio como vacío en lugar de dar error, y esta es la forma más rápida de detectarlo.

Instala y confirma

helm install my-webapp ./webapp
kubectl get all -l app=my-webapp

my-webapp aquí es el nombre del release y ./webapp es el directorio del chart. Nada en instalar un chart escrito a mano difiere de instalar uno publicado.

Cambia un valor y actualiza

Edita values.yaml (sube image.tag, cambia config.customHeader, lo que estés probando) y aplica el cambio:

helm upgrade my-webapp ./webapp
helm list

helm list ahora muestra la revisión 2. Cada upgrade vuelve a aplicar todo el chart con los valores actuales, así que esta es también la forma de desplegar una nueva versión día a día.

Añade un NOTES.txt

# templates/NOTES.txt
Your release "{{ .Release.Name }}" has been deployed.

To access {{ .Values.appName }}, run:
  kubectl port-forward svc/{{ .Values.appName }} 8080:80

.Release.Name es un valor incorporado que Helm siempre proporciona, junto con .Chart y .Release.Namespace; no lo defines tú. Ejecuta helm upgrade my-webapp ./webapp de nuevo y este texto se imprime en la terminal, con el comando de port-forward ya rellenado para quien esté mirando.