From db13023b839ea4beead66eedcd9319c19dcf4484 Mon Sep 17 00:00:00 2001 From: Kevin Adams Date: Mon, 31 Aug 2026 09:46:21 -0400 Subject: [PATCH] docs: confirm multipath works over WebSocket transport, live-tested Full alloc_image/activate_volume/path/deactivate_volume/free_image cycle against .92 with zero code changes to TrueNASMultipath.pm -- real dm-multipath device came up with 2 active paths. Also notes a practical finding: .92 has only one TrueNAS portal object (0.0.0.0) rather than two per-IP ones, and iscsiadm still produced two genuine independent paths logging into different IPs against it. Co-Authored-By: Claude Sonnet 5 --- .../adrs/ADR-012-websocket-transport-v4.md | 23 +++++++++++++++---- docs/architecture.md | 2 +- 2 files changed, 19 insertions(+), 6 deletions(-) diff --git a/.claude/cos/adrs/ADR-012-websocket-transport-v4.md b/.claude/cos/adrs/ADR-012-websocket-transport-v4.md index 85dd06a..0377e03 100644 --- a/.claude/cos/adrs/ADR-012-websocket-transport-v4.md +++ b/.claude/cos/adrs/ADR-012-websocket-transport-v4.md @@ -272,15 +272,28 @@ dynamic/development node for whatever version-specific testing comes up next `pool.dataset.delete` returns one) and needs `ref() eq 'HASH'` guarding. - #249 (per-variant dispatch) stays deferred past v4.0.0 — tracked as possible v4.1/v5.0 scope, see Question 2 above. -- **`TrueNASMultipath.pm` needs no separate WebSocket work.** It calls +- **`TrueNASMultipath.pm` needs no separate WebSocket work — CONFIRMED live + 2026-08-31, not just by code inspection.** It calls `PVE::Storage::Custom::TrueNAS::_api(...)` directly (a fully-qualified sub call, not an overridable method) for every operation except its four multipath-specific overrides (`path`, `qemu_blockdev_options`, `activate_volume`, `deactivate_volume`, none of which touch the TrueNAS API - directly). Once `_api()` becomes the REST/WS dispatcher decided above, - multipath inherits WebSocket support automatically. Documented in - `docs/architecture.md` §9 (added 2026-08-30, alongside README/docs coverage - for the multipath package that had been missing since its v3.2.0 release). + directly). Ran a full `alloc_image` → `activate_volume` → `path` → + `deactivate_volume` → `free_image` cycle against `.92` with zero code + changes to `TrueNASMultipath.pm`: `iscsiadm` logged into both configured + portals, `multipathd` built a real `/dev/mapper/` device with 2 active + paths (`multipath -ll` showed both `active ready running` under one + `multibus` group), and teardown cleanly flushed/logged out/removed + everything. Notably, TrueNAS's own `.92` only has *one* portal object + (listening on `0.0.0.0`) rather than the two per-IP portals the + CORE-vs-SCALE table in `docs/architecture.md` §9 describes as the SCALE + requirement — `iscsiadm` logging into two different IPs against that same + `0.0.0.0`-listening portal still produced two genuine, independent paths, + since the Linux initiator/target don't care about TrueNAS's internal + portal-object bookkeeping, only the actual IP:port endpoints reached. + Documented in `docs/architecture.md` §9 (added 2026-08-30, alongside + README/docs coverage for the multipath package that had been missing since + its v3.2.0 release; live-confirmation note added 2026-08-31). ## Implementation branch diff --git a/docs/architecture.md b/docs/architecture.md index 0eb8acb..2d763ea 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -560,7 +560,7 @@ Ships as a separate package, `truenas-proxmox-multipath` (v3.2.0+, #256), becaus ### What it overrides vs. inherits -Everything in §5–§6 (`alloc_image`, `free_image`, zvol/extent/target lifecycle) is **inherited unchanged** — `TrueNASMultipath.pm` calls the shared `PVE::Storage::Custom::TrueNAS::_api(...)` helper directly (a fully-qualified sub call, not a virtual method), so any future transport change to that helper (e.g. the WebSocket work in [ADR-012](../.claude/cos/adrs/ADR-012-websocket-transport-v4.md)) applies to multipath automatically with no separate implementation work. +Everything in §5–§6 (`alloc_image`, `free_image`, zvol/extent/target lifecycle) is **inherited unchanged** — `TrueNASMultipath.pm` calls the shared `PVE::Storage::Custom::TrueNAS::_api(...)` helper directly (a fully-qualified sub call, not a virtual method), so any future transport change to that helper (e.g. the WebSocket work in [ADR-012](../.claude/cos/adrs/ADR-012-websocket-transport-v4.md)) applies to multipath automatically with no separate implementation work. **Confirmed live 2026-08-31**, not just by code inspection: a full `alloc_image`/`activate_volume`/`path`/`deactivate_volume`/`free_image` cycle against a WebSocket-transport SCALE host (`.92`, 25.04.2.6) worked with zero code changes to this file — see ADR-012's Consequences section. Only four methods are overridden, replacing the `iscsi://` model from §3 with a kernel iSCSI + `dm-multipath` model: