Is your feature request related to a problem?
The current GraphQL schema has strong read/telemetry coverage and mutations for array, Docker, VM, parity check, RClone, API key, and notification management — but there's no mutation surface for the three primitives needed to manage storage lifecycle programmatically: user shares, ZFS datasets/snapshots, and iSCSI targets/extents. These are only reachable today through the legacy webGUI PHP/emhttp forms.
This gap is the main thing standing between Unraid and being usable as a proper dynamic storage backend for container-orchestration systems — Kubernetes CSI drivers in particular — the way TrueNAS/TrueNAS SCALE already is via its middleware API (midclt).
Concretely: democratic-csi is a widely used Kubernetes CSI driver that provisions persistent volumes dynamically by talking to a storage backend's native API — create a ZFS dataset (or zvol), a share (NFS/SMB) or iSCSI target/extent, tear it down on volume delete, snapshot/clone for volume cloning. It ships first-class TrueNAS/FreeNAS drivers that do all of this entirely through midclt — no SSH, no shell-outs, no separate agent process.
There's no equivalent path for Unraid today. Anyone wanting Unraid-backed dynamic provisioning has to stand up an out-of-band bridge service that SSHes in and shells out to zfs/tgt/share-config file writes directly, reimplementing the locking, validation, and config-reload semantics that unraid-api's existing resolvers (and the legacy webGUI) already handle correctly — and adding a whole extra service and credential surface to every install.
Describe the solution you'd like
A bounded mutation surface covering just the primitives needed for dataset/share/target lifecycle management:
Share mutations
createShare, updateShare, deleteShare- Covering: name, allocation method/included disks, export protocol (NFS/SMB) and per-protocol permissions, use-cache setting
ZFS dataset mutations (scoped to pools already recognized by Unraid's native ZFS support)
createDataset, deleteDataset, setDatasetPropertiescreateSnapshot, deleteSnapshot, cloneSnapshot
iSCSI mutations
createIscsiTarget / deleteIscsiTargetcreateIscsiExtent / deleteIscsiExtentcreateTargetExtent / deleteTargetExtent- (Naming intentionally mirrors TrueNAS's
iscsi.target/iscsi.extent/iscsi.targetextent split — a proven decomposition for LUN mapping.)
TrueNAS's middleware already solves this exact problem (zfs.dataset.*, pool.snapshot.*, sharing.nfs.*/sharing.smb.*, iscsi.*) — I'm not asking for anything TrueNAS doesn't already expose, and I'm happy to use it as the naming/shape reference if useful for review.
I'd rather get agreement on scope and naming here first, then follow up with a Work Intent and full implementation PR (input/output types, resolvers, service layer, tests) once there's rough consensus, per the contribution process.
Describe alternatives you've considered
- Bespoke SSH bridge — what I'm currently running: a separate Node.js service that SSHes into Unraid and shells out to
zfs/tgt directly. Works, but means a second service + credential surface per install, and reimplements locking/validation the webGUI already gets right.
- Ship it purely as a third-party plugin, no upstream change — possible using the existing plugin scaffolding (resolvers registered in-process), but doesn't solve the "extra install artifact" problem for adoption, and duplicates effort that's clearly generalizable to every Unraid-as-storage-backend use case, not just mine.
- Reverse-engineer the webGUI's PHP POST endpoints — the least maintainable option; not a real API contract and breaks silently across releases.
Additional context
Two open questions I'd like maintainer input on before scoping a Work Intent:
- Permission/scope model — should these sit under the existing
unraid:admin scope, or warrant a narrower scope (e.g. unraid:storage-admin) given the blast radius of dataset/share deletion?
- ZFS pool scoping — should dataset mutations be restricted to pools outside the parity array (to avoid overlapping with array-disk share semantics), or is a unified model preferred?
Not asking for general shell/command execution — every operation above maps to a specific, validated config change plus the existing reload mechanism, comparable in shape to what the existing ArrayMutations/DockerMutations resolvers already do. Not proposing this replace or deprecate the webGUI share/ZFS pages — additive only, and doesn't touch array management or cache pool behavior.
Environment (if relevant)
Unraid OS Version: 7.2+ (native ZFS pool support)
Pre-submission Checklist
Is your feature request related to a problem?
The current GraphQL schema has strong read/telemetry coverage and mutations for array, Docker, VM, parity check, RClone, API key, and notification management — but there's no mutation surface for the three primitives needed to manage storage lifecycle programmatically: user shares, ZFS datasets/snapshots, and iSCSI targets/extents. These are only reachable today through the legacy webGUI PHP/emhttp forms.
This gap is the main thing standing between Unraid and being usable as a proper dynamic storage backend for container-orchestration systems — Kubernetes CSI drivers in particular — the way TrueNAS/TrueNAS SCALE already is via its middleware API (
midclt).Concretely: democratic-csi is a widely used Kubernetes CSI driver that provisions persistent volumes dynamically by talking to a storage backend's native API — create a ZFS dataset (or zvol), a share (NFS/SMB) or iSCSI target/extent, tear it down on volume delete, snapshot/clone for volume cloning. It ships first-class TrueNAS/FreeNAS drivers that do all of this entirely through
midclt— no SSH, no shell-outs, no separate agent process.There's no equivalent path for Unraid today. Anyone wanting Unraid-backed dynamic provisioning has to stand up an out-of-band bridge service that SSHes in and shells out to
zfs/tgt/share-config file writes directly, reimplementing the locking, validation, and config-reload semantics thatunraid-api's existing resolvers (and the legacy webGUI) already handle correctly — and adding a whole extra service and credential surface to every install.Describe the solution you'd like
A bounded mutation surface covering just the primitives needed for dataset/share/target lifecycle management:
Share mutations
createShare,updateShare,deleteShareZFS dataset mutations (scoped to pools already recognized by Unraid's native ZFS support)
createDataset,deleteDataset,setDatasetPropertiescreateSnapshot,deleteSnapshot,cloneSnapshotiSCSI mutations
createIscsiTarget/deleteIscsiTargetcreateIscsiExtent/deleteIscsiExtentcreateTargetExtent/deleteTargetExtentiscsi.target/iscsi.extent/iscsi.targetextentsplit — a proven decomposition for LUN mapping.)TrueNAS's middleware already solves this exact problem (
zfs.dataset.*,pool.snapshot.*,sharing.nfs.*/sharing.smb.*,iscsi.*) — I'm not asking for anything TrueNAS doesn't already expose, and I'm happy to use it as the naming/shape reference if useful for review.I'd rather get agreement on scope and naming here first, then follow up with a Work Intent and full implementation PR (input/output types, resolvers, service layer, tests) once there's rough consensus, per the contribution process.
Describe alternatives you've considered
zfs/tgtdirectly. Works, but means a second service + credential surface per install, and reimplements locking/validation the webGUI already gets right.Additional context
Two open questions I'd like maintainer input on before scoping a Work Intent:
unraid:adminscope, or warrant a narrower scope (e.g.unraid:storage-admin) given the blast radius of dataset/share deletion?Not asking for general shell/command execution — every operation above maps to a specific, validated config change plus the existing reload mechanism, comparable in shape to what the existing
ArrayMutations/DockerMutationsresolvers already do. Not proposing this replace or deprecate the webGUI share/ZFS pages — additive only, and doesn't touch array management or cache pool behavior.Environment (if relevant)
Unraid OS Version: 7.2+ (native ZFS pool support)
Pre-submission Checklist