Configurar QDevice en Proxmox con una Raspberry Pi para mantener el quórum del clúster
Tabla de contenidos
Introducción
Cuando montamos un clúster de Proxmox, una de las piezas más importantes —y a veces menos entendidas— es el quórum.
El quórum es el mecanismo que utiliza el clúster para decidir si tiene suficientes nodos activos como para seguir funcionando de forma segura. En un entorno de alta disponibilidad, esto es fundamental: evita que dos partes separadas del clúster tomen decisiones contradictorias al mismo tiempo.
El problema aparece especialmente en clústeres pequeños. Por ejemplo, en un clúster de dos nodos, si uno cae, el otro puede quedarse sin quórum. Y en un clúster de tres nodos, si por mantenimiento, ahorro energético o una política de apagado ante corte eléctrico dejamos encendido solo un nodo, ese nodo también puede quedarse sin quórum.
Para resolver este problema podemos utilizar un QDevice, también llamado dispositivo de quórum. En este artículo vamos a configurar un QDevice usando una Raspberry Pi, de forma que pueda actuar como testigo externo del clúster Proxmox.
La configuración que se explica a continuación está basada en un entorno real, pero los nombres de host, direcciones IP y recursos se han anonimizado usando datos de ejemplo.
¿Qué problema resuelve un QDevice?
En Proxmox, cada nodo del clúster tiene normalmente un voto. Para que el clúster funcione con normalidad, necesita alcanzar quórum, es decir, tener suficientes votos activos.
En un clúster de tres nodos, la situación habitual es:
Nodo 1 → 1 votoNodo 2 → 1 votoNodo 3 → 1 votoTotal: 3 votosQuórum necesario: 2 votos
Si uno de los tres nodos cae, los otros dos siguen teniendo quórum. Pero si apagamos dos nodos y dejamos solo uno, la situación queda así:
Nodo 1 → 1 votoTotal activo: 1 votoQuórum necesario: 2 votos
Ese único nodo puede estar perfectamente encendido, con sus máquinas virtuales y contenedores, pero el clúster ya no tiene quórum. En la práctica, esto puede afectar a operaciones de HA, migraciones, cambios de configuración y gestión de recursos.
Con un QDevice externo, por ejemplo una Raspberry Pi, añadimos un testigo adicional al clúster.
En el ejemplo de este artículo, tras configurarlo, el clúster queda así:
node-main → 1 votonode-backup → 1 votonode-lab → 1 votoQDevice → 2 votosTotal: 5 votosQuórum: 3 votos
Esto permite que, si apagamos node-backup y node-lab, el nodo principal node-main pueda seguir manteniendo quórum junto con el QDevice:
node-main → 1 votoQDevice → 2 votosTotal activo: 3 votosQuórum: 3 votos
¿Cuándo tiene sentido usar QDevice?
El caso más típico es un clúster de dos nodos. En ese escenario, el QDevice actúa como tercer voto externo y permite que el clúster pueda seguir tomando decisiones de forma segura si uno de los nodos cae.
También puede tener sentido en entornos como este:
- Clúster Proxmox de tres nodos.- Un nodo principal con servicios críticos.- Dos nodos secundarios que se quieren apagar ante un corte eléctrico para ahorrar batería.- Una Raspberry Pi siempre encendida como NUT server, qdevice y sistema de recuperación.
En este caso, el QDevice no se instala únicamente por tener un clúster de dos nodos, sino para resolver un escenario concreto: poder apagar los nodos secundarios durante un corte de corriente y mantener operativo el nodo crítico con quórum.
Proxmox suele presentar QDevice como una solución especialmente útil para clústeres pequeños, sobre todo de dos nodos, aunque también debe usarse con criterio. En clústeres impares, como uno de tres nodos, no siempre es necesario en condiciones normales. Sin embargo, puede tener mucho sentido si durante determinadas situaciones operativas queremos dejar temporalmente encendido un único nodo Proxmox junto a un testigo externo.
Arquitectura del entorno de ejemplo
La infraestructura de ejemplo será la siguiente:
Clúster Proxmox: labclusterNodo crítico:- node-main- IP: 10.20.30.11- Servicios críticos: Home Assistant, DNS, proxy inverso, bases de datos, automatizaciones...- Debe mantenerse encendido el máximo tiempo posible ante un corte eléctrico.Nodo secundario:- node-backup- IP: 10.20.30.12- Se puede apagar pronto para ahorrar batería.Nodo secundario / destino HA:- node-lab- IP: 10.20.30.13- Puede recibir recursos HA, pero también se puede apagar en fase de ahorro si el QDevice mantiene el quórum.Raspberry Pi:- quorum-pi- IP: 10.20.30.50- Funciones: - Servidor NUT. - QDevice/qnetd. - Recuperación por Wake-on-LAN. - Automatización del apagado y recuperación.
El objetivo es que, ante un corte de corriente, el sistema pueda apagar node-backup y node-lab, mantener encendido node-main y conservar quórum gracias a la Raspberry Pi.
Requisitos previos
Antes de empezar, conviene tener:
- Clúster Proxmox ya creado y funcionando.- Acceso root a todos los nodos Proxmox.- Raspberry Pi con Debian/Raspberry Pi OS o similar.- Conectividad SSH entre Proxmox y la Raspberry.- Repositorios Proxmox correctamente configurados.- El clúster en estado sano y con quórum.
Comprobamos el estado inicial del clúster desde uno de los nodos:
pvecm statusha-manager status
En este ejemplo, antes de instalar QDevice, el clúster tiene tres nodos:
node-mainnode-backupnode-lab
Paso 1: instalar qnetd en la Raspberry Pi
En la Raspberry Pi, que en este ejemplo se llama quorum-pi, instalamos el servicio corosync-qnetd.
apt updateapt install -y corosync-qnetd
Activamos el servicio:
systemctl enable --now corosync-qnetd
Y comprobamos que está activo:
systemctl status corosync-qnetd --no-pager
También confirmamos la IP de la Raspberry:
hostnamehostname -I
En este ejemplo:
quorum-pi10.20.30.50
Paso 2: instalar corosync-qdevice en todos los nodos Proxmox
En cada nodo Proxmox del clúster debemos instalar corosync-qdevice.
Desde la Raspberry, si ya tenemos SSH configurado hacia los nodos:
ssh node-main "apt update && apt install -y corosync-qdevice"ssh node-backup "apt update && apt install -y corosync-qdevice"ssh node-lab "apt update && apt install -y corosync-qdevice"
También se puede hacer entrando manualmente en cada nodo:
apt updateapt install -y corosync-qdevice
Es importante instalar corosync-qdevice en todos los nodos del clúster, no solo en uno. Si falta en alguno, la configuración del QDevice puede fallar o quedar incompleta.
Comprobamos la instalación:
dpkg -l | grep corosync-qdevice
Paso 3: corregir repositorios Proxmox si aparece error 401
Durante la instalación puede aparecer un error como este:
401 UnauthorizedThe repository 'https://enterprise.proxmox.com/debian/pve trixie InRelease' is not signed.
Esto sucede cuando el nodo tiene activos los repositorios Enterprise de Proxmox sin disponer de suscripción.
En este ejemplo se utiliza Proxmox VE 9 sobre Debian Trixie, por lo que dejamos activo el repositorio no-subscription y desactivamos los repositorios Enterprise.
En cada nodo Proxmox:
mkdir -p /root/apt-sources-disabledfor f in \ /etc/apt/sources.list.d/pve-enterprise.sources \ /etc/apt/sources.list.d/ceph.sources \ /etc/apt/sources.list.d/pve-enterprise.list \ /etc/apt/sources.list.d/ceph.listdo if [ -e "$f" ]; then mv "$f" /root/apt-sources-disabled/ fidone
Creamos el repositorio no-subscription de Proxmox VE 9:
cat > /etc/apt/sources.list.d/pve-no-subscription.sources <<'EOF'Types: debURIs: http://download.proxmox.com/debian/pveSuites: trixieComponents: pve-no-subscriptionArchitectures: amd64Signed-By: /usr/share/keyrings/proxmox-archive-keyring.gpgEOF
Actualizamos:
apt update
Y repetimos la instalación:
apt install -y corosync-qdevice
Paso 4: permitir SSH desde Proxmox hacia la Raspberry
Para que pvecm qdevice setup pueda configurar el QDevice, uno de los nodos Proxmox debe poder acceder por SSH a la Raspberry.
En la Raspberry habilitamos el acceso root por clave pública:
mkdir -p /etc/ssh/sshd_config.dcat > /etc/ssh/sshd_config.d/99-root-keyonly.conf <<'EOF'PermitRootLogin prohibit-passwordPubkeyAuthentication yesEOFsystemctl reload ssh 2>/dev/null || systemctl reload sshd
Desde la Raspberry, copiamos la clave pública del nodo node-backup al authorized_keys de root en la Raspberry:
ssh node-backup 'test -f /root/.ssh/id_rsa.pub || ssh-keygen -t rsa -b 4096 -f /root/.ssh/id_rsa -N ""; cat /root/.ssh/id_rsa.pub' >> /root/.ssh/authorized_keyschmod 700 /root/.sshchmod 600 /root/.ssh/authorized_keys
Probamos desde node-backup hacia la Raspberry:
ssh node-backup 'ssh -o StrictHostKeyChecking=accept-new -o BatchMode=yes root@10.20.30.50 "hostname && systemctl is-active corosync-qnetd"'
La salida esperada es:
quorum-piactive
Paso 5: comprobar el estado del clúster antes de añadir QDevice
Antes de tocar el quórum, comprobamos que el clúster está correcto:
ssh node-backup "pvecm status"ssh node-backup "ha-manager status"
Debemos ver:
Quorate: YesNodes: 3
En este ejemplo, los recursos HA críticos están arrancados en node-main:
service ct:201 (node-main, started)service ct:202 (node-main, started)service ct:203 (node-main, started)service vm:301 (node-main, started)
Paso 6: configurar el QDevice
Desde uno de los nodos del clúster, ejecutamos:
pvecm qdevice setup 10.20.30.50
En este ejemplo lo lanzamos desde node-backup:
ssh node-backup "pvecm qdevice setup 10.20.30.50"
Si Proxmox advierte de que el clúster ya tiene un número impar de nodos y la configuración se está haciendo de forma intencionada, puede ser necesario utilizar --force:
ssh node-backup "pvecm qdevice setup 10.20.30.50 --force"
La IP 10.20.30.50 corresponde a la Raspberry Pi.
Durante el proceso, Proxmox configura certificados y prepara la comunicación entre el clúster y el servicio qnetd de la Raspberry.
Paso 7: verificar que QDevice está activo
Comprobamos el estado del clúster:
ssh node-backup "pvecm status"
La salida relevante debería ser similar a esta:
Cluster information-------------------Name: labclusterConfig Version: 10Transport: knetSecure auth: onQuorum information------------------Quorum provider: corosync_votequorumNodes: 3Quorate: YesVotequorum information----------------------Expected votes: 5Highest expected: 5Total votes: 5Quorum: 3Flags: Quorate QdeviceMembership information---------------------- Nodeid Votes Qdevice Name0x00000001 1 A,V,NMW node-main0x00000002 1 A,V,NMW node-backup0x00000003 1 A,V,NMW node-lab0x00000000 2 Qdevice
La parte importante es:
Expected votes: 5Total votes: 5Quorum: 3Flags: Quorate Qdevice
Esto confirma que el QDevice está activo y participando en el quórum.
También podemos comprobar los servicios:
ssh node-backup "systemctl status corosync-qdevice --no-pager"ssh node-main "systemctl status corosync-qdevice --no-pager"ssh node-lab "systemctl status corosync-qdevice --no-pager"systemctl status corosync-qnetd --no-pager
Paso 8: probar el escenario real
La prueba más importante es verificar que el clúster mantiene quórum dejando encendido únicamente el nodo crítico node-main junto con la Raspberry.
Primero apagamos node-backup:
ssh node-backup "shutdown -h now"
Después comprobamos desde node-main:
ssh node-main "pvecm status"ssh node-main "ha-manager status"
Después apagamos node-lab:
ssh node-lab "shutdown -h now"
Y volvemos a comprobar desde node-main:
ssh node-main "pvecm status"ssh node-main "ha-manager status"
La salida debería confirmar que node-main mantiene quórum gracias al QDevice:
Expected votes: 5Total votes: 3Quorum: 3Flags: Quorate Qdevice
Esto significa que están activos:
node-main → 1 votoQDevice → 2 votosTotal activo: 3 votosQuórum: 3 votos
Y los servicios críticos deben seguir funcionando:
service ct:201 (node-main, started)service ct:202 (node-main, started)service ct:203 (node-main, started)service vm:301 (node-main, started)
Integración con una política de apagado por SAI/NUT
El motivo de montar QDevice en este entorno era integrarlo con una política de apagado ante corte eléctrico.
El flujo final es:
1. El SAI pasa a batería.2. NUT espera 120 segundos para evitar actuar ante microcortes.3. Si el corte continúa: - apaga node-backup. - apaga node-lab. - apaga el nodo de almacenamiento o servicios no críticos.4. node-main sigue encendido.5. La Raspberry sigue encendida como NUT server y QDevice.6. node-main conserva quórum gracias al QDevice.7. Si vuelve la corriente: - la Raspberry envía Wake-on-LAN. - levanta los nodos apagados. - repara HA si es necesario. - fuerza los servicios críticos a started.
Sin QDevice, al apagar node-backup y node-lab, node-main se quedaría sin quórum. Con QDevice, el problema queda resuelto.
Comandos útiles de comprobación
Ver estado del clúster
pvecm status
Ver estado HA
ha-manager status
Ver si el QDevice está activo
pvecm status | grep -E 'Expected votes|Total votes|Quorum|Flags|Qdevice|Quorate'
Ver servicio qdevice en Proxmox
systemctl status corosync-qdevice --no-pager
Ver servicio qnetd en la Raspberry
systemctl status corosync-qnetd --no-pager
Ver votos esperados
pvecm status
Con QDevice activo deberíamos ver algo como:
Expected votes: 5Total votes: 5Quorum: 3Flags: Quorate Qdevice
Y si solo queda un nodo Proxmox más el QDevice:
Expected votes: 5Total votes: 3Quorum: 3Flags: Quorate Qdevice
Problemas frecuentes
Error 401 Unauthorized en repositorios Proxmox
Si aparece:
401 Unauthorizedenterprise.proxmox.com
hay que desactivar los repositorios Enterprise si no tenemos suscripción y activar el repositorio no-subscription.
El comando pvecm qdevice setup falla
Comprobar en la Raspberry:
systemctl status corosync-qnetd
Y en cada nodo Proxmox:
dpkg -l | grep corosync-qdevice
corosync-qdevice debe estar instalado en todos los nodos Proxmox del clúster.
No aparece Qdevice en pvecm status
Comprobar que el servicio está activo en los nodos Proxmox:
systemctl status corosync-qdevice --no-pager
Y en la Raspberry:
systemctl status corosync-qnetd --no-pager
El clúster sigue sin quórum al apagar nodos
Revisar la salida completa de:
pvecm status
Hay que confirmar:
Flags: Quorate Qdevice
y que el QDevice aparece como miembro con votos.
Consideraciones de seguridad
Durante la instalación, Proxmox necesita acceder por SSH a la Raspberry para configurar certificados y qdevice.
En este ejemplo se permitió acceso root por clave pública:
PermitRootLogin prohibit-password
Esto permite root por clave, pero no por contraseña. Es una configuración más segura que permitir root con contraseña.
Aun así, después de configurar QDevice conviene revisar si se desea mantener o endurecer aún más el acceso SSH. En entornos más expuestos, se puede limitar el acceso por IP, usar firewall o incluso desactivar el acceso root directo una vez finalizada la configuración, siempre comprobando antes que el QDevice sigue funcionando.
Resultado final
Tras la configuración, el clúster queda con QDevice funcionando correctamente:
Expected votes: 5Total votes: 5Quorum: 3Flags: Quorate Qdevice
Y en el escenario real de apagado de nodos secundarios:
node-main encendidonode-backup apagadonode-lab apagadoRaspberry/qdevice encendida
el clúster sigue teniendo quórum:
Expected votes: 5Total votes: 3Quorum: 3Flags: Quorate Qdevice
Esto permite mantener vivos los servicios críticos en node-main incluso después de apagar los otros nodos Proxmox para ahorrar batería durante un corte eléctrico.
Conclusión
Un QDevice en Proxmox es una herramienta muy útil para mejorar la resiliencia de clústeres pequeños o de escenarios donde no siempre van a permanecer encendidos todos los nodos.
En un clúster de dos nodos, permite evitar muchos de los problemas clásicos de quórum. En un clúster de tres o más nodos, aunque no siempre es necesario en funcionamiento normal, puede ser muy útil en escenarios concretos: mantenimiento, apagados controlados, ahorro energético o estrategias avanzadas con SAI/NUT.
En este ejemplo, la Raspberry Pi no solo actúa como QDevice. También forma parte de una estrategia más amplia:
- Servidor NUT.- Testigo de quórum.- Encendido por Wake-on-LAN.- Recuperación automática tras cortes eléctricos.
Con esta configuración, el clúster Proxmox puede mantener servicios críticos activos incluso cuando se apagan los nodos secundarios, sin perder quórum y sin comprometer la alta disponibilidad del entorno.
