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:
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:
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:
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:
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:
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:
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:
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:
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:
GET /storage/fabric/plugin/pools/{id}/stats

Pool capacity

Parameters:
  • id (string) – Pool id

Status Codes:
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:
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:
GET /storage/fabric/plugin/volumes/{id}

Get a volume

Parameters:
  • id (string) – Volume id

Status Codes:
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:
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:
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:
POST /storage/fabric/plugin/volumes/{id}/resize

Resize a volume

Parameters:
  • id (string) – Volume id

Request JSON Object:
  • size_bytes (integer)

Status Codes:
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:
POST /storage/fabric/volumes/{id}/paths

Live multipath health of a volume

Parameters:
  • id (string) – Fabric volume id

Status Codes:
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