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, IP addresses and SSH keys, 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, the SSH keys on the Access tab, and the instance's backups. Backups are archives of their own, so you can restore one over the new disk.

Erased

Every file on the disk and the instance's snapshots. The snapshots go with the old disk, so we take them off the Snapshots tab and they stop counting towards the 8 an instance can hold. 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". You cannot select an image the instance cannot run: it says why instead, such as "Needs 60 GB of disk", "Needs 4 GB of memory" or "Not ready in this location". 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, primary address, IPv6 address and SSH keys. 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:

• Connect over SSH with one of the instance's keys. The SSH keys card on the Access tab lists them. To add a key, save it there and select Restart in the header, as Manage SSH keys describes.
• Reset the password. This needs the 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.

A message that the image needs more disk or memory than the instance has

A rebuild keeps the plan, and it cannot make the disk smaller than the image needs. Choose an image that fits. To run the larger image, get a different size.

A message that the image is not ready for this instance yet

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

A message that the image is not available right now

We no longer offer the image. Choose another one.

We do not offer that operating system. Choose one from the list.

The request named an image we do not have. Choose one on the Access tab, or from GET /api/v1/client/vps/templates.

No operating systems are ready

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

Too many requests for this action. Try again later.

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

The instance still runs its old system after you started a rebuild

We read the instance's SSH keys before we erase anything. When we cannot read them, we stop, and nothing on the instance changes. Start the rebuild again, and contact support if it stops again.

A second floating IP does not answer after the rebuild

The rebuild sets up only the instance's primary address and its IPv6 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 the instance cannot take answers 409, and we start nothing. Its detail says why and what to do, such as Rocky Linux 9 is not ready for this instance yet. Choose another operating system, or try again later. The reasons are an image we no longer offer, one that needs more disk or memory than the plan has, and one that is not ready on the instance's host. To see which images fit before you send the request, list them with GET /api/v1/client/vps/templates?uuid={uuid}, as Operating system images describes. More than 8 rebuilds in 10 minutes answer 429, as Rate limits describes.