Qué hace el plugin de TrueNAS para Proxmox y cuándo compensa

TrueNAS publicó el 10 de septiembre de 2026 la página "Open Storage for Proxmox", y detrás del nombre comercial hay un plugin de almacenamiento para Proxmox VE con licencia GPL-3.0. Crea en TrueNAS un zvol por cada disco de máquina virtual, lo publica por iSCSI o NVMe/TCP y conecta los nodos del clúster sin que abras la consola del NAS. He leído el código de la versión 2.1.23~beta3, he reproducido los pasos de instalación oficiales en un contenedor Debian 13 y he repasado las incidencias abiertas; no lo he probado en un clúster real, porque esta máquina no tiene virtualización anidada. Aquí tienes qué hace, en qué se diferencia de ZFS over iSCSI, NFS, LVM sobre iSCSI y Ceph, cómo se instala y qué sigue sin resolver.

Puntos clave

• Es un plugin de almacenamiento de Proxmox VE, de tipo truenasplugin, que se instala en cada nodo; en TrueNAS no se instala nada
• Habla con la API WebSocket de TrueNAS 25.10 o posterior, así que no necesita la clave SSH de root que exige el ZFS over iSCSI integrado
• Añade lo que el tipo integrado no tiene: clones enlazados desde plantillas, creados como clones de ZFS en el propio NAS
• La última versión es la 2.1.23~beta3, del 11 de septiembre de 2026, pero el repositorio APT oficial todavía sirve la 2.1.17
• Un solo TrueNAS sostiene los discos de todas las VM, y la alta disponibilidad de Proxmox tiene una incidencia abierta con el plugin

Qué es Open Storage for Proxmox y qué instala en cada nodo

Open Storage for Proxmox es el nombre comercial del TrueNAS Proxmox VE Storage Plugin, un módulo Perl que Proxmox VE carga como almacenamiento externo. La guía de desarrollo de plugins de Proxmox^[1] explica el mecanismo: los plugins de terceros viven en /usr/share/perl5/PVE/Storage/Custom/ y deben usar una licencia compatible con AGPLv3. El de TrueNAS declara el paquete PVE::Storage::Custom::TrueNASPlugin, el tipo truenasplugin y dos tipos de contenido, images para discos de VM y rootdir para contenedores LXC, siempre en formato raw.

El paquete .deb de la versión 2.1.23~beta3 pesa 197 384 bytes e instala cuatro piezas: el módulo TrueNASPlugin.pm (8736 líneas), el servicio truenas-plugin-broker con su unidad de systemd, la utilidad truenas-plugin-lvm-filter y el instalador interactivo install.sh. Depende de pve-manager 8.0 o posterior, open-iscsi y multipath-tools, y recomienda nvme-cli. En TrueNAS no se añade software: el plugin usa los servicios iSCSI y NVMe-oF que ya trae el sistema.

Los requisitos publicados son Proxmox VE 8.x o posterior, con la 9.x recomendada, y TrueNAS 25.10 o posterior. El transporte NVMe/TCP exige Proxmox VE 9.x. En el código, la función api devuelve la versión de la API de almacenamiento del sistema mientras esté entre la 11 y la 15, que cubre desde Proxmox VE 8 hasta la 9.2.

Cómo llega un disco de TrueNAS a la máquina virtual

El plugin usa dos canales distintos: la API de TrueNAS para crear, clonar y borrar recursos, e iSCSI o NVMe/TCP para leer y escribir los bloques del disco. Cuando añades un disco desde la interfaz de Proxmox, alloc_image pide a TrueNAS un zvol con pool.dataset.create, lo publica con iscsi.extent.create e iscsi.targetextent.create (o con nvmet.namespace.create) y después cada nodo se conecta con iscsiadm o nvme connect.

La función _tn_dataset_create crea volúmenes dispersos por defecto (tn_sparse vale 1 si no lo cambias) con un tamaño de bloque de 16K. El nombre del volumen en Proxmox guarda el número de LUN, con la forma vol-vm-109-disk-0-lun11, o el UUID del namespace NVMe. En total, el código fuera de comentarios invoca 37 métodos distintos del middleware de TrueNAS, repartidos entre las familias pool, iscsi, nvmet, service, auth y core.

Por qué necesita un servicio broker en cada nodo

Cada comando qm o pvesh y cada trabajador de pvedaemon es un proceso Perl distinto, y cada uno que abriera su propia sesión tendría que autenticarse otra vez. El comentario de cabecera del broker lo cuantifica: TrueNAS limita auth.login_with_api_key a 20 llamadas cada 60 s por IP. Por eso el paquete instala truenas-plugin-broker, que mantiene una sola sesión WebSocket autenticada contra wss://tu_truenas:443/api/current y atiende al plugin por el socket Unix /run/truenas-plugin/broker.sock.

