TrueNAS Proxmox plugin 25.10.6: four observations from our test lab, fed back to iXsystems as a partner

When we mapped out the official early-adopter rollout of the TrueNAS Proxmox plugin in mid-September, we drew our own conclusion: anyone taking “early adopter” seriously brings the plugin into a real test lab and feeds back what they find. That is what we have done over the last few weeks. Our setup: plugin 2.1.17+deb1 on Proxmox VE 9.2.11, TrueNAS SCALE 25.10.6, NVMe/TCP transport over /api/current.

This article is a practitioner’s contribution, not a bug report. We document four observations we made during commissioning, their workarounds — and how we handed them back to iXsystems as a partner, so the next release wave lands cleanly for everyone. Early adoption is not consumption; it is collaboration, with responsibility running in both directions. That is how we see our role as an authorised iXsystems partner in Germany.

Why we run the plugin in production conditions

The official plugin is the path along which iXsystems will carry the Proxmox–TrueNAS integration long term. For an authorised DACH system integrator with a TrueNAS focus that means one thing: we have to accompany the maturation process, not wait it out. Two Gold-certified Solutions Architects on the team, a working test lab, and a clean documentation line into vendor engineering — those are the preconditions for substantive partner feedback.

What follows are the four themes we observed during a fresh install, in the order they came up. For each point we reference the related GitHub issues in the project tracker and, where no open discussion existed yet, we are contributing material ourselves.

1) Property-name mismatch between broker and plugin module

The Perl broker in truenas-proxmox-manage builds the $scfg structure with the field names api_host, api_key and api_insecure. The plugin module TrueNASPlugin.pm reads the tn_-prefixed variants everywhere: tn_api_host, tn_api_key, tn_api_insecure, tn_api_port. The result in the wizard is a visible “Could not connect to TrueNAS API” message — the dialog aborts before any socket is even opened.

The affected lines are around 6595 for the read broker and around 6660 for the write broker. The error text initially pointed us at API-key checks until the deeper cause surfaced. Our observation likely maps to #63 and to item 5 of #93 in the project issue tracker; we have cross-referenced accordingly.

Workaround until the patch lands: enforce consistent naming — either align the broker’s field names to the tn_ prefix, or adjust the read paths in the plugin module. In our lab, the aligned-broker variant runs stable.

2) A call to a private hook that does not exist

At line 6684 the broker calls PVE::Storage::Custom::TrueNASPlugin::_api_call_write(). The module in the same package exports only _api_call() and _api_call_mutate(). A dpkg -V truenas-proxmox-plugin shows no package tampering; this is not a local modification artefact. Related discussion lives in #72 and #74; as far as we can see, those primarily corrected the documentation while the stable-branch script still carried the call.

Workaround: in our test lab we temporarily added the missing hook as a wrapper around _api_call_mutate(); the code path runs cleanly through until the downstream fix lands in the package. For production environments we would stay on the previous plugin version until the official fix, or deliberately keep the test-lab patch set active.

3) pool.dataset.create with _NotRequired sentinels

This point brings the most interesting detail work and ties in with #58 and #90. The issue documents the VOLUME case with five fields. In practice the wizard also needs the FILESYSTEM case to create tn_dataset — that case is not described anywhere in the public docs yet, and one field needs a different value depending on type.

We worked out the property sets field by field in trial-and-error. The sets that pass cleanly in our setup:

FILESYSTEM: acltype / aclmode / atime / recordsize / snapdev = INHERIT
            casesensitivity = SENSITIVE
            quota / refquota / reservation / refreservation = 0
            special_small_block_size = 0

VOLUME:     snapdev = INHERIT
            special_small_block_size = INHERIT
            reservation / refreservation = 0
            force_size = false
            volblocksize = 16K

The subtle one is special_small_block_size: the value 0 is fine on a filesystem; on a volume it reaches libzfs and returns with 'special_small_blocks' does not apply to datasets of this type. On volumes this needs to be INHERIT. volblocksize cannot be omitted on volumes either, because dataset.py:348 reads the first three characters of the value via data['volblocksize'][:3] without checking presence. Simply sending the filesystem properties along is no way out either — that triggers a union-validation fail against PoolDatasetCreateVolume. A single shared default set for both types is therefore insufficient.

