Portabilidad de banderas de características de ZFS: evitar sorpresas de “No se puede importar”

Qué son realmente las banderas de características (y por qué rompen las importaciones)

Las “banderas de características” de ZFS son capacidades del formato en disco registradas a nivel de pool. Reemplazaron el antiguo modelo de
“versión del pool” donde un único número creciente intentaba representar todo. Las banderas son más granulares:
un pool puede soportar algunas características y no otras; distintas implementaciones pueden añadir nuevas características sin coordinar un contador global.

Aquí está la trampa de la portabilidad: una vez que una característica se vuelve activa en un pool (o a veces cuando simplemente está habilitada),
puede que necesites una implementación de ZFS que la entienda para importar el pool. Si mueves los discos a un host con ZFS más antiguo,
o una compilación del proveedor sin esa característica, ZFS puede negarse a importar. Esto no es capricho de ZFS. Es prevención de corrupción silenciosa.

Habilitada vs activa: el detalle pequeño que arruina fines de semana

ZFS registra las características en estados que suelen verse así: disabled, enabled, active.
La presentación exacta varía ligeramente según la plataforma, pero la idea es consistente:

• Enabled: al pool se le permite usar la característica si es necesario.
• Active: el pool la ha utilizado realmente; existen estructuras en disco que requieren la característica para interpretarlas correctamente.

El riesgo de portabilidad aumenta drásticamente cuando una característica se vuelve activa. A veces basta con que esté “enabled” para bloquear la importación en ZFS más antiguos;
otras veces solo importa que esté “active”. No quieres descubrir cuál es cuál durante una ventana de migración.

Por qué no puedes simplemente “apagarla”

La mayoría de las banderas de características son puertas de un solo sentido. Una vez que un pool ha usado una característica, eliminarla requeriría reescribir metadatos
y posiblemente estructuras de datos en todo el pool. ZFS no suele proporcionar herramientas de “downgrade” de características. La vía práctica de degradación
es normalmente: replicar los datos a un pool nuevo creado con características más antiguas/compatibles.

Ese es el primer punto de decisión hacia el que te empujará este artículo: la portabilidad es algo que diseñas y pruebas. No es una propiedad
que descubres más tarde mirando errores de zpool import.

El chequeo de realidad seco y gracioso

Chiste #1: Un pool ZFS es portátil de la misma manera que un piano de cola es “movible”. Sí, técnicamente—solo no te sorprendas cuando necesite planificación.

Una cita que vale la pena pegar al monitor

“La esperanza no es una estrategia.” — General Gordon R. Sullivan

Trata la compatibilidad de las banderas de características exactamente como tratas las copias de seguridad: si no la has probado, no la tienes.

Hechos y breve historia: cómo llegamos hasta aquí

Los detalles importan porque la gente sigue repitiendo vieja sabiduría ZFS que solo fue cierta en una era específica.
Aquí hay hechos concretos y puntos de contexto que te ayudarán a razonar sobre la portabilidad hoy.

1. Las “versiones” del pool eran un contador único. ZFS temprano usaba un número de versión de pool; actualizarlo lo incrementaba y podía bloquear importaciones antiguas.
   Las banderas de características se introdujeron para evitar ese modelo todo-o-nada.
2. Las banderas de características se registran en disco. Esto no es un interruptor en tiempo de ejecución; forma parte de la descripción del pool a través de reinicios.
   Eso es excelente para la recuperación—hasta que cambias la descripción a un dialecto que otros hosts no entienden.
3. OpenZFS unificó lo que antes estaba fragmentado. ZFS derivado de Solaris/Illumos y los distintos downstreams divergieron; OpenZFS hizo la coordinación de banderas más realista, pero no perfecta entre empaquetados de proveedores.
4. Linux ZFS (ahora OpenZFS en Linux) popularizó flotas heterogéneas. Muchas organizaciones ejecutan ZFS en Linux, FreeBSD y appliances simultáneamente,
   y la portabilidad entre ellos es una preocupación operativa diaria, no una curiosidad.
5. “zpool upgrade” cambia el contrato. En muchos sistemas, zpool upgrade no solo habilita características; puede habilitar un conjunto
   que los sistemas más antiguos no pueden importar. La gente lo trata como “aplicar actualizaciones de seguridad” y luego se arrepiente.
