Block Storage API
Volumes, attachment, snapshots, move, and failover (v2.10)
Overview
Block volumes are virtual disks. Commands go to
POST https://api.rackcorp.net/api/rest/v2.10/json.php
with Authorization: Bearer YOUR_JWT_TOKEN.
List and fetch are the calls most integrations start with. Lifecycle commands (create, attach, snapshot, move, failover) use the same cmd style.
POST storage.block.getall
List volumes. Optional stdname filters by customer trading name, name by volume name, plus resStart and resWindow.
{
"cmd": "storage.block.getall",
"stdname": "Example",
"name": "data",
"resStart": 0,
"resWindow": 50
}
POST storage.block.get
One volume. Requires blockStorageId. The volume object is returned as storage and includes name, sizeBytes, type, status, and descriptor.
{
"cmd": "storage.block.get",
"blockStorageId": 1001
}
List calls also accept deviceId to return volumes mounted on that device. A numeric name matches the volume name or the volume id. storage.blocklocation.get returns where a volume is placed.
Lifecycle
| Command | Purpose |
|---|---|
storage.block.create | Create a volume |
storage.block.update | Update a volume |
storage.block.delete | Request deletion |
storage.block.driver.update | Change the storage driver |
storage.block.associate | Attach the volume to a device |
storage.block.unassociate | Detach the volume from a device |
storage.block.mount | Mount the volume |
storage.block.unmount | Unmount the volume |
Snapshots
| Command | Purpose |
|---|---|
storage.block.snapshot.getall | List snapshots |
storage.block.snapshot.create | Create a snapshot |
storage.block.snapshot.delete | Delete a snapshot |
Move, failover, and replication
REPLICATEDV2 is DRBD high availability. REPLICATEDV3 is io-engine.
storage.block.getrecoverystatus returns availableActions. Only call a recovery command when its action is in that list.
| Command | Parameters |
|---|---|
storage.block.move | blockStorageId. REPLICATEDV2 only. Optional targetDeviceId (otherwise a host is chosen) and force (JSON true to move a locked volume). Refused while a transition is running or the volume is DRIFTED. |
storage.block.moveabort | blockStorageId. REPLICATEDV2 only, and only in phase ADDING, SYNCING, or READY_TO_SWITCH. |
storage.block.failover | blockStorageId, targetDeviceId. REPLICATEDV2 or REPLICATEDV3. Optional force. Force is only accepted on io-engine volumes, and it is the path that is allowed while the volume is DRIFTED. |
storage.block.getfailovertargets | blockStorageId. HA volumes only. |
storage.block.replicamaintenance | blockStorageId, targetDeviceId, maintenance (offline or online). Io-engine volumes only. The target must be an active replica, and the volume must not already be in transition. |
storage.block.getavailablesecondaryhosts | blockStorageId. Optional dcPreference: SAME (default) or ALTERNATIVE. The volume must be mounted. |
storage.block.upgradetoreplicatedv2 | blockStorageId. The volume must be REGULAR and NORMAL. Optional targetDeviceId or placementDeviceIds, storageDomainId, dcPreference (SAME or ALTERNATIVE), replicationMode (SYNCHRONOUS default, or ASYNCHRONOUS). |
Recovery
Read status first. force on the write calls below must be the JSON boolean true.
storage.block.getdriftstatus is the same diagnosis as getrecoverystatus, plus recoveryOptions booleans.
| Command | Parameters |
|---|---|
storage.block.getrecoverystatus | blockStorageId. Returns database locations, observed fabric state, and availableActions. |
storage.block.gettransitionstatus | blockStorageId. Returns inTransition, operation, and transition (phase, kind, target, started). |
storage.block.getdriftstatus | blockStorageId. |
storage.block.recoverprimary | blockStorageId. REPLICATEDV2. Optional targetDeviceId. Only when availableActions contains RECOVER_PRIMARY. |
storage.block.retryreconcile | blockStorageId, force: true. REPLICATEDV2. Optional reason. Only when availableActions contains RETRY_RECONCILE. Refused during a move. |
storage.block.forcereconcile | blockStorageId, force: true. REPLICATEDV2. Optional reason. Allowed when the volume is DRIFTED or availableActions contains FORCE_RECONCILE. |
storage.block.adoptcurrentstate | blockStorageId. Optional force on io-engine volumes. Copies the fabric's observed locations into the database and sets the volume IN_SYNC. Only when the volume is DRIFTED or availableActions contains ADOPT_CURRENT_STATE. |
storage.block.transition.abandon | blockStorageId, force: true. Io-engine only. Optional targetDeviceId and reason. Clears a stuck transition and re-drives the recorded intent. It does not move data. Refused when the volume is already converged. |
Domain change and NVMe-oF
| Command | Parameters |
|---|---|
storage.block.changedomain | blockStorageId, storageDomainId. Optional targetDeviceId. Refused while the volume is locked or already in transition. |
storage.block.changedomain.cancel | blockStorageId. Only while the domain change is still cancellable. |
storage.block.domainplacement.evaluate | blockStorageId, storageDomainId. Reports whether that domain can take the volume. |
storage.block.nvmeof.exports.get | deviceId. Exports currently enabled on that host. |
storage.block.nvmeof.export.set | blockStorageId, deviceId (an active location of the volume), nvmeofExport (true or false). Optional nvmeofExportDevice path. An empty path, or turning the export off, clears the override. |