Description

A domain snapshot is a "moment in time" of a domain. After a snapshot is created, a domain can be reverted to that snapshot (i.e. reverted to the exact same state it was when the snapshot was created). If a snapshot is created while the domain is stopped, only its disks will be used in that snapshot; otherwise, its memory state will also be used.

A snapshot can be created on top of another snapshot, which makes it possible to have a tree-like snapshot structure for each domain. When a snapshot is created, the last snapshot used in that domain execution will be its parent. If there are no previous snapshot in that execution, the new snapshot will have no parent.

Existing functions which also deal with snapshots will be updated.

REST API

Create a domain snapshot

Syntax

POST /vms/<vm-name>/snapshots

Parameters

name: The snapshot name (optional). If omitted, a default name will be used.

Return

An asynchronous Task with "target_uri" containing "/vms/<vm-name>/snapshots/<new-snapshot-name>". As expected with any Task, the process can be tracked by checking the corresponding task's status.

Look up one domain snapshot

Syntax

GET /vms/<vm-name>/snapshots/<snapshot-name>

Parameters

None.

Return

A snapshot structure with the following properties:

name: The snapshot name.
state: The corresponding domain state when the snapshot was created.
created: The time when the snapshot was created (in seconds, since the epoch).
parent: The name of the parent snapshot, or an empty string if there is no parent.

Look up multiple domain snapshosts

Syntax

GET /vms/<vm-name>/snapshots

Parameters

parent: The name of the parent snapshot of the requested snapshots (optional). If omitted, only the "root" snapshots for that domain will be returned.

Return

A list of the structures returned by the action "Look up one domain snapshot". All snapshots returned by this call will have "parent" as their parents.

Update a domain snapshot

Syntax

PUT /vms/<vm-name>/snapshots/<snapshot-name>

Parameters:

name: The new snapshot name.

Return:

The structure returned by the action "Look up one domain snapshot" with the updated values.

Delete a domain snapshot

Syntax

DELETE /vms/<vm-name>/snapshots/<snapshot-name>

Parameters

None.

Return

None.

Revert to a domain snapshot

Syntax

POST /vms/<vm-name>/snapshots/<snapshot-name>/revert

Parameters

None.

Return

None.

CHANGE: List the current snapshot in a domain

Syntax

GET /vms/<vm-name>

Additional parameters

None.

Additional return

current-snapshot: the snapshot name in which the domain execution is on, or an empty string if there is no current snapshot.

CHANGE: Delete snapshots when deleting a domain

Syntax

DELETE /vms/<vm-name>

Additional parameters

None.

Additional return

None.

CHANGE: Clone snapshots when cloning a domain

Syntax

POST /vms/<vm-name>/clone

Additional parameters

None.

Additional return

Open discussion

1. When creating a snapshot in a running domain, should we try to minimize the domain's downtime? There's a libvirt flag for that but it increases the memory dump file size.
   
2. When deleting a snapshot, should we keep their children or should we only delete that snapshot? Keep in mind that snapshots follow a tree-like structure. This feature is already implemented by libvirt, it makes no difference for us in the implementation (it's just a different flag), but we need to think if the user would expect that the snapshot's children will be deleted as well when deleting one snapshot.
   
3. The properties returned by the action "Look up one domain snapshot" are just the ones I thought it might be useful for now. A snapshot has more properties than that but I'm not sure if we should just dump everything.
   
4. The property updated by the action "Update a domain snapshot" (i.e. "name") is the only one I thought it might be relevant. Other properties can be updated as well if we want to.
   

Any feedback is welcome.

Best regards,
Crístian.