Problema

En entornos de alta disponibilidad basados en Proxmox, los administradores suelen necesitar:

  1. Poner un nodo en modo de mantenimiento con un solo clic y que todas las máquinas virtuales (VMs) o contenedores (CTs) se reubiquen automáticamente.
  2. Ejecutar actualizaciones de nodo de forma rodante, de modo que mientras un host se reinicia para aplicar parches, sus cargas de trabajo continúen operando en los demás nodos del clúster.

En la versión actual del GUI de Proxmox estas acciones solo están disponibles mediante la línea de comandos. La ausencia de un botón “Maintenance” y de un flujo de actualización integrado obliga a scripts externos o a herramientas de terceros, lo que complica la automatización y la consistencia en entornos productivos.

Causa

El GUI de Proxmox está pensado principalmente para operaciones manuales y de bajo nivel. Las funcionalidades de evacuación y actualización rodante son, por diseño, operaciones de orquestación que dependen de:

  • HA manager: decide dónde re‑iniciar VMs cuando un nodo se marca como offline.
  • Dynamic load balancer (disponible a partir de la versión que introdujo el balanceo de recursos): permite redistribuir carga, pero no expone una UI para iniciar el proceso.
  • Scripts de mantenimiento: la comunidad ha creado utilidades como ProxPatch, pero no forman parte del core.

El resultado es que, aunque la lógica subyacente exista, el UI no la expone y los administradores deben recurrir a la CLI.

Solución

Implementar un flujo de trabajo nativo usando las herramientas ya incluidas en Proxmox:

  1. Crear un alias de CLI que marque el nodo como “maintenance” y dispare la evacuación automática.
  2. Encadenar la evacuación con la actualización del paquete y el reinicio del nodo.
  3. Re‑activar el nodo una vez completado y dejar que el HA manager redistribuya las VMs según la carga actual.

Paso a paso

1. Definir el modo de mantenimiento

Proxmox permite cambiar el estado del nodo con pvecm nodeset. Un alias sencillo:

alias pmm-maintenance='pvecm nodeset $(hostname) --offline && echo "Node set to maintenance (offline)"'

Al ejecutar pmm-maintenance, el nodo pasa a estado offline y el HA manager comienza a migrar VMs que tengan HA habilitado.

2. Evacuación forzada de VMs no HA

Para VMs sin HA, se necesita migrarlas manualmente. Un bucle Bash que recorra todas las VMs del nodo y las mueva al nodo con menor carga:

#!/bin/bash
CURRENT=$(hostname)
TARGET=$(pvecm status | awk '/Online/ && $2 != "'"$CURRENT"'" {print $2}' | sort | head -n1)

for VMID in $(qm list | awk 'NR>1 {print $1}'); do
    qm migrate $VMID $TARGET --online
done

for CTID in $(pct list | awk 'NR>1 {print $1}'); do
    pct migrate $CTID $TARGET --online
done

Este script asume que el clúster tiene al menos otro nodo online y que la red está configurada para migraciones en vivo.

3. Aplicar actualizaciones y reiniciar

Una vez evacuado, el nodo está listo para recibir paquetes. Proxmox usa apt (Debian‑based) para sus actualizaciones:

apt update && apt full-upgrade -y
reboot

4. Reactivar el nodo

Después del arranque, volver a poner el nodo en línea:

pvecm nodeset $(hostname) --online
echo "Node back online"

El HA manager detectará el nodo activo y, según la política de balanceo, redistribuirá VMs de nuevo o dejará que el dynamic load balancer asigne carga.

5. Automatizar todo en un único script

Combinar los fragmentos anteriores en un script pmm-rolling-update.sh:

#!/bin/bash
set -e

# 1. Set maintenance
pvecm nodeset $(hostname) --offline
echo "Node offline – starting evacuation"

# 2. Evacuate non‑HA VMs/CTs
TARGET=$(pvecm status | awk '/Online/ && $2 != "'"$(hostname)"'" {print $2}' | sort | head -n1)

for VMID in $(qm list | awk 'NR>1 {print $1}'); do
    qm migrate $VMID $TARGET --online
done

for CTID in $(pct list | awk 'NR>1 {print $1}'); do
    pct migrate $CTID $TARGET --online
done

echo "Evacuation complete – applying updates"
apt update && apt full-upgrade -y

echo "Rebooting node"
reboot

Al iniciar el script, el nodo se marca como offline, migra todas sus cargas y se reinicia con los últimos paquetes. Cuando el nodo vuelva, el administrador solo necesita ejecutar pvecm nodeset $(hostname) --online.

Cuándo aplicar esta solución

  • Clústeres con al menos 3 nodos: garantiza que siempre haya un nodo de destino para la evacuación.
  • Entornos con HA activado: el HA manager ya gestiona la migración de VMs críticas.
  • Política de parches regular: ideal para ciclos de actualización semanal o mensual.
  • No aplicar si el clúster está en modo de solo lectura, si la red no soporta migraciones en vivo, o si las VMs dependen de dispositivos locales que no pueden ser migrados (por ejemplo, discos locales sin Ceph/RBD).

Código

#!/bin/bash
set -e

# Maintenance mode
pvecm nodeset $(hostname) --offline
echo "Node set to maintenance (offline)"

# Choose target node (least loaded)
TARGET=$(pvecm status | awk '/Online/ && $2 != "'"$(hostname)"'" {print $2}' | sort | head -n1)

# Migrate VMs
for VMID in $(qm list | awk 'NR>1 {print $1}'); do
    qm migrate $VMID $TARGET --online
done

# Migrate containers
for CTID in $(pct list | awk 'NR>1 {print $1}'); do
    pct migrate $CTID $TARGET --online
done

# Update packages
apt update && apt full-upgrade -y

# Reboot
reboot

Verificación

  1. Estado del nodo: pvecm status debe mostrar el nodo como offline antes del reboot y online después.
  2. Migraciones: qm list y pct list en el nodo de origen deben quedar vacíos; los mismos IDs deben aparecer en el nodo objetivo.
  3. HA manager: ha-manager status debe indicar que todas las VMs HA están running y asignadas a nodos activos.
  4. Versión de paquetes: pveversion -v después del reboot debe reflejar la versión esperada.

Notas adicionales

  • Persistencia de IP: si usas IP estáticas dentro de VMs, verifica que la red virtual (VLAN/bridge) esté disponible en el nodo de destino.
  • Almacenamiento compartido: la solución asume que el almacenamiento está en Ceph, NFS o cualquier backend compartido. Con discos locales la migración fallará.
  • Ventana de mantenimiento: aunque el script automatiza el proceso, es recomendable ejecutar la actualización fuera de los picos de carga para evitar saturar el nodo objetivo.
  • Logs: revisa /var/log/syslog y /var/log/pve/tasks para detectar errores de migración o de paquetes.
  • Extensión a ProxMox VE 8: la sintaxis de pvecm nodeset se mantiene, pero verifica la documentación de la versión específica antes de usar flags nuevos.