Versiones del módulo ZFS: evitar conflictos entre el kernel y ZFS

Qué significa realmente “kernel vs ZFS peleando”

En Linux, ZFS es un módulo de kernel más herramientas de userland. El módulo del kernel hace el trabajo real: ARC, grupos de transacciones, planificación de IO,
sumas de verificación, compresión, estado de vdev, import/export de pools. Las herramientas de userland (zpool, zfs, zdb,
zed) son el plano de control.

La “pelea” ocurre cuando esas piezas no coinciden en interfaces, expectativas o funciones activadas. Eso puede manifestarse como:

• El módulo no carga después de una actualización del kernel (fallo clásico de DKMS, headers faltantes, símbolos incompatibles).
• El módulo carga pero el pool no se importa debido a expectativas sobre flags de funciones o formatos en disco no soportados.
• Las herramientas informan una versión y el kernel ejecuta otra, lo que conduce a errores extraños como “unsupported pool version” o propiedades faltantes.
• Fallos en el arranque porque el initramfs no incluye el módulo correcto, de modo que el pool raíz nunca aparece.

Tu trabajo es mantener alineados: expectativas ABI del kernel, compilación del módulo ZFS y las funciones del pool en disco. En otras palabras: no dejes que tu pila de almacenamiento se convierta en un proyecto de grupo.

Broma #1: Una actualización del kernel es como un simulacro de incendio sorpresa—excepto que el incendio es tu almacenamiento, y las señales de salida las mantiene DKMS.

Datos interesantes y contexto histórico (lo que la gente olvida)

1. ZFS nació en Sun Microsystems (mediados de los 2000) e incorporó sumas de verificación de extremo a extremo, copy-on-write y almacenamiento agrupado cuando la mayoría de los sistemas de archivos todavía confiaban en “fsck y rezar.”
2. Linux no incluye ZFS en el árbol del kernel principalmente por incompatibilidades de licencia (CDDL vs GPL). Por eso vives en el mundo de módulos externos.
3. “Versiones de pool” fueron reemplazadas por “feature flags” en OpenZFS moderno. Los flags permiten negociación incremental de capacidades en lugar de números monolíticos de versión.
4. FreeBSD e illumos integran ZFS de forma distinta. En Linux gestionas módulos fuera del árbol; en FreeBSD está más cerca de ser un ciudadano de primera clase.
5. DKMS popularizó el flujo “recompilar al actualizar kernel” para que módulos de terceros (ZFS, NVIDIA, etc.) no te obliguen a recompilar manualmente cada vez.
6. Incluir en initramfs es un asunto de disponibilidad de almacenamiento, no una “optimización de arranque.” Si ZFS no está en initramfs y tu raíz está en ZFS, estás a punto de tener una experiencia formativa.
7. OpenZFS es un proyecto multiplataforma. Eso significa que las decisiones de funciones a menudo se limitan a “funciona en Linux/FreeBSD/macOS,” no solo en tu distribución.
8. La versión del módulo del kernel no es la versión del formato del pool. La gente las confunde. Luego “actualizan” el pool y descubren que no hay downgrade.

Las tres capas de compatibilidad que debes tener claras

1) Kernel ↔ módulo ZFS del kernel (compatibilidad de compilación/ABI)

Tu kernel en ejecución exporta símbolos. El módulo ZFS espera ciertos símbolos y estructuras. Si el kernel cambia y el módulo
no coincide, modprobe zfs falla o carga con piezas que faltan.

En muchas distribuciones verás ZFS empaquetado en una de dos formas generales:

• Compilaciones DKMS: el código fuente de ZFS está instalado; el módulo se construye localmente para cada kernel. Flexible, pero ahora eres una canalización de compilación.
• kmods precompilados: paquetes de módulo compilados por la distro para kernels específicos. Menos flexible, normalmente más predecible.

2) Herramientas de userland ZFS ↔ módulo del kernel ZFS (compatibilidad ioctl/API)

Las herramientas zfs/zpool hablan con el kernel vía ioctls y interfaces en sysfs/proc. Si userland es más nuevo que el
módulo (o al revés), puedes obtener comportamiento extraño: propiedades faltantes, “unknown command” o mensajes engañosos de “pool is outdated.”

La mayoría de las distros se esfuerzan por enviar pares compatibles. Los problemas surgen cuando mezclas repos, fijas solo la mitad de la pila o compilas a mano.