Desde la versión 2.1.21~alpha1 el broker es obligatorio. La función _ws_get_persistent aborta si el socket no existe, y su mensaje de error pide expresamente que no copies TrueNASPlugin.pm a mano. El README sigue documentando esa copia manual como alternativa, así que ese camino ya no funciona salvo que definas TRUENAS_PLUGIN_ALLOW_DIRECT_WS=1, que el propio código reserva para desarrollo.

Snapshots, clones y migración en vivo

Las snapshots son snapshots de ZFS en el NAS: volume_snapshot llama a pool.snapshot.create dentro de un bloqueo de clúster, y el estado de la RAM lo guarda Proxmox aparte. La función volume_rollback_is_possible rechaza volver a una snapshot que no sea la más reciente, igual que el plugin de ZFS local de Proxmox, porque un rollback de ZFS destruye las posteriores.

Los clones enlazados sí son clones de ZFS. Al convertir una VM en plantilla, create_base renombra el zvol a base-<vmid>-disk-N y crea la snapshot @__base__; cada clon enlazado sale de ahí con pool.snapshot.clone. Los clones completos, los movimientos de disco y las copias de seguridad copian los datos a través del nodo. TrueNAS lo reconoce en su anuncio: "Clones, moves, backups, and imports still run host-side".

Proxmox permite la migración en vivo porque el almacenamiento se declara shared 1 y todos los nodos ven el mismo destino iSCSI o subsistema NVMe. La replicación es otra historia: la replicación de almacenamiento de Proxmox^[2] solo admite ZFS local, de modo que las copias entre sitios se configuran con las tareas de replicación de TrueNAS, fuera de Proxmox.

Qué cambia frente a ZFS over iSCSI, NFS, LVM sobre iSCSI y Ceph

El plugin reúne tres cosas que las alternativas no juntan: discos creados desde la interfaz de Proxmox, snapshots y clones de ZFS en el NAS, y ninguna credencial SSH de root en el almacenamiento. Las columnas de snapshots y clones salen de las tablas de funciones de la documentación de almacenamiento de Proxmox^[3] y de sus páginas por tipo.

Frente al ZFS over iSCSI integrado

El tipo zfs de Proxmox hace lo mismo por otra vía: entra por SSH en el servidor, crea el zvol y lo exporta como LUN. La página de ZFS over iSCSI^[4] pide una clave sin contraseña en /etc/pve/priv/zfs/<target_ip>_id_rsa y admite cuatro implementaciones de destino: LIO, IET, ISTGT y Comstar. TrueNAS usa SCST, que el middleware configura a partir de la plantilla scst.conf^[5], y no está en esa lista.

La misma tabla de Proxmox marca los clones de este tipo como no disponibles, y ahí está la ventaja funcional del plugin. TrueNAS llama "legacy" al tipo integrado, aunque la tabla general de Proxmox lo sigue marcando como estable. Hasta ahora el hueco lo cubría el proyecto comunitario freenas-proxmox^[6], con licencia AGPL-3.0, que gestiona los LUN con la API REST de TrueNAS en lugar de SSH. Aun así sigue pidiendo las claves SSH para listar el pool, y su rama estable 2.x llega hasta Proxmox VE 8.4.

Frente a NFS y a LVM sobre iSCSI

Según TrueNAS, los clústeres de Proxmox que ya usan sus equipos funcionan hoy sobre NFS o sobre LUNs iSCSI creados a mano, y el problema de NFS está documentado. La guía de almacenamiento de Proxmox advierte que crear y borrar snapshots internas de qcow2 "will block a running VM". Añade que el rendimiento es "particularly bad with network storages like NFS" y que en discos grandes puede tardar "several minutes, or in extreme cases, even hours". El plugin no sustituye a NFS para todo: ISOs, plantillas de contenedor y copias de seguridad siguen necesitando un almacenamiento de ficheros.

Un LUN iSCSI a pelo no tiene snapshots ni clones, así que Proxmox recomienda crear un LUN grande y poner LVM encima. La página de LVM^[7] aclara que LVM no admite clones enlazados y que las snapshots como cadena de volúmenes "are currently a technology preview in Proxmox VE". Cada ampliación del LUN sigue siendo un cambio manual en TrueNAS.

Frente a Ceph

