Debug a VM that will not come up

Start with what the API can tell you, then move to the guest, which the API cannot see. In this order:

1. Did the create even succeed?

POST /v1/vms blocks until the machine is built, so a provisioning failure came back on the create itself as 409 create_failed, carrying the hypervisor's own text, and the partial VM was destroyed and its IP released. There is no half-built machine to inspect. Fix what detail said and create again.

2. What does the platform think the machine is doing?

GET /v1/vms/{id}

Two separate fields, and there is no state:

• status is the state of the VM's record on our side: creating, active, retained or deleting.
• power is read live from the hypervisor on every request — running, stopped, or unknown.

power: "unknown" with health: "unreachable" means the hypervisor could not be reached. That is a problem on our side, and actions on that VM fail right away until the hypervisor is back. A VM that was running when the hypervisor under it rebooted comes back up on its own.

If power is stopped, start it: creation leaves a machine stopped, and starting it is a separate call.

3. What happened, in order?

GET /v1/vms/{id}/events

The newest 100 events for that VM, newest first: what the platform did, when, and what failed. This is where to look when an action did not do what you expected; a failed create was answered in step 1.

4. Is it running but unreachable?

If power is running, nothing on our side is left to check. Then:

• The address. Each machine carries its own ip in GET /v1/vms. A recreated VM has a different address — the old one went back to the pool. If you wrote an address down rather than putting a DNS name in front, this is the usual cause.
• Your own firewall. The only rule the platform enforces is anti-spoof. Nothing else inbound is filtered by us, so anything dropping your connection is running in your guest: Firewall.
• Your key. The keys you passed at creation are the only way in. Log in as ubuntu, or as root while GET /v1/vms/{id} shows "rescue": true: the VM is then running the rescue system, not its own disk.

5. If the guest locked you out

There is no console and no password. You have three options:

• Boot it into rescue, mount its disk and undo the change: the firewall rule, the sshd config, the fstab line. The VM and everything on it stay as they are.
• Roll back a snapshot, if you took one before the change. It needs the VM stopped and leaves it stopped, and only the newest snapshot is restorable. See Snapshots.
• Recreate the VM and re-run your configuration. Your volumes detach from the old machine and attach to the new one with their data intact; the root disk does not survive.

To avoid this next time, make every firewall and sshd change revert itself unless you confirm it: Harden a VM.