3) Funciones en disco del pool ↔ implementación ZFS (compatibilidad de feature flags)

Esta es la parte que te morderá entre máquinas. Los pools llevan feature flags: encryption, large_dnode, spacemap_histogram, etc.
Un sistema solo puede importar un pool si soporta las funciones activadas. La importación puede ser de solo lectura en algunos escenarios, pero “solo necesito montarlo para copiar datos” no es una estrategia.

El comando peligroso no es zpool import. Es zpool upgrade. El primero negocia. El segundo hace cambios irreversibles.

Un máximo de fiabilidad que vale la pena tener en una nota adhesiva. Aquí hay una idea parafraseada de Werner Vogels (CTO de Amazon): Construyan sistemas que asuman que fallarán, y que hagan la recuperación rutinaria. —idea parafraseada

Guion de diagnóstico rápido

Cuando ZFS y el kernel están “peleando”, no deambules. Sigue un orden estricto para localizar el cuello de botella: arranque, módulo o funciones del pool.

Primero: ¿está el módulo cargado y realmente es el que crees?

• Comprueba uname -r, luego confirma que los módulos ZFS están cargados para ese kernel.
• Revisa los logs del kernel por “Unknown symbol” o mismatch de vermagic.
• Confirma que las herramientas de userland y las versiones del módulo del kernel están alineadas.

Segundo: ¿se puede ver e importar el pool?

• zpool import sin importar: ¿lista el pool?
• Prueba zpool import -N (no montar) para aislar la importación de problemas de montaje/propiedades.
• Busca feature flags que no sean soportadas en este host.

Tercero: ¿es un problema de arranque/initramfs?

• Si la raíz está en ZFS y caíste al shell de initramfs: verifica que /lib/modules/$(uname -r) incluya ZFS, reconstruye initramfs.
• Confirma que se arrancó el kernel correcto (no un kernel de respaldo que carezca de los paquetes kmod de ZFS coincidentes).

Cuarto: incidentes de rendimiento que parecen “problemas de versión”

A veces el sistema arranca bien y solo ves problemas bajo carga. Si ZFS silenciosamente recurrió a una compilación distinta del módulo, o estás ejecutando
un combo kernel/ZFS con una regresión conocida, el síntoma es “ZFS está lento” o “txg tarda una eternidad”, no “mismatch de módulo.”

• Revisa estadísticas de ARC y la presión de memoria.
• Revisa tiempos de sync de txg y saturación de I/O.
• Verifica si estás en un kernel recién actualizado sin un kmod precompilado que coincida (DKMS compiló algo, pero ¿lo hizo correctamente?).

Tareas prácticas: comandos, salidas y la decisión que tomas

A continuación hay tareas reales que puedes ejecutar en un host Linux típico usando paquetes OpenZFS. Los comandos se muestran con salidas representativas; tu
entorno variará. El punto es lo que la salida significa y qué haces después.

Tarea 1: Confirmar el kernel en ejecución (el objetivo que debes igualar)

cr0x@server:~$ uname -r
6.8.0-52-generic

Significado: El módulo ZFS debe estar construido específicamente para 6.8.0-52-generic.
Decisión: Cualquier paso de construcción/instalación del módulo ZFS debe referenciar esta versión del kernel. Si estás resolviendo problemas, guarda este valor en la cabeza.

Tarea 2: Comprobar si el módulo ZFS está cargado

cr0x@server:~$ lsmod | grep -E '^zfs|^spl'
zfs                  6340608  6
spl                   131072  1 zfs

Significado: El kernel tiene ZFS y SPL cargados (SPL es la Solaris Porting Layer).
Decisión: Si no aparece nada, intenta cargarlo y busca errores en las siguientes tareas.

Tarea 3: Intentar cargar ZFS y leer el error (el kernel te dirá)

cr0x@server:~$ sudo modprobe zfs
modprobe: ERROR: could not insert 'zfs': Unknown symbol in module, or unknown parameter (see dmesg)

Significado: El binario del módulo no coincide con los símbolos exportados por el kernel (mismatch clásico tras actualizar el kernel).
Decisión: Revisa inmediatamente dmesg, luego recompila/reinstala los módulos ZFS para este kernel, o arranca el kernel anterior que coincida.