6. Algunas características son de dataset y otras de pool, pero la restricción de importación es a nivel de pool. Si el pool necesita una característica, toda la importación se ve afectada aunque solo un dataset la haya usado.
7. El cifrado cambió las discusiones sobre portabilidad. El cifrado nativo de ZFS introdujo gestión de claves e integraciones de almacén de claves diferentes entre SO,
   además de banderas necesarias para datasets cifrados.
8. Los appliances de proveedores a veces van rezagados. Los appliances de almacenamiento pueden distribuir sistemas “basados en ZFS” con conjuntos de características conservadores o versiones de OpenZFS demoradas,
   lo que los convierte en los miembros menos compatibles de tu flota.
9. La importación en solo lectura aún puede fallar. Algunas personas asumen que zpool import -o readonly=on evitará requisitos de características. No lo hará si
   el formato en disco no puede interpretarse de forma segura.

La conclusión: las banderas de características son la solución de ingeniería correcta, pero exigen disciplina operativa. Si tu proceso es “actualizar cuando se solicita”,
básicamente estás dejando que tus pools escriban cheques que otras máquinas no podrán cobrar.

Modos de fallo que conducen a “no se puede importar”

1) El pool se actualizó en un host y luego se movió a un host más antiguo

Escenario clásico: tienes un pool que a veces se importa en el Host A (OpenZFS más reciente) y a veces en el Host B (más antiguo). Alguien ejecuta
zpool upgrade en el Host A porque parece un paso de mantenimiento inofensivo. Ahora Host B no puede importar.

2) Una característica se volvió activa porque se cambió una propiedad del dataset

Ciertas propiedades de dataset pueden activar características del pool indirectamente. No ejecutaste una actualización; “simplemente habilitaste xattr=sa” o “habilitaste cifrado”
o “habilitaste special_small_blocks”. Esas acciones pueden activar características. Ahora tu sistema de DR no puede importar, o tu objetivo de replicación se niega a recibir.

3) Versiones heterogéneas de OpenZFS en una flota, con empaquetado inconsistente

Incluso dentro de “OpenZFS”, las distribuciones y proveedores pueden incluir distintas versiones, backports o conjuntos de características. Puedes tener dos sistemas “2.1.x”
donde uno soporta una característica y el otro no debido a la selección de parches. Asumir que la paridad semántica de versiones equivale a paridad de características es una buena forma de redactar informes de incidentes.

4) Alguien usó una ruta de snapshot/replicación por conveniencia que arrastró características

El envío raw para datasets cifrados, soporte de bloques grandes, datos embebidos—esto puede ligar la compatibilidad de tu replicación al soporte de características.
Puedes replicar datos y aun así quedar atascado si el receptor no puede soportar el formato en disco implicado por el stream de send.

5) El pool se creó ignorando la “compatibilidad”

OpenZFS moderno tiene una propiedad compatibility (en algunas plataformas) que puede restringir características al crear el pool para que coincida con un conjunto objetivo.
Si no la configuras y luego descubres que la necesitabas, estás en terreno de reconstrucción.

Guion de diagnóstico rápido

Cuando un pool no se importa y la gente está mirando, no tienes tiempo para redescubrir ZFS. Necesitas una ruta de triaje rápida que distinga
“banderas de características no compatibles” vs “discos/rutas faltantes” vs “daño”. Este es el orden que suele llevarte a la verdad más rápido.

Primero: confirma que es un problema de banderas y no discos faltantes

• Ejecuta zpool import y lee la salida completa. Si dice “unsupported feature(s)”, deja de adivinar y comienza a recopilar información.
• Comprueba que el SO vea todos los discos (rutas by-id). Si el pool está incompleto, puedes recibir ruido engañoso.

Segundo: identifica qué características se requieren y qué ZFS estás ejecutando

• Obtén la implementación local de ZFS y la información de versión (zfs version en Linux; uname/kldstat e info de paquetes en BSD).
• Extrae la lista de características que requiere el pool desde la salida de importación, luego compárala con las características soportadas localmente.

Tercero: decide si puedes importar en algún sitio, aunque sea temporalmente

• Encuentra un host (o medio de arranque) con una versión de ZFS que soporte las características requeridas.
• Si puedes importar allí, tus opciones se abren: replicar fuera, volver a snapshots previos a la activación (a veces), o mantener el pool en el host más nuevo.

Cuarto: elige una ruta de recuperación segura

