TrueNAS-Proxmox-Plugin 25.10.6: vier Beobachtungen aus unserem Testlab, die wir an iXsystems zurückspielen

Als wir Mitte September den offiziellen Early-Adopter-Rollout des TrueNAS-Proxmox-Plugins eingeordnet haben, haben wir für uns die Konsequenz gezogen: wer “Early Adopter” ernst meint, bringt das Plugin in ein echtes Testlab und spielt zurück, was er findet. Genau das haben wir in den letzten Wochen gemacht. Unser Setup: Plugin 2.1.17+deb1 auf Proxmox VE 9.2.11, TrueNAS SCALE 25.10.6, Transport NVMe/TCP über /api/current.

Dieser Artikel ist ein Praxis-Beitrag, kein Bug-Report. Wir dokumentieren vier Beobachtungen, die wir im Zuge der Inbetriebnahme gemacht haben, die zugehörigen Workarounds — und wie wir sie als Partner an iXsystems weitergegeben haben, damit die kommende Release-Welle für alle rund läuft. Early Adoption ist kein Konsum, sondern Mitarbeit; genau so verstehen wir unsere Rolle als autorisierter iXsystems-Partner in Deutschland.

Warum wir das Plugin produktiv betreiben

Das offizielle Plugin ist der Weg, auf dem iXsystems die Proxmox-TrueNAS-Integration langfristig führt. Für ein autorisiertes DACH-Systemhaus mit TrueNAS-Fokus heißt das: wir müssen den Reifungsprozess begleiten, nicht abwarten. Zwei Gold-zertifizierte Solutions Architects im Team, ein funktionierendes Testlab, und eine saubere Dokumentations-Linie an die Hersteller-Engineering — das ist die Setup-Voraussetzung für belastbares Partner-Feedback.

Was folgt sind die vier Themen, die wir im Zuge einer Fresh-Installation beobachtet haben, in der Reihenfolge, in der sie uns begegnet sind. Zu jedem Punkt haben wir die relevanten GitHub-Issues im Projekt-Tracker verlinkt und, wo noch keine offene Diskussion existierte, selbst Material beigetragen.

1) Property-Namen zwischen Broker und Plugin-Modul

Der Perl-Broker in truenas-proxmox-manage baut die $scfg-Struktur mit den Feldnamen api_host, api_key und api_insecure. Das Plugin-Modul TrueNASPlugin.pm liest an allen Stellen die Varianten mit tn_-Präfix: tn_api_host, tn_api_key, tn_api_insecure, tn_api_port. Das Resultat waren im Wizard beobachtbare “Could not connect to TrueNAS API”-Meldungen — der Dialog bricht ab, bevor überhaupt ein Socket geöffnet wird.

Betroffen sind der Read-Broker (um Zeile 6595) und der Write-Broker (um Zeile 6660). Der Fehlertext führte uns zunächst in Richtung API-Key-Prüfung, bis der tiefere Grund klar war. Unsere Beobachtung passt vermutlich zu #63 sowie zu Punkt 5 von #93 im Projekt-Issue-Tracker; wir haben entsprechend referenziert.

Workaround, bis der Patch durch ist: eine konsistente Namensgebung erzwingen — entweder im Broker die Feldnamen mit tn_-Präfix angleichen oder im Plugin-Modul die Lesevorgänge umstellen. In unserem Lab läuft die abgeglichene Broker-Variante stabil.

2) Aufruf eines nicht vorhandenen Private-Hooks

In Zeile 6684 ruft der Broker PVE::Storage::Custom::TrueNASPlugin::_api_call_write() auf. Das Modul im selben Paket exportiert jedoch nur _api_call() und _api_call_mutate(). Ein dpkg -V truenas-proxmox-plugin zeigt keine Paket-Inkonsistenz, es ist also kein lokaler Manipulations-Effekt. Verwandte Diskussion in #72 und #74; soweit wir sehen, wurde dort primär die Doku angepasst, das Script auf dem Stable-Zweig trug den Aufruf aber weiter.

Workaround: Wir haben in unserem Testlab den fehlenden Hook temporär als Wrapper um _api_call_mutate() eingebaut; der Code-Pfad läuft dadurch glatt durch, bis die Downstream-Korrektur im Paket ankommt. Für Produktionsumgebungen würden wir bis zum offiziellen Fix bei der vorherigen Plugin-Version bleiben oder das Testlab-Patch-Set bewusst aktiv halten.