Tarea 4: Leer los logs del kernel por mismatch de vermagic/símbolos

cr0x@server:~$ dmesg | tail -n 30
[  112.941230] zfs: disagrees about version of symbol module_layout
[  112.941251] zfs: Unknown symbol spl_kmem_cache_alloc (err -22)
[  112.941260] zfs: Unknown symbol spl_kmem_cache_free (err -22)

Significado: Módulo compilado contra headers de un kernel distinto o contra otro par SPL/ZFS.
Decisión: Trata esto como “problema de compilación del módulo”, no como “problema del pool”. Arregla la cadena de módulos antes de tocar las funciones en disco de ZFS.

Tarea 5: Confirmar las versiones de paquetes ZFS instaladas (userland y kmods)

cr0x@server:~$ apt-cache policy zfsutils-linux zfs-dkms libzfs4linux
zfsutils-linux:
  Installed: 2.2.2-0ubuntu9
  Candidate: 2.2.2-0ubuntu9
zfs-dkms:
  Installed: 2.2.2-0ubuntu9
  Candidate: 2.2.2-0ubuntu9
libzfs4linux:
  Installed: 2.2.2-0ubuntu9
  Candidate: 2.2.2-0ubuntu9

Significado: Userland y el paquete fuente DKMS están alineados en versión.
Decisión: Si estas versiones difieren significativamente (o provienen de repos mezclados), detente y alinea antes de depurar cualquier otra cosa.

Tarea 6: Comprobar estado de DKMS (¿realmente construyó para el kernel actual?)

cr0x@server:~$ dkms status
zfs/2.2.2, 6.8.0-52-generic, x86_64: installed

Significado: DKMS afirma que existe una construcción del módulo ZFS para el kernel en ejecución.
Decisión: Si dice “added” o “built” pero no “installed”, probablemente tengas una compilación a medio hacer. Reconstruye e instala.

Tarea 7: Forzar una reconstrucción DKMS para el kernel actual (cuando sospechas una compilación rota)

cr0x@server:~$ sudo dkms remove -m zfs -v 2.2.2 --all
Deleting module zfs-2.2.2 completely from the DKMS tree.

cr0x@server:~$ sudo dkms install -m zfs -v 2.2.2 -k 6.8.0-52-generic
Building module:
Cleaning build area...
make -j8 KERNELRELEASE=6.8.0-52-generic...
Installing module...
DKMS: install completed.

Significado: Eliminaste compilaciones obsoletas y reconstruiste para el kernel específico.
Decisión: Si esto falla, la cadena de herramientas del compilador, los headers o cambios en el kernel son tu problema—soluciona eso antes de reiniciar en producción.

Tarea 8: Verificar que el módulo en disco coincide con el kernel en ejecución

cr0x@server:~$ modinfo -F vermagic zfs
6.8.0-52-generic SMP preempt mod_unload modversions

Significado: El vermagic del módulo coincide con el kernel en ejecución.
Decisión: Si el vermagic no coincide, estás cargando el módulo equivocado o compilado para el kernel incorrecto. Arregla el empaquetado o arranca el kernel correcto.

Tarea 9: Verificar que userland y el módulo del kernel reportan versiones ZFS consistentes

cr0x@server:~$ zfs version
zfs-2.2.2-0ubuntu9
zfs-kmod-2.2.2-0ubuntu9

Significado: Herramientas y módulo del kernel están sincronizados.
Decisión: Si difieren (por ejemplo, userland más nuevo que kmod), espera propiedades faltantes y errores extraños. Alinea paquetes; no “trabajes alrededor”.

Tarea 10: Listar pools disponibles para importar (sin hacerlo)

cr0x@server:~$ sudo zpool import
   pool: tank
     id: 1283947562198834211
  state: ONLINE
 action: The pool can be imported using its name or numeric identifier.
 config:

        tank        ONLINE
          mirror-0  ONLINE
            sda3    ONLINE
            sdb3    ONLINE

Significado: El kernel puede leer las etiquetas y ver la topología del pool.
Decisión: Si el pool no aparece, esto no es un “problema de punto de montaje”. Es descubrimiento de dispositivos, disponibilidad de claves de cifrado o fallo del kernel/módulo.

Tarea 11: Importar sin montar datasets (separa importación de problemas de montaje)