• Si el pool debe ser portátil a sistemas más antiguos, planifica una migración: crea un pool nuevo con características restringidas y usa zfs send | zfs receive.
• Si el sistema antiguo debe permanecer, actualiza su ZFS (si es compatible y seguro) en lugar de forzar una degradación del pool (usualmente no posible).

Chiste #2: La frase “lo importaremos en la otra máquina” ha terminado más ventanas de cambios que la cafeína.

Tareas prácticas: comandos, salidas, decisiones

Estas tareas están escritas como si estuvieras de guardia: comando, salida realista y qué decisión tomar a partir de ello.
Los ejemplos asumen Linux con utilidades OpenZFS instaladas. Los mismos conceptos aplican en FreeBSD/Illumos, pero algunos comandos difieren.

Tarea 1: Listar pools importables y detectar “funcionalidades no compatibles” inmediatamente

cr0x@server:~$ zpool import
   pool: data
     id: 13462978123456789012
  state: UNAVAIL
status: The pool was last accessed by another system.
action: The pool cannot be imported due to missing or damaged devices.
   see: zpool import -F for recovery
config:

        data        UNAVAIL  insufficient replicas
          raidz1-0  UNAVAIL  insufficient replicas
            sda     UNAVAIL  cannot open
            sdb     UNAVAIL  cannot open
            sdc     UNAVAIL  cannot open

   pool: backup
     id: 998877665544332211
  state: UNAVAIL
status: The pool uses the following feature(s) not supported on this system:
        com.delphix:spacemap_histogram
        com.delphix:extensible_dataset
action: The pool cannot be imported. Access the pool on a system that supports
        the required feature(s), then migrate the data.
config:

        backup      UNAVAIL  unsupported feature(s)

Decisión: “data” parece un problema de visibilidad de dispositivos/replicas insuficientes. “backup” es un problema de compatibilidad por banderas.
No pierdas tiempo cambiando cables por “backup”; busca un host ZFS más reciente.

Tarea 2: Intentar una importación en solo lectura (para confirmar que aún falla por características)

cr0x@server:~$ sudo zpool import -o readonly=on backup
cannot import 'backup': unsupported version or feature
unsupported feature(s): com.delphix:spacemap_histogram com.delphix:extensible_dataset

Decisión: La lectura en solo lectura no ayuda. Necesitas un sistema que soporte esas características, o debes actualizar el ZFS de este sistema.

Tarea 3: Comprobar qué características soporta tu ZFS actual

cr0x@server:~$ zpool get -H -o property,value all | grep feature@
feature@async_destroy                         enabled
feature@empty_bpobj                           active
feature@lz4_compress                          active
feature@spacemap_histogram                    -
feature@extensible_dataset                    -
feature@embedded_data                         -
feature@bookmarks                             enabled

Significado de la salida: Las características con - son desconocidas/no soportadas por esta implementación.

Decisión: Si el pool requiere spacemap_histogram y tú muestras -, la importación nunca funcionará aquí.
Detente y elige: actualiza ZFS aquí, o mueve los discos a un host que ya lo soporte.

Tarea 4: Identificar la versión de OpenZFS local (Linux)

cr0x@server:~$ zfs version
zfs-2.1.5-1
zfs-kmod-2.1.5-1

Decisión: Ahora puedes comparar esta versión con la que importó el pool por última vez. Si el pool se importó por última vez en 2.2+,
deberías asumir incompatibilidad de características hasta demostrar lo contrario.

Tarea 5: Ver qué host importó por última vez el pool (ayuda a encontrar la caja “más nueva”)

cr0x@server:~$ zdb -C backup | head -n 25
MOS Configuration:
        version: 5000
        name: 'backup'
        state: 0
        txg: 925331
        pool_guid: 998877665544332211
        hostid: 0x3f2a9c10
        hostname: 'stor-ops-07'
        vdev_tree:
            type: 'root'
            id: 0
            guid: 1234567890123456789

Significado de la salida: El pool registra el hostname/hostid que más recientemente escribió en él.

Decisión: Ve a buscar stor-ops-07 (o su reemplazo). Ese es tu mejor candidato para un entorno de importación compatible.

Tarea 6: En el host “más nuevo”, listar los estados de características del pool

cr0x@server:~$ sudo zpool get -H -o property,value all backup | grep feature@
feature@async_destroy                         enabled
feature@empty_bpobj                           active
feature@lz4_compress                          active
feature@spacemap_histogram                    active
feature@extensible_dataset                    active
feature@embedded_data                         active
feature@bookmarks                             enabled

