Take and roll back instance snapshots

A snapshot saves the state of an instance's disk at one moment, so you can return the disk to that state later. Take one before a risky change, such as an upgrade, and roll back if the change goes wrong. An instance can hold 8 snapshots at a time.

A snapshot lives on the same storage as the instance's disk. It is quick to take and to roll back to, but it goes with the disk. A rebuild, a backup restore or a cancellation deletes it. For a copy that stays when you rebuild, create a backup.

The Snapshots card says the same in one line: snapshots are for undoing a change you made today, and Backups is for a copy that lasts. The card footer shows how many of the 8 snapshots you use.

• The instance is not suspended.
• To include the memory, the instance is running.

1. In the dashboard, go to Cloud Compute, open the instance and select the Snapshots tab.
2. Select Take snapshot…. A page opens with the heading Take a snapshot, the instance's name under it and a This snapshot card that counts the snapshots the instance holds out of 8.
3. Under Name, type a name such as before-upgrade. Start with a letter, and use letters, digits, hyphens and underscores. Use 37 characters or fewer. A name that breaks the rule shows its reason under the field, and Take snapshot stays off until you fix it.
4. Optionally, add a Description of up to 255 characters.
5. Under Memory, to save the memory as well, tick Include memory (RAM state). Rolling back to the snapshot then resumes the instance exactly where it was. The snapshot is larger, and the instance pauses while we save its memory. On a stopped instance the box is off, because there is no memory to save.
6. Select Take snapshot.

If we refuse the request, a Could not take the snapshot message says why, and every field keeps what you entered. When the instance is suspended or already holds 8 snapshots, the page opens with the reason (You cannot take a snapshot now or All 8 snapshots are in use) and shows no form. The Back to Snapshots button takes you back to the tab. On the form, Cancel and the Snapshots link above the heading do the same without taking a snapshot.

After Take snapshot, a message names the snapshot and you return to the Snapshots tab.

The snapshot appears in the table with its Contents, Disk or Disk and memory, and when it was Taken.

Rolling back returns the disk to the snapshot and loses everything written to it since.

1. On the Snapshots tab, open the menu at the end of the snapshot's row and select Roll back….
2. Type the snapshot's name to confirm, then select Roll back.

We shut the instance down, roll the disk back and start it again. A snapshot with memory resumes from its saved state. The snapshot stays, so you can roll back to it again later.

1. On the Snapshots tab, open the menu at the end of the snapshot's row and select Delete snapshot….
2. Type the snapshot's name to confirm, then select Delete snapshot.

Deleting a snapshot frees its space on the storage. The instance itself does not change.

The table lists each snapshot with its status, and the card above it counts how many of the 8 you use. A snapshot that failed does not count.

Snapshot limit reached

The instance holds 8 snapshots. Delete one before you take another.

Snapshot name must be alphanumeric (start with a letter), max 40 chars

The name has a character a snapshot name cannot hold, or does not start with a letter. Use letters, digits, hyphens and underscores only.

Snapshot failed

The host could not take the snapshot. The API accepts a name of up to 40 characters, but the host refuses one over 37, so a longer name sent through the API fails here. Choose a shorter name and try again.

Rollback failed after you rolled back a snapshot with memory

The instance may have rolled back anyway. Open the Console tab and check its state before you try again.

The snapshots are gone after a restore

The backup restore replaced the disk the snapshots belonged to, so we deleted them with it. A rebuild does the same. Take new snapshots once the instance runs again.

• Back up and restore an instance for full copies of the disk that a rebuild leaves in place.
• Rebuild an instance explains what a rebuild erases.
• Cloud Compute limits lists the snapshot limit with the others.

GET /api/v1/client/vps/{uuid}/snapshots lists the instance's snapshots, newest first. Each has an id, name, description, vmstate (1 when it holds memory), status and created_at. status is creating, ready, rolling_back, deleting or failed.

POST /api/v1/client/vps/{uuid}/snapshots takes a snapshot. Send name; description and vmstate are optional, and vmstate is false when left out. The request returns when the snapshot is ready.

curl -X POST https://api.coritan.com/api/v1/client/vps/$INSTANCE_UUID/snapshots \
  -H "Authorization: Bearer $CORITAN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "before-upgrade", "description": "Before the kernel upgrade", "vmstate": false}'

{"id": 3, "name": "before-upgrade", "proxmox_snapname": "cc-before-upgrade", "status": "ready"}

A ninth snapshot answers 409 with Snapshot limit of 8 reached. A name the rules refuse answers 400, and so does a snapshot the host could not take, with a message that starts Snapshot failed.

POST /api/v1/client/vps/{uuid}/snapshots/{snapshot_id}/rollback rolls back to a snapshot whose status is ready, and answers {"status": "rolled_back", "id": 3} once the instance runs again. Any other snapshot answers 404 with Snapshot not found or not ready.

DELETE /api/v1/client/vps/{uuid}/snapshots/{snapshot_id} deletes a snapshot and answers {"status": "deleted", "id": 3}. You can delete snapshots while the instance is suspended.

Taking a snapshot and rolling back answer 403 with Instance is suspended on a suspended instance. While we move the instance to another host, taking, rolling back and deleting answer 409 with Instance is migrating.