Curso Kubernetes 21 — Helm: empaquetando la aplicación

Hasta aquí hemos aplicado manifiestos a mano. Funciona para aprender, no escala: cada entorno se convierte en una copia con diferencias invisibles, y nadie sabe qué versión está corriendo.

Helm resuelve el problema de empaquetar y versionar el despliegue. No es magia: es template + values + un registro de releases.

Sello del curso: probado en Kubernetes 1.35 con Helm 3.

El problema real

Sin Helm, tres entornos suelen convertirse en tres carpetas:

k8s/
  homolog/deployment.yaml
  prod/deployment.yaml
  staging/deployment.yaml

Diferencias: imagen, réplicas, recursos, variables. Un día alguien corrige solo en prod y el resto queda mal. Es el comienzo del drift.

Con Helm:

chart/
  Chart.yaml
  values.yaml
  values-homolog.yaml
  values-prod.yaml
  templates/
    deployment.yaml
    service.yaml
    ingress.yaml
    _helpers.tpl

Un template, tres conjuntos de valores.

Estructura mínima

Chart.yaml:

apiVersion: v2
name: portal
description: Portal Nyverra
type: application
version: 1.4.0
appVersion: "v5"

• version: versión del chart.
• appVersion: versión de la aplicación (imagen).

Son cosas diferentes. Confunde las dos y pierdes la trazabilidad.

Templates y values

values.yaml (valores por defecto):

replicaCount: 2
image:
  repository: ghcr.io/example/portal-backend
  tag: v5
  pullPolicy: IfNotPresent
resources:
  requests:
    cpu: 100m
    memory: 256Mi
  limits:
    cpu: "1"
    memory: 512Mi
env:
  LOG_LEVEL: info

templates/deployment.yaml:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: {{ include "portal.fullname" . }}
  labels:
    {{- include "portal.labels" . | nindent 4 }}
spec:
  replicas: {{ .Values.replicaCount }}
  selector:
    matchLabels:
      {{- include "portal.selectorLabels" . | nindent 6 }}
  template:
    metadata:
      labels:
        {{- include "portal.selectorLabels" . | nindent 8 }}
    spec:
      containers:
        - name: backend
          image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
          imagePullPolicy: {{ .Values.image.pullPolicy }}
          resources:
            {{- toYaml .Values.resources | nindent 12 }}
          env:
            {{- range $k, $v := .Values.env }}
            - name: {{ $k }}
              value: {{ $v | quote }}
            {{- end }}

_helpers.tpl centraliza nombres y labels. Sin eso, cada template inventa un nombre diferente y el kubectl get se convierte en arqueología.

Values por entorno

values-prod.yaml:

replicaCount: 4
image:
  tag: v5
resources:
  requests:
    cpu: 500m
    memory: 512Mi
  limits:
    cpu: "2"
    memory: 1Gi

Renderiza sin aplicar:

helm template portal ./chart -f values-prod.yaml
helm template portal ./chart -f values-prod.yaml --show-only templates/deployment.yaml

Siempre revisa el render antes del install. Es el --dry-run de Helm.

Install, upgrade, rollback

helm upgrade --install portal ./chart -n portal --create-namespace -f values-prod.yaml
helm list -n portal
helm status portal -n portal
helm history portal -n portal
helm rollback portal 3 -n portal

Helm guarda releases como Secrets en el namespace (sh.helm.release.v1.portal.v1). No los borres a mano.

Hooks

Los hooks se ejecutan en momentos del ciclo:

• pre-install / pre-upgrade: migraciones de base de datos.
• post-install / post-upgrade: smoke test.
• pre-delete: limpieza.

metadata:
  annotations:
    "helm.sh/hook": pre-upgrade
    "helm.sh/hook-weight": "-5"
    "helm.sh/hook-delete-policy": before-hook-creation

Cuidado: la migración en el hook se ejecuta antes del rollout. Si la nueva versión del código depende de la migración, ok. Si la migración rompe la versión antigua, tienes una ventana de error.

Qué no poner en el chart

• Secretos reales en values.yaml (usa External Secrets o secret manager).
• Credenciales de registry en texto plano.
• Configuración que cambia por cluster y debería ser GitOps (capítulo 22).

Laboratorio

1. Crea el chart:

helm create portal
rm -rf portal/templates/tests

2. Ajusta values.yaml, _helpers.tpl y los templates.

3. Renderiza y compara entornos:

helm template portal ./portal -f values-homolog.yaml > /tmp/homolog.yaml
helm template portal ./portal -f values-prod.yaml > /tmp/prod.yaml
diff /tmp/homolog.yaml /tmp/prod.yaml

4. Instala en homolog y haz un upgrade con --atomic:

helm upgrade --install portal ./portal -n portal --create-namespace \
  -f values-homolog.yaml --atomic --timeout 5m

5. Fuerza un fallo (imagen inexistente) y observa cómo --atomic revierte solo.

6. helm rollback manual y verifica helm history.

Errores comunes

Síntoma	Causa
rendered manifests contain a resource that already exists	recurso creado fuera de Helm
Upgrade atascado en pending-upgrade	hook/rollout falló sin timeout
Valores ignorados	-f en el orden incorrecto o typo en la clave
nil pointer evaluating interface	clave ausente en values
Drift silencioso	recurso editado a mano después del install
Rollback no vuelve a la imagen	appVersion divergente del tag
Secret filtrado en Git	valor sensible en values.yaml

Checklist

• [ ] Chart.yaml con version y appVersion coherentes.
• [ ] _helpers.tpl para nombres y labels.
• [ ] values-<env>.yaml por entorno.
• [ ] helm template revisado antes del upgrade.
• [ ] --atomic y --timeout en el upgrade.
• [ ] Recursos (requests/limits) provenientes de values.
• [ ] Ningún secreto en texto plano en el chart.
• [ ] helm history y rollback probados.

Glosario

• chart: paquete Helm.
• release: instancia de un chart en el cluster.
• values: parámetros del template.
• hook: recurso ejecutado en fase del ciclo.
• atomic: revierte automáticamente en fallo.
• drift: diferencia entre lo declarado y lo que se ejecuta.

Próximo

Chart empaquetado. Ahora, ¿quién aplica el chart en el cluster? En el próximo capítulo, GitOps con ArgoCD: Git como fuente de verdad y el cluster corrigiéndose solo.

Próximo: Curso Kubernetes 22 — GitOps con ArgoCD