Skip to content

Node Evacuation

Node evacuation moves every eligible instance off a hypervisor. It is drain-first: the node stops accepting new placements before anything moves. Blocked instances are always reported and are never auto-powered-off.

Lifecycle

PLANNING → READY → RUNNING ⇄ PAUSED → COMPLETED | PARTIAL | FAILED | CANCELLED
  • COMPLETED — nothing blocked, nothing failed. The node is un-drained.
  • PARTIAL — a real, honest terminal state: some instances could not be moved and remain running on the source node. The node stays drained.

Planning

The plan builds one item per instance on the node with:

  • eligibility — ELIGIBLE or BLOCKED;
  • block_reason — the first concrete compatibility blocker;
  • target_hypervisor_id — the chosen target (failure-domain spread prefers the least-assigned target);
  • priority — running production first, then smaller disks.

The plan uses the real compatibility logic. The command's default dry-run persists nothing and reports the same evaluation read-only.

Running

  • At most batch_size pending items are processed per call.
  • The critical preflight is re-run immediately before each move; a target that became ineligible is skipped, not forced.
  • pause()/resume() are state transitions; the next batch recomputes targets.
  • Blocked instances are marked BLOCKED and left untouched: the evacuation never issues a power-off for a blocked guest.

Commands

# Dry-run by default: real evaluation, zero mutations.
php artisan pterocloud:hypervisor:evacuate <hv_uuid> --dry-run --mode=AUTO
# Apply: drain the node, build the plan, start it.
php artisan pterocloud:hypervisor:evacuate <hv_uuid> --apply --mode=AUTO

Reporting

The admin page (/admin/pterocloud/evacuations/{uuid}/view) and the API show total / migratable / blocked / estimated bytes / candidate targets, blocked reasons and progress. Partial vs completed is explicit.

Honesty

  • Mock-tested: drain-first, plan counts, blocked reporting and no power-off, partial vs completed finalize, un-drain on completion, pause/resume, batch sizing, and a 1000-instance plan that stays responsive.
  • NOT TESTED on hardware: real concurrent evacuation, real bandwidth throttling and real node maintenance windows.
  • Known limitation: the evacuation batch size is the enforced concurrency knob in this deliverable.