Significado de la salida: Esas características de origen Delphix ahora están active, por lo que el pool depende verdaderamente de ellas.

Decisión: Degradar no es realista. Tu camino es actualizar el sistema antiguo o migrar los datos a un pool compatible nuevo.

Tarea 7: Confirmar si un pool tiene un perfil de compatibilidad (si es soportado)

cr0x@server:~$ sudo zpool get -H compatibility backup
compatibility    off

Decisión: Si tienes objetivos de sistemas mixtos, “off” es una mala señal. Para pools nuevos deberías establecer un perfil de compatibilidad alineado con
el sistema más antiguo en el que necesites importar.

Tarea 8: Crear un pool “portátil” nuevo con características restringidas (patrón de ejemplo)

cr0x@server:~$ sudo zpool create -o ashift=12 -o compatibility=openzfs-2.1 portable mirror /dev/disk/by-id/wwn-0x5000c500a1b2c3d4 /dev/disk/by-id/wwn-0x5000c500a1b2c3d5
cannot set property for 'portable': invalid property 'compatibility'

Significado de la salida: Tus herramientas actuales no soportan la propiedad (OpenZFS más antiguo, o compilación del proveedor).

Decisión: No improvises. Si no puedes usar un perfil de compatibilidad, debes imponer la portabilidad por política:
evita zpool upgrade, evita activar características riesgosas y valida listas de características antes de migrar.

Tarea 9: Mostrar el estado del pool y confirmar que no hay vdevs faltantes

cr0x@server:~$ sudo zpool status -v backup
  pool: backup
 state: ONLINE
status: Some supported features are not enabled on the pool.
action: The pool can be upgraded using 'zpool upgrade'. Once this is done,
        the pool may no longer be accessible by software that does not support
        the features. See zpool-features(7) for details.
config:

        NAME                                            STATE     READ WRITE CKSUM
        backup                                           ONLINE       0     0     0
          raidz2-0                                       ONLINE       0     0     0
            /dev/disk/by-id/wwn-0x5000c50011111111      ONLINE       0     0     0
            /dev/disk/by-id/wwn-0x5000c50022222222      ONLINE       0     0     0
            /dev/disk/by-id/wwn-0x5000c50033333333      ONLINE       0     0     0
            /dev/disk/by-id/wwn-0x5000c50044444444      ONLINE       0     0     0

Decisión: Resiste la tentación de ejecutar zpool upgrade porque se sugiere.
Ese mensaje es ZFS ofreciéndote amablemente una pistola de portabilidad.

Tarea 10: Auditar propiedades de datasets que suelen activar características no portables

cr0x@server:~$ sudo zfs get -r -o name,property,value -s local encryption,keystatus,special_small_blocks,xattr,recordsize backup
NAME                     PROPERTY              VALUE
backup                    encryption            off
backup                    keystatus             -
backup                    special_small_blocks  0
backup                    xattr                 sa
backup                    recordsize            128K
backup/vm                 encryption            aes-256-gcm
backup/vm                 keystatus             available
backup/vm                 special_small_blocks  16K
backup/vm                 xattr                 sa
backup/vm                 recordsize            16K

Significado de la salida: Tienes datasets cifrados y comportamiento de asignación especial. Estos son activadores comunes de activación de características.

Decisión: Si el receptor/sitio DR no puede soportar cifrado o características especiales de vdev, necesitas un plan de migración que los evite
(nuevo diseño de datasets, o actualizar el receptor).

Tarea 11: Determinar si tu stream de replicación requerirá características más nuevas (ensayo)

cr0x@server:~$ sudo zfs send -nP backup/vm@daily-2025-12-25
size	26.4G
incremental	backup/vm@daily-2025-12-24	backup/vm@daily-2025-12-25

Decisión: Un ensayo confirma que el stream existe y da el tamaño. A continuación, decide si debes usar raw send para cifrado
(lo que implica soporte de características en el receptor) o si puedes replicar en texto plano (lo que cambia tu modelo de amenaza).

Tarea 12: Usar un objetivo de receive controlado y probar importación en el sistema “más antiguo”

cr0x@server:~$ sudo zfs send -R backup/vm@daily-2025-12-25 | ssh dr-old 'sudo zfs receive -uF drpool/test-vm'
receiving full stream of backup/vm@daily-2025-12-25 into drpool/test-vm@daily-2025-12-25
received 26.4G stream in 00:12:41 (35.4M/sec)

