Guía completa: desplegar un clúster Kubernetes con kubeadm

Tabla de contenidos

Kubernetes se ha convertido en el estándar de facto para la orquestación de contenedores. En esta guía completa, aprenderás a desplegar un clúster de producción usando kubeadm, la herramienta oficial de Kubernetes para bootstrapping de clústeres.

1. Requisitos Previos

Antes de comenzar, asegúrate de tener los siguientes recursos disponibles:

3 servidores Ubuntu 22.04 LTS (1 master + 2 workers)
Mínimo 2 CPUs y 2GB RAM por nodo (4GB recomendado para master)
Conectividad de red entre todos los nodos
Acceso root o sudo
Swap deshabilitado

Importante: Los puertos 6443 (API server), 2379-2380 (etcd), 10250-10252 (kubelet) deben estar abiertos entre los nodos.

2. Preparación de los Nodos

Ejecuta estos comandos en todos los nodos (master y workers):

Deshabilitar Swap

# Deshabilitar swap inmediatamente
$ sudo swapoff -a

# Comentar la línea de swap en fstab para persistir el cambio
$ sudo sed -i '/ swap / s/^\(.*\)$/#\1/g' /etc/fstab

# Verificar
$ free -h
              total        used        free
Swap:            0B          0B          0B

Configurar módulos del kernel

# Cargar módulos necesarios
$ cat <<EOF | sudo tee /etc/modules-load.d/k8s.conf
overlay
br_netfilter
EOF

$ sudo modprobe overlay
$ sudo modprobe br_netfilter

# Configurar sysctl
$ cat <<EOF | sudo tee /etc/sysctl.d/k8s.conf
net.bridge.bridge-nf-call-iptables  = 1
net.bridge.bridge-nf-call-ip6tables = 1
net.ipv4.ip_forward                 = 1
EOF

$ sudo sysctl --system

3. Instalación de containerd y kubeadm

Instalar containerd

# Instalar dependencias
$ sudo apt-get update
$ sudo apt-get install -y apt-transport-https ca-certificates curl gnupg

# Añadir repositorio Docker
$ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
    sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

$ echo "deb [arch=amd64 signed-by=/etc/apt/keyrings/docker.gpg] \
    https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | \
    sudo tee /etc/apt/sources.list.d/docker.list

# Instalar containerd
$ sudo apt-get update
$ sudo apt-get install -y containerd.io

# Configurar containerd para usar systemd cgroup
$ sudo mkdir -p /etc/containerd
$ containerd config default | sudo tee /etc/containerd/config.toml
$ sudo sed -i 's/SystemdCgroup = false/SystemdCgroup = true/' \
    /etc/containerd/config.toml

$ sudo systemctl restart containerd
$ sudo systemctl enable containerd

Instalar kubeadm, kubelet y kubectl

# Añadir repositorio 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

# Instalar componentes
$ sudo apt-get update
$ sudo apt-get install -y kubelet kubeadm kubectl
$ sudo apt-mark hold kubelet kubeadm kubectl

# Verificar versiones
$ kubeadm version
kubeadm version: v1.29.0

4. Inicialización del Clúster

Ejecuta el siguiente comando solo en el nodo master:

# Inicializar el clúster
$ sudo kubeadm init \
    --pod-network-cidr=192.168.0.0/16 \
    --cri-socket unix:///var/run/containerd/containerd.sock

[init] Using Kubernetes version: v1.29.0
[preflight] Running pre-flight checks
...
Your Kubernetes control-plane has initialized successfully!

# Configurar 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

Tip: Guarda el comando kubeadm join que aparece al final. Lo necesitarás para añadir los worker nodes.

5. Configuración de Red (Calico)

Instalamos Calico como CNI (Container Network Interface):

# Instalar Calico
$ kubectl apply -f https://raw.githubusercontent.com/projectcalico/calico/v3.27.0/manifests/calico.yaml

# Verificar que los pods de Calico están corriendo
$ kubectl get pods -n kube-system | grep calico
calico-kube-controllers-xxx   1/1     Running   0
calico-node-xxx               1/1     Running   0

# Verificar el estado del nodo master
$ kubectl get nodes
NAME     STATUS   ROLES           AGE   VERSION
master   Ready    control-plane   5m    v1.29.0

6. Añadir Worker Nodes

En cada worker node, ejecuta el comando join que guardaste anteriormente:

# Ejecutar en cada worker node
$ sudo kubeadm join <MASTER_IP>:6443 --token <TOKEN> \
    --discovery-token-ca-cert-hash sha256:<HASH>

[preflight] Running pre-flight checks
[kubelet-start] Starting the kubelet
This node has joined the cluster

Desde el master, verifica que los workers se han unido correctamente:

$ kubectl get nodes
NAME      STATUS   ROLES           AGE   VERSION
master    Ready    control-plane   10m   v1.29.0
worker1   Ready    <none>          2m    v1.29.0
worker2   Ready    <none>          1m    v1.29.0

7. Verificación y Pruebas

Vamos a desplegar una aplicación de prueba para verificar que todo funciona:

# Desplegar nginx de prueba
$ kubectl create deployment nginx --image=nginx --replicas=3
$ kubectl expose deployment nginx --port=80 --type=NodePort

# Verificar deployment
$ kubectl get deployments
NAME    READY   UP-TO-DATE   AVAILABLE   AGE
nginx   3/3     3            3           30s

# Ver pods distribuidos en los nodos
$ kubectl get pods -o wide
NAME                     READY   STATUS    NODE
nginx-xxx-abc            1/1     Running   worker1
nginx-xxx-def            1/1     Running   worker2
nginx-xxx-ghi            1/1     Running   worker1

# Obtener el puerto del servicio
$ kubectl get svc nginx
NAME    TYPE       CLUSTER-IP     PORT(S)        AGE
nginx   NodePort   10.96.x.x      80:31234/TCP   1m

¡Ahora puedes acceder a nginx en http://:31234!

Conclusión

Has configurado exitosamente un clúster Kubernetes de producción con kubeadm. Este es solo el comienzo - a partir de aquí puedes:

Configurar un Ingress Controller (nginx-ingress o Traefik)
Añadir monitorización con Prometheus y Grafana
Implementar storage persistente con NFS o Longhorn
Configurar backups con Velero

Si tienes dudas o necesitas ayuda profesional para implementar Kubernetes en tu infraestructura, no dudes en contactarme.