The second — and in our view more important — part of this observation is the audit-logger crash that can also occur when pool.dataset.create succeeded on the backend. Anyone reacting to the returned error with rollback or retry then produces duplicates; in our lab this appeared as cannot create 'pool1/ccN': dataset already exists. Anything that rolls back on error leaves orphans here. Highly likely related to the orphaned zvols already observed in #88 and #90.

Workaround for operators: on errors from pool.dataset.create, check the backend state first (zfs list on the pool) before any retry or cleanup. That costs one line of logic and prevents orphan creation.

4) interface.query on 25.10.6 during serialisation

The fourth observation sits on the response side, not the request side. For a perfectly ordinary configuration — static IPv4, one interface, nothing exotic — interface.query returns a response in which state.aliases[].broadcast, .protocol, .parent, .tag and .pcp carry the _NotRequired sentinel. The server-side JSON encoder aborts with Failed to JSON serialize server message. The wizard, which pulls the portal addresses from this call, receives nothing and falls back to manual entry.

Because the issue sits on the response side, there is no clean client-side workaround — we document it and fall back to manual portal configuration in the meantime. We could not find a matching open discussion in the issue tracker and will therefore contribute our own, so the observation lands in the problem history.

How we hand this back

Our approach is clear: no complaining in forums, direct engagement with iXsystems. In practice this means:

• Document observations in the plugin’s GitHub issue tracker — with concrete line references, reproduction steps and the lab environment
• Where we have tested our own patch code, submit it as a discussion basis, not as a finished pull request. The final implementation stays with the maintainers.
• In DATAZONE blog posts include only what provides value for admins in the wild — workarounds, interpretation, expectation management
• For our own customers, bake the current state into the advisory process when a project will depend on the plugin in production

This is the partnership model we live with iXsystems. Early adoption is not a status symbol; it is a process with responsibility running in both directions.

What admins should take from this today

For anyone currently standing up the plugin in a test lab or deciding on introduction:

• The four observations above all occurred on our specific setup combination. Depending on transport (iSCSI instead of NVMe/TCP), API path, or TrueNAS minor version, the picture can shift slightly.
• For a first familiarisation round the plugin is entirely usable. For production with SLA obligations the early-adopter rules apply: lab first, staged production rollout, rollback plan on paper.
• If you get stuck on one of the points, reach out — either via the contact page or, if it is a configuration topic, via the TrueNAS configurator. We can scope the maturity state per transport variant and workload type concretely.

FAQ

Is the plugin production-ready today?

For a test lab and non-critical pre-production: yes. For mission-critical HA clusters under strict enterprise support obligations: not yet without a staged rollout. The early-adopter label means exactly what it says — actively developed, documented, vendor-maintained, but enterprise validation is still running. Our current understanding of the rollout state is in the early-adopter article.

Which exact version combination do you run in the test lab?

Plugin 2.1.17+deb1 on Proxmox VE 9.2.11, TrueNAS SCALE 25.10.6, NVMe/TCP transport over /api/current. Our network practice: dedicated 25 GbE storage network, MTU 9000, nvme-cli on every PVE node.

Why do you feed this back to iXsystems directly rather than publish it as sharp criticism?

Because sharp criticism helps no one — not iXsystems, not our customers, not us. As an authorised partner we have a direct channel to vendor engineering. We use it for clean, structured feedback. In public we document what admins actually need in practice — workarounds, interpretation, expectation management.

Which bugs are already fixed upstream?

At the time of our lab runs the described behaviours were still present in our version combination. The official GitHub repository is the authoritative source for current fix status. We update this article when the maturity state shifts meaningfully.

Do you have publicly viewable patch code?

For the discussion with iXsystems we contributed code fragments. We do not open finished pull requests — the responsibility for the final version should stay with the maintainers. Anyone testing in their own lab with the property sets described above gets through the three blocks cleanly.

Which transport variant do you recommend for newcomers?

For the first lab rounds, iSCSI, because troubleshooting NIC, switch, and target topics is best documented there. For production setups with a 25 GbE network and matching NIC support, NVMe/TCP is the transport target. Details are worked out in a DATAZONE storage consultation or concretely per model in the TrueNAS configurator.

What does “partner contribution” mean for our customers in concrete terms?

That we do not just sell hardware but actively carry the maturation of the software stack. For customers with TrueNAS or Proxmox projects that means we can scope current plugin maturity per project, provide workarounds, and anchor the “plugin yes or no” decision in real practical experience — not in marketing figures. For projects we are currently planning or implementing we fold this assessment into the quotation process.