Helm es el gestor de paquetes de Kubernetes. Agrupa los manifiestos de una aplicación (Deployments, Services, ConfigMaps, etc.) en un paquete versionado llamado chart, que se instala con valores configurables y se puede actualizar o revertir como una unidad. En este tutorial instalarás Helm en una máquina con Ubuntu 24.04, desplegarás una aplicación desde un repositorio público, cambiarás su configuración, harás un rollback y crearás un chart propio.

Requisitos previos

Para seguir esta guía necesitas:

  • Una máquina con Ubuntu 24.04 LTS desde la que administras el clúster (tu equipo o un servidor, por ejemplo un VPS de CubePath), con un usuario no root con sudo.
  • Un clúster de Kubernetes en funcionamiento (gestionado, k3s, kubeadm, etc.) en una versión soportada.
  • kubectl instalado y configurado con un kubeconfig que tenga permisos para crear recursos en al menos un namespace.

Comprueba que kubectl llega al clúster antes de empezar:

kubectl get nodes

NAME     STATUS   ROLES           AGE   VERSION
node-1   Ready    control-plane   12d   v1.33.4
node-2   Ready    <none>          12d   v1.33.4

Helm usa el mismo kubeconfig y contexto que kubectl (~/.kube/config o la variable KUBECONFIG), así que no necesita configuración adicional para conectarse.

Paso 1: Instalar Helm

Helm publica un repositorio APT oficial para Debian y Ubuntu. Descarga su clave de firma en /etc/apt/keyrings:

sudo apt update
sudo apt install curl gpg
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://packages.buildkite.com/helm-linux/helm-debian/gpgkey | sudo gpg --dearmor -o /etc/apt/keyrings/helm.gpg

Añade el repositorio e instala el paquete:

echo "deb [signed-by=/etc/apt/keyrings/helm.gpg] https://packages.buildkite.com/helm-linux/helm-debian/any/ any main" | sudo tee /etc/apt/sources.list.d/helm-stable-debian.list
sudo apt update
sudo apt install helm

Comprueba la versión instalada:

helm version --short

v4.0.4+g8650e1d

Tu versión puede ser más reciente; Helm 4 es la rama actual. Todos los comandos de esta guía funcionan igual en Helm 3.

Paso 2: Añadir un repositorio de charts

Un repositorio de charts es un servidor HTTP que publica un índice de charts. En esta guía usarás podinfo, una pequeña aplicación web de demostración mantenida por el proyecto Flux, ideal para practicar porque arranca en segundos y expone varios valores configurables:

helm repo add podinfo https://stefanprodan.github.io/podinfo
helm repo update

Busca el chart y consulta las versiones disponibles:

helm search repo podinfo

NAME            CHART VERSION   APP VERSION     DESCRIPTION
podinfo/podinfo 6.9.2           6.9.2           Podinfo Helm chart for Kubernetes

Muchos proyectos publican ahora sus charts también como artefactos OCI en un registro de contenedores. En ese caso no hace falta helm repo add: se referencian directamente, por ejemplo oci://ghcr.io/stefanprodan/charts/podinfo.

Paso 3: Instalar un chart

Cada instalación de un chart se llama release y tiene un nombre único dentro de su namespace. Crea un namespace para las pruebas e instala podinfo con el nombre de release web:

kubectl create namespace demo
helm install web podinfo/podinfo --namespace demo --wait

NAME: web
LAST DEPLOYED: Thu Sep 25 10:20:31 2026
NAMESPACE: demo
STATUS: deployed
REVISION: 1

La opción --wait hace que Helm espere a que los pods estén listos antes de dar la instalación por buena. Lista las releases y los recursos que se han creado:

helm list --namespace demo
kubectl get deploy,svc,pods --namespace demo

Prueba la aplicación con un reenvío de puerto al Service, que se llama web-podinfo:

kubectl port-forward --namespace demo svc/web-podinfo 9898:9898

En otra terminal:

curl -s http://localhost:9898 | head -n 5

