Instalar el plugin de TrueNAS para Proxmox en un clúster: guía paso a paso

Esta es la guía de instalación de nuestro fork del plugin de almacenamiento de TrueNAS para Proxmox VE. Es el que usamos en producción y el que trae los arreglos que contamos en TrueNAS + Proxmox: arreglamos el CHAP iSCSI roto en SCALE 25.10.

El procedimiento va en CADA nodo Proxmox del clúster. La configuración del almacenamiento, en cambio, se hace una sola vez para todos.

Antes de empezar, lo que más veces se hace mal:

No uses el install.sh ni el repositorio APT que menciona el README. Esas son las instrucciones de instalación de upstream y están ahí a propósito: instalan la build oficial de upstream, no la nuestra. El README del fork lo advierte en las primeras líneas.

Requisitos

TrueNAS SCALE 25.10 o superior. Es la versión que publica namespaces NVMe/TCP en caliente; por debajo de esa, la parte de NVMe no funciona como se describe aquí.
Un usuario y una API key en la cabina con los roles mínimos que documenta el repositorio en wiki/API-Permissions.md. No hace falta un usuario con todos los permisos, y no conviene dárselos.

1. Instalar, en cada nodo

Desde septiembre de 2026 ya no hace falta clonar ni compilar nada. Cada versión se publica como paquete en las releases del repositorio, junto con su suma sha256, y un instalador se encarga del resto:

curl -sSL https://github.com/alfonsokuen/truenas-proxmox-plugin/releases/latest/download/install-idk.sh | bash

Descarga el .deb de la última release, verifica su sha256 antes de instalar y aborta si no cuadra. Acepta --dry-run para ver qué haría sin tocar el sistema, --version idkNN para fijar una versión concreta y --wizard para lanzar el asistente de configuración al terminar.

Si prefieres leer el script antes de ejecutarlo —que es lo razonable con cualquier curl a un intérprete—, descárgalo primero y míralo:

wget https://github.com/alfonsokuen/truenas-proxmox-plugin/releases/latest/download/install-idk.sh
less install-idk.sh
bash install-idk.sh --dry-run

El postinst del paquete se encarga del resto: activa el broker de sesión y recarga los servicios de PVE por su cuenta. No hay que reiniciar nada a mano.

Compilar el paquete a mano (ya no es necesario)

Si quieres construirlo tú, la rama del fork es idk-fork; main es upstream sin tocar, deliberadamente, para poder comparar.

git clone -b idk-fork https://github.com/alfonsokuen/truenas-proxmox-plugin.git
cd truenas-proxmox-plugin
./tools/build-deb.sh

El .deb queda en el directorio padre, no en el del repositorio, y se instala con apt install ../truenas-proxmox-plugin_<version>_all.deb. Mira el nombre real del fichero que ha quedado en vez de copiar una versión de una guía: cambia en cada release.

2. Configurar el almacenamiento (una sola vez para todo el clúster)

La configuración vive en /etc/pve/storage.cfg, que Proxmox replica a todos los nodos. Se edita una vez, no una por nodo.

El repositorio trae un storage.cfg.example como guía, con lo que hay que definir:

host y API key de la cabina;
los portales;
whitelist y DH-CHAP, si quieres un subsistema cerrado;
los parámetros de resiliencia.

Tres avisos que evitan una instalación coja

1. No instales copiando el .pm a mano. Es el atajo más tentador y el que deja el plugin a medias: el paquete instala además el broker de sesión (una unidad systemd) sin el cual el plugin no funciona completo. Siempre por el .deb.

2. No mezcles con la instalación de upstream. Ya está dicho arriba, pero es el error que más cuesta diagnosticar: todo parece instalado y lo que corre es otro código. Si el nodo tuvo antes la build oficial, asegúrate de que no queda.

3. Si compilas a mano, la rama importa. git clone sin -b idk-fork te trae main, que es upstream íntegro. El paquete se construirá y se instalará sin quejarse; simplemente no tendrá ninguno de nuestros arreglos. Con el instalador no aplica: siempre baja la release del fork.

Qué cambia respecto a upstream

Todo lo que diverge, y por qué, está documentado en DIVERGENCE-IDK.md dentro del propio repositorio. Dos de los arreglos están propuestos de vuelta a upstream.

Conviene decirlo con claridad: upstream no da soporte a esta copia. Si encuentras algo, repórtalo contra este fork, no contra el proyecto original.

Si prefieres no operar esto tú

Montar NVMe/TCP entre una cabina y un clúster de virtualización es la parte fácil; sostenerlo — actualizaciones, snapshots que no se rompen, un fallo de la API de la cabina a las tres de la mañana — es la que cuesta.

Almacenamiento NAS empresarial — cabina, configuración y operación, con la política de snapshots y respaldo definida antes de que haga falta.
Cloud y respaldos — cuando la copia tiene que salir del edificio.
DevOps e infraestructura — para el clúster completo, no solo el almacenamiento.

O escríbenos y lo revisamos sobre tu instalación concreta.