Rebuild an instance

A rebuild erases the instance's disk and installs an operating system image on it from scratch. Use it to start again with a clean system, or to move to another distribution or release. The instance keeps its plan, hostname and IP addresses, and its billing does not change.

Kept

The plan with its vCPU, memory and disk size, the hostname, the floating IPs attached to the instance, and its backups.

Erased

Every file on the disk, the instance's snapshots, and the SSH keys saved on the Access tab. The instance also gets a new random password, which we do not show.

• Back up anything on the disk that you want to keep. A rebuild cannot be undone.
• The instance is not suspended.
• Leave rescue mode first if the instance is in it.
• Choose an image that fits the instance. Each image shows the disk it needs, such as "Needs 20 GB", and the instance's disk size is on the Disk card of the Console tab.

1. In the dashboard, go to Cloud Compute, open the instance and select the Access tab. The Rebuild operating system card is at the bottom.
2. Choose an image. The images are grouped by distribution, and each one names the user you sign in as and the disk it needs. Current marks the image the instance runs now; choose it to reinstall the same release.
3. Select Rebuild instance….
4. In the dialog, type the instance's hostname to confirm, then select Erase and rebuild.

The Danger zone card on the Settings tab has the same rebuild: its Open Access button brings you to this card.

We stop the instance, replace its disk with a fresh copy of the image, and start it again with the same hostname and primary address. A message confirms that the rebuild has started. When it has finished, reload the page: the header names the new image.

To sign in to the rebuilt instance, do one of these:

• Save your SSH keys again on the Access tab, then select Restart in the header, as Manage SSH keys describes.
• Reset the password. This needs the QEMU guest agent, which not every image includes.

The rebuilt instance has new SSH host keys, so your SSH client warns that the host identification has changed. Connect to an instance over SSH shows how to clear the warning.

Cannot rebuild a suspended instance

The service behind the instance is suspended. Settle it from the Billing tab first.

Template not available (ready) on this node

The image is not ready on the host that runs your instance, although it is ready elsewhere. Choose another image, or try again later.

No templates are ready

None of the images is ready right now. Try again later.

Too many requests for this action. Please wait and try again.

You started more than 8 rebuilds of this instance in 10 minutes. Wait for the time the response gives in Retry-After.

A second floating IP does not answer after the rebuild

The rebuild sets up only the instance's primary address. For each other floating IP on the instance, detach it and attach it again, then restart the instance from the header.

• Operating system images describes what each image sets up on its first boot.
• Back up and restore an instance to keep a copy of the disk first.
• Repair an instance in rescue mode to fix a system without erasing it.

POST /api/v1/client/vps/{uuid}/rebuild starts a rebuild. Send the image's template_id, which GET /api/v1/client/vps/templates lists, as Operating system images describes.

curl -X POST https://api.coritan.com/api/v1/client/vps/$INSTANCE_UUID/rebuild \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"template_id": 7}'

The response is {"status": "rebuild_queued"}, and the rebuild runs in the background. Follow it with GET /api/v1/client/vps/{uuid}/tasks: the host destroys the old machine in a qmdestroy task and starts the new one in a qmstart task, and the rebuild is done when that qmstart reads OK.

A suspended instance answers 403 with Cannot rebuild a suspended instance, and one we are moving answers 409 with Instance is migrating. An image that is not ready on the instance's host answers 400 with Template not available (ready) on this node. More than 8 rebuilds in 10 minutes answer 429, as Rate limits describes.