Significado de la salida: El receive tuvo éxito, y el dataset no está montado (-u), lo cual es bueno para una validación controlada.

Decisión: Ahora prueba si drpool puede exportarse/importarse en ese sistema más antiguo sin errores de características.
Si puede, tienes una ruta de portabilidad compatible: migrar por replicación, no moviendo discos.

Tarea 13: Verificar la deriva en la activación de características con el tiempo (detectar “alguien lo habilitó”)

cr0x@server:~$ sudo zpool get -H -o property,value all backup | awk -F'\t' '/feature@/ && $2=="active"{print $1}' | sort | head
feature@allocation_classes
feature@embedded_data
feature@extensible_dataset
feature@spacemap_histogram

Decisión: Pon esto en monitoreo o en un informe diario. Si la lista cambia, trátalo como deriva de esquema en una base de datos:
investiga quién/qué cambió el comportamiento y si las suposiciones de portabilidad siguen siendo válidas.

Tarea 14: Confirmar las características soportadas por el host “más antiguo” antes de prometer nada

cr0x@server:~$ zpool get -H -o property,value all | grep feature@ | head
feature@async_destroy                         enabled
feature@empty_bpobj                           active
feature@lz4_compress                          active
feature@spacemap_histogram                    -
feature@extensible_dataset                    -
feature@embedded_data                         -

Decisión: Si ves - para características que están activas en el pool que necesitas mover, detente.
O bien actualiza este host o acepta que no es un destino válido de importación.

Tarea 15: Exportar de forma segura antes de mover hardware (evitar confusión de “en uso”)

cr0x@server:~$ sudo zpool export backup
cr0x@server:~$ zpool import | grep -A2 'pool: backup'
   pool: backup
     id: 998877665544332211
  state: ONLINE

Significado de la salida: Exportar limpia y desancla el pool para que la siguiente importación sea una acción deliberada, no una toma confusa.

Decisión: Haz que “exportar antes de mover” sea un requisito de control de cambios. Reduce ambigüedad en recuperación y facilita diagnósticos posteriores.

Tarea 16: Si debes importar un pool que estaba “en uso”, usa flags de importación seguros con cautela

cr0x@server:~$ sudo zpool import -f backup
cannot import 'backup': unsupported version or feature

Decisión: -f puede anular comprobaciones de “en uso”. No puede anular “característica no soportada”.
Si alguien sugiere “intenta -f otra vez”, tienes permiso para terminar la reunión.

Tres microhistorias corporativas desde el campo

Microhistoria 1: El incidente causado por una suposición equivocada

Una compañía mediana tenía dos servidores de almacenamiento: uno en producción y otro en un laboratorio que también hacía de “DR si nos esforzamos”.
El equipo trataba su pool ZFS como infraestructura portable: mismo modelo de chasis, misma HBA, mismo cableado, así que mover los discos debía funcionar.
Lo habían hecho una vez, meses antes. “Funcionó”, así que se convirtió en un plan.

Durante un fin de semana de mantenimiento, el host de producción se reemplazó con una nueva imagen del SO. Alguien notó una advertencia que parecía inofensiva:
“Algunas características soportadas no están habilitadas en el pool.” Ejecutaron zpool upgrade para limpiarlo.
El pool permaneció en línea. Nada explotó. Todos se fueron a casa temprano y se dijeron a sí mismos que eran responsables.

Dos semanas después, la producción tuvo una falla de placa madre. El equipo puso los discos en el host del laboratorio para recuperar servicios.
La importación falló con “unsupported feature(s)”. El ZFS del laboratorio era más antiguo; no conocía las características que se habían activado.
El plan no estaba mal porque ZFS sea quisquilloso. El plan estaba mal porque dependía de una suposición no documentada: “los pools ZFS son portables entre nuestros hosts.”

La solución fue dolorosamente poco glamurosa: actualizaron el ZFS del host del laboratorio para que coincidiera con producción (tras validar soporte del módulo kernel),
importaron el pool y luego planificaron una reconstrucción real de DR donde la replicación, no el intercambio de discos, sería el método de recuperación.
Lo mejor: el postmortem mostró que el zpool upgrade inicial no era necesario para ninguna característica de negocio.
Fue una acción cosmética que multiplicó la posibilidad de outage.

Microhistoria 2: La optimización que salió mal

