Skip to main content

Evacuate a data disk before removal

POST 
/disks/array/evacuate

Required role: admin. Only an account or token with the admin role can call this operation.

Example request
curl --request POST \
  --header "Authorization: Bearer $HOSERVA_TOKEN" \
  --header "Content-Type: application/json" \
  --data @body.json \
  "https://$HOSERVA_HOST:8008/api/v1/disks/array/evacuate"

Recomputes the evacuation plan for mountpoint (never trusting a client-supplied one, as startRebalance does) and, once confirmation matches the exact phrase the matching planDiskEvacuation call returned, queues a resumable evacuation job. Before copying anything — and again on every resume — the job marks the disk evacuating (persisted in SQLite) and applies no-create to its own branch in every pool mount, live; a failure to apply that fails the job before any copy. It then runs the plan unchanged: copy and verify every batch, sync through the threshold guard (each such sync naming this disk in the guard's own zero-files exemption, since the batch that finally empties it would otherwise trip that rule), delete the batch's sources, sync again — then, once the whole plan finishes without being interrupted, a post-check confirms the disk's own share branches hold nothing but empty directories and the job marks the disk evacuated before reporting success. A wrong or missing confirmation is refused (confirmation_required) before anything runs, a disk already unpooled or unlisted is refused (disk_leaving_array, 409) as planDiskEvacuation refuses it, a second disk is refused (disk_removal_in_progress) while one is already in removal, and any new evacuation is refused (evacuation_pending) while another evacuation job is queued, running or interrupted. The removal state belongs to the job that set it: cancelling that job — queued, running or interrupted — clears it and puts the disk back to taking writes, and cancelling any other job never does. A job that fails leaves the disk evacuating; evacuating it again takes the state over, and cancelling that run clears it. Success here means the disk's data as this job saw it is safely off it and it is no longer taking new writes, not that it is empty of every file or safe to physically remove: the mergerfs branch-list removal, SnapRAID removal and unmount are finishDiskRemoval's.

Request​

Responses​

The queued, resumable evacuation job.