Crea tu clúster de Ku­be­r­ne­tes en Proxmox

Crear un clúster de Ku­be­r­ne­tes en Proxmox te permite operar una pla­ta­fo­r­ma de or­que­s­ta­ción de co­n­te­ne­do­res de alto re­n­di­mie­n­to en un entorno vi­r­tua­li­za­do y ge­s­tio­na­do por ti. Es ideal para entornos de prueba, flujos de trabajo de de­sa­rro­llo y CI, así como para es­ce­na­rios de pro­du­c­ción de menor escala. En esta guía apre­n­de­rás paso a paso cómo co­n­fi­gu­rar máquinas virtuales en Proxmox y, a partir de ellas, desplegar un clúster de Ku­be­r­ne­tes estable.

Paso 1: comprobar los re­qui­si­tos previos

Antes de empezar con la co­n­fi­gu­ra­ción del clúster de Ku­be­r­ne­tes, asegúrate de que tu entorno cumple todos los re­qui­si­tos técnicos ne­ce­sa­rios. Contar con una base inicial limpia te ahorrará tiempo más adelante y evitará errores de co­n­fi­gu­ra­ción in­ne­ce­sa­rios.

En primer lugar, necesitas una in­s­ta­la­ción funcional de Proxmox VE. Por motivos de re­n­di­mie­n­to, se re­co­mie­n­da una in­s­ta­la­ción bare metal de Proxmox. Tanto el acceso web a través de la interfaz de Proxmox como el acceso SSH a la línea de comandos deben estar di­s­po­ni­bles. Mediante SSH podrás ejecutar comandos, subir imágenes y au­to­ma­ti­zar co­n­fi­gu­ra­cio­nes.

Para operar un clúster de Ku­be­r­ne­tes estable, también ne­ce­si­ta­rás varias máquinas virtuales. Se re­co­mie­n­da la siguiente di­s­tri­bu­ción de nodos de Ku­be­r­ne­tes:

• un nodo maestro (para la de­no­mi­na­da control plane) y
• al menos dos nodos worker.

Esta co­n­fi­gu­ra­ción aporta un cierto grado de re­du­n­da­n­cia y permite operar Ku­be­r­ne­tes de forma similar a entornos reales de pro­du­c­ción. No obstante, para fines de prueba o de­sa­rro­llo también puede ser su­fi­cie­n­te una co­n­fi­gu­ra­ción más reducida con un nodo maestro y un nodo worker.

Además, el host de Proxmox debe disponer de una interfaz de red tipo bridge co­rre­c­ta­me­n­te co­n­fi­gu­ra­da. Esto permite que las máquinas virtuales accedan a la red local y, si es necesario, a Internet, algo im­pre­s­ci­n­di­ble para descargar ac­tua­li­za­cio­nes e instalar po­s­te­rio­r­me­n­te los co­m­po­ne­n­tes de Ku­be­r­ne­tes.

Paso 2: descargar la imagen cloud y pre­pa­rar­la como plantilla

La in­s­ta­la­ción de Ku­be­r­ne­tes resulta mucho más sencilla con las de­no­mi­na­das cloud images. Se trata de imágenes de sistemas ope­ra­ti­vos pre­co­n­fi­gu­ra­das, no­r­ma­l­me­n­te Ubuntu o Debian, que están op­ti­mi­za­das para el arranque au­to­má­ti­co mediante cloud-init. En este ejemplo uti­li­za­mos una imagen cloud de Ubuntu 22.04 LTS, ya que es estable, está bien do­cu­me­n­ta­da y resulta es­pe­cia­l­me­n­te adecuada para su uso con Ku­be­r­ne­tes.

En primer lugar, descarga la imagen cloud actual de Ubuntu di­re­c­ta­me­n­te en tu host de Proxmox. Para ello, inicia sesión por SSH en el servidor Proxmox y cambia al di­re­c­to­rio en el que Proxmox almacena los archivos ISO e imágenes:

cd /var/lib/vz/template/iso

A co­n­ti­nua­ción, descarga la imagen de Ubuntu con el siguiente comando:

wget -O ubuntu-22.04-server-cloudimg-amd64.img https://cloud-images.ubuntu.com/releases/22.04/release/ubuntu-22.04-server-cloudimg-amd64.img

scp ubuntu-22.04-server-cloudimg-amd64.img root@<proxmox-ip>:/var/lib/vz/template/iso/

