Proxmox «sistema de archivos del clúster no listo»: por qué ocurre y cómo solucionarlo

Qué significa realmente “cluster filesystem not ready”

En Proxmox VE, el “sistema de archivos del clúster” no es tu CephFS, NFS, ZFS ni nada montado bajo /mnt. Es pmxcfs, un sistema de archivos en espacio de usuario (FUSE) que vive en /etc/pve. Ahí Proxmox guarda y distribuye la configuración del clúster: definiciones de nodo, configuraciones de VM, configuración de almacenamiento, configuración de corosync, reglas de firewall y un montón de metadatos de estado.

Cuando Proxmox dice que el sistema de archivos del clúster no está listo, te está informando:

• /etc/pve no está montado correctamente (pmxcfs no se ejecuta o está atascado), o
• pmxcfs está en ejecución pero se niega a servir configuración escribible porque el clúster no está en un estado consistente (a menudo un problema de quorum o corosync), o
• pmxcfs no puede operar por problemas locales del nodo (disco lleno, presión de RAM, salto de tiempo, bloqueo de FUSE).

La interfaz y la mayoría de acciones CLI hablan con /etc/pve. Si ese montaje falta o está en solo lectura, Proxmox no puede cambiar el estado del clúster de forma segura. Por eso ves errores que parecen no relacionados: “unable to parse storage config”, “cannot write file”, “failed to lock file”, y similares. Todos son consecuencias del mismo cuello de botella: pmxcfs no está proveyendo el sistema de archivos de configuración.

Cómo funciona pmxcfs y /etc/pve (y por qué es delicado)

pmxcfs es el pequeño motor detrás de la configuración del clúster. Se ejecuta como demonio, monta un sistema de archivos FUSE en /etc/pve y replica cambios entre nodos usando la capa de comunicaciones del clúster (corosync). También mantiene una copia local para que un nodo pueda arrancar y ejecutar VMs aunque otros estén caídos—dentro de ciertos límites.

Verdades operacionales clave

• /etc/pve no es un directorio normal. Es un montaje vivo. “Arreglarlo” editando archivos mientras pmxcfs está caído puede ser inteligente o desastroso, dependiendo de lo que toques.
• El quorum importa. En un clúster de múltiples nodos, Proxmox quiere mayoría antes de permitir escrituras de configuración. Esto no es pedantería; evita divergencia por split-brain.
• Corosync es el transporte. Si corosync no puede formar una membresía estable, pmxcfs normalmente no estará “listo” o estará en solo lectura.
• Latencia, pérdida de paquetes y deriva de tiempo no son “problemas de red”, son “problemas de integridad del clúster”. La pila de clúster los trata como amenazas a la consistencia porque eso es lo que representan.

Este es el modelo operativo que quiero que mantengas en la cabeza:

1. El sistema arranca.
2. corosync intenta formar la membresía del clúster.
3. pve-cluster (pmxcfs) monta /etc/pve.
4. pvedaemon/pveproxy (API/UI) leen y escriben configuración bajo /etc/pve.

Si rompes el #2, el #3 tambalea. Si rompes el #3, el #4 se vuelve una escena del crimen.

Una idea parafraseada, atribuida a Werner Vogels (confiabilidad y sistemas distribuidos): todo falla, así que diseñas asumiendo que fallará (idea parafraseada).

Broma #1: Un clúster Proxmox sin quorum es como una reunión sin actas—todos la recuerdan distinto y nadie está de acuerdo en lo que pasó.

Guía de diagnóstico rápido

Si tienes cinco minutos y el pager vibrando sobre la mesa como un serrucho, no te disperses. Ejecuta esto en orden. Cada paso reduce el cuello de botella.

Primero: ¿/etc/pve está montado y pmxcfs vivo?

• Revisa el montaje y el estado de pve-cluster. Si pmxcfs está muerto o el montaje falta, estás en territorio “nodo local”: choque del servicio, bloqueo de FUSE, disco lleno, presión de memoria.

Segundo: ¿la membresía de corosync y el quorum son saludables?

• Revisa pvecm status y corosync-cfgtool. Si se perdió el quorum, decide si puedes restaurar la red/los pares, o si debes forzar temporalmente el quorum (rara vez es la opción correcta a largo plazo).

Tercero: ¿el tiempo y la red son suficientemente estables para el consenso?

• Revisa la sincronización de tiempo (timedatectl) y los logs de corosync en busca de retransmisiones, timeouts de token y flaps de enlace. Arregla la deriva de tiempo y la pérdida de paquetes antes de reiniciar servicios; de lo contrario solo generarás logs nuevos.