3) pool.dataset.create mit _NotRequired-Sentinels

Dieser Punkt bringt die interessanteste Detailarbeit mit und bezieht sich auf #58 und #90. Dokumentiert ist im Issue bisher der VOLUME-Fall mit fünf Feldern. In der Praxis braucht der Wizard aber auch den FILESYSTEM-Fall, um das tn_dataset anzulegen — der ist in der öffentlichen Doku bisher nicht beschrieben, und ein Feld verlangt je nach Typ einen anderen Wert.

Wir haben die Property-Sets durch Feld-für-Feld-Trial ermittelt. Was in unserem Setup sauber durchläuft:

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

Die Besonderheit liegt bei special_small_block_size: der Wert 0 passt beim Filesystem, beim Volume läuft er aber bis in libzfs durch und kommt mit 'special_small_blocks' does not apply to datasets of this type zurück. Auf Volumes muss hier INHERIT gesetzt werden. volblocksize darf auf Volumes zudem nicht fehlen, weil dataset.py:348 die ersten drei Zeichen des Werts via data['volblocksize'][:3] liest, ohne auf Vorhandensein zu prüfen. Die Filesystem-Properties einfach mit zu senden ist kein Ausweg — das triggert einen Union-Validation-Fail gegen PoolDatasetCreateVolume. Ein gemeinsamer Default-Satz für beide Typen reicht also nicht aus.

Der zweite, aus unserer Sicht wichtigere Teil dieser Beobachtung ist der Audit-Logger-Crash, der auch dann auftreten kann, wenn das pool.dataset.create auf dem Backend erfolgreich war. Wer auf einen zurückgemeldeten Fehler mit Rollback oder Retry reagiert, erzeugt dann Dubletten — in unserem Lab zeigte sich das als cannot create 'pool1/ccN': dataset already exists. Alles, was auf Fehler-Rollback setzt, hinterlässt hier Orphans. Mit großer Wahrscheinlichkeit verwandt zu den beobachteten verwaisten zvols aus #88 und #90.

Workaround für Operatoren: bei Fehlermeldungen aus pool.dataset.create zunächst den Backend-Status prüfen (zfs list auf dem Pool), bevor ein Retry oder Cleanup erfolgt. Das kostet eine Zeile Logik, verhindert aber Orphan-Erzeugung.

4) interface.query auf 25.10.6 beim Serialisieren

Die vierte Beobachtung betrifft die Response-Seite, nicht die Request-Seite. Bei einer vollkommen regulären Konfiguration — statisches IPv4, ein Interface, keine Exotik — liefert interface.query eine Response, in der state.aliases[].broadcast, .protocol, .parent, .tag und .pcp den _NotRequired-Sentinel tragen. Der Server-seitige JSON-Encoder bricht mit Failed to JSON serialize server message ab. Der Wizard, der die Portal-Adressen daraus zieht, bekommt nichts zurück und fällt auf die manuelle Eingabe zurück.

Da das Problem auf der Response-Seite liegt, lässt es sich clientseitig nicht sauber umgehen — wir dokumentieren es und greifen für die Portal-Konfiguration in der Zwischenzeit auf die manuelle Eingabe zurück. Wir konnten im Issue-Tracker keine passende offene Diskussion finden und werden daher einen eigenen Beitrag beisteuern, damit die Beobachtung in der Problem-Historie landet.

Wie wir das weitergeben

Unser Weg ist klar: nicht in Communities oder Foren schimpfen, sondern direkt bei iXsystems. Das heißt in der Praxis:

• Beobachtungen im GitHub-Issue-Tracker des Plugins dokumentieren — mit konkreten Zeilenangaben, Reproduzierschritten und Lab-Umgebung
• Wo wir eigenen Patch-Code getestet haben: diesen als Diskussionsgrundlage einreichen, nicht als fertigen Pull-Request. Die endgültige Umsetzung liegt bei den Maintainern.
• In den DATAZONE-Blog-Beiträgen nur das aufnehmen, was für Admins in freier Wildbahn Mehrwert hat — Workarounds, Interpretation, Erwartungsmanagement
• Für unsere eigenen Kunden entsprechende Vorab-Hinweise im Angebotsprozess einbauen, wenn ein Projekt das Plugin produktiv nutzen soll

Das ist das Partnerschafts-Modell, das wir mit iXsystems leben. Early Adoption ist kein Status-Symbol, es ist ein Prozess mit Verantwortung in beide Richtungen.

