Helm empaqueta una aplicación de Kubernetes en un chart: un directorio de manifiestos con plantillas más un conjunto de valores predeterminados. Esta guía cubre la estructura de carpetas que comparte todo chart y los tres conceptos, chart, values y release, sobre los que se construye todo lo demás en Helm.

Por qué no simplemente escribir manifiestos planos

Una aplicación no trivial rara vez es un solo Deployment. Es un Deployment, un Service, un ConfigMap, quizá un Secret y un Ingress, y quieres el mismo conjunto desplegado en dev, staging y producción con solo un puñado de valores distintos entre ellos: una etiqueta de imagen, un número de réplicas, un namespace. Copiar y pegar manifiestos por entorno significa que cada campo compartido puede desincronizarse. Un chart guarda los manifiestos una sola vez, como plantillas, y deja que cada instalación aporte sus propios valores.

La estructura de carpetas

helm create webapp

Esto genera:

webapp/
├── Chart.yaml           # metadatos del chart: nombre, versión, descripción
├── values.yaml          # valores de configuración predeterminados
├── charts/              # cualquier chart del que dependa este
├── .helmignore
└── templates/
    ├── deployment.yaml
    ├── service.yaml
    ├── _helpers.tpl      # fragmentos de plantilla reutilizables
    ├── NOTES.txt         # se imprime tras install/upgrade
    └── tests/
        └── test-connection.yaml

Chart.yaml son metadatos sobre el propio chart, sobre todo su nombre, versión y apiVersion (v2 para Helm 3 y el actual Helm 4). values.yaml contiene la configuración predeterminada. templates/ contiene manifiestos de Kubernetes con la sintaxis de plantillas de Helm mezclada. charts/ contiene los charts de los que depende este, algo que solo surge cuando empiezas a componer charts entre sí. El ejemplo generado es un chart nginx funcional con más de lo que normalmente necesitas; la mayoría de los equipos o borran el andamiaje y escriben sus propias tres o cuatro plantillas, o recortan lo que no aplica.

Los valores fluyen hacia las plantillas

Una plantilla se parece a un manifiesto normal con marcadores de posición:

# templates/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ .Values.appName }}
spec:
  replicas: {{ .Values.replicaCount }}
  template:
    spec:
      containers:
        - name: {{ .Values.appName }}
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"

# values.yaml
appName: webapp
replicaCount: 2
image:
  repository: nginx
  tag: "1.25"

.Values es un objeto construido a partir de values.yaml, fusionado con todo lo que se aporte en la línea de comandos. Ejecutar helm install o helm template renderiza cada archivo de templates/ con ese objeto, produciendo YAML plano de Kubernetes. La sintaxis {{ }} son plantillas de Go, el mismo lenguaje de plantillas usado en otras partes del ecosistema de Kubernetes, así que no hay nada propietario que aprender más allá de ella. Los valores pueden sobrescribirse de tres maneras, en orden creciente de precedencia: los valores predeterminados de values.yaml, un archivo adicional pasado con -f y flags individuales --set clave=valor en la línea de comandos.

Un release es un despliegue concreto de un chart

Renderizar un chart y aplicar el resultado a un clúster crea un release: una instalación con nombre y rastreada, con su propio historial.

helm install web-dev ./webapp
helm list

web-dev es el nombre del release. Puedes instalar el mismo chart varias veces con nombres de release distintos, en el mismo namespace o en distintos, por ejemplo web-dev y web-staging. Cada helm upgrade sobre un release añade una nueva revisión a su historial, que es exactamente lo que hace posible helm rollback más adelante: Helm no solo aplica YAML, rastrea qué se aplicó y cuándo. La guía de gestión de releases de esta serie cubre ese flujo de trabajo completo.

Para qué sirve NOTES.txt

templates/NOTES.txt es texto plano, también con plantillas del mismo modo, que Helm imprime tras install o upgrade. Úsalo para decirle a quien instaló el chart qué hacer a continuación: un comando kubectl port-forward, la URL en la que será accesible un Service o un primer paso de arranque. No tiene ningún efecto sobre el clúster; es puramente un mensaje para la persona que ejecuta el comando.

De dónde vienen los charts

No tienes que escribir todos los charts tú mismo. Los charts públicos para software común, bases de datos, stacks de monitorización, ingress controllers, se publican en Artifact Hub y se instalan con un solo comando. El resto de esta serie cubre primero cómo escribir tu propio chart y luego cómo encontrar e instalar los publicados.