Un grupo de ingeniería de datos ejecutaba un clúster respaldado por ZFS. Amaban las optimizaciones de rendimiento como a otros les gustan los cuchillos de cocina nuevos.
Un ingeniero habilitó algunas propiedades para mejorar el rendimiento de metadatos y E/S pequeñas: xattr=sa, registros más pequeños para datasets tipo VM,
y más tarde un vdev especial para metadatos y bloques pequeños. Los benchmarks mejoraron. Las gráficas p99 dejaron de ser vergonzosas.

Luego decidieron replicar el pool a un sistema DR más pequeño y barato. El servidor DR era otra distribución y estaba rezagado en la versión de OpenZFS.
La replicación inicial funcionó para datasets sencillos. En el momento de incluir los datasets “optimizados”, el receive empezó a fallar de maneras extrañas.
Incluso donde la replicación tenía éxito, las pruebas de importación en DR fallaban: características no soportadas vinculadas a clases de asignación y comportamiento de vdev especial.

Lo que salió mal no fue la optimización en sí, sino la suposición organizacional de que DR tenía las mismas capacidades que producción.
El ingeniero mejoró producción activando características que, de hecho, elevaron el dialecto mínimo de ZFS necesario para interpretar el pool.
DR no estaba construido para ese dialecto.

Su solución a largo plazo fue dejar de tratar DR como algo secundario y estandarizar el soporte de características ZFS entre niveles.
A corto plazo, crearon un pool con compatibilidad en DR y cambiaron el alcance de replicación: solo enviar datasets que coincidieran con el perfil de DR,
y mantener los datasets “avanzados” en un pool separado con un plan de DR que incluyera actualizar el objetivo. La optimización fallida se convirtió en una lección arquitectónica:
las características de rendimiento también son decisiones de portabilidad.

Microhistoria 3: La práctica aburrida pero correcta que salvó el día

Una compañía SaaS tenía una política que molestaba a todos: los pools de almacenamiento llevaban una etiqueta con un “entorno mínimo de importación”.
Antes de cualquier actualización de ZFS o cambio de características del pool, el ingeniero de guardia tenía que ejecutar una auditoría rápida de compatibilidad y pegar la salida en la solicitud de cambio.
Parecía teatro burocrático. Hasta que no lo fue.

Durante una renovación urgente de hardware, un ingeniero notó que los hosts nuevos estaban en una versión de OpenZFS más reciente y quería “actualizar todo mientras estamos aquí.”
La plantilla de cambio requería listar las banderas que se habilitarían y compararlas con el host de retroceso más antiguo.
La auditoría mostró que la actualización activaría características no soportadas en el sistema de respaldo.

Tomaron la decisión impopular: no ejecutar zpool upgrade durante la renovación. Los servicios migraron bien.
Dos días después, una regresión en un driver de red en los hosts nuevos obligó a un retroceso temporal al entorno anterior.
Como los pools no se habían actualizado, el retroceso fue un baile estándar de exportar/importar, no una situación de rehenes por banderas de características.

El incidente nunca se convirtió en una caída visible para clientes, y nadie organizó una fiesta. Ese es el punto.
La práctica era aburrida, ligeramente molesta y exactamente lo que parece la fiabilidad en empresas reales.

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

1) Síntoma: “cannot import ‘POOL’: unsupported version or feature”

Causa raíz: El pool tiene características activas que el host actual no soporta.

Solución: Importar en un host con OpenZFS más reciente/coincidente que soporte esas características; luego migrar vía zfs send/receive a un pool compatible, o actualizar el ZFS del host antiguo.

2) Síntoma: “unsupported feature(s): …” la lista contiene entradas com.delphix:*

Causa raíz: El sistema importador es demasiado antiguo (o tiene una compilación de ZFS sin esas características), común en appliances antiguos o distribuciones conservadoras.

Solución: Estandarizar en una base mínima de OpenZFS en los sistemas que deben compartir pools, o dejar de mover discos y cambiar a migración basada en replicación.

3) Síntoma: Puedes importar en producción pero no en DR

Causa raíz: DR está rezagado en características ZFS; un cambio de propiedades en un dataset activó características en producción.

Solución: O bien actualizar DR para que coincida con las características de producción, o rediseñar la replicación para aterrizar en un pool con compatibilidad creada para las capacidades de DR.

4) Síntoma: Alguien dice “solo ejecuta zpool upgrade, está recomendado”

Causa raíz: Confundir “recomendado” con “necesario”. ZFS te está diciendo que existen nuevas características, no que las necesites.