Cuarto: ¿el propio nodo está enfermo (disco/RAM/IO)?

• Revisa uso de disco (df), uso de inodos, presión de memoria y bloqueos de IO. pmxcfs es ligero pero no mágico; puede fallar bajo presión extrema.

Quinto: ¿es esto un split brain o un aislamiento de nodo único?

• Si varios nodos reclaman ser primarios/activos con membresías inconsistentes, detente y planifica. El split brain es donde los “arreglos rápidos” se convierten en problemas de carrera profesional.

Tareas prácticas: comandos, salidas, decisiones (12+)

Estos son los chequeos que realmente ejecuto. Cada uno incluye qué implica la salida y qué decisión debes tomar después. ejecútalos en el nodo afectado primero, luego en un nodo conocido como bueno para comparar.

Task 1: Confirmar que /etc/pve está montado como pmxcfs

cr0x@server:~$ mount | grep -E '(/etc/pve|pmxcfs)'
pmxcfs on /etc/pve type fuse.pmxcfs (rw,nosuid,nodev,relatime,user_id=0,group_id=0,allow_other)

Significado: Si ves fuse.pmxcfs, el montaje existe. Si no retorna nada, el error de la interfaz está explicado: pmxcfs no está montado.

Decisión: Si falta, ve a las comprobaciones del servicio pve-cluster (Task 2) y a los logs (Task 3). Si está presente pero aún “no listo”, mira el quorum y corosync (Tasks 5–8).

Task 2: Comprobar la salud del servicio pve-cluster (pmxcfs)

cr0x@server:~$ systemctl status pve-cluster --no-pager
● pve-cluster.service - The Proxmox VE cluster filesystem
     Loaded: loaded (/lib/systemd/system/pve-cluster.service; enabled)
     Active: active (running) since Fri 2025-12-26 09:41:18 UTC; 3min ago
   Main PID: 1187 (pmxcfs)
      Tasks: 3 (limit: 154214)
     Memory: 38.2M
        CPU: 1.012s
     CGroup: /system.slice/pve-cluster.service
             └─1187 /usr/bin/pmxcfs

Significado: Si no está activo/en ejecución, pmxcfs no está sirviendo /etc/pve. Si está reiniciándose constantemente, probablemente haya un problema subyacente de corosync/tiempo/disco.

Decisión: Si falló, inspecciona los logs (Task 3) y luego reinicia con cuidado (Task 4) después de entender por qué falló.

Task 3: Leer los logs de pve-cluster para conocer la queja real

cr0x@server:~$ journalctl -u pve-cluster -n 200 --no-pager
Dec 26 09:41:18 server pmxcfs[1187]: [main] notice: starting pmxcfs
Dec 26 09:41:18 server pmxcfs[1187]: [main] notice: resolved node name 'server' to '10.10.0.11'
Dec 26 09:41:19 server pmxcfs[1187]: [dcdb] notice: data verification successful
Dec 26 09:41:20 server pmxcfs[1187]: [status] notice: quorum not present - operations restricted
Dec 26 09:41:20 server pmxcfs[1187]: [status] notice: continuing in local mode

Significado: “quorum not present” es el titular. pmxcfs puede montar, pero puede estar en solo lectura o restringir operaciones. Si ves mensajes de corrupción de base de datos, ese es otro escenario.

Decisión: Si falta quorum, pasa a las comprobaciones de corosync/quorum (Tasks 5–8). Si se menciona corrupción, planifica recuperación y copias de seguridad antes de cambiar nada.

Task 4: Reiniciar pve-cluster (solo después de leer los logs)

cr0x@server:~$ systemctl restart pve-cluster
cr0x@server:~$ systemctl is-active pve-cluster
active

Significado: Si el reinicio tiene éxito y aparece el montaje, es posible que hayas recuperado. Si falla de inmediato otra vez, no solucionaste la causa—vuelve a los logs y a corosync.

Decisión: Si falla repetidamente, deja de reiniciar. Primero arregla tiempo/red/quorum o agotamiento de recursos.

Task 5: Comprobar quorum y membresía del clúster

cr0x@server:~$ pvecm status
Cluster information
-------------------
Name:             prod-cluster
Config Version:   42
Transport:        knet
Secure auth:      on

Quorum information
------------------
Date:             Fri Dec 26 09:44:02 2025
Quorum provider:  corosync_votequorum
Nodes:            3
Node ID:          0x00000001
Ring ID:          1.1
Quorate:          Yes

Significado: Quorate: Yes es lo que quieres. Si dice No, es probable que pmxcfs esté restringiendo escrituras y la interfaz avise.

