K3s Kubernetes: Tu Clúster Ligero en 7 Pasos 2026

K3s Kubernetes es una distribución certificada que cabe en un binario de unos 70 MB y arranca en máquinas con 512 MB de RAM. Un comando y en treinta segundos tienes un clúster funcional, sin el ritual de kubeadm ni tres días peleándote con certificados.

Y conviene aclararlo pronto porque genera dudas: no es un Kubernetes «de juguete». Pasa la certificación de conformidad, así que tus manifiestos funcionan igual aquí que en un clúster gestionado de cualquier nube.

Qué es K3s Kubernetes y qué le quitaron

K3s Kubernetes nació en Rancher y hoy es un proyecto de la CNCF. La idea fue coger Kubernetes y podar todo lo que un despliegue pequeño no necesita: proveedores de nube heredados, complementos en desuso y dependencias externas. El resultado es un único binario que empaqueta el plano de control, el kubelet y el tiempo de ejecución de contenedores.

La diferencia de fondo más importante es el almacén de datos. Un Kubernetes estándar exige etcd; K3s Kubernetes usa SQLite por defecto, lo que elimina de un plumazo la operación más delicada de un clúster pequeño. Cuando necesitas alta disponibilidad, cambias a etcd embebido con una opción.

Esa fila del Ingress explica muchos despliegues confusos: K3s trae Traefik puesto, así que si esperabas instalar Ingress NGINX te encontrarás con dos controladores peleándose por el puerto 80.

Requisitos para K3s Kubernetes

K3s Kubernetes funciona en x86_64, ARM64 y ARMv7, así que una Raspberry Pi es candidata válida. Eso sí, atención al disco: si vas a usar etcd embebido, una tarjeta microSD no aguanta el ritmo de escritura y acabará dando errores intermitentes muy difíciles de diagnosticar. Un SSD por USB resuelve el problema por poco dinero.

Instalar K3s Kubernetes en 7 pasos

Paso 1: preparar el sistema

Poca ceremonia: sistema actualizado y dos ajustes que evitan sorpresas más adelante.

sudo apt update && sudo apt upgrade -y
sudo swapoff -a
sudo sed -i '/ swap / s/^/#/' /etc/fstab
hostnamectl set-hostname k3s-servidor

Los nombres de máquina deben ser únicos en todo el clúster. Si clonas máquinas virtuales y se repiten, los nodos se pisan entre sí al registrarse.

Paso 2: instalar el nodo servidor

curl -sfL https://get.k3s.io | sh -

Eso es todo. El script de K3s Kubernetes instala el binario, crea un servicio de systemd y arranca el clúster. Comprueba que el nodo aparece listo:

sudo k3s kubectl get nodes
sudo systemctl status k3s

Paso 3: acceder con kubectl desde tu equipo

Usar sudo k3s kubectl a todas horas cansa. El fichero de configuración está en una ruta fija y solo hay que cambiarle la dirección del servidor.

sudo cat /etc/rancher/k3s/k3s.yaml

# En tu portatil:
mkdir -p ~/.kube
scp usuario@k3s-servidor:/etc/rancher/k3s/k3s.yaml ~/.kube/config-k3s
sed -i 's/127.0.0.1/IP-DEL-SERVIDOR/' ~/.kube/config-k3s
export KUBECONFIG=~/.kube/config-k3s
kubectl get nodes -o wide

Ese fichero contiene credenciales de administrador del clúster: trátalo como una contraseña y no lo dejes en repositorios ni en carpetas compartidas.

Paso 4: añadir nodos agente

Primero recoge el token del servidor. Después ejecuta el instalador en cada máquina que quieras sumar.

# En el servidor
sudo cat /var/lib/rancher/k3s/server/node-token

# En cada agente
curl -sfL https://get.k3s.io | \
  K3S_URL=https://IP-DEL-SERVIDOR:6443 \
  K3S_TOKEN=el-token-copiado sh -

En menos de un minuto el nodo aparece en kubectl get nodes. Necesitas abrir el puerto 6443 entre agentes y servidor, y el 8472/UDP si usas la red por defecto con Flannel.

Paso 5: decidir qué componentes desactivar

De serie, K3s Kubernetes trae CoreDNS, Traefik como Ingress, ServiceLB para exponer servicios de tipo LoadBalancer, un aprovisionador de almacenamiento local y el servidor de métricas. Si prefieres montar tu propia pila, desactívalos en la instalación.

curl -sfL https://get.k3s.io | sh -s - \
  --disable=traefik \
  --disable=servicelb \
  --write-kubeconfig-mode=644

Desactivar después de haber instalado no elimina lo ya desplegado, así que conviene decidirlo antes. Mi recomendación para empezar es dejarlo todo puesto: ServiceLB es lo que hace que un servicio de tipo LoadBalancer funcione en un servidor sin nube detrás, y eso resuelve un problema que en un clúster casero es incómodo.

Paso 6: desplegar tu primera aplicación

En K3s Kubernetes todo lo que ya sabes aplica sin cambios. Aquí un despliegue con su servicio expuesto.

kubectl create deployment web --image=nginx:alpine --replicas=3
kubectl expose deployment web --type=LoadBalancer --port=80
kubectl get svc web

Gracias a ServiceLB verás una IP real asignada, no un <pending> eterno. A partir de ahí puedes instalar cualquier cosa del ecosistema: Helm para gestionar charts, cert-manager para certificados TLS o Prometheus para monitorización.

Hay además un atajo muy propio de esta distribución: cualquier manifiesto que dejes en /var/lib/rancher/k3s/server/manifests se aplica solo al arrancar y cuando cambia el fichero. Es cómodo para el arranque inicial, aunque para un flujo serio prefiero GitOps continuo con Flux.

Paso 7: alta disponibilidad con etcd embebido