Solución: Hacer de zpool upgrade un cambio controlado con una evaluación de impacto de compatibilidad y un plan de reversión explícito.

5) Síntoma: Tras habilitar cifrado, hosts más antiguos no pueden importar ni recibir replicación

Causa raíz: El cifrado depende de banderas de características y además introduce diferencias en el manejo de claves; la replicación puede requerir raw send y características compatibles.

Solución: Validar el soporte de características de cifrado en todos los endpoints de importación/receive antes de habilitar. Si debes soportar endpoints antiguos, cifra en otra capa o actualiza los endpoints.

6) Síntoma: El pool se importa, pero las herramientas se comportan de forma extraña entre sistemas

Causa raíz: Versiones mezcladas de usuario/ kernel module de ZFS, o soporte parcial/backports de características.

Solución: Alinear versiones de userland y módulos kernel de ZFS; trata a ZFS como una unidad, no como un menú de paquetes.

7) Síntoma: “zpool import” muestra el pool pero el estado es UNAVAIL con “unsupported feature(s)” y también hay dispositivos faltantes

Causa raíz: Dos problemas a la vez: visibilidad incompleta de vdevs más incompatibilidad de características. La gente persigue primero el problema equivocado.

Solución: Confirma la visibilidad de discos primero (rutas by-id), luego maneja el soporte de características. Si las características no son soportadas, ningún cableado solucionará el problema.

8) Síntoma: La replicación tiene éxito, pero la prueba de importación del pool recibido falla en otro sitio

Causa raíz: Probaste send/receive entre dos sistemas, no la portabilidad al tercer sistema. El pool recibido puede haber activado también características.

Solución: Añade un paso de prueba de importación en la plataforma más antigua requerida como puerta en el proceso de migración.

Listas de verificación / plan paso a paso

Lista A: Antes de migrar un pool moviendo discos

1. Identifica el sistema más antiguo que debe importar el pool.
   Si no puedes nombrarlo, asume que es más antiguo de lo que crees.
2. En el sistema origen, inventaría las características activas.
   Captura zpool get all | grep feature@ y guarda la salida con el registro de cambio.
3. En el sistema destino, inventaría las características soportadas.
   Cualquier - para una característica activa en el pool significa “no se puede importar”.
4. Haz una exportación controlada.
   Exporta antes de mover hardware para evitar estados “en uso” sucios y propiedad ambigua.
5. Tener un “host de importación conocido y bueno” listo.
   Un entorno de rescate con un OpenZFS reciente puede salvarte cuando el destino sea demasiado antiguo.

Lista B: Al construir un pool que deba ser portable

1. Define una línea base de portabilidad. Ejemplo: “debe importarse en OpenZFS 2.1 en Linux y FreeBSD” (lo que realmente use tu flota).
2. Usa perfiles de compatibilidad si tu plataforma los soporta. Si no, documenta “no actualizar características” y aplica mediante procesos.
3. Separa características experimentales en pools separados. Trátalo como migraciones de esquema en beta: aisla el radio de impacto.
4. Estandariza versiones de ZFS entre entornos. Producción y DR no deberían ejecutar conjuntos de características mayores diferentes a menos que te guste el riesgo.
5. Automatiza la detección de deriva de características. Si las características activas cambian, alerta e investiga.

Lista C: Plan de migración que evita trampas de portabilidad por banderas (recomendado)

1. Crea un pool objetivo nuevo que coincida con tu línea base requerida.
   Usa restricciones de compatibilidad si están disponibles; de lo contrario usa un host con la línea base de ZFS para crear el pool y no lo actualices.
2. Replica con zfs send/receive y valida.
   Envía datasets por etapas; prueba montajes y comportamiento de la aplicación.
3. Prueba la importación en el sistema más antiguo requerido.
   Exporta/importa el pool nuevo en ese sistema como una puerta real, no como un experimento mental.
4. Corta el servicio y mantén el pool antiguo en solo lectura por una ventana corta.
   Te da una reversión más segura que “revertir toda la migración”.
5. Solo entonces considera habilitar nuevas características.
   Trata la activación de características como un cambio de API que rompe compatibilidad.

Lista D: Qué hacer cuando ya estás atascado

