La mayor parte de lo que hace un chart es declarar recursos que se mantienen en ejecución. A veces necesitas algo que se ejecute una sola vez en un momento concreto: una migración de base de datos antes de una actualización, un trabajo de limpieza tras una desinstalación o una comprobación de que el release realmente funciona una vez levantado. Helm cubre ambos casos con hooks y tests de chart.

Qué es un hook

Un hook es un recurso de Kubernetes corriente, con más frecuencia un Job, anotado para indicarle a Helm cuándo ejecutarlo en relación con una instalación, actualización, rollback o desinstalación:

# templates/hooks/pre-install-job.yaml
apiVersion: batch/v1
kind: Job
metadata:
  name: {{ .Values.appName }}-pre-install
  annotations:
    "helm.sh/hook": pre-install
    "helm.sh/hook-weight": "0"
    "helm.sh/hook-delete-policy": before-hook-creation,hook-succeeded
spec:
  template:
    spec:
      restartPolicy: Never
      containers:
        - name: migrate
          image: myorg/webapp-migrate:1.0
          command: ["./run-migrations.sh"]

La anotación helm.sh/hook es lo que convierte esto en un hook en lugar de un recurso normal que Helm rastrea como parte del release. Los puntos de hook habituales son pre-install, post-install, pre-upgrade, post-upgrade, pre-rollback, post-rollback, pre-delete y post-delete; la lista completa, que incluye un par relacionados con tests, está en la documentación de hooks de Helm.

Cómo secuencia Helm un hook

Para un hook pre-install:

1. Helm renderiza el recurso del hook y lo crea en el clúster, antes que cualquier otra cosa del chart.
2. Helm espera a que alcance un estado de listo o completado (un Job que se ejecuta hasta terminar cuenta).
3. Solo entonces Helm renderiza y aplica el resto de los recursos del chart.

post-install invierte los pasos 1 y 3: los recursos normales del chart entran primero y luego se ejecuta el hook. Un hook pre-upgrade que falla detiene la actualización, que es justo el objetivo de ejecutar una migración ahí en lugar de esperar que tenga éxito después.

Peso del hook y política de eliminación

helm.sh/hook-weight ordena varios hooks en el mismo punto: los números más bajos se ejecutan primero, como cadenas de texto ("0", "5"), y los hooks sin peso toman 0 por defecto. helm.sh/hook-delete-policy controla la limpieza, ya que un Job completado de otro modo permanece indefinidamente en el clúster:

• before-hook-creation (el predeterminado): elimina el recurso de hook anterior antes de crear uno nuevo, para que los reintentos no choquen con un Job sobrante del mismo nombre.
• hook-succeeded: elimina el recurso una vez que se completa con éxito.
• hook-failed: lo elimina si falla, útil cuando prefieres limpiar a dejar un Job fallido para inspeccionarlo; omítelo si quieres hacer kubectl logs de un fallo antes de que se elimine.

Una combinación pre-install,hook-succeeded, por ejemplo, significa que el hook se ejecuta una vez, tiene éxito y se limpia solo, sin dejar rastro más allá de la propia salida de tu Job; añade también hook-failed si tampoco quieres que un intento fallido se quede por ahí.

Pruébalo

kubectl get jobs -w

En otra terminal:

helm install web ./webapp

Mirando la primera terminal, deberías ver aparecer el Job del hook, ejecutarse, completarse y (según su política de eliminación) desaparecer, todo antes de que aparezca el Deployment del chart. Es la forma más fácil de ver realmente la secuenciación en lugar de darla por buena.

Tests de chart: verifica un release una vez levantado

Un test de chart es un Job que se ejecuta bajo demanda, después de que exista un release, para comprobar que realmente funciona:

# templates/tests/test-connection.yaml
apiVersion: v1
kind: Pod
metadata:
  name: "{{ .Values.appName }}-test-connection"
  annotations:
    "helm.sh/hook": test
spec:
  containers:
    - name: wget
      image: busybox:1.36
      command: ["wget", "-qO-", "{{ .Values.appName }}"]
  restartPolicy: Never

helm install web ./webapp
helm test web

helm test ejecuta todos los recursos anotados con helm.sh/hook: test en el release e informa de éxito o fallo según el estado de salida de cada Pod; un wget que obtiene respuesta sale con 0, uno que no puede conectar no. A diferencia de los hooks de instalación/actualización, los recursos de test no se eliminan automáticamente por defecto; ejecuta helm test --logs para ver su salida en línea, o límpialos tú mismo entre ejecuciones.

Cuándo usar cada uno

• Usa un hook cuando algo deba ocurrir exactamente una vez, en un punto concreto del ciclo de vida de un release, y el resto del despliegue deba esperar o reaccionar a ello: migraciones de esquema antes de una actualización, notificar a un sistema externo tras la instalación, limpiar recursos externos antes de una desinstalación.
• Usa un test de chart para cualquier cosa que quieras volver a ejecutar bajo demanda contra un release que ya está en marcha, con mayor frecuencia como smoke test tras helm install o helm upgrade en un pipeline de CI, sin que forme parte de la secuencia de despliegue en sí.

Ambos son recursos de Kubernetes corrientes por debajo de las anotaciones, así que todo lo que ya sepas sobre depurar un Job o un Pod, kubectl describe, kubectl logs, se aplica directamente.