Montando mi propio clúster de K3s HA en Proxmox

Introducción

En este tutorial explicaremos de forma detallada cómo crear un clúster de alta disponibilidad (HA) utilizando K3s sobre máquinas virtuales alojadas en Proxmox. Kubernetes es una tecnología ampliamente adoptada por su capacidad para gestionar contenedores a escala, ofreciendo características esenciales como despliegues automáticos, gestión de recursos y auto-recuperación. Su variante ligera, K3s, nos permite obtener estas ventajas con requisitos de hardware reducidos, ideal para entornos domésticos o pequeñas empresas.

¿Por qué Kubernetes y K3s?

Kubernetes ofrece numerosas ventajas:

• Orquestación de contenedores: Automatiza el despliegue, escalado y manejo de aplicaciones en contenedores.
• Alta Disponibilidad y Resiliencia: Gestiona la recuperación automática ante fallos y asegura que las aplicaciones estén siempre disponibles.
• Escalabilidad Horizontal: Permite añadir fácilmente nuevos recursos según la demanda.
• Facilidad en la gestión del ciclo de vida: Desde actualizaciones automáticas hasta control exhaustivo del estado de las aplicaciones.

K3s mejora estas ventajas al ser más ligero y rápido de implementar:

• Menos recursos necesarios: Ideal para hardware limitado.
• Fácil despliegue: Instalación rápida y sencilla, sin sacrificar funcionalidades esenciales.
• Optimizado para pequeños y medianos entornos: Especialmente diseñado para homelabs o entornos productivos de menor escala.

Configuración

0. Planificación

Nuestro clúster estará formado por 9 nodos: 3 maestros para el control plane y 6 workers para ejecutar aplicaciones. Esta configuración garantiza robustez y tolerancia a fallos, ya que el clúster seguirá operativo incluso si alguno de los nodos maestros deja de funcionar.

Tipo de nodo	Nombre	IP
Maestro	Pathos	192.168.1.201
Maestro	Techne	192.168.1.202
Maestro	Sophia	192.168.1.203
Worker	Logos	192.168.1.204
Worker	Ethos	192.168.1.205
Worker	Mythos	192.168.1.206
Worker	Thanatos	192.168.1.207
Worker	Chronos	192.168.1.208
Worker	Kairos	192.168.1.209

Usaremos un balanceador de carga HAProxy desplegado en un contenedor LXC en Proxmox con la IP 192.168.1.210.

1. Crear las VMs y contenedores

1.1. Crear las VMs

El primer paso sera crear las máquinas virtuales en las que se desplegarán los nodos de K3s. En este caso, usare Debian 12.10 como sistema operativo. Puedes usar cualquier distribución de Linux que soporte K3s pero ten en cuenta que los comandos que aparecerán a continuación son específicos para Debian.

Para crear las máquinas virtuales, puedes usar la interfaz web de Proxmox o la línea de comandos. Aquí te muestro cómo lo voy a estar haciendo a través de la interfaz web.

Una vez creadas las máquinas virtuales instalaremos Debian en cada una de ellas. La instalación de Debian puede varias dependiendo de tus necesidades, aquí te muestro algunos pasos que elegi yo:

1.2. Preconfiguración de las VMs

Una vez que tengamos Debian instalado en cada una de las máquinas virtuales, procederemos a realizar la configuración inicial. Esto incluye la instalación de actualizaciones, la creación de un usuario y la configuración de SSH.

apt-get update && apt-get dist-upgrade -y && apt-get autoremove -y
apt-get install sudo -y
useradd -m -s /bin/bash k3s
echo "k3s ALL=(ALL) NOPASSWD: ALL" >> /etc/sudoers

# Configuración IP estática (adaptar IP según el nodo)
cat <<EOF > /etc/network/interfaces
auto lo
iface lo inet loopback

auto enp6s18
iface enp6s18 inet static
    address 192.168.1.201
    netmask 255.255.255.0
    gateway 192.168.1.1
    dns-domain xabierland.local
    dns-nameservers 192.168.1.254 1.1.1.1 1.0.0.1
EOF

systemctl restart networking

# Configuración SSH para usuario k3s
mkdir -p /home/k3s/.ssh
chmod 700 /home/k3s/.ssh
wget -qO- https://raw.githubusercontent.com/xabierland/xabierland.github.io/main/assets/keys/xabierland.pub >> /home/k3s/.ssh/authorized_keys
chmod 600 /home/k3s/.ssh/authorized_keys
chown -R k3s:k3s /home/k3s/.ssh

reboot

Es recomendable modificar el archivo /etc/ssh/sshd_config para solo permitir el acceso SSH a través de claves públicas. Cambia PasswordAuthentication yes a PasswordAuthentication no. Esto mejorará la seguridad de tu servidor.

1.3. Crear el contenedor LXC

Desde la shell de uno de nuestros nodos de Proxmox creamos el contenedor LXC para el balanceador de carga HAProxy. Este es un ejemplo del comando que puedes usar para ello:

pct create 210 local:vztmpl/debian-12.7.1-standard_12.7-1_amd64.tar.zst \
    --hostname HAProxy --cores 1 --memory 1024 --swap 0 \
    --net0 name=eth0,bridge=vmbr0,ip=192.168.1.210/24,gw=192.168.1.1 \
    --rootfs local-lvm:8

Tambien es posible crear el contenedor LXC desde la interfaz web de Proxmox si asi lo prefieres.

2. Configurar el Load Balancer HAProxy

Ahora para instalar HAProxy como balanceador de carga en el contenedor LXC que hemos creado usaremos el siguiente comando:

apt-get update && apt-get dist-upgrade -y
apt-get install haproxy -y

Configuramos /etc/haproxy/haproxy.cfg añadiendo al final del archivo la siguiente configuración:

frontend k3s
    bind *:6443
    mode tcp
    default_backend k3s

backend k3s
    mode tcp
    option tcp-check
    balance roundrobin
    server Pathos 192.168.1.201:6443 check
    server Techne 192.168.1.202:6443 check
    server Sophia 192.168.1.203:6443 check

frontend k3s-node-ports
        bind *:30000-32767
        mode tcp
        default_backend k3s-nodes-ports

backend k3s-nodes-ports
        mode tcp
        option tcp-check
        balance roundrobin
        server Pathos 192.168.1.201: check port 30000-32767
        server Techne 192.168.1.202: check port 30000-32767
        server Sophia 192.168.1.203: check port 30000-32767

Esta configuración permite que el balanceador de carga escuche en el puerto 6443 y redirija el tráfico a los nodos maestros del clúster. También hemos configurado el balanceo de carga para los puertos de servicio de Kubernetes 30000-32767.

Para aplicar la configuración, reiniciamos el servicio HAProxy:

systemctl restart haproxy

3. Configurar los nodos server

Con el balanceador de carga configurado y las máquinas virtuales listas, ahora procederemos a instalar K3s en los nodos maestros. Para ello, nos conectamos a los nodos mediante SSH y ejecutamos el siguiente comando:

export TOKEN="<mi_token>"
curl -sfL https://get.k3s.io | INSTALL_K3S_CHANNEL=stable sh -s - server \
  --cluster-init --token "$TOKEN" --tls-san 192.168.1.210

Mediante el siguiente configuramos el comando kubectl para poder interactuar con el clúster:

mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown $USER:$USER ~/.kube/config
echo "export KUBECONFIG=~/.kube/config" >> ~/.bashrc
source ~/.bashrc

Tambien podemos copiar el kubeconfig a nuestra máquina local mediante el siguiente comando:

scp k3s@192.168.1.201:/home/k3s/.kube/config ~/.kube/config

Ahora agregamos los nodos maestros restantes:

export TOKEN="<mi_token>"
curl -sfL https://get.k3s.io | INSTALL_K3S_CHANNEL=stable sh -s - server \
  --server https://192.168.1.210:6443 --token "$TOKEN"

4. Configurar los nodos worker

Con los nodos maestros listos solo nos queda añadir los nodos worker al cluster ejecutando:

export TOKEN="<mi_token>"
curl -sfL https://get.k3s.io | INSTALL_K3S_CHANNEL=stable sh -s - agent \
  --server https://192.168.1.210:6443 --token "$TOKEN"

5. Configurar el Upgrade Plan

Vamos a implementar también Rancher System Updrade Controller. Este controlador nos permitirá mantener nuestro clúster actualizado de forma sencilla y automatizada.

kubectl apply -f https://github.com/rancher/system-upgrade-controller/releases/latest/download/system-upgrade-controller.yaml
kubectl apply -f https://github.com/rancher/system-upgrade-controller/releases/latest/download/crd.yaml

kubectl apply -f - <<EOF
# Server plan
apiVersion: upgrade.cattle.io/v1
kind: Plan
metadata:
  name: server-plan
  namespace: system-upgrade
spec:
  concurrency: 1
  cordon: true
  nodeSelector:
    matchExpressions:
    - key: node-role.kubernetes.io/control-plane
      operator: In
      values:
      - "true"
  serviceAccountName: system-upgrade
  upgrade:
    image: rancher/k3s-upgrade
  channel: https://update.k3s.io/v1-release/channels/stable
---
# Agent plan
apiVersion: upgrade.cattle.io/v1
kind: Plan
metadata:
  name: agent-plan
  namespace: system-upgrade
spec:
  concurrency: 1
  cordon: true
  nodeSelector:
    matchExpressions:
    - key: node-role.kubernetes.io/control-plane
      operator: DoesNotExist
  prepare:
    args:
    - prepare
    - server-plan
    image: rancher/k3s-upgrade
  serviceAccountName: system-upgrade
  upgrade:
    image: rancher/k3s-upgrade
  channel: https://update.k3s.io/v1-release/channels/stable
---
EOF

Conclusión

Siguiendo estos pasos obtendremos un clúster K3s robusto y con alta disponibilidad sobre Proxmox, facilitando futuras escalabilidades, actualizaciones y mantenimiento.