Un solo servidor de K3s Kubernetes es un punto único de fallo. Para producción hacen falta tres nodos de control con etcd embebido. El primero se inicia de forma especial:

# Primer servidor
curl -sfL https://get.k3s.io | sh -s - server \
  --cluster-init \
  --token=un-secreto-compartido

# Segundo y tercero
curl -sfL https://get.k3s.io | sh -s - server \
  --server https://IP-DEL-PRIMERO:6443 \
  --token=un-secreto-compartido

Tienen que ser tres o cinco, número impar, porque etcd necesita mayoría para decidir. Con dos nodos no ganas disponibilidad: la pierdes, porque cualquier caída rompe el quórum.

Los nodos agente se unen igual que antes, apuntando a cualquiera de los servidores. Lo que sí necesitas resolver es el acceso a la API: si tus clientes apuntan a la IP de un servidor concreto, cuando ese caiga te quedas sin administrar el clúster aunque los otros dos sigan vivos. La solución habitual es poner un balanceador delante de los tres, o al menos un nombre DNS con varios registros, y usar esa dirección en el kubeconfig.

Conviene también programar instantáneas del almacén. La propia distribución las genera de forma periódica cuando usa etcd, y puedes ajustar la frecuencia y cuántas conservar; guárdalas fuera de los nodos, porque una copia que vive solo en la máquina que se ha estropeado no sirve de nada.

Almacenamiento persistente en K3s Kubernetes

Aquí hay una trampa que pilla a mucha gente. K3s Kubernetes incluye un aprovisionador de almacenamiento local que crea volúmenes en el disco del nodo donde arranca el pod. Funciona sin configurar nada, y por eso parece que el almacenamiento «ya está resuelto».

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: datos-app
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: local-path
  resources:
    requests:
      storage: 5Gi

El problema aparece con varios nodos: ese volumen vive en un disco concreto. Si el pod se reprograma en otra máquina, no encuentra sus datos, y si el nodo muere, los datos mueren con él. Para un clúster de un solo nodo es perfectamente válido; en cuanto añades trabajadores, deja de serlo.

Las salidas razonables son dos. Si tienes ya un NAS, exporta por NFS y usa su clase de almacenamiento. Si quieres replicación dentro del propio clúster, instala Longhorn como almacenamiento distribuido, que replica cada volumen entre nodos y sobrevive a la caída de uno. Ten en cuenta que Longhorn pide bastante más músculo que el aprovisionador local, así que dimensiona en consecuencia.

Frente a k0s y MicroK8s

No es la única distribución ligera, y merece la pena saber en qué se diferencian antes de casarse con una.

La ventaja práctica de K3s Kubernetes es el volumen de documentación y de gente que ha pasado por tus mismos problemas. Cuando algo falle a las once de la noche, eso vale más que cualquier diferencia técnica de la tabla.

Buenas prácticas con K3s Kubernetes

• Fija la versión. El script instala la última estable; con INSTALL_K3S_VERSION controlas exactamente qué versión entra y evitas sorpresas al reinstalar.
• Respalda el almacén. Con SQLite basta con copiar /var/lib/rancher/k3s/server/db; con etcd usa las instantáneas automáticas que hace la propia distribución.
• Vigila la memoria. En nodos de 1 GB, tres o cuatro aplicaciones ya rozan el límite y el sistema empieza a matar procesos.
• Desinstala con el script. Existe /usr/local/bin/k3s-uninstall.sh; borrar ficheros a mano deja restos de red que dan problemas al reinstalar.

Endurecer el clúster antes de exponerlo

La configuración por defecto está pensada para arrancar rápido, no para resistir Internet. Cuatro ajustes cambian bastante el panorama y ninguno lleva más de diez minutos.

• No publiques el puerto 6443. La API no debe ser accesible desde fuera de tu red; si necesitas administrarlo en remoto, hazlo por VPN.
• Cuidado con --write-kubeconfig-mode=644. Es cómodo porque evita el sudo, pero deja las credenciales de administrador legibles para cualquier usuario del sistema. En un servidor compartido, no lo uses.
• Rota el token de unión si alguna vez lo compartiste por chat o correo: con él, cualquiera añade un nodo a tu clúster.
• Activa políticas de red. Por defecto todos los pods se hablan entre sí; con NetworkPolicy limitas el movimiento lateral si una aplicación se ve comprometida.

Para las actualizaciones existe además un controlador propio que las orquesta desde dentro del clúster, drenando cada nodo antes de reiniciarlo. Merece la pena en cuanto tengas más de tres máquinas, porque hacerlo a mano y en orden es justo el tipo de tarea que se acaba haciendo mal un viernes por la tarde.

Problemas frecuentes con K3s Kubernetes

Para diagnosticar cualquier cosa en K3s Kubernetes, los registros del servicio son el primer sitio donde mirar, y suelen decir el problema con bastante claridad.

sudo journalctl -u k3s -f
sudo journalctl -u k3s-agent -f

Conclusión sobre K3s Kubernetes

Si has estado posponiendo aprender Kubernetes, K3s Kubernetes porque montar un clúster parecía un proyecto en sí mismo, esta es la forma de saltarte esa barrera. En un mini PC de segunda mano tienes en cinco minutos un entorno donde practicar todo lo demás, y lo que aprendas se traslada tal cual a un clúster gestionado.

Para producción pequeña, K3s Kubernetes también cumple de sobra: tres nodos con etcd embebido y SSD aguantan cargas reales con un consumo ridículo comparado con la alternativa. Tienes la guía rápida en la documentación oficial, el detalle de dimensionamiento en la página de requisitos, la configuración de alta disponibilidad en la guía de etcd embebido y el código en su repositorio de GitHub.

Preguntas frecuentes sobre K3s Kubernetes