Ceph es otra arquitectura: el almacenamiento vive en los propios nodos de Proxmox y no hay NAS. La guía de Ceph hiperconvergente^[8] pide al menos tres servidores, preferiblemente idénticos, y recomienda una red dedicada de 10 Gbps o más. El anuncio de TrueNAS lo deja claro: "Treat it as separated compute and storage on TrueNAS, not as a hyperconverged Ceph substitute".

Cómo se instala el plugin de TrueNAS para Proxmox

La instalación tiene una parte en TrueNAS (dataset, servicio, destino y clave de API) y otra en los nodos de Proxmox (paquete y entrada en storage.cfg). Los puertos que deben estar abiertos entre ambos son el 443 para la API, el 3260 para iSCSI y el 4420 para NVMe/TCP.

Preparar TrueNAS

Estos pasos resumen la guía de instalación de TrueNAS^[9] y el README del repositorio:

1. Crea un dataset para Proxmox, por ejemplo tank/proxmox, con el preset Generic
2. Activa el servicio iSCSI (o NVMe-oF Target si vas a usar NVMe/TCP) y márcalo para arrancar automáticamente
3. Crea un destino iSCSI llamado proxmox, que queda como iqn.2005-10.org.freenas.ctl:proxmox, y comprueba que existe el portal en el puerto 3260
4. Genera una clave de API en Credentials > Local Users, mejor para un usuario dedicado que para root

La wiki del proyecto tiene una página de permisos mínimos. Para iSCSI bastan los roles POOL_READ, DATASET_WRITE, DATASET_DELETE, SNAPSHOT_WRITE, SNAPSHOT_DELETE y SERVICE_READ, más los cuatro de iSCSI (SHARING_ISCSI_GLOBAL_READ, SHARING_ISCSI_TARGET_READ, SHARING_ISCSI_EXTENT_WRITE y SHARING_ISCSI_TARGETEXTENT_WRITE). Con NVMe/TCP, los de iSCSI se sustituyen por SHARING_NVME_TARGET_WRITE.

Instalar el paquete en Proxmox VE

La documentación recomienda el repositorio APT, con la suite bookworm para Proxmox VE 8 y trixie para la 9. Reproduje esos pasos el 15 de septiembre de 2026 y el repositorio ofrece una versión antigua:

$ apt-cache policy truenas-proxmox-plugin
truenas-proxmox-plugin:
  Installed: (none)
  Candidate: 2.1.17+deb1