Una vez que la imagen esté di­s­po­ni­ble en el host de Proxmox, puedes crear a partir de ella una nueva máquina virtual que más adelante servirá como plantilla. Para ello, crea primero una VM vacía con un ID único, por ejemplo 9000, y asígnale recursos de hardware básicos:

qm create 9000 --name ubuntu-template --memory 2048 --net0 virtio,bridge=vmbr0

Ahora importa la imagen cloud de­s­ca­r­ga­da pre­via­me­n­te como disco duro virtual en el al­ma­ce­na­mie­n­to deseado (en este ejemplo, local-lvm):

qm importdisk 9000 /var/lib/vz/template/iso/ubuntu-22.04-server-cloudimg-amd64.img local-lvm

A co­n­ti­nua­ción, conecta el disco importado a la VM y configura el co­n­tro­la­dor adecuado. De este modo, la imagen queda vinculada al co­n­tro­la­dor SCSI virtual de la máquina:

qm set 9000 --scsihw virtio-scsi-pci --scsi0 local-lvm:vm-9000-disk-0

Para poder co­n­fi­gu­rar au­to­má­ti­ca­me­n­te di­re­c­cio­nes IP, nombres de host y claves SSH al clonar las VM más adelante, necesitas añadir una unidad Cloud-Init. Esta unidad virtual contiene los datos de co­n­fi­gu­ra­ción que se aplican au­to­má­ti­ca­me­n­te durante el primer arranque de la máquina virtual. Añade la unidad Cloud-Init y define el orden de arranque con los si­guie­n­tes comandos:

qm set 9000 --ide2 local-lvm:cloudinit
qm set 9000 --boot c --bootdisk scsi0

Activa también el QEMU Guest Agent, para que Proxmox pueda leer in­fo­r­ma­ción de estado de la VM, y configura una consola serie que permita acceder di­re­c­ta­me­n­te a la consola en caso de eme­r­ge­n­cia:

qm set 9000 --agent 1
qm set 9000 --serial0 socket --vga serial0

Si todo está co­n­fi­gu­ra­do co­rre­c­ta­me­n­te, puedes convertir la máquina virtual en una plantilla. En Proxmox, las pla­n­ti­llas sirven como base a partir de la cual puedes crear tantos clones como necesites, lo que las hace ideales para los nodos maestro y worker de Ku­be­r­ne­tes:

qm template 9000

Tras completar este paso, di­s­po­n­drás de una plantilla de Ubuntu lista para crear los nodos de tu clúster de Ku­be­r­ne­tes.

Paso 3: clonar máquinas virtuales para maestro y worker mediante la CLI

En este paso crearás, a partir de la plantilla generada an­te­rio­r­me­n­te, las máquinas virtuales que actuarán como nodos maestro y worker de tu clúster de Ku­be­r­ne­tes. Cada VM recibe su propia dirección IP, un nombre de host único y una clave SSH para un acceso seguro. Proxmox aplica au­to­má­ti­ca­me­n­te la co­n­fi­gu­ra­ción básica mediante cloud-init, por lo que no es necesario realizar ajustes manuales dentro de las máquinas virtuales.

En primer lugar, clona la plantilla (en este ejemplo, con el ID 9000) y crea tres máquinas virtuales: una para el nodo maestro y dos para los nodos worker. Durante el proceso puedes ajustar de forma in­di­vi­dual los recursos de CPU y memoria RAM:

qm clone 9000 101 --name k8s-master-1 --full true
qm set 101 --cores 2 --memory 4096
qm clone 9000 102 --name k8s-worker-1 --full true
qm set 102 --cores 2 --memory 4096
qm clone 9000 103 --name k8s-worker-2 --full true
qm set 103 --cores 2 --memory 4096

A co­n­ti­nua­ción, define mediante cloud-init la co­n­fi­gu­ra­ción básica de red, el nombre de usuario y la clave SSH. Puedes asignar di­re­c­cio­nes IP estáticas o utilizar DHCP. En este ejemplo se emplean di­re­c­cio­nes IP estáticas.