Decisión: Si no hay quorum, comprueba qué nodos son visibles (Task 6) y por qué hay enlaces caídos (Tasks 7–8).

Task 6: Listar nodos y ver quién falta

cr0x@server:~$ pvecm nodes
Membership information
----------------------
    Nodeid      Votes Name
         1          1 pve-a (local)
         2          1 pve-b
         3          1 pve-c

Significado: Nodos ausentes aquí explican la pérdida de quorum. Si solo aparece un nodo en un clúster de 2 o 3 nodos, estás aislado.

Decisión: Si faltan nodos, revisa los enlaces de corosync (Task 7) y la conectividad de red (Task 9).

Task 7: Comprobar el estado del anillo de corosync

cr0x@server:~$ corosync-cfgtool -s
Printing link status.
Local node ID 1
LINK ID 0
        addr    = 10.10.0.11
        status  = connected
LINK ID 1
        addr    = 172.16.0.11
        status  = disconnected

Significado: Esto muestra qué red(es) de corosync están arriba. Un anillo desconectado puede estar bien si planeaste redundancia, o ser fatal si es tu única ruta funcional.

Decisión: Si el único anillo está abajo, arregla la red o el enrutamiento/VLAN/MTU antes de tocar la configuración de corosync.

Task 8: Buscar timeouts de token y retransmisiones en corosync

cr0x@server:~$ journalctl -u corosync -n 200 --no-pager
Dec 26 09:42:10 pve-a corosync[1050]: [TOTEM ] Token has not been received in 15000 ms
Dec 26 09:42:10 pve-a corosync[1050]: [TOTEM ] Retransmit List: 12
Dec 26 09:42:11 pve-a corosync[1050]: [KNET  ] link: host: 2 link: 0 is down
Dec 26 09:42:12 pve-a corosync[1050]: [QUORUM] Members[1]: 1

Significado: Token no recibido + enlace caído significa que corosync no puede mantener la membresía. Normalmente es pérdida de red, desajuste de MTU o un switch “ayudando” con multicast/unicast.

Decisión: Trata esto como un incidente de red primero. No “forces” el quorum para solucionar un transporte inestable a menos que disfrutes el caos.

Task 9: Verificar alcance L2/L3 entre nodos (y detectar problemas de MTU)

cr0x@server:~$ ping -c 3 10.10.0.12
PING 10.10.0.12 (10.10.0.12) 56(84) bytes of data.
64 bytes from 10.10.0.12: icmp_seq=1 ttl=64 time=0.435 ms
64 bytes from 10.10.0.12: icmp_seq=2 ttl=64 time=0.401 ms
64 bytes from 10.10.0.12: icmp_seq=3 ttl=64 time=0.398 ms

--- 10.10.0.12 ping statistics ---
3 packets transmitted, 3 received, 0% packet loss, time 2022ms
rtt min/avg/max/mdev = 0.398/0.411/0.435/0.016 ms

Significado: La conectividad básica es necesaria pero no suficiente. Corosync puede fallar por jitter/pérdida que ping no muestra.

Decisión: Si ping falla, repara direccionamiento/VLAN/enrutamiento. Si ping tiene éxito pero corosync es inestable, prueba MTU y pérdida de paquetes bajo carga.

Task 10: Comprobar sincronización de tiempo (a corosync no le gusta viajar en el tiempo)

cr0x@server:~$ timedatectl
               Local time: Fri 2025-12-26 09:46:33 UTC
           Universal time: Fri 2025-12-26 09:46:33 UTC
                 RTC time: Fri 2025-12-26 09:46:33
                Time zone: Etc/UTC (UTC, +0000)
System clock synchronized: yes
              NTP service: active
          RTC in local TZ: no

Significado: Quieres System clock synchronized: yes. Una deriva significativa puede contribuir a la inestabilidad de la membresía y a logs confusos.

Decisión: Si no está sincronizado, arregla NTP/chrony/systemd-timesyncd. Luego reinicia corosync/pve-cluster si es necesario.

Task 11: Revisar espacio en disco y agotamiento de inodos (asesinos silenciosos)

cr0x@server:~$ df -h /
Filesystem      Size  Used Avail Use% Mounted on
/dev/pve/root    96G   92G  0.0G 100% /

Significado: Un filesystem raíz lleno provoca fallos extraños en servicios, incluido pmxcfs y el logging. Aunque pmxcfs sea mayormente en memoria, el sistema alrededor necesita espacio libre.

Decisión: Libera espacio inmediatamente (logs, kernels antiguos, caché de ISO). Luego vuelve a comprobar la salud de los servicios.

cr0x@server:~$ df -ih /
Filesystem     Inodes IUsed IFree IUse% Mounted on
/dev/pve/root    6.1M  6.1M     0  100% /