Es lo que más me sorprendió de la revisión: la vía que la documentación llama recomendada instala una versión diez semanas más antigua que la última. El fichero Release de ese repositorio tiene fecha del 1 de julio de 2026. La 2.1.22 corrigió un fallo de pool.dataset.create con TrueNAS 25.10.4 que impedía crear discos (incidencias #58, #65 y #78), y la 2.1.17 no lleva ese arreglo. Si tu TrueNAS está en 25.10.4 o posterior, instala el .deb de la última versión publicada en GitHub:

rel=https://github.com/truenas/truenas-proxmox-plugin/releases/download
wget "$rel/v2.1.23-beta3/truenas-proxmox-plugin_2.1.23.beta3_all.deb"
wget "$rel/v2.1.23-beta3/SHA256SUMS"
sha256sum truenas-proxmox-plugin_2.1.23.beta3_all.deb
grep _all.deb SHA256SUMS
dpkg -i truenas-proxmox-plugin_2.1.23.beta3_all.deb
apt-get -f install -y

Compara las dos sumas a ojo. El fichero SHA256SUMS nombra el paquete con 2.1.23~beta3 y el adjunto de GitHub se llama 2.1.23.beta3, así que sha256sum -c falla con "No such file" aunque el contenido coincida; en mi descarga ambas sumas empezaban por 223fc74f. El script postinst arranca el broker y reinicia pvedaemon, pveproxy y pvestatd, lo que corta tu sesión en la interfaz web; si no te conviene en ese momento, instala con TRUENAS_PLUGIN_NO_RESTART=1 y reinícialos después.

Si usas el gestor de alta disponibilidad, reinicia también pve-ha-crm y pve-ha-lrm en cada nodo. La incidencia #100^[10] documenta que, sin ese reinicio, las VM gestionadas por HA no arrancan y el registro muestra unsupported type 'truenasplugin'. El arreglo entró en la rama alpha el 14 de septiembre y no está en la beta3.

Declarar el almacenamiento

La entrada va en /etc/pve/storage.cfg. Este es el ejemplo mínimo para iSCSI del README, con los nombres de opción que usa la versión actual:

truenasplugin: truenas-storage
    tn_api_host 192.168.1.100
    tn_api_key tu_clave_de_api_de_truenas
    tn_api_insecure 1
    tn_target_iqn iqn.2005-10.org.freenas.ctl:proxmox
    tn_dataset tank/proxmox
    tn_discovery_portal 192.168.1.100:3260
    content images
    shared 1

La página de TrueNAS pide añadir la entrada en cada nodo, pero Proxmox replica /etc/pve/storage.cfg en todo el clúster, así que con editarlo en un nodo basta. Esa misma página, modificada por última vez el 26 de marzo de 2026, muestra las opciones sin el prefijo tn_ (api_host, dataset), que el paquete renombra al instalarse tras guardar una copia storage.cfg.bak.<fecha>. Quita tn_api_insecure 1 si TrueNAS tiene un certificado válido: con ese valor el plugin no verifica TLS.

Para NVMe/TCP cambian tres líneas: tn_transport_mode nvme-tcp, tn_subsystem_nqn en lugar de tn_target_iqn y el portal en el puerto 4420. Comprueba el resultado con dos comandos del README, el primero para ver si el almacenamiento está activo y el segundo para crear un disco de 32 GiB en la VM 100:

pvesm status truenas-storage
qm set 100 --scsi0 truenas-storage:32

Qué he comprobado sin un clúster Proxmox

No he arrancado TrueNAS ni Proxmox VE. El equipo de pruebas es un ARM64 de 18 núcleos sin /dev/kvm, así que no puede virtualizar ninguno de los dos, y el repositorio APT solo publica índice para amd64. Lo que sí he verificado, el 15 de septiembre de 2026:

• El código de la etiqueta v2.1.23-beta3, función por función: api, plugindata, _ws_open, _tn_dataset_create, volume_snapshot, volume_rollback_is_possible, clone_image y _ws_get_persistent
• Los pasos del repositorio APT en un contenedor Debian 13: la versión candidata es la 2.1.17+deb1 y apt-get install -s se detiene en la dependencia pve-manager, de modo que el paquete no se instala fuera de Proxmox VE
• La suma SHA256 del .deb de la beta3, que coincide con la publicada, y su lista de ficheros
• La lista de las 38 incidencias y peticiones de cambio abiertas en el repositorio ese día

Esta es la lista de ficheros del paquete, con el tamaño en bytes de cada uno:

$ dpkg-deb -c truenas-proxmox-plugin_2.1.23.beta3_all.deb \
    | awk '{print $3, $6}'
783 ./usr/lib/systemd/system/truenas-plugin-broker.service
23027 ./usr/sbin/truenas-plugin-broker
7010 ./usr/sbin/truenas-plugin-lvm-filter
387282 ./usr/share/perl5/PVE/Storage/Custom/TrueNASPlugin.pm
410605 ./usr/share/truenas-proxmox-plugin/install.sh

Límites, riesgos y preguntas abiertas

El riesgo mayor es de arquitectura: todos los discos de todas las VM dependen de un solo TrueNAS. Lo demás son síntomas de un proyecto en beta que avanza deprisa, con 22 versiones publicadas en GitHub desde el 19 de febrero de 2026.

Un solo NAS es un punto único de fallo

La documentación de Proxmox lo advierte para su tipo ZFS over iSCSI, y el aviso vale igual para el plugin. Dice así: "You need to make sure that the ZFS appliance does not become a single point of failure in your deployment". La alta disponibilidad de Proxmox^[11] exige al menos tres nodos y almacenamiento compartido, pero si el NAS cae, caen todas las VM a la vez. TrueNAS atribuye la alta disponibilidad a sus equipos Enterprise de las series H y V; una instalación de Community Edition en un solo servidor no la tiene.

Madurez y soporte

TrueNAS presenta esta versión como dirigida a "Early Adopters". La beta3 se etiquetó sobre la rama alpha, mientras main se quedó el 20 de julio con un changelog de la 2.1.17 y un $VERSION que todavía dice 2.1.5 (incidencia #87).

Los mensajes oficiales tampoco coinciden. La página de documentación dice que el plugin "is not yet supported on TrueNAS Enterprise systems" y pide no usarlo en producción. El anuncio del 11 de septiembre^[12], en cambio, dice que el soporte Enterprise "is in active validation and orderable".

Todo el código es GPL-3.0: plugin, broker e instalador. No hay precio publicado: lo que se paga es el hardware y el contrato de soporte de TrueNAS Enterprise, que se negocia con ventas. La documentación aclara que ese soporte "covers plugin functionality only". Los problemas de Proxmox siguen siendo cosa de Proxmox y de su suscripción.

Incidencias abiertas que conviene leer antes

Estas son las que afectan a un despliegue normal, según el estado del 15 de septiembre:

• #100: las VM gestionadas por HA no arrancan hasta reiniciar pve-ha-crm y pve-ha-lrm; arreglado en alpha, sin publicar
• #96: con NVMe/TCP y TrueNAS 25.10.4, peticiones de 6 a 32 MiB fallan de forma esporádica con error interno bajo carga; el autor lo atribuye al destino nvmet-tcp del kernel y envió un parche a la lista linux-nvme
• #88: un clon completo fallido o qm destroy dejan datasets huérfanos y reutilizar el VMID falla con "already exists"
• #89: dos clones completos simultáneos de la misma plantilla compiten al crear el dataset
• #59: las copias de LXC en modo snapshot fallan si quedó un clon de una ejecución anterior

Lo que la documentación dice y el código ya no

La página Known Limitations de la wiki, incluida en la propia beta3, sostiene que solo admite content images y que no hay clones rápidos. El código de la misma etiqueta declara rootdir para contenedores e implementa clones enlazados desde la 2.1.17, del 29 de junio. Cuando la wiki y el código discrepan, fíate del código y del changelog.

Aprovisionamiento fino sin red de seguridad

Los zvols son dispersos por defecto, así que puedes asignar más espacio del que tiene el pool. La guía de Proxmox es explícita sobre lo que pasa si se llena: "all guests using volumes on that storage receive IO errors". El plugin comprueba el espacio libre antes de crear un disco, con una caché de hasta una hora, y rechaza las ampliaciones que superan el 80 % del espacio libre del dataset. Ninguna de las dos comprobaciones impide que los datos escritos después llenen el pool, así que vigila su uso con Prometheus o con las alertas del propio TrueNAS.

Preguntas frecuentes

¿Puedo guardar ISOs y copias de seguridad en este almacenamiento?

No. El plugin solo declara discos de VM y raíces de contenedor; las ISOs, las plantillas y las copias de vzdump van a un recurso NFS o SMB del mismo TrueNAS o a Proxmox Backup Server. Para copias de ficheros fuera de Proxmox tienes la guía de restic con cifrado.

¿Necesito NVMe/TCP o sirve iSCSI?

Empieza por iSCSI, que funciona con Proxmox VE 8 y 9. NVMe/TCP exige la 9, nvme-cli en cada nodo y el servicio NVMe-oF en TrueNAS, y tiene abierta la incidencia #96 sobre errores con peticiones grandes. Migrar después de uno a otro supone crear otro almacenamiento y mover los discos.

¿Sustituye a Ceph en un clúster de tres nodos?

No, y TrueNAS no lo vende así. Ceph replica los datos entre los nodos de Proxmox; el plugin concentra los discos en un NAS externo. Elige el plugin si ya tienes TrueNAS y quieres separar cómputo y almacenamiento, y Ceph si quieres que el almacenamiento sobreviva a la caída de un servidor.

Conclusión

El plugin de TrueNAS para Proxmox compensa si ya tienes un TrueNAS 25.10 y hoy creas LUNs a mano o sufres snapshots de qcow2 sobre NFS. Te da discos, snapshots y clones enlazados desde la interfaz de Proxmox sin claves SSH de root. No compensa todavía si necesitas alta disponibilidad del almacenamiento sin comprar hardware Enterprise, ni si ya operas Ceph con soltura.

Pruébalo en un clúster que no sea de producción, con el .deb de GitHub en lugar del repositorio APT, y lee antes las incidencias #100 y #96. Si montas la prueba en un laboratorio en casa con dos clústeres, dale a cada uno su propio dataset y su propio destino. PegaProx te da una vista común de ambos. La versión en inglés está en /en/truenas-proxmox-plugin/.

Fuentes

1. guía de desarrollo de plugins de Proxmox
2. replicación de almacenamiento de Proxmox
3. documentación de almacenamiento de Proxmox
4. página de ZFS over iSCSI
5. plantilla scst.conf
6. freenas-proxmox
7. página de LVM
8. guía de Ceph hiperconvergente
9. guía de instalación de TrueNAS
10. incidencia #100
11. alta disponibilidad de Proxmox
12. anuncio del 11 de septiembre
13. TrueNAS, Open Storage for Proxmox
14. TrueNAS, Proxmox Integration Early Access Brief (PDF)
15. GitHub, truenas/truenas-proxmox-plugin
16. GitHub, versión v2.1.23-beta3
17. GitHub, incidencia #96 sobre NVMe/TCP