cr0x@server:~$ sudo zpool import -N tank
cr0x@server:~$ zpool status -x
all pools are healthy

Significado: La importación del pool funciona; los problemas restantes son propiedades de datasets, claves o servicios.
Decisión: Si tu problema original era “unidades systemd se quedan colgadas”, esto lo aclara: el pool está bien; la pelea es el flujo de montaje.

Tarea 12: Comprobar feature flags y compatibilidad antes de “actualizar” cualquier cosa

cr0x@server:~$ zpool get all tank | grep feature@
tank  feature@async_destroy          enabled   local
tank  feature@encryption             enabled   local
tank  feature@project_quota          active    local

Significado: El pool tiene funciones activadas/activas; importarlo en otro lugar requiere soporte para esas funciones.
Decisión: Si necesitas portabilidad entre hosts (DR, recuperación forense), mantén una matriz de qué hosts soportan qué funciones. No actives funciones a la ligera.

Tarea 13: Ver qué upgrades están disponibles (soporte de decisión en modo solo lectura)

cr0x@server:~$ zpool upgrade
This system supports ZFS pool feature flags.

The following pools are formatted with legacy version numbers and can be upgraded to use feature flags:
  none

The following pools can be upgraded:
  pool 'tank' has the following supported feature flags:
    spacemap_histogram
    extensible_dataset
    bookmarks
    filesystem_limits

Significado: “Puede ser actualizado” significa “puedes hacer cambios en disco que este sistema entiende”.
Decisión: Solo ejecuta zpool upgrade -a si estás cómodo haciendo al pool potencialmente inimportable en sistemas más antiguos. La mayoría de entornos no debería actualizar pools automáticamente.

Tarea 14: Identificar si usas kmods precompilados o DKMS (la forma del empaquetado importa)

cr0x@server:~$ dpkg -l | grep -E 'zfs-dkms|zfs-kmod|spl-dkms' | awk '{print $1, $2, $3}'
ii zfs-dkms 2.2.2-0ubuntu9

Significado: Este host depende de DKMS para compilar el módulo para cada kernel.
Decisión: Trata las actualizaciones de kernel como “eventos de compilación”. Asegura headers, compilador y hooks DKMS funcionando antes de reiniciar.

Tarea 15: Comprobar si initramfs contiene módulos ZFS (verificación de fiabilidad de arranque)

cr0x@server:~$ lsinitramfs /boot/initrd.img-6.8.0-52-generic | grep -E '/zfs\.ko|/spl\.ko' | head
usr/lib/modules/6.8.0-52-generic/updates/dkms/spl.ko
usr/lib/modules/6.8.0-52-generic/updates/dkms/zfs.ko

Significado: ZFS está presente en initramfs para ese kernel.
Decisión: Si no está presente y tu pool raíz depende de él, reconstruye initramfs antes de reiniciar. Esta es una de esas comprobaciones “baratas ahora, caras después”.

Tarea 16: Reconstruir initramfs tras cambios en el módulo ZFS (hacer que el arranque use la nueva realidad)

cr0x@server:~$ sudo update-initramfs -u -k 6.8.0-52-generic
update-initramfs: Generating /boot/initrd.img-6.8.0-52-generic

Significado: La imagen initramfs se regenera con módulos y hooks actuales.
Decisión: Después de reconstrucciones DKMS, siempre actualiza initramfs en hosts que importan pools durante el arranque (especialmente root-on-ZFS).

Tarea 17: Confirmar salud del pool y descartar “problemas reales de almacenamiento” que se hacen pasar por fallos de versión

cr0x@server:~$ zpool status -v tank
  pool: tank
 state: ONLINE
  scan: scrub repaired 0B in 00:21:43 with 0 errors on Thu Dec 19 03:11:52 2025
config:

        NAME        STATE     READ WRITE CKSUM
        tank        ONLINE       0     0     0
          mirror-0  ONLINE       0     0     0
            sda3    ONLINE       0     0     0
            sdb3    ONLINE       0     0     0

errors: No known data errors

Significado: El almacenamiento está sano a nivel ZFS.
Decisión: Si ves errores de checksum o vdevs degradados, no culpes a las versiones. Arregla hardware/rutas primero; el cambio de versiones durante una falla real es cómo se alargan los outages.

Tarea 18: Revisar eventos ZED y estado del servicio (a veces no carga la política)