Significado: El agotamiento de inodos parece “disco lleno” pero es peor porque deja de crearse archivos pequeños, incluidos locks y ficheros de estado.

Decisión: Encuentra y elimina directorios con millones de ficheros (ofensores comunes: logs descontrolados, backups mal configurados, overlays de contenedores).

Task 12: Revisar presión de memoria y OOM kills

cr0x@server:~$ journalctl -k -n 100 --no-pager | grep -E 'Out of memory|Killed process' || true
Dec 26 09:35:07 pve-a kernel: Out of memory: Killed process 28814 (pveproxy) total-vm:620004kB, anon-rss:112344kB

Significado: Si el kernel está matando pveproxy/pvedaemon/corosync, tu “cluster filesystem not ready” es daño colateral por agotamiento de recursos.

Decisión: Corrige la presión: para procesos que consumen mucha memoria, añade swap (con cuidado), reduce overcommit e investiga la carga que provocó el OOM.

Task 13: Confirmar que /etc/pve es escribible (y no engaña)

cr0x@server:~$ touch /etc/pve/.pmxcfs-write-test && echo "ok"
ok
cr0x@server:~$ rm -f /etc/pve/.pmxcfs-write-test

Significado: Si touch falla con “Read-only file system” o “Input/output error”, pmxcfs está montado pero no es saludable para escrituras.

Decisión: Solo lectura suele significar falta de quorum. Errores de IO sugieren un montaje FUSE atascado o una falla interna de pmxcfs—vuelve a los logs y considera reiniciar pve-cluster tras arreglar causas subyacentes.

Task 14: Inspeccionar consistencia de la configuración de corosync (no editar aún)

cr0x@server:~$ sed -n '1,120p' /etc/pve/corosync.conf
totem {
  version: 2
  cluster_name: prod-cluster
  transport: knet
  interface {
    linknumber: 0
    bindnetaddr: 10.10.0.0
  }
}

nodelist {
  node {
    name: pve-a
    nodeid: 1
    quorum_votes: 1
    ring0_addr: 10.10.0.11
  }
  node {
    name: pve-b
    nodeid: 2
    quorum_votes: 1
    ring0_addr: 10.10.0.12
  }
  node {
    name: pve-c
    nodeid: 3
    quorum_votes: 1
    ring0_addr: 10.10.0.13
  }
}

Significado: Compruebas errores obvios: IPs equivocadas, bindnetaddr incorrecto, nodo faltante, nodeid duplicado. También confirma que puedes leer el archivo; si no, pmxcfs no lo está sirviendo.

Decisión: Si la configuración está mal por un cambio conocido, planifica una corrección controlada. Ediciones aleatorias durante pérdida de quorum son la forma de manufacturar un split brain.

Task 15: Ver si pveproxy/pvedaemon fallan porque /etc/pve está caído

cr0x@server:~$ systemctl status pveproxy pvedaemon --no-pager
● pveproxy.service - PVE API Proxy Server
     Active: active (running) since Fri 2025-12-26 09:41:22 UTC; 6min ago
● pvedaemon.service - PVE API Daemon
     Active: active (running) since Fri 2025-12-26 09:41:21 UTC; 6min ago

Significado: Estos pueden aparecer “en ejecución” pero aún registrar errores porque no pueden leer la configuración del clúster de forma fiable.

Decisión: Si la interfaz está rota pero los servicios corren, revisa sus logs por fallos de lectura/escritura en “/etc/pve” y vuelve a centrarte en pmxcfs/corosync.

Causas raíz por subsistema

1) Pérdida de quorum (la más común, y comportamiento habitual)

El quorum no es un castigo; es un cinturón de seguridad. Sin quorum, un clúster no puede estar seguro de que la configuración que vas a escribir no entre en conflicto con otro nodo que haga lo mismo. pmxcfs responde restringiendo operaciones. La interfaz interpreta eso como “cluster filesystem not ready”, porque desde su perspectiva no puede hacer su trabajo.

Desencadenantes típicos:

• Un nodo caído en un clúster de 2 nodos (no hay mayoría).
• Partición de red (los nodos no se ven; ambas partes pueden pensar que la otra está muerta).
• Interfaz de corosync caída, cambio de VLAN, problema en switch, desajuste de MTU.
• Deriva de tiempo más red inestable provoca churn en la membresía.

Patrón de solución: restaurar la membresía (traer nodos, arreglar la red), añadir un dispositivo de quorum para clústeres pequeños, o rediseñar para evitar clústeres de 2 nodos sin qdevice.