1. No sigas intentando flags de importación al azar. Las características no soportadas no ceden por persistencia.
2. Encuentra un host compatible (o entorno de arranque) que soporte las características requeridas. Importa allí.
3. Pon el negocio en línea usando el host compatible si es necesario. Estabiliza primero; migra después.
4. Planifica la migración a un pool portable vía replicación. Esta es la “degradación” que en realidad tienes.
5. Después de la recuperación, añade salvaguardas. Monitoreo de deriva de características y actualizaciones controladas previenen repeticiones.

Preguntas frecuentes

1) ¿Las banderas de características de ZFS son lo mismo que la “versión del pool”?

No. Las versiones de pool eran un número único de compatibilidad. Las banderas de características son capacidades individuales que pueden habilitarse/activarse independientemente.
Los problemas de portabilidad aún existen; ahora son más granulares.

2) Si nunca ejecuto zpool upgrade, ¿estoy a salvo?

Más seguro, no invulnerable. Algunas características pueden volverse activas mediante operaciones normales o cambios de propiedades (cifrado, asignación especial, etc.).
“No actualizar” es necesario en algunos entornos, pero no es suficiente sin auditoría.

3) ¿Puedo deshabilitar una bandera después de que se vuelva activa?

Normalmente no. La mayoría de las características son efectivamente irreversibles en un pool en vivo. La vía práctica es migrar datos a un pool nuevo creado con el conjunto de características deseado.

4) ¿La importación en solo lectura evita las características no soportadas?

No. Si el sistema importador no puede interpretar estructuras en disco de forma segura, ZFS rechazará incluso una importación en solo lectura.

5) ¿Cuál es la diferencia entre “enabled” y “active” en los listados de características?

Enabled significa que al pool se le permite usar la característica; active significa que el pool la ha usado y ahora depende de ella.
Active es la restricción mayor de portabilidad, pero enabled también puede importar dependiendo de la característica y la implementación.

6) ¿Puedo replicar desde un pool con “características nuevas” hacia un sistema más antiguo?

A veces. La compatibilidad de zfs send/receive depende de qué características de dataset están representadas en el stream y lo que el receptor soporta.
El cifrado y ciertos metadatos pueden forzar que el receptor soporte banderas más nuevas.

7) ¿Por qué el error de importación menciona características com.delphix:*?

Esos nombres provienen del trabajo temprano sobre banderas de características en el ecosistema ZFS más amplio. El nombre no significa que uses productos Delphix.
Significa que tu ZFS importador no entiende características que tu pool ha usado.

8) ¿Cuál es la mejor regla operativa para una flota mixta?

Elige un conjunto base de características de OpenZFS y trátalo como un contrato API. Crea pools según esa línea base y no habilites características que la excedan
salvo que las aísles intencionalmente.

9) ¿Es seguro mover discos entre Linux y FreeBSD si ambos dicen “OpenZFS”?

Puede serlo, pero solo si los conjuntos de características coinciden. “OpenZFS” es un nombre de familia, no una garantía de soporte idéntico de características.
Compara siempre características soportadas, no solo la marca del SO.

10) ¿Qué debo almacenar en los registros de cambio para la portabilidad de ZFS?

Como mínimo: zfs version, la lista de características del pool (zpool get all | grep feature@) y la lista de características soportadas del sistema destino.
Si no puedes demostrar compatibilidad en texto, no tienes compatibilidad.

Conclusión: siguientes pasos que puedes hacer esta semana

Las banderas de características no son un defecto de ZFS. Son un contrato. O gestionas ese contrato, o lo violas por accidente y ZFS se niega a colaborar.
La negativa es el sistema de archivos haciéndote un favor—solo que en el peor momento posible.

1. Inventaría las versiones de ZFS de tu flota. Anota qué corre dónde, incluyendo DR y máquinas de laboratorio que de pronto se vuelven “producción”.
2. Elige una línea base de portabilidad. El sistema más antiguo en el que realmente necesitas importar fija el techo de características.
3. Implementa un paso de auditoría de características antes de actualizaciones o migraciones. Captura las características del pool y compáralas con las características soportadas del destino.
4. Deja de mover pools como método de migración por defecto. Prefiere la replicación hacia un pool creado con restricciones de compatibilidad explícitas.
5. Monitorea la deriva de características. Si el conjunto de características activas cambia, trátalo como un cambio que rompe compatibilidad e investiga de inmediato.

Si no haces nada más: deja de ejecutar zpool upgrade solo porque un mensaje de estado lo sugirió. Actualiza deliberadamente, con un objetivo de compatibilidad,
o acepta que estás quemando el puente detrás de ti. ZFS lo recordará. También tu rotación de guardias.