cr0x@server:~$ systemctl status zfs-zed.service
● zfs-zed.service - ZFS Event Daemon (zed)
     Loaded: loaded (/lib/systemd/system/zfs-zed.service; enabled; vendor preset: enabled)
     Active: active (running) since Thu 2025-12-26 08:14:12 UTC; 10min ago

Significado: ZED está vivo; puede manejar hotplug y notificaciones de fallos.
Decisión: Si ZED está muerto, perderás reemplazos automatizados y alertas. No causará mismatch de módulos, pero ocultará la historia hasta que sea feo.

Tres micro-historias corporativas (anonimizadas, plausibles y dolorosamente familiares)

Incidente causado por una suposición equivocada: “La actualización del kernel son solo parches de seguridad”

Una empresa SaaS de tamaño medio ejecutaba ZFS en Linux para réplicas de bases de datos. Tenían una ventana de parches semanal, y las actualizaciones de kernel se trataban como
“higiene rutinaria”. El almacenamiento no estaba en el ticket de cambio porque, según decían, “ZFS ya está instalado”.

La corrida de parches actualizó el kernel y reinició la flota de nodos. Un grupo de nodos volvió bien. Algunos no. Los rotos cayeron
en modo de emergencia con sistemas de archivos faltantes, y el on-call vio la típica pista falsa: “cannot import pool”.

La falla real fue aburrida: esos nodos tenían una variante de kernel ligeramente distinta instalada antes (misma serie mayor, build distinto),
y DKMS no compiló ZFS para ese kernel específico porque no estaban presentes los headers. Sin headers, no hay módulo. Sin módulo, no hay pool. ZFS hizo
exactamente lo que debía: se negó a fingir.

La solución no fue heroica. Instalaron los headers correctos, reconstruyeron DKMS, regeneraron initramfs y reiniciaron. Luego actualizaron su
flujo de parches: las actualizaciones de kernel son cambios de almacenamiento si ejecutas módulos fuera del árbol. La “suposición equivocada” fue pensar que OS y
almacenamiento son capas separadas. En Linux, son compañeros de cuarto.

Optimización que salió mal: “Activemos todas las feature flags brillantes en todas partes”

Una compañía estandarizó ZFS para almacenamiento de artefactos de build. Alguien vio que zpool upgrade listaba un bufé de funciones y concluyó:
más funciones = mejor. Actualizaron pools en el clúster primario durante un trimestre tranquilo. Nada se rompió de inmediato.

Meses después, la prueba de recuperación ante desastres movió un pool replicado a un entorno de espera más pequeño que iba un par de lanzamientos de OpenZFS atrasado.
La importación falló por funciones no soportadas. El host de DR no estaba “equivocado”, simplemente era más antiguo.

El equipo intentó arreglarlo bajo presión. Spoiler: no puedes “downgradear feature flags.” Terminaron desplegando un host de standby más nuevo
para importar el pool y luego mover datos a nivel de sistema de archivos. Eso costó tiempo, añadió riesgo y convirtió la prueba de DR en teatro de improvisación.

La lección: las funciones del pool son un contrato de compatibilidad. Si debes mover pools entre hosts, trata los feature flags como versiones de API.
Solo activa lo que necesitas y solo después de confirmar que tus entornos de recuperación pueden importarlo. “Porque está disponible” no es un requisito.

Práctica aburrida pero correcta que salvó el día: fijar kernels y actualizar ZFS por etapas

Una gran empresa ejecutaba cargas mixtas: almacenamiento para VM, analytics y algo de NFS legacy. Tenían presupuesto para buen hardware y
paciencia para procesos. Su gestión de cambios no era glamorosa, pero funcionaba.

Fijaron kernels en nodos de almacenamiento a una serie conocida y avanzada solo tras un horneado en staging. Los paquetes ZFS se actualizaban con
una cadencia controlada, y nunca ejecutaban zpool upgrade automáticamente. Los pools se mantuvieron con un conjunto conservador de funciones hasta que
toda la flota—incluidos hosts de recuperación break-glass—fue confirmada compatible.

Luego llegó un advisory de seguridad del kernel y todos entraron en pánico. No lo hicieron. Introdujeron el nuevo kernel en staging, validaron compilaciones DKMS,
verificaron el contenido de initramfs, testearon reinicios y ejecutaron pruebas I/O focalizadas. Solo entonces pasaron a producción.

