Highlights
Adds TrueNAS HA (dual-controller) support for the NVMe/TCP transport, with discoverable documentation across the primary doc entry points.
tn_nvme_manage_ports (new storage property) — enables TrueNAS HA + NVMe/TCP
TrueNAS 25.10.x's nvmet middleware has a hard-coded choices dict inside map_attrs() that validates every nvmet.port record's addr_traddr. On an HA pair, that dict accepts only the pair's VIP. The plugin's default port-management creates one nvmet.port per configured portal with physical controller IPs as addr_traddr, which trips a KeyError in write_config(), aborts the whole configfs render, and leaves every namespace in the subsystem unpublished (controller appears connected, nvme list sees nothing). On a single-head TrueNAS the dict accepts the physical IP and the default works.
New boolean storage property tn_nvme_manage_ports (default 1 for back-compat). Set to 0 on an HA pair's storage stanza: the plugin skips every nvmet.port.* mutation, trusting the admin to pre-provision exactly one VIP-based port record with three midclt calls. TrueNAS renders that one port on both controllers; kernel NVMe multipath + ANA handles failover. The plugin continues to manage subsystem lookup, namespace lifecycle, and initiator-side nvme connect.
If the subsystem named by tn_subsystem_nqn is missing and tn_nvme_manage_ports=0, the plugin refuses to auto-create it and prints the three midclt calls needed to bootstrap the TrueNAS side.
Documentation
The HA setup is now discoverable from every primary doc entry point:
- README gains a one-paragraph HA callout under NVMe/TCP Requirements.
- wiki/NVMe-Setup.md gets a new "HA Pair (Dual Controller) Deployment" subsection with the midclt bootstrap recipe.
- wiki/Best-Practices.md — the existing "NVMe/TCP HA failover" subsection, previously two sentences about
nvme list-subsys, is now a full walk-through of the storage-config, TrueNAS-side pre-provisioning, failover behavior, verification, and the NGUID cross-check. - wiki/Known-Limitations.md documents the TrueNAS middleware KeyError constraint that drives the knob.
- wiki/Configuration.md carries the field reference.
- storage.cfg.example has an HA-pair stanza showing the knob in context.
- wiki/HA-NVMe-TCP-Validation.md and wiki/HA-Transport-Comparison.md (new) are supporting material: a 50-iteration failover record against a real production-shape HA pair (50/50 PASS, 0 fio errors, 20.6 s average pause) and the ANA-vs-ALUA transport-mechanism comparison that explains why NVMe/TCP HA recovery looks different from iSCSI HA recovery.
Install
Debian/Proxmox package attached. Install with:
dpkg -i truenas-proxmox-plugin_2.1.24~beta3_all.deb
Verify integrity with the attached SHA256SUMS.
Full Changelog: v2.1.24-beta2...v2.1.24-beta3