2) Inestabilidad del transporte de corosync (knet, flaps de enlace y “hace ping bien”)

Corosync no solo necesita conectividad; necesita entrega predecible. Pérdida de paquetes, microbursts, bufferbloat o un firewall “inteligente” en el camino pueden causar timeouts de token. Cuando eso ocurre, la membresía cambia constantemente y pmxcfs se pone nervioso o se niega a estar listo.

Patrón de solución: pon corosync en una red dedicada y aburrida. Nada de NAT. Nada de firewalls stateful en medio. Coincide el MTU. Evita ruteos asimétricos. Si necesitas redundancia, usa múltiples enlaces de forma intencionada y pruébalos.

3) Deriva de tiempo (el ingrediente furtivo)

Los sistemas distribuidos no requieren tiempo perfecto, pero sí que el tiempo no brinque. Si un nodo está minutos fuera, o si NTP ajusta el reloj de forma agresiva, puedes obtener secuencias de logs extrañas, fallos de autenticación y comportamiento inestable del clúster.

Patrón de solución: configura sincronización de tiempo fiable en cada nodo; prefiere slewing gradual; no ejecutes daemons de tiempo mezclados que compitan entre sí.

4) Agotamiento de recursos del nodo local (disco lleno, inodos, OOM, stalls de IO)

pmxcfs es pequeño, pero vive en un sistema operativo real. Si la raíz está llena, journald no puede escribir, los servicios fallan al arrancar y los montajes FUSE pueden comportarse mal. Si la memoria es escasa, el OOM mata procesos críticos en el peor momento. Si el almacenamiento está en espera, los procesos se bloquean, incluido corosync.

Patrón de solución: trátalo como causa de outage del nodo. Libera espacio, arregla el logging, para el proceso descontrolado y luego reinicia servicios.

5) Montaje FUSE o estado atascado de pmxcfs

A veces pmxcfs “está en ejecución” pero el montaje /etc/pve está trabado. Ves errores de IO, esperas largas en ls /etc/pve o procesos en estado D. Puede deberse a problemas del kernel/FUSE, presión extrema o deadlock interno de pmxcfs.

Patrón de solución: estabiliza primero el nodo (CPU/IO/memoria), luego reinicia pve-cluster. Si el montaje no se desmonta limpiamente, puede que necesites reiniciar el nodo (sí, de verdad).

6) Divergencia de configuración y split brain

El split brain es cuando partes del clúster discrepan sobre la membresía y actúan independientemente. En términos de Proxmox, es cuando nodos escriben versiones enfrentadas de la “verdad” bajo /etc/pve. La plataforma hace mucho por evitarlo; los administradores aún pueden derrotar esas salvaguardas forzando quorum, copiando configuraciones o trayendo nodos en orden equivocado.

Patrón de solución: deja de escribir, elige una fuente de la verdad y reconcilia con cuidado. A menudo eso implica apagar la partición minoritaria, restaurar conectividad y asegurar que el clúster se forme con los votos esperados.

Broma #2: “Simplemente forzar quorum” es la versión de sistemas distribuidos de “sujétame una cerveza”.

Tres micro-historias corporativas (anonimizadas, plausibles y educativas)

Incidente #1: una suposición equivocada (la trampa de dos nodos)

Tenían un clúster Proxmox sencillo: dos nodos, almacenamiento compartido y la cómoda creencia de que “si sobrevive cualquiera, estamos bien”. Funcionó durante meses. Entonces un switch top-of-rack se reinició durante una actualización de firmware y uno de los nodos perdió la conectividad del clúster durante un par de minutos.

Cuando la red volvió, el equipo encontró “cluster filesystem not ready” en el nodo aislado. No podían migrar. No podían editar almacenamiento. Algunas operaciones de VM seguían funcionando localmente, pero cualquier cosa que implicara configuración del clúster estaba bloqueada. El on-call asumió que el sistema de archivos del clúster era “un montaje de almacenamiento” y empezó a revisar NFS. NFS estaba bien; ese no era el problema.

La suposición equivocada era sutil: pensaban que “dos nodos” implica “redundante”. En lógica de quorum, dos nodos implica “empate”. Un empate no es una decisión, es un bloqueo con modales más educados.

Lo “resolvieron” forzando expected votes a 1 en el nodo aislado, editaron la configuración y luego reconectaron el segundo nodo. Ahora ambos nodos habían hecho cambios independientemente. No explotó de inmediato. Simplemente se convirtió en una divergencia de configuración de lento crecimiento: entradas de almacenamiento que no coincidían, recursos HA inconsistentes y una ventana de mantenimiento posterior que se volvió un rompecabezas.