Un mes después, otro equipo tuvo una actualización de kernel apresurada en nodos de cómputo general y sufrió problemas de módulos con un driver no relacionado.
Los nodos de almacenamiento siguieron sirviendo. La disciplina “aburrida” de la empresa hizo que su plataforma de almacenamiento permaneciera predecible mientras otras partes de la
compañía practicaban ingeniería sorpresa.

Broma #2: Lo único peor que una sorpresa en la actualización de ZFS es descubrir que tu plan de DR era “importar el pool y rezar”.

Cómo actualizar sin convertir tu pool en un proyecto científico

Regla 1: Separa “actualización de software” de “actualización del formato en disco”

Actualizar paquetes (userland ZFS + kmod) es reversible: puedes revertir paquetes, arrancar un kernel más antiguo o reinstalar versiones conocidas.
Actualizar los feature flags del pool no es reversible en ningún sentido práctico.

Haz las actualizaciones de software primero. Ejecuta por un tiempo. Confirma estabilidad. Solo entonces considera los feature flags, y solo si tienes una razón que puedas explicar
sin usar la palabra “moderno”.

Regla 2: Mantén kernels y módulos ZFS emparejados intencionalmente

En sistemas basados en DKMS, las actualizaciones de kernel son eventos de compilación. Tu CI/CD puede ser impecable y aún así los hooks DKMS pueden fallar porque un host carece de
headers, o porque un nuevo kernel cambió una interfaz interna lo suficiente como para romper la compilación.

Si ejecutas una flota, quieres:

• Una sola serie de kernel por clase de nodo (almacenamiento vs cómputo)
• Verificación automatizada de que DKMS compiló para los kernels instalados
• Una prueba de reinicio antes de declarar la actualización “lista”

Regla 3: Trata la portabilidad del pool como un requisito de primera clase (o renúnciala explícitamente)

Algunos entornos realmente no necesitan importar pools en otro lugar. Está bien. Escríbelo y acepta el riesgo. Pero muchas organizaciones asumen portabilidad
para DR, recuperación forense o soporte del proveedor. Si asumes que puedes mover un pool, debes preservar compatibilidad.

En la práctica: mantén una matriz de compatibilidad de versiones OpenZFS entre todos los hosts que puedan importar un pool. Si un entorno queda atrás,
no actives funciones que no pueda manejar.

Regla 4: No mezcles repositorios de la distribución y “compilaciones aleatorias” en almacenamiento de producción

Mezclar kernels de proveedor, kernels HWE, backports y compilaciones de terceros de ZFS puede funcionar—hasta que no. Entonces estás depurando un ecosistema,
no un sistema. Quieres el conjunto más pequeño de partes móviles que cumpla los requisitos.

Si debes desviarte (kernel personalizado, ZFS personalizado), hazlo de forma consistente en todas partes y asume la carga de pruebas. “Un host especial” siempre
se convierte en el host que falla de la manera más creativa.

Regla 5: Prefiere rutas de actualización predecibles sobre la máxima novedad

La pila de almacenamiento no es el lugar para perseguir cada nueva versión del kernel. Tus usuarios no te agradecerán por descubrir proactivamente una regresión.
Elige líneas de kernel estables, mantén ZFS a juego y gasta tu presupuesto de innovación en cosas que mejoren los SLO.

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

1) Síntoma: modprobe zfs falla tras actualizar el kernel

Causa raíz: Módulo ZFS no construido para el nuevo kernel; headers faltantes; compilación DKMS fallida; mismatch de vermagic.

Solución: Instala headers del kernel que coincidan, reconstruye DKMS para ese kernel, confirma que modinfo -F vermagic zfs coincide, reconstruye initramfs y reinicia.

2) Síntoma: zfs version muestra userland más nuevo que kmod (o viceversa)

Causa raíz: Repos mezclados, actualizaciones parciales, paquetes fijados o instalaciones manuales.

Solución: Alinea los paquetes a la misma versión de OpenZFS desde el mismo canal de repos. No “solo actualices zfsutils-linux” sin la parte del kernel.

3) Síntoma: El pool no se importa en otro host; el error menciona funciones no soportadas

Causa raíz: Feature flags activadas en el pool no son soportadas por la implementación ZFS de ese host.

