Problema

En entornos donde Proxmox VE sirve como hipervisor y Rancher gestiona clústeres Kubernetes, la creación manual de máquinas virtuales para cada nodo se vuelve una tarea repetitiva y propensa a errores. Cada vez que se necesita añadir un control‑plane o un worker, el administrador debe clonar una plantilla, ajustar CPU, RAM, discos y ejecutar cloud‑init. Cuando el número de nodos crece o se requiere escalar rápidamente, este proceso se vuelve un cuello de botella. La falta de una integración nativa entre Rancher y Proxmox impide que Rancher realice el aprovisionamiento automático, el escalado dinámico y la limpieza de recursos al destruir un clúster.

Causa

  1. Ausencia de un node driver oficial – Rancher incluye drivers para los principales proveedores de nube (AWS, Azure, vSphere) pero no para Proxmox, por lo que no puede delegar la creación de VMs.
  2. Gestión manual de credenciales – Sin un driver, los scripts suelen almacenar contraseñas de root en texto plano, lo que rompe la política de mínimos privilegios.
  3. Desalineación de discos de datos – Al crear VMs con varios discos, la identificación basada en /dev/sdX es inestable; los volúmenes pueden cambiar de nombre y romper la configuración de storage como Longhorn o Ceph.
  4. Falta de sincronización de IP – Rancher necesita conocer la dirección IP de cada nodo antes de ejecutar RKE2/K3s. Sin una integración que consulte el guest‑agent, se pueden asignar direcciones de puente CNI en lugar de la IP real del host.
  5. Escalado y borrado incompletos – Los procesos manuales no eliminan automáticamente los recursos creados (VMs, discos, interfaces), dejando residuos que consumen capacidad.

Solución

Implementar un node driver personalizado para Proxmox VE que exponga la API de PVE a Rancher. El driver debe:

  • Autenticarse mediante API token limitado a un resource pool específico, evitando privilegios de root.
  • Clonar una plantilla VM que incluya qemu-guest-agent y cloud-init.
  • Permitir la parametrización de CPU, RAM, discos y puente de red mediante la UI de Rancher.
  • Adjuntar discos de datos, formatearlos y montar puntos de montaje antes de iniciar RKE2/K3s. La identificación de discos se hace por serial en vez de /dev/sdX.
  • Obtener la dirección IP del nodo consultando el guest‑agent (para DHCP) o leyendo una IP estática definida en cloud‑init.
  • Registrar cada VM en Rancher y, al destruir el clúster, eliminar automáticamente los recursos asociados.

Pasos generales

  1. Preparar la plantilla

    • Instalar qemu-guest-agent y habilitar cloud-init.
    • Configurar un usuario sin privilegios de sudo que pueda ejecutar los scripts de bootstrap.

  2. Crear un API token en Proxmox

    • Asignar el token a un resource pool dedicado.
    • Conceder permisos VM.Audit, VM.Clone, VM.Config.Disk, VM.Config.CPU, VM.Config.Memory, VM.PowerMgmt.

  3. Desplegar el driver en Rancher

    • Añadir dos Helm charts al clúster local de Rancher: uno para el backend del driver y otro para la extensión UI.
    • Configurar los valores del chart con la URL del API de Proxmox, el token y el ID del pool.

  4. Crear un clúster en Rancher

    • Seleccionar “Proxmox” como node driver.
    • Elegir la plantilla, la cantidad de nodos, recursos y discos. Rancher clona, inicia y bootstrapea los nodos automáticamente.

  5. Escalar y destruir

    • Cambiar el número de workers en la UI de Rancher; el driver crea o elimina VMs según corresponda.
    • Al borrar el clúster, el driver ejecuta una rutina de limpieza que desasigna discos y elimina las VMs del pool.

Cuándo aplicar esta solución

  • Entornos homelab o pequeñas nubes privadas donde Proxmox es el hipervisor principal y se desea gestionar Kubernetes con Rancher.
  • Equipos que requieren escalado rápido (p.ej., pruebas de CI/CD, demos) y no pueden permitirse la intervención manual para cada nodo.
  • Políticas de seguridad estrictas que prohíben el uso de contraseñas de root en scripts; el token limitado al pool satisface el principio de menor privilegio.
  • Implementaciones de storage distribuido (Longhorn, Ceph) que necesitan discos de bloque reales en cada nodo.

No aplicar si se usa un hipervisor sin API REST (p.ej., Hyper‑V sin extensión) o si el clúster Rancher está en una versión anterior a 2.10, ya que el driver requiere la API de node drivers introducida en esa versión.

Código

# 1. Añadir el repositorio del driver
helm repo add pve-driver https://raw.githubusercontent.com/Lore09/pve-rancher-driver/main/charts
helm repo update

# 2. Instalar el backend del driver
helm install pve-driver-backend pve-driver/pve-driver \
  --namespace cattle-system \
  --set proxmox.apiUrl=https://pve.example.com:8006/api2/json \
  --set proxmox.tokenId=terraform@pve!driver-token \
  --set proxmox.tokenSecret=YOUR_TOKEN_SECRET \
  --set proxmox.pool=terraform-pool

# 3. Instalar la UI extension
helm install pve-driver-ui pve-driver/pve-driver-ui \
  --namespace cattle-system

Verificación

  1. Acceso a la UI de Rancher → al crear un clúster, la opción “Proxmox” debe aparecer en la lista de node drivers.
  2. Crear un clúster de prueba con 1 control‑plane y 2 workers. Verificar que aparecen VMs en el pool especificado dentro de Proxmox.
  3. Comprobar IP – cada nodo debe registrar una dirección IP válida (no la del puente CNI) en la tabla de nodos de Rancher.
  4. Escalar a 4 workers – observar la aparición de dos VMs adicionales y su unión automática al clúster.
  5. Borrar el clúster – confirmar que todas las VMs y discos asociados desaparecen del pool.

Notas adicionales

  • Cloud‑init templates: si la plantilla no incluye cloud-init correctamente, los nodos pueden arrancar sin configuración de red y fallar el registro en Rancher.
  • Serial de discos: algunos sistemas operativos cambian el número de serie al formatear; usar lsblk -o NAME,SERIAL dentro de la VM ayuda a validar que el driver está seleccionando el disco correcto.
  • Rancher 2.10+: versiones anteriores no soportan la API de node drivers personalizada; actualizar antes de instalar.
  • Multi‑node Proxmox: cuando el API token está limitado a un pool, el driver funciona sin cambios en clusters de Proxmox con varios nodos físicos, siempre que el pool sea accesible desde todos ellos.
  • VLAN y bridges: la UI del driver permite seleccionar el bridge en tiempo real; sin embargo, en entornos con VLAN taggeada, asegúrese de que el bridge tenga la VLAN configurada en Proxmox, de lo contrario los nodos no obtendrán IP.