[libvirt] [RFC]: Snapshot API v2

[Daniel P. Berrange]

On Wed, Mar 24, 2010 at 02:34:41PM +0100, Matthias Bolte wrote:
> 2010/3/24 Chris Lalancette <clalance at redhat.com>:
> > Based on discussion, I've modified the snapshot API to the below.  I've
> > incorporated most of the semantic changes we talked about; the renaming
> > of various API calls I've left for later, since it is a minor point.
> > More comments welcome!
> >
> > /* NOTE: struct _virDomainSnapshot is a private structure, ala
> >  * struct _virDomain.
> >  */
> > typedef struct _virDomainSnapshot virDomainSnapshot;
> >
> > /* Take a snapshot of the current VM state.  Throws an error if
> >  * the VM is not currently running */
> > virDomainSnapshotPtr virDomainSnapshotCreateXML(virDomainPtr domain,
> >                                                const char *xmlDesc,
> >                                                unsigned int flags);
> >
> > /* Dump the XML of a snapshot */
> > /* NOTE: see below for proposed XML */
> > char *virDomainSnapshotGetXMLDesc(virDomainSnapshotPtr snapshot,
> >                                  unsigned int flags);
> >
> > /* Return the number of snapshots for this domain */
> > int virDomainSnapshotNum(virDomainPtr domain, unsigned int flags);
> >
> > /* Get the names of all snapshots for this domain */
> > int virDomainListSnapshotNames(virDomainPtr domain, char **names, int nameslen,
> >                               unsigned int flags);
> >
> > /* Get a handle to a named snapshot */
> > virDomainSnapshotPtr virDomainSnapshotLookupByName(virDomainPtr domain,
> >                                                   const char *name,
> >                                                   unsigned int flags);
> >
> > /* Start the guest "domain" from the snapshot "snapshot" */
> > int virDomainCreateWithSnapshot(virDomainPtr domain,
> >                                virDomainSnapshotPtr snapshot,
> >                                unsigned int flags);
> >
> > /* Deactivate a snapshot - with no flags, the snapshot is not used anymore,
> >  * but also not removed.  With a MERGE flag, it merges the snapshot into
> >  * the parent snapshot (or the base image, if there is no parent snapshot).
> >  * Note that if other snapshots would be discarded because of this
> >  * MERGE action, this operation will fail.  If that is really what is intended,
> >  * use MERGE_FORCE.
> >  *
> >  * With a DISCARD flag, it deletes the snapshot.  Note that if other snapshots
> >  * would be discarded because of this delete action, this operation will
> >  * fail.  If this is really what is intended, use DISCARD_FORCE.
> >  *
> >  * MERGE, MERGE_FORCE, DISCARD, and DISCARD_FORCE are mutually-exclusive.
> >  *
> >  * Note that this operation can generally only happen when the domain is shut
> >  * down, though this is hypervisor-specific */
> > typedef enum {
> >    VIR_DOMAIN_SNAPSHOT_DEACTIVATE_MERGE,
> >    VIR_DOMAIN_SNAPSHOT_DEACTIVATE_MERGE_FORCE,
> >    VIR_DOMAIN_SNAPSHOT_DEACTIVATE_DISCARD,
> >    VIR_DOMAIN_SNAPSHOT_DEACTIVATE_DISCARD_FORCE,
> > } virDomainSnapshotDeactivate;
> > int virDomainSnapshotDeactivate(virDomainSnapshotPtr snapshot,
> >                                unsigned int flags);
> >
> > int virDomainSnapshotFree(virDomainSnapshotPtr snapshot);
> >
> > NOTE: During snapshot creation, *none* of the fields are required.  That is,
> > you can call virDomainSnapshotCreateXML() with an XML of "<domainsnapshot/>".
> > In this case, the individual driver will make up a <name> for you, the
> > <creationdate> will be set to the current time+date, <description> will be
> > empty, <state> will be "off", <compression> will be empty, and <parent> will
> > be set to the current snapshot (if any).  If you do want to specify some
> > fields during virDomainSnapshotCreateXML(), note that the only ones that are
> > settable are <name>, <description>, and <compression>; the rest are ignored,
> > and filled in by the driver when the snapshot is actually created.
> > NOTE: <compression> is used to compress snapshots, and may or may not be
> > supported by individual hypervisor implementations.  If <compression> is
> > specified and the underlying hypervisor does not support it, an error will
> > be thrown.
> >
> > <domainsnapshot>
> >   <name>XYZ</name>
> >   <creationdate>...</creationdate>
> >   <description>...</description>
> >   <state>RUNNING</state>
> >   <domain>
> >      <uuid>XXXXX-XXXX-XXXX-XXXX-XXXXXXXXX</uuid>
> >   </domain>
> >   <compression>gzip</compression>
> >   <parent>
> >     <name>ABC</name>
> >   </parent>
> > </domainsnapshot>
> >
> > The virsh commands will be:
> > virsh snapshot-create [--compress] <dom> <xmlfile>
> > virsh snapshot-list <dom>
> > virsh snapshot-dumpxml <dom> <name>
> > virsh create-with-snapshot <dom> <snapshotname>
> 
> It should be called start-with-snapshot.
> 
> I'm not sure if this start-with-snapshot is a good idea, because I
> think this concept is not intuitive to the user. A typical lifecycle
> of a domain in the ESX or VirtualBox context may look like this:
> 
> - define a new domain
> - start it
> - install the OS
> - create a snapshot A to have a backup of the state with a clean OS installation
> - do some work in the domain
> - shutdown the domain
> - start the domain again (in ESX or VirtualBox UIs this is done by the
> normal start button)
> 
> The user expects to start the domain with the exact same state as at
> last shutdown. But with virsh if you use the normal start command as
> you normally do you'll get something different. In the context of ESX
> or VirtualBox I'm not even sure what the "base image" would be, is it
> the empty disk before OS installation?

Essentially the normal 'start' operation should always start with the
most recently used snapshot, if any.  'start-with-snapshot' is to be used 
where you want to switch a snapshot which isn't the most recently used.

You never want to start with the base image, if you were previously
running with a snapshot

Danil
-- 
|: Red Hat, Engineering, London    -o-   http://people.redhat.com/berrange/ :|
|: http://libvirt.org -o- http://virt-manager.org -o- http://deltacloud.org :|
|: http://autobuild.org        -o-         http://search.cpan.org/~danberr/ :|
|: GnuPG: 7D3B9505  -o-   F3C9 553F A1DA 4AC2 5648 23C1 B3DF F742 7D3B 9505 :|