Solución: Importa en un host que soporte las funciones, luego migra datos (send/receive, rsync, replicación a nivel de aplicación). Prevén recurrencias: deja de activar funciones sin compatibilidad a nivel de flota.

4) Síntoma: El sistema cae al shell de initramfs; pool raíz no encontrado

Causa raíz: Módulos ZFS faltan en initramfs o no se cargan temprano; kernel erróneo arrancado; initramfs no regenerado tras DKMS.

Solución: Arranca un kernel antiguo que funcione, reconstruye initramfs para el kernel previsto, asegura que los hooks ZFS estén incluidos y luego prueba el reinicio.

5) Síntoma: Tras la actualización, los montajes se quedan colgados o la importación es lenta

Causa raíz: No siempre son versiones. Podría ser cambios en rutas de dispositivo, problemas de multipath, nombres by-id faltantes o un txg stall por timeouts de I/O.

Solución: Revisa dmesg por errores de I/O, confirma estabilidad de nombres de dispositivos, verifica zpool status y resultados de scrub, luego investiga estadísticas de rendimiento (ARC, txg, colas de vdev).

6) Síntoma: “Lo arreglaste” reiniciando, luego vuelve a fallar en el siguiente reinicio

Causa raíz: Cargaste un módulo manualmente pero no reconstruiste/initramfs, o DKMS compiló para un kernel pero arrancaste otro.

Solución: Haz la corrección persistente: asegura que el kernel correcto esté instalado y por defecto, DKMS compilado para él, initramfs actualizado y paquetes gestionados correctamente.

7) Síntoma: zpool import ve el pool pero la importación falla con “missing log” o “cannot open” dispositivos

Causa raíz: Cambio en el descubrimiento de dispositivos entre reinicios (por ejemplo, /dev/sdX cambiante), partición faltante, HBA fallado o carrera de udev; no es principalmente un problema de versión de módulo.

Solución: Usa rutas persistentes de dispositivo (by-id), revisa HBAs, valida particiones y solo entonces culpa al software.

Listas de verificación / plan paso a paso

Checklist A: Antes de una actualización del kernel en hosts ZFS

1. Confirma si este host usa DKMS o kmods precompilados (Tarea 14).
2. Asegura que los headers del nuevo kernel se instalarán junto al kernel.
3. Confirma que la herramienta de compilación está presente (compilador, make) si usas DKMS.
4. Haz una comprobación en seco: después de instalar el nuevo kernel (pero antes de reiniciar), verifica que el estado DKMS muestre el módulo construido para el nuevo kernel.
5. Regenera initramfs para el nuevo kernel (Tarea 16) y verifica que contenga zfs.ko (Tarea 15).
6. Tener un plan de rollback: asegura que el kernel antiguo siga instalado y pueda arrancar.

Checklist B: Actualización segura de paquetes OpenZFS (userland + módulo)

1. Actualiza paquetes en bloque (no actualices solo zfsutils).
2. Confirma que zfs version muestre userland y kmod coincidentes (Tarea 9).
3. Confirma que modinfo -F vermagic zfs coincida con uname -r (Tareas 1 y 8).
4. Verifica salud del pool (zpool status -v) antes y después (Tarea 17).
5. Reinicia en una ventana controlada y verifica comportamiento de import/montaje.

Checklist C: Decidir si ejecutar zpool upgrade

1. Escribe la razón (feature específica necesaria, bug de rendimiento corregido, necesidad operativa).
2. Confirma que cada sistema que pueda necesitar importar el pool soporta las funciones que vas a activar.
3. Confirma que backups/replicación están al día.
4. Prefiere actualizar primero un pool de prueba, luego validar send/receive, scrub y flujos de failover/import.
5. Actualiza un pool a la vez. Obsérvalo. Luego continúa.

Paso a paso: Cuando un host no importa pools después de reiniciar

1. Confirma el kernel en ejecución (uname -r).
2. Revisa carga del módulo (lsmod, modprobe zfs).
3. Si modprobe falla, lee dmesg por errores de símbolos/vermagic.
4. Confirma estado DKMS para ese kernel; reconstruye si es necesario.
5. Verifica que initramfs contenga módulos ZFS; regenera si falta.
6. Sólo después de resolver problemas de módulo: ejecuta zpool import e intenta zpool import -N.
7. Revisa feature flags y restricciones de portabilidad si importas en un host diferente.