{
  "hostname": "web-podinfo-6c7f9d8b5-kx2lp",
  "version": "6.9.2",
  "revision": "",
  "color": "#34577c",

Detén el reenvío de puerto con Ctrl+C.

Paso 4: Personalizar la instalación con values

Cada chart declara sus parámetros configurables en un archivo values.yaml. Consulta los valores por defecto antes de cambiar nada:

helm show values podinfo/podinfo | less

Guarda tus cambios en un archivo propio en lugar de pasar muchas opciones --set; así la configuración queda versionada y es reproducible:

nano web-values.yaml

replicaCount: 3

ui:
  message: "Desplegado con Helm"
  color: "#1f7a4d"

resources:
  requests:
    cpu: 50m
    memory: 64Mi
  limits:
    memory: 128Mi

Aplica los valores con helm upgrade. Antes, si quieres ver qué manifiestos se generarán sin tocar el clúster, usa helm template podinfo/podinfo -f web-values.yaml.

helm upgrade web podinfo/podinfo --namespace demo -f web-values.yaml --wait

Comprueba que ahora hay tres réplicas y que Helm ha registrado tus valores:

kubectl get pods --namespace demo
helm get values web --namespace demo

USER-SUPPLIED VALUES:
replicaCount: 3
resources:
  limits:
    memory: 128Mi
  requests:
    cpu: 50m
    memory: 64Mi
ui:
  color: '#1f7a4d'
  message: Desplegado con Helm

Paso 5: Ver el historial y hacer un rollback

Helm guarda cada revisión de una release como un Secret en su namespace. Consulta el historial:

helm history web --namespace demo

REVISION  UPDATED                   STATUS      CHART           APP VERSION  DESCRIPTION
1         Thu Sep 25 10:20:31 2026  superseded  podinfo-6.9.2   6.9.2        Install complete
2         Thu Sep 25 10:27:12 2026  deployed    podinfo-6.9.2   6.9.2        Upgrade complete

Si una actualización causa problemas, vuelve a la revisión anterior:

helm rollback web 1 --namespace demo --wait
kubectl get pods --namespace demo

El rollback crea una revisión nueva (la 3) con la configuración de la revisión 1, por lo que verás de nuevo una sola réplica.

Paso 6: Crear tu propio chart

Genera el esqueleto de un chart. Helm crea una plantilla funcional que despliega Nginx, con Deployment, Service, Ingress opcional y ServiceAccount:

helm create myapp
ls -R myapp

El comando crea el directorio myapp/ con los archivos Chart.yaml y values.yaml, un directorio charts/ para dependencias y un directorio templates/ con los manifiestos (deployment.yaml, service.yaml, ingress.yaml, hpa.yaml, serviceaccount.yaml), el archivo de ayudas _helpers.tpl, las notas NOTES.txt que se muestran tras instalar y una prueba en tests/test-connection.yaml. Los archivos importantes son:

  • Chart.yaml: nombre, versión del chart (version) y versión de la aplicación (appVersion).
  • values.yaml: valores por defecto que usan las plantillas.
  • templates/: manifiestos de Kubernetes con sintaxis de plantillas de Go, por ejemplo {{ .Values.replicaCount }}.

Adapta values.yaml a tu aplicación. Por ejemplo, para cambiar la imagen:

nano myapp/values.yaml

image:
  repository: nginx
  pullPolicy: IfNotPresent
  tag: "1.29"

Valida el chart y revisa los manifiestos generados antes de instalarlo:

helm lint myapp
helm template test ./myapp | less

==> Linting myapp
[INFO] Chart.yaml: icon is recommended

1 chart(s) linted, 0 chart(s) failed

Instálalo desde el directorio local y ejecuta la prueba de conexión incluida en templates/tests/:

helm install myapp ./myapp --namespace demo --wait
helm test myapp --namespace demo

TEST SUITE:     myapp-test-connection
Last Started:   Thu Sep 25 10:41:05 2026
Last Completed: Thu Sep 25 10:41:09 2026
Phase:          Succeeded

Cuando quieras distribuir el chart, empaquétalo en un archivo .tgz versionado. Cada cambio en el chart debe ir acompañado de un incremento de version en Chart.yaml:

helm package myapp

Successfully packaged chart and saved it to: /home/your_user/myapp-0.1.0.tgz

Ese paquete puede publicarse en un registro OCI con helm push myapp-0.1.0.tgz oci://your_registry/charts tras autenticarte con helm registry login.

Paso 7: Desinstalar las releases

Elimina las releases de prueba. helm uninstall borra todos los recursos que creó el chart y su historial:

helm uninstall web myapp --namespace demo
kubectl delete namespace demo

Solución de problemas

Error: INSTALLATION FAILED: cannot re-use a name that is still in use. Ya existe una release con ese nombre en el namespace. Usa helm upgrade --install, que instala si no existe y actualiza si existe, o elige otro nombre.

Kubernetes cluster unreachable. Helm no encuentra el kubeconfig. Comprueba que kubectl get nodes funciona con el mismo usuario y, si usas un archivo distinto, exporta KUBECONFIG=/ruta/al/kubeconfig.

La release queda en estado pending-upgrade o failed. Una operación se interrumpió. Consulta helm history y vuelve a la última revisión buena con helm rollback; para depurar, revisa los eventos con kubectl get events -n demo --sort-by=.lastTimestamp.

--wait termina con timeout. Algún pod no llega a estar listo, normalmente por una imagen inexistente o recursos insuficientes. Revisa kubectl describe pod y amplía el tiempo con --timeout 10m si el arranque es lento.

Conclusión

Has instalado Helm, desplegado una aplicación desde un repositorio, gestionado su configuración con un archivo de valores, revertido una actualización y creado y empaquetado tu propio chart. Como siguientes pasos puedes gestionar varios entornos con archivos de valores separados (values-staging.yaml, values-prod.yaml), declarar dependencias entre charts en Chart.yaml, o automatizar los despliegues con una herramienta GitOps como Argo CD o Flux, que entienden charts de Helm de forma nativa.