Skip to main content
An instance carries two states and they answer different questions.

desired_state

What you asked for. Three values, because there are three things you can ask an instance to be.

current_state

Where it actually is. Read this one to answer “is it up”.
They are not two halves of one answer — they are a request and its progress. POST /v1/instances/{instance_id}/start sets desired_state to running immediately, and current_state stays stopped until the guest is actually up. That pairing is the honest reading of “asked to start, not there yet”.

​
desired_state

Three values, and every call that changes one sets it to one of them. Nothing else appears here. stopping is not something anyone requests — it is where the instance has got to — which is why it lives on the other field.

​
current_state

Treat an unrecognized current_state as “busy, do not act” rather than as a failure. The list grows as the platform learns to tell states apart — a guest that has crashed currently reports stopped, because the host cannot yet distinguish a panic from a clean shutdown.

​
Start, stop, reboot

Each is a 202 with an empty body — poll the instance to see the result.
Open the instance from Compute → Instances. The header offers only the actions its current state allows: Start while it is stopped, Stop and Reboot while it is running.A hard power cycle is not among them. It sits on the Settings tab as Hard reboot, described there as Power-cycles the instance without a clean OS shutdown and gated behind a typed confirmation.
POST /v1/instances/{instance_id}/start accepts an instance in stopped or in error — the second case is how you retry an instance that failed on the way up, without recreating it. Any other state is a 409.
POST /v1/instances/{instance_id}/stop requires running. Anything else is a 409 — including an instance already stopped, so this is not a “make it stopped” idempotent call.
POST /v1/instances/{instance_id}/reboot requires running. The default is a graceful ACPI reboot the guest can act on; {"hard": true} is a power cycle — the reset button, with no chance to flush anything.

​
Resize

A resize changes vCPU and RAM, and nothing else. Disks are untouched, addresses are untouched, the guest’s data is untouched.
Resize on the instance header opens Resize instance, a flavor picker that summarizes Current against New flavor before you commit and then asks you to confirm.
The console offers Resize while the instance is still running, but the resize itself needs it stopped — submitting from a running instance comes back as Failed to resize instance. Stop it first.
Two things about it are worth knowing before you plan a resize window:
1

The instance must be stopped

A running guest’s CPU and memory maximums cannot be changed underneath it, so a resize on a running instance is a 409. Stop it, resize, start it.
2

The new size is applied at the next start

The call records the target and returns. The guest comes up on the new flavor when you start it — there is no separate confirm step, and no state in which the instance is half-resized.
A resize does not move the instance to another host. Growing means the extra vCPU and RAM have to be free on the host it is already on, so a resize can be refused for capacity while the region as a whole has plenty. Moving to a dedicated flavor is the strictest case: it needs whole threads nothing else may run on, which a busy-but-not-full host may not have.
Two more refusals, both 400: resizing to the flavor the instance already uses, and resizing onto a loadbalancer or database flavor. An instance’s network ceiling moves with the flavor as part of the resize, so a downsize gives up the larger flavor’s bandwidth too.

​
Reinstall

POST /v1/instances/{instance_id}/reinstall re-images the boot disk while keeping the instance itself. Also stopped-only, and also applied at the next start.

Kept

The instance id, name, CRN, IP addresses and MAC addresses, its network interfaces, its keypairs, its cloud-init seed, and every attached data volume.

Replaced

The boot volume. A fresh one is cloned from the image and swapped in, and the old one is deleted. Everything on the root filesystem is gone.
The console calls this Replace root volume, and it is on the instance’s Settings tab, in the danger zone. It opens an Image and a Boot volume card — Operating system for the replacement root volume. The current one is deleted — and confirms with the instance name typed back.
Same operation, different name. Nothing in the console is labelled “reinstall”: look for Replace root volume, which is the more literal description of what happens to the disk.
Every field is optional. Omit image and it reinstalls from the image the instance already has; omit size_gb and the replacement is the image’s min_disk_gb; omit volume_type and it lands on the region default. The same floor applies as at launch — size_gb must be at least the image’s min_disk_gb, and within 1–16384 GB. Because the addresses survive, reinstall is the operation for “same machine, clean OS” — a rebuild where anything pointing at the instance keeps working.

​
Delete

Delete instance is on the instance’s Settings tab, in the danger zone. The confirmation restates the rule below — Volumes marked delete on termination are destroyed with it; others are detached and kept — and needs the instance name typed back.
It answers 202. The instance moves to deleting, the guest is torn down, and the row is removed once its interfaces and volumes have been reclaimed — so a completed delete stops answering reads entirely rather than leaving a deleted row behind. Deleting an instance already deleting is accepted and re-drives the teardown rather than starting a second one.

​
What survives a delete

To keep a boot disk past its instance, flip the flag on the attachment: PATCH /v1/instances/{instance_id}/volumes/{volume_id} with {"delete_on_termination": false}. The volume is then unbound and returned to available on teardown instead of destroyed. This works on the boot volume like any other attachment.In the console it is the Delete on termination switch on the instance’s Volumes tab, one per attachment.