Instalar Kubernetes en Ubuntu desde cero: guía completa

Kubernetes es el estándar para orquestar contenedores a escala, pero su instalación puede parecer intimidante la primera vez. Esta guía te lleva por el proceso completo para instalar un clúster Kubernetes funcional en Ubuntu usando kubeadm, la herramienta oficial para configurar clústeres de producción. Al final tendrás un nodo maestro y sabrás cómo agregar nodos trabajadores. Los comandos están verificados para Ubuntu 22.04 y 24.04 LTS.

Si todavía no tienes claro qué es Docker ni cómo funcionan los contenedores, empieza primero por esta guía: Docker: qué es y para qué sirve. Kubernetes trabaja sobre contenedores, así que ese conocimiento previo es importante.

Requisitos antes de empezar

Requisitos de hardware (por nodo)

• Mínimo 2 CPU (o vCPU en máquina virtual).
• Mínimo 2 GB de RAM (4 GB recomendado para el nodo maestro).
• 20 GB de espacio en disco.
• Conectividad de red entre todos los nodos del clúster.
• Acceso a internet para descargar paquetes.

Requisitos de sistema

• Ubuntu 22.04 LTS o Ubuntu 24.04 LTS.
• Usuario con privilegios sudo.
• Dirección MAC y product_uuid únicos para cada nodo.
• Swap desactivado (Kubernetes lo requiere).

Paso 1: preparar el sistema en todos los nodos

Estos pasos deben ejecutarse en cada nodo del clúster (tanto en el maestro como en los trabajadores).

Actualizar el sistema

sudo apt update && sudo apt upgrade -y

Desactivar la memoria swap

Kubernetes requiere que la swap esté desactivada para gestionar la memoria de forma predecible:

# Desactivar swap inmediatamente
sudo swapoff -a

# Desactivar swap de forma permanente (editar /etc/fstab)
sudo sed -i '/ swap / s/^\(.*\)$/#\1/g' /etc/fstab

Configurar módulos del kernel necesarios

cat <

Paso 2: instalar containerd como runtime de contenedores

Kubernetes necesita un runtime de contenedores. Usaremos containerd, el estándar actual y más ligero que Docker para este propósito:

# Instalar dependencias
sudo apt install -y curl gnupg2 software-properties-common apt-transport-https ca-certificates

# Añadir repositorio de Docker (containerd viene en él)
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo $VERSION_CODENAME) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update
sudo apt install -y containerd.io

# Generar configuración por defecto
sudo mkdir -p /etc/containerd
containerd config default | sudo tee /etc/containerd/config.toml

# Configurar SystemdCgroup (requerido por Kubernetes)
sudo sed -i 's/SystemdCgroup = false/SystemdCgroup = true/' /etc/containerd/config.toml

sudo systemctl restart containerd
sudo systemctl enable containerd

Paso 3: instalar kubeadm, kubelet y kubectl

Estos tres componentes son el núcleo de la instalación de Kubernetes:

• kubeadm: herramienta para inicializar y gestionar el clúster.
• kubelet: el agente que corre en cada nodo y gestiona los pods.
• kubectl: la herramienta de línea de comandos para interactuar con el clúster.

# Añadir repositorio oficial de Kubernetes
curl -fsSL https://pkgs.k8s.io/core:/stable:/v1.29/deb/Release.key | \
  sudo gpg --dearmor -o /etc/apt/keyrings/kubernetes-apt-keyring.gpg

echo 'deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] \
  https://pkgs.k8s.io/core:/stable:/v1.29/deb/ /' | \
  sudo tee /etc/apt/sources.list.d/kubernetes.list

sudo apt update
sudo apt install -y kubelet kubeadm kubectl

# Fijar la versión para evitar actualizaciones automáticas no controladas
sudo apt-mark hold kubelet kubeadm kubectl

# Activar e iniciar kubelet
sudo systemctl enable --now kubelet

Paso 4: inicializar el nodo maestro (control plane)

Este paso solo se ejecuta en el nodo maestro. Sustituye 192.168.1.100 por la IP real de tu nodo maestro:

sudo kubeadm init \
  --pod-network-cidr=10.244.0.0/16 \
  --apiserver-advertise-address=192.168.1.100

Al finalizar, kubeadm mostrará un comando kubeadm join con un token. Guárdalo, lo necesitarás para unir los nodos trabajadores.

Configura kubectl para el usuario actual:

mkdir -p $HOME/.kube
sudo cp -i /etc/kubernetes/admin.conf $HOME/.kube/config
sudo chown $(id -u):$(id -g) $HOME/.kube/config

Paso 5: instalar el plugin de red (CNI)

Kubernetes necesita un plugin de red para que los pods se comuniquen entre sí. Usaremos Flannel, uno de los más sencillos y ampliamente usados:

kubectl apply -f https://raw.githubusercontent.com/flannel-io/flannel/master/Documentation/kube-flannel.yml

Espera unos minutos y verifica que todos los pods del sistema estén corriendo:

kubectl get pods -n kube-system

Todos deben mostrar el estado Running. Si alguno muestra Pending o CrashLoopBackOff, espera un minuto más y vuelve a verificar.

Paso 6: unir nodos trabajadores al clúster

En cada nodo trabajador, ejecuta el comando kubeadm join que guardaste en el paso 4. Tendrá el siguiente formato:

sudo kubeadm join 192.168.1.100:6443 \
  --token abcdef.1234567890abcdef \
  --discovery-token-ca-cert-hash sha256:xxxxxxxx...

Si el token expiró (duran 24 horas por defecto), genera uno nuevo desde el nodo maestro:

kubeadm token create --print-join-command

Desde el nodo maestro, verifica que los nodos se unieron correctamente:

kubectl get nodes

Paso 7: verificar el clúster con un despliegue de prueba

# Desplegar Nginx como prueba
kubectl create deployment nginx-test --image=nginx
kubectl expose deployment nginx-test --port=80 --type=NodePort

# Ver el estado del despliegue
kubectl get deployments
kubectl get pods
kubectl get services

Errores comunes y cómo resolverlos

Error: "The connection to the server was refused"

El API server no está corriendo. Verifica el estado de kubelet: sudo systemctl status kubelet. Si está caído, revisa los logs con journalctl -xeu kubelet para identificar el error específico.

Error: nodos en estado NotReady

Generalmente indica que el plugin de red no se instaló o no está funcionando. Verifica los pods de kube-system: kubectl get pods -n kube-system. Si los pods de Flannel o Calico están en error, reinstala el plugin de red.

Error: "swap is enabled"

La swap no se desactivó correctamente. Ejecuta sudo swapoff -a y verifica con free -h que el swap aparece en 0.

En pocas palabras

Instalar Kubernetes con kubeadm en Ubuntu requiere preparar el sistema en todos los nodos, instalar containerd como runtime, instalar los tres componentes clave (kubeadm, kubelet, kubectl), inicializar el clúster en el nodo maestro, instalar un plugin de red y unir los nodos trabajadores. El proceso completo toma entre 20 y 40 minutos en un entorno limpio. El siguiente paso natural es aprender a desplegar aplicaciones y gestionar el clúster con kubectl.

Si prefieres una instalación más ligera y rápida para desarrollo o entornos edge, considera Kubernetes con K3s, que requiere muchos menos recursos.