SAN Fabric
- POST /agent/sanfabric/attach
Attach a SAN volume on this host
Loopback call from the KVM agent scripts, gated by the node token; other KF-coded refusals use the status mapped to their code.
- Request JSON Object:
lun (string)
timeout_seconds (integer) – TimeoutSeconds is the caller’s attach budget (karios-fabricctl –timeout). Absent or zero keeps the node’s own deadline, which is what the the platform scripts get; a positive value shorter than that deadline cuts the attach there with the fabric’s KF-4012, so the caller reads a structured refusal instead of abandoning its socket first. A value above the node’s deadline is clamped to it: the deadline sits under the platform’s multimap.disk.wait.secs and a request cannot raise it. Negative is refused with KF-4000.
wwid (string)
- Status Codes:
200 OK – Attached device
400 Bad Request – KF-4000 malformed request or negative timeout
401 Unauthorized – Node token required
500 Internal Server Error – Unexpected node error
504 Gateway Timeout – KF-4012 attach did not complete within the budget
- Response JSON Object:
device (string)
identity (string)
pool_id (string)
protocol (string)
- GET /agent/sanfabric/attachments
List SAN attachments on this host
Loopback call gated by the node token; lists the volumes this host holds.
- Status Codes:
200 OK – host and attachments
401 Unauthorized – Node token required
- GET /agent/sanfabric/desired
Get this host’s accepted desired state
Loopback call gated by the node token; returns the desired state this host last accepted, secrets included.
- Status Codes:
200 OK – Last accepted desired state
401 Unauthorized – Node token required
- Response JSON Object:
host (string)
pools[].grant_required (boolean) – GrantRequired: the target does not mask per host, so the node attaches only volumes this state names to it.
pools[].id (string)
pools[].min_paths (integer)
pools[].name (string)
pools[].portals[].address (string)
pools[].portals[].ana_group (string)
pools[].portals[].auth_mode (string)
pools[].portals[].auth_secret (string)
pools[].portals[].auth_secret_in (string)
pools[].portals[].auth_user (string)
pools[].portals[].auth_user_in (string) – The target’s credentials for mutual-chap: what the host challenges the target with.
pools[].portals[].port (integer)
pools[].portals[].subsystem_nqn (string)
pools[].portals[].target_iqn (string)
pools[].protocol (string)
pools[].scan_mode (string) – ScanMode is ScanModeManual for a mapping-only pool: its sessions add only the LUNs core names.
pools[].target_iqns[] (string)
pools[].volumes[].fence_token (integer)
pools[].volumes[].identity_kind (string)
pools[].volumes[].identity_value (string)
pools[].volumes[].lun (integer)
pools[].volumes[].state (string)
pools[].volumes[].volume_id (string)
storage (any) – Storage is the host’s pod storage network from Atlas: the fallback when the node’s seed has none.
- POST /agent/sanfabric/detach
Detach a SAN volume on this host
Loopback call from the KVM agent scripts, gated by the node token; 200 means the device is gone from this host.
- Request JSON Object:
wwid (string)
- Status Codes:
200 OK – released=true
400 Bad Request – KF-4000 malformed request
401 Unauthorized – Node token required
500 Internal Server Error – Unexpected node error or KF-coded refusal
- GET /agent/sanfabric/volumes/{wwid}/paths
Get multipath health of a SAN volume
Loopback call gated by the node token; reports live multipath health of one volume attached to this host.
- Parameters:
wwid (string) – Volume WWID
- Status Codes:
200 OK – Path health
401 Unauthorized – Node token required
500 Internal Server Error – Unexpected node error or KF-coded refusal
- Response JSON Object:
device (string)
host (string)
identity (string)
min_paths (integer)
paths[].alua (string) – optimized / non-optimized / inaccessible / change / “”
paths[].device (string) – sdc, nvme0c0n1
paths[].up (boolean)
paths[].usable (boolean)
protocol (string)
state (string) – healthy / degraded / critical / detached
summary (string) – one-line operator explanation
total_paths (integer)
usable_paths (integer)
- POST /storage/fabric/backends/create
Create a SAN backend
Validate, probe and store one array or software target. For a driver whose drivers/list management is “ssh” (comstar) tls_verify verifies the array’s SSH host key, not a TLS certificate: it needs extras.host_key, one line of the array’s /etc/ssh/ssh_host_*_key.pub (or ssh-keyscan output), and the client then negotiates only that key’s algorithm.
- Request JSON Object:
driver (string)
extras (object)
mgmt_addr (string)
name (string)
password (string)
tls_verify (boolean)
token (string)
username (string)
- Status Codes:
201 Created – Created backend, with effective_dataset: the dataset its driver carves under
400 Bad Request – Invalid request, including an SSH host key (extras.host_key) that is missing while tls_verify is on, malformed, or set while tls_verify is off
409 Conflict – A backend by that name exists
502 Bad Gateway – KF-5010 backend unreachable
- Response JSON Object:
backend.created_at (string)
backend.driver (string)
backend.effective_dataset (string) – EffectiveDataset is extras.pool when set, else the driver’s default, by the driver’s own rule; “” for a driver that names none.
backend.extras[] (integer)
backend.id (string)
backend.last_probe_at (string)
backend.last_probe_err (string)
backend.mgmt_addr (string)
backend.name (string)
backend.state (string)
backend.tls_verify (boolean)
backend.updated_at (string)
status (string)
- POST /storage/fabric/backends/delete
Delete a SAN backend
Remove a backend that no pool references: its hosts are deregistered on the array and the parent dataset core created is destroyed when empty, then the row goes
- Query Parameters:
force (boolean) – Delete the row even when the array keeps registrations or the parent dataset still holds volumes; the response lists them
- Request JSON Object:
id (string)
- Status Codes:
200 OK – Deleted, with what was removed, kept and left on the array
400 Bad Request – Invalid request
404 Not Found – No such backend, or another delete of it finished while this one ran (the message names what this one took off the array)
409 Conflict – Pools still reference this backend, a pool appeared while it ran, or KF-4095 the array keeps registrations core could not remove or a parent dataset that still holds volumes
- POST /storage/fabric/backends/list
List SAN backends
List every registered backend without any credential material. Each carries effective_dataset, the dataset its driver carves under: extras.pool when set, else the driver’s default, “” for a driver that names none.
- Status Codes:
200 OK – Backends
- Response JSON Object:
backends[].created_at (string)
backends[].driver (string)
backends[].effective_dataset (string) – EffectiveDataset is extras.pool when set, else the driver’s default, by the driver’s own rule; “” for a driver that names none.
backends[].extras[] (integer)
backends[].id (string)
backends[].last_probe_at (string)
backends[].last_probe_err (string)
backends[].mgmt_addr (string)
backends[].name (string)
backends[].state (string)
backends[].tls_verify (boolean)
backends[].updated_at (string)
count (integer)
- POST /storage/fabric/backends/probe
Probe a SAN backend
Re-run the backend reachability check and store the verdict
- Request JSON Object:
id (string)
- Status Codes:
200 OK – Probe verdict
400 Bad Request – Invalid request
404 Not Found – No such backend
- Response JSON Object:
last_probe_at (string)
last_probe_err (string)
state (string)
- POST /storage/fabric/backends/update
Update a SAN backend
Merge address, credentials, tls_verify and extras into a stored backend and re-probe it. Extras replace the stored ones whole, so send extras.pool with extras.host_key. For a driver whose drivers/list management is “ssh” tls_verify verifies the array’s SSH host key in extras.host_key, not a TLS certificate.
- Request JSON Object:
extras (object)
id (string)
mgmt_addr (string)
password (string)
tls_verify (boolean)
token (string)
username (string)
- Status Codes:
200 OK – Updated backend, with effective_dataset: the dataset its driver carves under
400 Bad Request – Invalid request
404 Not Found – No such backend
409 Conflict – The backend was deleted while it was updated, the new dataset overlaps one another backend on the array uses, or pools still carve under the dataset the update moves off
502 Bad Gateway – KF-5010 backend unreachable
- Response JSON Object:
backend.created_at (string)
backend.driver (string)
backend.effective_dataset (string) – EffectiveDataset is extras.pool when set, else the driver’s default, by the driver’s own rule; “” for a driver that names none.
backend.extras[] (integer)
backend.id (string)
backend.last_probe_at (string)
backend.last_probe_err (string)
backend.mgmt_addr (string)
backend.name (string)
backend.state (string)
backend.tls_verify (boolean)
backend.updated_at (string)
status (string)
- GET /storage/fabric/backends/{id}/orphans
List a SAN backend’s untracked array objects
Reads the zvols, LUs, views and host groups under the backend’s own dataset and lists those no volume row, tenure or host accounts for, each with why and with the owner its stamp names. Nothing outside the dataset is listed and nothing is changed.
- Parameters:
id (string) – Backend id
- Status Codes:
200 OK – {success, data: {backend, dataset, owner, parent_gone, tracked_volumes, zvols, lus, views, host_groups, unread_hosts, note}}; unread_hosts names each known host whose initiators could not all be read
400 Bad Request – KF-4000 the id is not a uuid
404 Not Found – KF-4046 no such backend
501 Not Implemented – KF-4096 the driver cannot list what it holds
502 Bad Gateway – KF-5010 unreachable, KF-5012 the listing failed
- GET /storage/fabric/backends/{id}/portals
List a SAN backend’s portals
Reads the backend’s target endpoints live through its driver, for the pool form’s portal picker; nothing on the array changes. Each portal carries its protocol, address and port, the iSCSI target_iqn or NVMe subsystem_nqn it serves, and any_address when the target listens on every array address (the default portal group), so no address is listed for it.
- Parameters:
id (string) – Backend id
- Status Codes:
200 OK – {success, data: {backend, driver, portals: [{protocol, address, port, target_iqn, subsystem_nqn, any_address}]}}
400 Bad Request – KF-4000 the id is not a uuid
404 Not Found – KF-4046 no such backend
502 Bad Gateway – KF-5010 unreachable, KF-5012 the listing failed
- POST /storage/fabric/luns/acknowledge
Acknowledge a generic iSCSI LUN’s conflict or size notice
Root only. Clears identity_conflict (and the counterpart row carrying the same text), deleted_outside or size_notice (an unattached shrink, which also resolves its SANFABRIC.LUN.SIZE_REDUCED info alert), then recomputes the state.
- Request JSON Object:
lun_id (string)
- Status Codes:
200 OK – {success, data: {lun}}
400 Bad Request – KF-4000 malformed request or no lun_id
404 Not Found – KF-4046 no such LUN
409 Conflict – KF-4019 nothing to acknowledge (no identity change, size reduction or delete outside Karios)
- POST /storage/fabric/luns/attach
Attach a generic iSCSI LUN to a VM
Root only. vm_id is required. Has the platform import the LUN as a volume through the Karios Fabric plugin and attaches it to the VM. 200 when the platform confirmed the volume; 202 while the platform’s answer is unknown: core then finishes it on its own and attaches it to the VM. An attach that fails leaves the LUN to go back to Detached on its own within a few minutes.
- Request JSON Object:
account (string)
domain_id (string)
lun_id (string)
name (string)
project_id (string)
vm_id (string)
- Status Codes:
200 OK – {success, data: MapLUNResult}
202 Accepted – {success, data: MapLUNResult} with state binding: the attach is still completing
400 Bad Request – KF-4000 malformed request or name, no lun_id, or no vm_id
404 Not Found – KF-4046 no such LUN or VM
409 Conflict – KF-4019 LUN not detached; KF-4098 the platform refused
503 Service Unavailable – KF-5022 could not read the platform or the fabric’s records
- POST /storage/fabric/luns/detach
Detach a generic iSCSI LUN
Root only. Records the intent, detaches the volume from its stopped VM and deletes it on the platform, which releases the LUN back to Detached; its data stays on the LUN. Refused while the VM runs. 202 while a host still releases it; press Detach again to resume after a refusal.
- Request JSON Object:
lun_id (string)
- Status Codes:
200 OK – {success, data: UnmapLUNResult}
202 Accepted – {success, data: UnmapLUNResult} with state releasing or unmapping: the detach is still completing
400 Bad Request – KF-4000 malformed request or no lun_id
404 Not Found – KF-4046 no such LUN
409 Conflict – KF-4019 not attached, an attach still completing, or the VM runs; KF-4098 the platform refused
503 Service Unavailable – KF-5022 could not read the platform or the fabric’s records
- POST /storage/fabric/luns/list
List generic iSCSI LUNs across pools
Root only. zone_id lists every LUN of the zone’s mapping-only pools (state=available with mappable=true is what Attach existing LUN may map); cs_volume_ids (at most 200) lists the LUNs bound to those platform volumes in any zone, so Block Storage finds the LUN behind each volume with one call. An unknown volume id matches nothing. Each row is the LUNs tab’s row plus pool_name, pool_state, zone_id and mappable.
- Request JSON Object:
cs_volume_ids[] (string)
state (string)
zone_id (string)
- Status Codes:
200 OK – {success, data: {luns: [LunZoneView]}}
400 Bad Request – KF-4000 malformed request, no zone_id and no cs_volume_ids, an unknown state, or too many volume ids
403 Forbidden – Not root
503 Service Unavailable – KF-5022 the fabric’s records could not be read
- POST /storage/fabric/node/certificate
Expiry of this node’s SAN fabric mutual-TLS certificate
Reports when the leaf this node serves and presents expires. It reports only; it never refuses.
- Status Codes:
200 OK – Certificate verdict, including when it could not be read
- Response JSON Object:
days_left (integer) – negative once past
host (string)
next (string)
not_after (string) – earliest in the file: a chain dies with its first member
path (string)
reason (string)
status (string)
warn (boolean)
- GET /storage/fabric/plugin/hosts/{name}/access
Host access
- Parameters:
name (string) – Host name
- Query Parameters:
pool (string) – Pool id
- Status Codes:
200 OK – access true or false
- GET /storage/fabric/plugin/pools/{id}
Get the plugin’s pool
- Parameters:
id (string) – Pool id
- Status Codes:
200 OK – The pool
401 Unauthorized – No plugin token
404 Not Found – Not this token’s pool
- GET /storage/fabric/plugin/pools/{id}/stats
Pool capacity
- Parameters:
id (string) – Pool id
- Status Codes:
200 OK – Capacity
502 Bad Gateway – KF-5010 backend unreachable
- Response JSON Object:
capacity_bytes (integer)
used_bytes (integer)
- GET /storage/fabric/plugin/volumes
Find a volume by identity
- Query Parameters:
address (string) – NAA / NGUID as stored in volumes.path
- Status Codes:
200 OK – volume
404 Not Found – No such volume in this pool
- POST /storage/fabric/plugin/volumes
Create a volume
- Request JSON Object:
cs_volume_uuid (string)
kind (string) – Kind is “volume” (default) or “template”: the base the platform keeps once per pool and clones roots from.
name (string)
size_bytes (integer)
source_volume_id (string) – SourceVolumeID, when set, asks for a clone of that volume (same pool) instead of an empty carve; the result is at least as large as the source.
- Status Codes:
201 Created – The volume
400 Bad Request – KF-4000 malformed request
409 Conflict – KF-4017 the pool maps existing LUNs; KF-4020 identity collision
502 Bad Gateway – KF-5010 backend unreachable
- GET /storage/fabric/plugin/volumes/{id}
Get a volume
- Parameters:
id (string) – Volume id
- Status Codes:
200 OK – volume
404 Not Found – No such volume in this pool
- POST /storage/fabric/plugin/volumes/{id}/attach
Attach a volume to a host
- Parameters:
id (string) – Volume id
- Request JSON Object:
host (string)
mode (string)
- Status Codes:
200 OK – Connection id and path
400 Bad Request – KF-4000 malformed request
404 Not Found – No such volume or host
409 Conflict – KF-4091 another host holds it
502 Bad Gateway – KF-5010 backend unreachable
- Response JSON Object:
connid (string)
fence_token (integer)
path (string)
- POST /storage/fabric/plugin/volumes/{id}/detach
Detach a volume from a host
- Parameters:
id (string) – Volume id
- Request JSON Object:
confirmed (boolean)
host (string)
- Status Codes:
200 OK – Released
202 Accepted – Releasing, not yet confirmed
404 Not Found – No mapping for that host
502 Bad Gateway – KF-5010 backend unreachable
- Response JSON Object:
fence_token (integer)
state (string)
fence_token
state
- GET /storage/fabric/plugin/volumes/{id}/mappings
List a volume’s mappings
- Parameters:
id (string) – Volume id
- Status Codes:
200 OK – host to LUN
- POST /storage/fabric/plugin/volumes/{id}/resize
Resize a volume
- Parameters:
id (string) – Volume id
- Request JSON Object:
size_bytes (integer)
- Status Codes:
200 OK – The volume
400 Bad Request – KF-4000 malformed request
409 Conflict – KF-4017 the pool maps existing LUNs
502 Bad Gateway – KF-5010 backend unreachable
- POST /storage/fabric/pools/luns
List the LUNs of a generic iSCSI pool
Root only. The pool’s targets and portals, each in-scope host’s latest scan (status ok, failed or never; features_ok is true only when that scan carries both safety markers, so a host that never scanned reads false) and sessions, and every LUN the hosts reported with its state, paths and binding. Lists are never null.
- Request JSON Object:
pool_id (string)
- Status Codes:
200 OK – {success, data: PoolLUNs}
400 Bad Request – KF-4000 malformed request, or pool_id missing or not a uuid
403 Forbidden – Not root
404 Not Found – KF-4046 no mapping-only pool by that id
503 Service Unavailable – KF-5022 the fabric’s records could not be read
- POST /storage/fabric/volumes/{id}/paths
Live multipath health of a volume
- Parameters:
id (string) – Fabric volume id
- Status Codes:
200 OK – OK
- Response JSON Object:
hosts[].host (string)
hosts[].note (string)
hosts[].paths.device (string)
hosts[].paths.host (string)
hosts[].paths.identity (string)
hosts[].paths.min_paths (integer)
hosts[].paths.paths[].alua (string) – optimized / non-optimized / inaccessible / change / “”
hosts[].paths.paths[].device (string) – sdc, nvme0c0n1
hosts[].paths.paths[].up (boolean)
hosts[].paths.paths[].usable (boolean)
hosts[].paths.protocol (string)
hosts[].paths.state (string) – healthy / degraded / critical / detached
hosts[].paths.summary (string) – one-line operator explanation
hosts[].paths.total_paths (integer)
hosts[].paths.usable_paths (integer)
identity (string)
min_paths (integer)
name (string)
pool_id (string)
state (string) – rolled up across hosts: healthy / degraded / critical / detached
volume_id (string)
- POST /storage/fabric/zones/initiators
List the initiator IQNs of a zone’s hosts
Root only. The zone’s Routing hosts that are configured Karios nodes, each with the initiator IQN its node last reported; a host never in a fabric pool’s scope answers reported false and an empty initiator_iqn (a generic pool create names every host’s IQN in its refusal).
- Request JSON Object:
zone_id (string)
- Status Codes:
200 OK – {success, data: {hosts: [{name, cs_host_id, initiator_iqn, reported}]}}
400 Bad Request – KF-4000 malformed request, or zone_id missing or malformed
403 Forbidden – Not root
503 Service Unavailable – KF-5022 the platform’s hosts or the fabric’s records could not be read