La solución final fue aburrida: agregar un dispositivo de quorum y dejar de tratar a dos nodos como un clúster real sin desempate. También reconfiguraron corosync en una VLAN dedicada. La gran ganancia no fue el tiempo de actividad; fue que el clúster dejó de discutir sobre la realidad.

Incidente #2: una optimización que salió mal (jumbo frames y el token que desaparece)

Otra organización quiso reducir CPU y mejorar rendimiento en la “red de clúster”, así que activaron jumbo frames extremo a extremo. Excepto que no era extremo a extremo. Un puerto intermedio del switch se quedó en MTU 1500 porque formaba parte de un trunk legado y nadie quería tocarlo en horario laboral.

El tráfico de VM casi no lo notó. TCP puede negociar y recuperarse. Corosync lo notó de inmediato, porque depende de entrega oportuna de mensajes. No falló limpiamente. Flapeó: timeouts de token, retransmisiones, miembros que caían y se reincorporaban. Cada pocos minutos alguien veía “cluster filesystem not ready” en la interfaz, luego desaparecía, luego volvía.

El equipo optimizó para rendimiento y accidentalmente optimizó fuera la fiabilidad. Peor, el síntoma no apuntaba a MTU; apuntaba a Proxmox. Reiniciaron servicios durante horas, lo que mayormente generó nuevas líneas de log y una renovada confianza en que “es aleatorio”.

La solución fue simple: hacer consistente el MTU. No “más grande”. Consistente. Después de eso, corosync dejó de hacer timeouts, el quorum se estabilizó y pmxcfs volvió a ser aburrido—que es exactamente lo que quieres para la distribución de configuración.

Incidente #3: práctica aburrida pero correcta que salvó el día (NICs dedicadas de corosync y cambios disciplinados)

Una empresa financiera tenía un clúster Proxmox en un rack de centro de datos compartido donde los cambios de red ocurrían con frecuencia. Ya les había pasado antes, así que mantuvieron el tráfico de corosync en un par de NIC dedicadas, ancladas a un par de switches separado, y documentaron las IPs y MTUs exactas como si fuera un contrato legal.

Un día un incidente de la instalación tumbó un switch. La mitad de los servidores del rack vieron pérdida de enlace en un lado. Sus nodos Proxmox registraron un enlace caído, pero corosync permaneció conectado por el segundo enlace. El quorum nunca cayó. pmxcfs nunca se volvió solo lectura. La interfaz se mantuvo funcional.

Lo que lo hizo funcionar no fue heroísmo. Fue que habían diseñado para la falla aburrida: perder un switch. También tenían una regla operativa: no editar la configuración de corosync durante un incidente activo. Cuando las cosas tambalean, los humanos hacen elecciones “creativas”. La regla lo previno.

Después del incidente no cambiaron nada salvo reemplazar el switch muerto. Luego ejecutaron una prueba controlada de failover la semana siguiente para confirmar el comportamiento. No fue emocionante. Y ese es el punto.

Errores comunes: síntoma → causa raíz → solución

1) Síntoma: banner de UI “cluster filesystem not ready”, pero las VMs siguen corriendo

Causa raíz: pmxcfs está restringiendo escrituras por pérdida de quorum; las cargas pueden correr localmente, pero los cambios de configuración están bloqueados.

Solución: restaura la membresía de corosync y el quorum. Trae los nodos faltantes en línea, arregla la red de corosync o despliega un dispositivo de quorum para clústeres pequeños.

2) Síntoma: ls /etc/pve se queda colgado o devuelve “Input/output error”

Causa raíz: montaje FUSE trabado, pmxcfs atascado o el nodo bajo fuerte presión de IO.

Solución: revisa stalls de IO y logs del kernel, luego reinicia pve-cluster. Si el montaje no se recupera, reinicia el nodo después de garantizar que las VMs estén gestionadas (migradas o detenidas de forma segura si usan almacenamiento local).

3) Síntoma: “quorum not present – operations restricted” en los logs de pve-cluster

Causa raíz: el clúster no tiene mayoría; a menudo un diseño de 2 nodos o una caída de nodo/red.

Solución: restaura la conectividad del nodo faltante o añade qdevice. Evita forzar expected votes a menos que entiendas los riesgos de split-brain y estés operando en modo de emergencia de nodo único.

4) Síntoma: logs de corosync muestran timeouts de token y lista de retransmisiones crece

Causa raíz: pérdida de paquetes, desajuste de MTU, etiqueta VLAN incorrecta o un firewall/ACL interfiriendo con el tráfico de corosync.

Solución: mueve corosync a una red dedicada y estable; valida la consistencia del MTU; elimina dispositivos stateful en el camino. Luego reinicia corosync y confirma membresía estable.

5) Síntoma: los servicios se siguen reiniciando; logs escasos; comportamiento “aleatorio”

Causa raíz: filesystem raíz lleno o agotamiento de inodos; journald no puede escribir y los servicios fallan de formas confusas.

Solución: libera espacio/inodos inmediatamente. Luego reinicia servicios y vuelve a comprobar. No persigas fantasmas mientras el SO no puede crear ficheros.

6) Síntoma: tras “arreglar”, las configuraciones del clúster difieren entre nodos

Causa raíz: alguien editó configuraciones mientras el nodo estaba aislado o forzaron el quorum, provocando divergencia.

Solución: detén escrituras de configuración, establece una única fuente de la verdad y reconcilia con cuidado. Si hace falta, reincorpora nodos en secuencia controlada y verifica la progresión de la versión de configuración del clúster.

7) Síntoma: solo un nodo muestra consistentemente “not ready” tras reinicios

Causa raíz: mismatch de hostname/IP, ring0_addr incorrecto, resolución DNS rota o renombrado de NIC que cambió la interfaz usada por corosync.

Solución: confirma resolución de nombre del nodo, bindnetaddr de corosync y la interfaz correcta. Arregla la red del SO primero, luego corosync y luego pmxcfs.

Listas de verificación / plan paso a paso

Checklist A: Restaurar el estado “listo” de forma segura (nodo único afectado)

1. Deja de hacer cambios. Nada de editar almacenamiento, unir nodos o copiar archivos al tun tun.
2. Verifica el montaje: mount | grep /etc/pve. Si falta, enfócate en pve-cluster.
3. Revisa el servicio: systemctl status pve-cluster y journalctl -u pve-cluster.
4. Comprueba el quorum: pvecm status. Si no hay quórum, no esperes configuración escribible.
5. Revisa corosync: journalctl -u corosync, corosync-cfgtool -s.
6. Comprueba el tiempo: timedatectl.
7. Revisa disco/inodos: df -h /, df -ih /.
8. Sólo entonces reinicia: reinicia corosync si el transporte está arreglado; reinicia pve-cluster tras estabilizar corosync.
9. Valida: pvecm status quorate, touch /etc/pve/test funciona, el banner de la UI desaparece.

Checklist B: Clúster de dos nodos “not ready” tras caída de un nodo

1. Asume que la pérdida de quorum es comportamiento esperado.
2. Trae el segundo nodo de vuelta (o arregla el interconector) en lugar de forzar escrituras.
3. Si esto se repite: implementa un dispositivo de quorum.
4. Documenta una regla estricta: “no forzar quorum durante incidentes salvo autorización y registro”.

Checklist C: Sospecha de split brain

1. Congela escrituras de configuración. Impide que la gente “arregle” editando archivos del clúster.
2. Identifica particiones: qué nodos ven qué miembros (ejecuta pvecm status en cada uno).
3. Elige una fuente de la verdad basada en la partición mayoritaria y la versión de configuración consistente más reciente.
4. Restaura la red y asegura que el clúster se forme como una sola membresía.
5. Sólo entonces reconcilia las configuraciones divergentes. Verifica definiciones de almacenamiento y configuraciones de VM antes de aplicar acciones de HA.

Checklist D: Cuando un reinicio es la respuesta correcta

Reiniciar está justificado cuando:

• /etc/pve está colgado y no puedes desbloquear FUSE limpiamente.
• El nodo está en espera de IO severa o con rarezas a nivel de kernel (procesos en estado D) y reiniciar servicios no ayuda.
• Condiciones de OOM son persistentes y necesitas resetear a un estado conocido (después de reducir la carga).

Reiniciar no está justificado cuando:

• No has comprobado disco lleno/inodos/tiempo/red y solo estás probando suerte.
• El clúster está particionado y reiniciar solo barajará sin restaurar conectividad.

Hechos interesantes y contexto histórico (para quienes gustan saber el porqué)