# Configurar el nodo maestro
qm set 101 --ipconfig0 ip=192.168.1.10/24,gw=192.168.1.1
qm set 101 --sshkey "$(cat ~/.ssh/id_rsa.pub)"
qm set 101 --ciuser ubuntu
qm set 101 --nameserver 192.168.1.1
qm set 101 --description "K8s Master 1"
# Configurar los nodos worker
qm set 102 --ipconfig0 ip=192.168.1.11/24,gw=192.168.1.1
qm set 102 --sshkey "$(cat ~/.ssh/id_rsa.pub)"
qm set 102 --ciuser ubuntu
qm set 103 --ipconfig0 ip=192.168.1.12/24,gw=192.168.1.1
qm set 103 --sshkey "$(cat ~/.ssh/id_rsa.pub)"
qm set 103 --ciuser ubuntu

Por último, inicia las tres máquinas virtuales:

qm start 101
qm start 102
qm start 103

Espera unos instantes a que los sistemas arranquen por completo y comprueba la conexión por SSH. Por ejemplo, puedes iniciar sesión en el nodo maestro con el siguiente comando:

ssh ubuntu@192.168.1.10

Paso 4: añadir la co­n­fi­gu­ra­ción básica en todas las máquinas virtuales

Antes de instalar Ku­be­r­ne­tes en las VM, es necesario aplicar algunos ajustes a nivel de sistema para ga­ra­n­ti­zar un fu­n­cio­na­mie­n­to estable. Entre ellos se incluyen la des­ac­ti­va­ción del swap, la co­n­fi­gu­ra­ción de pa­rá­me­tros del kernel re­la­cio­na­dos con la red y el reenvío de IP, así como la si­n­cro­ni­za­ción de la hora del sistema. Estas medidas son im­pre­s­ci­n­di­bles para el correcto fu­n­cio­na­mie­n­to de Ku­be­r­ne­tes y para ga­ra­n­ti­zar una co­mu­ni­ca­ción de red fiable entre nodos y co­n­te­ne­do­res.

En primer lugar, desactiva el swap en todos los nodos, ya que Ku­be­r­ne­tes lo exige para el correcto fu­n­cio­na­mie­n­to del scheduler. Además, elimina la entrada co­rre­s­po­n­die­n­te en /etc/fstab para evitar que el swap se reactive tras reiniciar el sistema:

sudo swapoff -a
sudo sed -i '/ swap / s/^/#/' /etc/fstab

A co­n­ti­nua­ción, configura los pa­rá­me­tros del kernel ne­ce­sa­rios para que el tráfico de red pueda pro­ce­sar­se co­rre­c­ta­me­n­te entre co­n­te­ne­do­res y nodos. Para ello, crea un archivo de co­n­fi­gu­ra­ción es­pe­cí­fi­co y aplica los cambios:

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

Otro paso im­po­r­ta­n­te es si­n­cro­ni­zar la hora del sistema, ya que di­fe­re­n­cias de tiempo pueden provocar errores en ce­r­ti­fi­ca­dos y en distintos co­m­po­ne­n­tes del clúster. Para ello, instala y activa chrony:

sudo apt update && sudo apt install -y chrony
sudo systemctl enable --now chrony

Por último, se re­co­mie­n­da instalar algunas he­rra­mie­n­tas au­xi­lia­res básicas que serán ne­ce­sa­rias en los pasos po­s­te­rio­res de la co­n­fi­gu­ra­ción:

sudo apt install -y curl apt-transport-https ca-certificates gnupg lsb-release

Tras completar estos pasos, todos los nodos quedan pre­pa­ra­dos de forma uniforme: el swap está des­ac­ti­va­do, los ajustes de red están co­rre­c­ta­me­n­te co­n­fi­gu­ra­dos y la hora del sistema está si­n­cro­ni­za­da. Las máquinas virtuales ya están listas para instalar Ku­be­r­ne­tes y continuar con la creación del clúster.

Paso 5: elección de la di­s­tri­bu­ción de Ku­be­r­ne­tes

Antes de comenzar con la in­s­ta­la­ción de Ku­be­r­ne­tes, conviene elegir una di­s­tri­bu­ción adecuada en función de tus re­qui­si­tos y del entorno de uso previsto. En este contexto, hay dos opciones es­pe­cia­l­me­n­te re­co­me­n­da­bles:

• RKE2 (Rancher Ku­be­r­ne­tes Engine 2): RKE2 es una di­s­tri­bu­ción de Ku­be­r­ne­tes estable y preparada para pro­du­c­ción, de­sa­rro­lla­da por Rancher. Resulta es­pe­cia­l­me­n­te adecuada si más adelante quieres utilizar una gestión gráfica mediante Rancher o si planeas operar un clúster con varios nodos de control plane.
• k3s: k3s es una di­s­tri­bu­ción de Ku­be­r­ne­tes ligera, ideal para entornos de prueba, la­bo­ra­to­rios do­mé­s­ti­cos o sistemas con recursos limitados. Destaca por su in­s­ta­la­ción sencilla y por requerir menos memoria y CPU que otras di­s­tri­bu­cio­nes completas.

Para crear un clúster de Ku­be­r­ne­tes robusto en Proxmox, que también pueda uti­li­zar­se en es­ce­na­rios cercanos a pro­du­c­ción, se re­co­mie­n­da RKE2. En cambio, si tu objetivo es co­n­fi­gu­rar rá­pi­da­me­n­te un clúster pequeño para pruebas o de­sa­rro­llo, k3s suele ser la al­te­r­na­ti­va más práctica. En el resto de esta guía se utilizará RKE2.

Paso 6: instalar RKE2 en el nodo maestro

Una vez co­m­ple­ta­da la co­n­fi­gu­ra­ción básica de las máquinas virtuales, puedes comenzar con la in­s­ta­la­ción de RKE2 en el nodo maestro. Para ello, inicia sesión por SSH en el nodo maestro:

ssh ubuntu@192.168.1.10

A co­n­ti­nua­ción, descarga y ejecuta el script oficial de in­s­ta­la­ción de RKE2. De forma opcional, puedes es­pe­ci­fi­car el canal de versión que deseas utilizar:

curl -sfL https://get.rke2.io | sudo INSTALL_RKE2_CHANNEL=v1.28 bash -

Una vez fi­na­li­za­da la in­s­ta­la­ción, habilita el servicio del servidor RKE2 y arráncalo de inmediato:

sudo systemctl enable --now rke2-server.service

Comprueba que el servicio se esté eje­cu­ta­n­do co­rre­c­ta­me­n­te con el siguiente comando:

sudo systemctl status rke2-server

Para poder ad­mi­ni­s­trar el clúster de Ku­be­r­ne­tes desde tu equipo local, copia el archivo kubeconfig generado por RKE2. Primero, ajusta los permisos del archivo en el nodo maestro y, a co­n­ti­nua­ción, tra­n­s­fié­re­lo a tu equipo local:

sudo chmod 644 /etc/rancher/rke2/rke2.yaml
scp ubuntu@192.168.1.10:/etc/rancher/rke2/rke2.yaml ~/rke2-kubeconfig

Después, adapta la dirección IP del nodo maestro en el archivo kubeconfig para que kubectl pueda co­ne­c­tar­se co­rre­c­ta­me­n­te al servidor de la API de Ku­be­r­ne­tes:

sed -i 's/127.0.0.1:6443/192.168.1.10:6443/' ~/rke2-kubeconfig
export KUBECONFIG=~/rke2-kubeconfig

Si ya tienes kubectl instalado en tu equipo local, puedes comprobar si el nodo maestro está accesible y re­gi­s­tra­do co­rre­c­ta­me­n­te en el clúster:

kubectl get nodes

Si el nodo maestro aparece en la salida, la in­s­ta­la­ción de RKE2 se ha co­m­ple­ta­do co­rre­c­ta­me­n­te. En el siguiente paso podrás añadir los nodos worker al clúster.

Paso 7: instalar el agente de RKE2 en los nodos worker

Una vez que el nodo maestro esté co­n­fi­gu­ra­do co­rre­c­ta­me­n­te, puedes integrar los nodos worker en el clúster. Para ello, debes instalar el agente de RKE2 en cada nodo worker y co­ne­c­tar­lo al nodo maestro.

En el nodo maestro, obtén primero el token del clúster, que se utiliza para au­te­n­ti­car los nodos worker al unirse al clúster:

sudo cat /var/lib/rancher/rke2/server/node-token

Guarda el valor del token, ya que lo ne­ce­si­ta­rás en los nodos worker.

A co­n­ti­nua­ción, inicia sesión por SSH en uno de los nodos worker (repite el proceso para cada nodo):

ssh ubuntu@192.168.1.11

