<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=utf-8">
</head>
<body bgcolor="#FFFFFF" text="#000000">
Hi everyone,<br>
<br>
I'm presenting here my proposal for the feature "Domain snapshots"
which is expected to be implemented for Kimchi 1.4.<br>
<h2>Description</h2>
<p>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.<br>
</p>
<p>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.<br>
</p>
<p>Existing functions which also deal with snapshots will be
updated.<br>
</p>
<h2>REST API</h2>
<h3>Create a domain snapshot<br>
</h3>
<h4>Syntax</h4>
<p><tt>POST /vms/<i><vm-name></i></tt><tt>/snapshots</tt><br>
</p>
<h4>Parameters</h4>
<p><tt>name</tt>: The snapshot name (optional). If omitted, a
default name will be used.<br>
</p>
<h4>Return</h4>
<p>An asynchronous Task with "<tt>target_uri</tt>" containing "<tt>/vms/<</tt><tt><i>vm-name</i></tt><tt>></tt><tt>/snapshots/<i><new-snapshot-name></i></tt>".
As expected with any Task, the process can be tracked by checking
the corresponding task's status.<br>
</p>
<h3>Look up one domain snapshot</h3>
<h4>Syntax</h4>
<p><tt>GET /vms/<i><vm-name></i>/snapshots/<i><snapshot-name></i></tt><br>
</p>
<h4>Parameters</h4>
<p>None.</p>
<h4>Return</h4>
<p>A snapshot structure with the following properties:<br>
</p>
<p><tt>name</tt>: The snapshot name.<br>
<tt>state</tt>: The corresponding domain state when the snapshot
was created.<br>
<tt>created</tt>: The time when the snapshot was created (in
seconds, since the epoch).<br>
<tt>parent</tt>: The name of the parent snapshot, or an empty
string if there is no parent.<br>
</p>
<h3>Look up multiple domain snapshosts</h3>
<h4>Syntax</h4>
<p><tt>GET /vms/<i><vm-name></i>/snapshots</tt><br>
</p>
<h4> Parameters</h4>
<p><tt>parent</tt>: The name of the parent snapshot of the requested
snapshots (optional). If omitted, only the "root" snapshots for
that domain will be returned.<br>
</p>
<h4> Return</h4>
<p>A list of the structures returned by the action "Look up one
domain snapshot". All snapshots returned by this call will have "<tt>parent</tt>"
as their parents.<br>
</p>
<h3>Update a domain snapshot</h3>
<h4>Syntax</h4>
<p><tt>PUT /vms/<i><vm-name></i>/snapshots/<i><snapshot-name></i></tt><br>
</p>
<h4>Parameters:</h4>
<p><tt>name</tt>: The new snapshot name.<br>
</p>
<h4>Return:</h4>
<p>The structure returned by the action "Look up one domain
snapshot" with the updated values.<br>
</p>
<h3>Delete a domain snapshot</h3>
<h4>Syntax</h4>
<p><tt>DELETE /vms/<i><vm-name></i>/snapshots/<i><snapshot-name></i></tt><br>
</p>
<h4> Parameters</h4>
<p>None.<br>
</p>
<h4> Return</h4>
<p>None.<br>
</p>
<h3>Revert to a domain snapshot</h3>
<h4>Syntax</h4>
<p><tt>POST /vms/<i><vm-name></i>/snapshots/<i><snapshot-name></i>/revert</tt><br>
</p>
<h4> Parameters</h4>
<p>None.</p>
<h4> Return</h4>
<p>None.<br>
</p>
<h3>CHANGE: List the current snapshot in a domain<br>
</h3>
<h4>Syntax</h4>
<p><tt>GET /vms/<i><vm-name></i></tt><br>
</p>
<h4>Additional parameters</h4>
<p>None.<br>
</p>
<h4>Additional return</h4>
<p><tt>current-snapshot</tt>: the snapshot name in which the domain
execution is on, or an empty string if there is no current
snapshot.<br>
</p>
<h3>CHANGE: Delete snapshots when deleting a domain</h3>
<h4>Syntax</h4>
<p><tt>DELETE /vms/<i><vm-name></i></tt><br>
</p>
<h4>Additional parameters</h4>
<p>None.<br>
</p>
<h4>Additional return</h4>
<p>None.<br>
</p>
<h3>CHANGE: Clone snapshots when cloning a domain</h3>
<h4>Syntax</h4>
<p><tt>POST /vms/<i><vm-name></i>/clone</tt><br>
</p>
<h4>Additional parameters</h4>
<p>None.</p>
<h4>Additional return</h4>
None.<br>
<h2>Open discussion</h2>
<ol>
<li>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.<br>
</li>
<li>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.<br>
</li>
<li>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.<br>
</li>
<li>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.<br>
</li>
</ol>
<p>Any feedback is welcome.<br>
</p>
<p>Best regards,<br>
CrÃstian.<br>
</p>
<h2> </h2>
</body>
</html>