Manage the TrueNAS NAS exclusively via the middleware API
Date: 2026-06-27 Status: Accepted Decision: hl-akt3 Deciders: sean
Context
Section titled “Context”nas is a TrueNAS 26 appliance, not a general-purpose Linux host. Its middleware regenerates /etc (Samba, NFS, cron, users) from a SQLite config database on boot and upgrade, so direct file edits are silently reverted. Ansible’s normal template/lineinfile reflex therefore cannot durably configure this host.
Decision
Section titled “Decision”Manage the NAS exclusively through the TrueNAS middleware API — midclt call <method> over SSH with become (talking to the local middleware socket) — for every host-side change (users, shares, datasets, apps, containers). Ansible never edits /etc on the appliance.
Rationale
Section titled “Rationale”- File edits to appliance-managed paths revert on reboot/upgrade; the middleware DB is the source of truth.
midclt-over-SSH needs no API key or WebSocket client — SSH is already the Ansible transport.- Keeps NAS state visible and consistent in the TrueNAS UI.
Alternatives Considered
Section titled “Alternatives Considered”- midclt-over-SSH + become (chosen): simplest; no extra client or key to manage.
- Remote JSON-RPC WebSocket + API key (rejected): adds a non-Ansible-native client and a key to manage, for no benefit when SSH is already the transport.
- File-based Ansible (
template/lineinfile) (rejected): the appliance reverts non-middleware changes; fundamentally unreliable.
Consequences
Section titled “Consequences”- Positive: durable, upgrade-safe configuration; UI-consistent; no secret/key sprawl.
- Negative: every change is a
midcltcall (more verbose than a file template); some operations are async jobs requiring poll-and-check. - Neutral: ties NAS automation to the TrueNAS middleware schema, a moving target on BETA releases (mitigated by spikes + schema verification).