Was Admins jetzt daraus mitnehmen

Für alle, die das Plugin aktuell im Testlab anlegen oder konkret über die Einführung nachdenken:

• Die vier Beobachtungen oben sind alle auf unserer Setup-Kombination aufgetreten. Je nach Transport (iSCSI statt NVMe/TCP), API-Pfad, oder TrueNAS-Minorversion kann das Bild leicht anders aussehen.
• Für eine erste Vertrautheits-Runde ist das Plugin absolut tauglich. Für Produktion mit SLA-Zusagen gelten die Frühadopter-Regeln: Testlab zuerst, Produktion gestaffelt, Rückfall-Plan dokumentieren.
• Wenn ihr an einem der Punkte hängenbleibt, meldet euch bei uns — entweder über die Kontaktseite oder, wenn es sich um ein Konfigurations-Thema handelt, direkt über den TrueNAS-Konfigurator. Wir können den Reife-Status pro Transport-Variante und Workload-Typ konkret einschätzen.

FAQ

Ist das Plugin aktuell produktionsreif?

Für Testlab und nicht-kritische Vorproduktion: ja. Für geschäftskritische HA-Cluster unter strenger Enterprise-Support-Zusage: noch nicht ohne gestaffelte Einführung. Der Early-Adopter-Status heißt genau das — aktiv entwickelt, dokumentiert, hersteller-gepflegt, aber die Enterprise-Validierung läuft noch. Unser aktuelles Verständnis des Rollout-Stands haben wir im Early-Adopter-Artikel beschrieben.

Welche konkrete Versionskombination betreibt ihr im Testlab?

Plugin 2.1.17+deb1 auf Proxmox VE 9.2.11, TrueNAS SCALE 25.10.6, Transport NVMe/TCP über /api/current. Unsere Netzwerk-Praxis: dediziertes 25-GbE-Storage-Netz, MTU 9000, nvme-cli auf jedem PVE-Node.

Warum spielt ihr das direkt an iXsystems zurück und veröffentlicht es nicht als scharfe Kritik?

Weil scharfe Kritik niemandem hilft — weder iXsystems, noch unseren Kunden, noch uns. Als autorisierter Partner haben wir einen direkten Kanal zur Hersteller-Engineering. Den nutzen wir für sauberes, strukturiertes Feedback. Öffentlich dokumentieren wir, was Admins in der Praxis helfen — Workarounds, Interpretation, Erwartungsmanagement.

Welche Bugs sind bereits upstream gefixt?

Zum Zeitpunkt der Testlab-Durchläufe waren die beschriebenen Verhaltensweisen in unserer Versionskombination noch vorhanden. Das offizielle GitHub-Repository des Plugins ist die autoritative Quelle für den aktuellen Fix-Status. Wir aktualisieren diesen Artikel, wenn sich der Reife-Status wesentlich verschiebt.

Habt ihr Patch-Code, der öffentlich einsehbar ist?

Für die Diskussion mit iXsystems haben wir Code-Fragmente beigesteuert. Fertige Pull-Requests legen wir nicht an — die Verantwortung für die Endfassung soll beim Maintainer bleiben. Wer in seiner Lab-Umgebung mit den oben beschriebenen Property-Sets testet, kommt die drei Themenblocks sauber durch.

Welche Transport-Variante empfehlt ihr für Neueinstiege?

Für die ersten Testlab-Runden iSCSI, weil die Fehlersuche hier bei NIC-, Switch- und Target-Themen am besten dokumentiert ist. Für produktive Setups mit 25-GbE-Netz und entsprechender NIC-Unterstützung ist NVMe/TCP das Transport-Ziel. Details klären wir im Rahmen eines DATAZONE Storage-Beratungsgesprächs oder konkret pro Modell im TrueNAS-Konfigurator.

Was heißt “Partner-Beitrag” für unsere Kunden konkret?

Dass wir nicht nur Hardware verkaufen, sondern den Reifungsprozess des Software-Stacks aktiv mittragen. Für Kunden mit TrueNAS- oder Proxmox-Projekten heißt das: wir können pro Projekt den aktuellen Plugin-Reifestatus einordnen, Workarounds bereitstellen und die Entscheidung “Plugin ja/nein” an realen Praxis-Erfahrungen festmachen — nicht an Marketing-Zahlen. Für Projekte, die wir aktuell planen oder umsetzen, bauen wir diese Einschätzung in den Angebotsprozess ein.