Descarga el script de in­s­ta­la­ción de RKE2 e instala el agente con el siguiente comando:

curl -sfL https://get.rke2.io | sudo INSTALL_RKE2_CHANNEL=v1.28 sh -

Después, crea el archivo de co­n­fi­gu­ra­ción del agente e introduce la dirección del nodo maestro y el token obtenido pre­via­me­n­te:

sudo mkdir -p /etc/rancher/rke2
cat <<EOF | sudo tee /etc/rancher/rke2/config.yaml
server: https://192.168.1.10
token: <INSERTAR_TOKEN_AQUI>
EOF

Por último, habilita e inicia el servicio del agente de RKE2:

sudo systemctl enable --now rke2-agent.service

Repite estos pasos en todos los nodos worker del clúster. Tras unos minutos, puedes comprobar desde el nodo maestro si los nodos se han unido co­rre­c­ta­me­n­te:

kubectl get nodes

Si todo ha fu­n­cio­na­do co­rre­c­ta­me­n­te, verás el nodo maestro y los nodos worker en el estado Ready. Con esto, el clúster de Ku­be­r­ne­tes ya está completo y preparado para instalar plugins de red, ba­la­n­cea­do­res de carga y otros co­m­po­ne­n­tes ese­n­cia­les.

Paso 8: instalar la CNI de red y el Loa­d­Ba­la­n­cer

Una vez que los nodos maestro y worker estén co­n­fi­gu­ra­dos co­rre­c­ta­me­n­te, necesitas una Container Network Interface (CNI) para que los pods del clúster puedan co­mu­ni­car­se entre sí, así como un Loa­d­Ba­la­n­cer para exponer los Services en la red. En esta guía uti­li­za­mos Calico como CNI y MetalLB para la fu­n­cio­na­li­dad de balanceo de carga de capa 2.

Calico se encarga de es­ta­ble­cer la co­ne­c­ti­vi­dad de red entre los pods, asignar di­re­c­cio­nes IP y, de forma opcional, aplicar políticas de red. Puedes in­s­ta­lar­lo con el siguiente comando:

kubectl apply -f https://docs.projectcalico.org/manifests/calico.yaml

A co­n­ti­nua­ción, comprueba que los pods de Calico se hayan iniciado co­rre­c­ta­me­n­te:

kubectl get pods -n kube-system

Todos los pods deberían aparecer con el estado Running o Completed. Si alguno permanece en Pending, espera unos minutos, ya que Calico necesita tiempo para desplegar la co­n­fi­gu­ra­ción de red en todos los nodos.

Ku­be­r­ne­tes admite de forma nativa Services del tipo Loa­d­Ba­la­n­cer, pero en clústeres au­to­alo­ja­dos, como los que se ejecutan en Proxmox, es necesario un co­m­po­ne­n­te adicional para asignar di­re­c­cio­nes IP externas. Para ello se utiliza MetalLB. Instálalo con el siguiente comando:

kubectl apply -f https://raw.githubusercontent.com/metallb/metallb/v0.13.10/config/manifests/metallb-native.yaml

Después, crea un pool de di­re­c­cio­nes IP desde el que MetalLB pueda asignar IP a los Services de tipo Loa­d­Ba­la­n­cer. Ajusta el rango de di­re­c­cio­nes a tu red local:

cat <<EOF | kubectl apply -f -
apiVersion: metallb.io/v1beta1
kind: IPAddressPool
metadata:
name: my-ip-pool
namespace: metallb-system
spec:
addresses:
- 192.168.1.200-192.168.1.210
---
apiVersion: metallb.io/v1beta1
kind: L2Advertisement
metadata:
name: l2adv
namespace: metallb-system
spec: {}
EOF

Comprueba también que los pods de MetalLB se estén eje­cu­ta­n­do co­rre­c­ta­me­n­te:

kubectl get pods -n metallb-system

Cuando todos los pods muestren el estado Running, la red del clúster estará lista. A partir de este momento, puedes utilizar Services de Ku­be­r­ne­tes del tipo Loa­d­Ba­la­n­cer para exponer apli­ca­cio­nes di­re­c­ta­me­n­te en la red local. Con esto, tu clúster de Ku­be­r­ne­tes en Proxmox queda co­m­ple­ta­me­n­te co­n­fi­gu­ra­do y preparado para desplegar apli­ca­cio­nes y gestionar recursos de red.