• pmxcfs es un sistema de archivos FUSE, por eso /etc/pve se comporta distinto a un directorio normal y puede “colgarse” cuando el demonio de espacio de usuario está enfermo.
• La configuración del clúster de Proxmox es distribuida, no basada en almacenamiento compartido. No necesitas un SAN para replicar la configuración; necesitas que corosync funcione.
• Históricamente corosync solía apoyarse en multicast en muchas configuraciones; Proxmox moderno usa a menudo el transporte knet, que puede usar unicast y maneja múltiples enlaces con más gracia.
• La lógica de quorum existe para prevenir el split brain, un modo de fallo conocido en primeros clústeres HA donde ambas mitades creían ser primarias y escribían estado en conflicto.
• Los clústeres de dos nodos son inherentemente ambiguos sin un desempate. Esto no es una peculiaridad de Proxmox; es un problema matemático de sistemas distribuidos con cara de operación.
• /etc/pve contiene más que configuraciones de VM: definiciones de almacenamiento, reglas de firewall y ajustes de alcance de clúster. Cuando cae, el radio de impacto parece mayor que “solo clustering”.
• La versión de configuración en pvecm status es una pista útil durante incidentes: te dice si los nodos progresan juntos o están divergiendo.
• La deriva de tiempo causa depuración “imposible” porque los logs no coinciden y los eventos de membresía aparecen fuera de orden; las pilas de clúster tienden a amplificar esa confusión.

Preguntas frecuentes

1) ¿Significa “cluster filesystem not ready” que mis discos de VM no están disponibles?

No. Normalmente significa que /etc/pve (pmxcfs) no está disponible para operaciones de configuración. Tus discos de VM pueden estar bien. Pero las acciones de gestión que dependen de la configuración del clúster pueden fallar.

2) ¿Puedo seguir ejecutando VMs cuando el sistema de archivos del clúster no está listo?

A menudo sí. Las cargas en ejecución no necesariamente se detienen. El riesgo es operativo: puede que no puedas migrar, cambiar configuración o gestionar HA limpiamente hasta que pmxcfs y el quorum vuelvan a estar sanos.

3) ¿Por qué Proxmox bloquea escrituras cuando se pierde el quorum?

Para evitar el split brain en la configuración. Sin quorum, dos particiones podrían aceptar cambios y luego entrar en conflicto. Bloquear escrituras es la opción segura.

4) ¿Es seguro forzar quorum / expected votes a 1?

Puede ser útil temporalmente en una emergencia controlada de nodo único, pero es arriesgado. Si otro nodo está vivo y también escribe, puedes crear divergencia. Trátalo como último recurso y documenta la acción.

5) ¿Cuál es la diferencia entre corosync “arriba” y quorum “quorate”?

Corosync “arriba” puede significar que el daemon está corriendo localmente. “Quorate” significa que ha formado una membresía válida con suficientes votos para tomar decisiones. pmxcfs se preocupa por lo segundo.

6) ¿Por qué ocurre esto después de un cambio de red que “no debería afectar” a Proxmox?

Porque corosync es extremadamente sensible a pérdida de paquetes, inconsistencia de MTU y flaps de enlace. Tu tráfico de VM puede sobrevivir a redes descuidadas; el tráfico de consenso es menos indulgente.

7) ¿Cómo sé si /etc/pve está realmente montado o solo es un directorio?

Ejecuta mount | grep /etc/pve. Debe mostrar fuse.pmxcfs. Si no, no estás viendo el sistema de archivos del clúster.

8) ¿Debo reinstalar el nodo si pmxcfs está roto?

Casi nunca como primer movimiento. La mayoría de los casos son quorum/red/tiempo/presión de disco. Reinstalar puede destruir evidencia y complicar la recuperación. Diagnostica primero.

9) ¿Pueden problemas de Ceph causar “cluster filesystem not ready”?

Indirectamente. Si Ceph provoca una gran espera de IO o presión en el nodo, puede desestabilizar corosync y pmxcfs. Pero pmxcfs en sí no se almacena en Ceph.

10) ¿Por qué la interfaz muestra el error incluso cuando pve-cluster está activo?

Porque “activo” no significa “listo para escrituras seguras”. pmxcfs puede estar montado pero operando en modo restringido por falta de quorum, o puede estar atascado aunque el proceso siga en ejecución.

Conclusión: siguientes pasos prácticos

Si vas a sacar una lección operativa de este error, que sea esta: no lo trates como un problema de almacenamiento; trátalo como un problema de consenso de clúster. Comprueba si /etc/pve está montado, después verifica el quorum y la salud de corosync, y luego arregla tiempo/red/recursos en ese orden.

Siguientes pasos que dan resultado:

• Si ejecutas dos nodos, añade un dispositivo de quorum. Deja de jugarte el empate.
• Dedica una red aburrida a corosync. MTU estable, nada de “appliances” de seguridad en el camino, enlaces redundantes solo si puedes probarlos.
• Monitoriza lo aburrido: disco/inodos en raíz, estado NTP y estabilidad de enlaces de corosync. El error del sistema de archivos del clúster suele ser el mensajero, no el villano.
• Escribe una regla de incidentes: no forzar quorum y no editar manualmente configs durante particiones a menos que haya un responsable único y se entienda el radio de impacto.