Preguntas frecuentes

1) ¿Cuál es la diferencia entre “versión de ZFS” y “versión del pool”?

“Versión de ZFS” suele significar la release del software (userland y módulo del kernel). “Versión del pool” solía ser un número monolítico; OpenZFS moderno usa feature flags.
El software puede actualizarse sin cambiar el pool. Activar nuevas funciones del pool cambia la compatibilidad en disco.

2) Si zfs version muestra userland y kmod desajustados, ¿siempre es fatal?

No siempre es fatal de inmediato. Siempre es una mala señal. Podrías obtener propiedades faltantes, errores extraños o diferencias sutiles de comportamiento.
En producción, alinéalos. “Funciona en mi máquina” es como se incuben los outages.

3) ¿Por qué ZFS se rompe tras una actualización del kernel cuando ext4 no?

ext4 está en el árbol del kernel. ZFS no. Las actualizaciones del kernel pueden cambiar interfaces internas, y los módulos fuera del árbol deben recompilarse (DKMS) o sustituirse por kmods que coincidan.

4) ¿Debo preferir DKMS o kmods precompilados?

Los kmods precompilados suelen ser más predecibles si tu distro los soporta bien. DKMS es flexible y común, pero traslada la fiabilidad a tu entorno de compilación.
Si usas DKMS, invierte en validación previa al reinicio y en staging.

5) ¿Puedo degradar un pool después de ejecutar zpool upgrade?

En la práctica, no. Una vez que se activan nuevos feature flags, las implementaciones más antiguas pueden rehusar la importación. Tu “downgrade” se convierte en “migrar datos a un nuevo pool”.

6) ¿Es seguro ejecutar zpool upgrade -a durante actualizaciones rutinarias?

No. Es el equivalente en almacenamiento de “formatear C: por limpieza.” Actualiza pools deliberada y raramente, tras verificar tus entornos de recuperación/importación.

7) Mi pool se importa manualmente, pero no en el arranque. ¿Qué pasa?

Generalmente initramfs u orden de arranque. El módulo ZFS puede no estar en initramfs, o el orden de servicios es incorrecto (claves no disponibles, dispositivos no listos).
Verifica el contenido de initramfs y las unidades systemd, y prueba con zpool import -N durante la depuración del arranque.

8) ¿Por qué dkms status dice “installed” pero modprobe aún falla?

DKMS puede estar “installed” para un kernel distinto del que arrancaste, o puedes tener múltiples kernels instalados y cargas módulos desde el árbol equivocado.
Revisa uname -r, modinfo -F vermagic y verifica la ruta del módulo bajo /lib/modules/$(uname -r).

9) ¿Un mismatch kernel/ZFS es solo un problema de arranque?

Mayormente, pero no exclusivamente. Puede ocurrir un escenario “funciona pero degradado” si estás en un combo nuevo con regresiones o valores por defecto cambiados.
Trata incidentes de rendimiento tras actualizaciones como sospechosos hasta probar lo contrario.

10) ¿Cuál es la estrategia de portabilidad más segura para DR?

Mantén los hosts de DR en versiones de OpenZFS iguales o más recientes que producción, y evita activar feature flags hasta verificar DR.
Si la portabilidad es crítica, considera estandarizar feature flags y documentarlos como un contrato de API.

Conclusión: próximos pasos que realmente reducen el ruido del pager

ZFS no “se rompe aleatoriamente” después de actualizaciones del kernel. Los humanos lo rompen dejando que kernel, módulo, herramientas y funciones del pool
se desalineen en combinaciones incompatibles.
La solución es aburrida: controlar versiones, verificar compilaciones, probar reinicios y tratar los feature flags como una promesa de compatibilidad.

Haz esto a continuación:

1. Elige tu modelo de actualización (DKMS vs prebuilt) y estandarízalo por clase de nodo.
2. Añade una puerta de verificación antes del reinicio: confirma que DKMS compiló para el kernel objetivo y que initramfs incluye módulos ZFS.
3. Deja de actualizar pools automáticamente. Requiere una decisión explícita y una comprobación de portabilidad.
4. Documenta un flujo de “diagnóstico rápido” de una página y haz que el on-call lo siga. La consistencia vence a la creatividad a las 02:00.