[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]

[libvirt] [PATCHv5 20/23] snapshot: add new snapshot delete flags

This completes the public API for using mirrored snapshots as a
means of performing live storage migration.  Of course, it will
take additional patches to actually provide the implementation.

The idea here is that oVirt can start with a domain with 'vda'
open on /path1/to/old.qcow2 with a base file of /path1/to/common,
then do the following steps for a live migration to /path2 (here
using virsh commands, although the underlying API would be
available to oVirt through other language bindings as well).

First, pre-create two files; it is important that the mirror file
have a relative backing file name (if we let qemu create the entire
snapshot, the backing file name would be absolute to /path1, and
pivoting to the mirror would still be using the original source):

$ qemu-img create -f qcow2 -o backing_file=old.qcow2 \
   -o backing_fmt=qcow2 /path1/to/old.migrate
$ qemu-img create -f qcow2 -o backing_file=old.qcow2 \
   -o backing_fmt=qcow2 /path2/to/new.qcow2

Next, create a mirrored snapshot, while telling qemu to respect
the pre-existing qcow2 header in both files:

$ virsh snapshot-create-as $dom migrate --reuse-external \
   --diskspec vda,file=/path1/to/old.migrate,mirror=/path2/to/new.qcow2

which means 'vda' is now open read-write on /path1/to/old.migrate
and mirrored (write only) on /path2/to/new.qcow2, where qemu is
using /path1/to/old.qcow2 as the logial backing for both files,
but where the relative name is still intact in /path2/to/new.qcow2.
Next, the backing files can be copied between locations:

$ cp /path1/to/common /path1/to/old.qcow2 /path2/to

When that is complete, the mirrored snapshot is no longer necessary,
and requesting a pivot while deleting things will force qemu to
reread the header of /path2/to/new.qcow2, notice a relative backing
file name, and open /path2/to/old.qcow2 as the logical backing file:

$ virsh snapshot-delete $dom migrate --mirror-pivot

Now /path1 is no longer in use, but the backing chain on /path2
is longer than original.  This can be cleaned up with:

$ virsh blockpull $dom vda --base /path2/to/common

to go back to having /path2/to/new.qcow2 directly backed by

That smells like a hack, right?  Well, there is a proposal for a
better, more powerful API named virDomainBlockCopy:
which would more appropriately expose the various knobs of the new
qemu commands; but being a new API, it lacks the ability to be
backported without causing a .so bump.  So this is the compromise.

* include/libvirt/libvirt.h.in
* src/libvirt.c (virDomainSnapshotDelete): Document them.
(virDomainSnapshotCreateXML, virDomainRevertToSnapshot)
(virDomainSaveFlags): Mention effects of mirrored snapshots.
* tools/virsh.c (vshParseSnapshotDiskspec): Add <mirror> support.
(cmdSnapshotDelete): Add --mirror-abort, --mirror-pivot flags.
* tools/virsh.pod (snapshot-delete, snapshot-create-as): Document
new options.
 include/libvirt/libvirt.h.in |    6 ++++++
 src/libvirt.c                |   37 +++++++++++++++++++++++++++++++++++--
 tools/virsh.c                |   17 ++++++++++++++---
 tools/virsh.pod              |   21 ++++++++++++++-------
 4 files changed, 69 insertions(+), 12 deletions(-)

diff --git a/include/libvirt/libvirt.h.in b/include/libvirt/libvirt.h.in
index aaee218..7a4d416 100644
--- a/include/libvirt/libvirt.h.in
+++ b/include/libvirt/libvirt.h.in
@@ -3430,6 +3430,12 @@ typedef enum {
     VIR_DOMAIN_SNAPSHOT_DELETE_CHILDREN      = (1 << 0), /* Also delete children */
     VIR_DOMAIN_SNAPSHOT_DELETE_METADATA_ONLY = (1 << 1), /* Delete just metadata */
     VIR_DOMAIN_SNAPSHOT_DELETE_CHILDREN_ONLY = (1 << 2), /* Delete just children */
+    VIR_DOMAIN_SNAPSHOT_DELETE_MIRROR_ABORT  = (1 << 3), /* Stop a mirrored
+                                                            snapshot, reopening
+                                                            to the source.  */
+    VIR_DOMAIN_SNAPSHOT_DELETE_MIRROR_PIVOT  = (1 << 4), /* Stop a mirrored
+                                                            snapshot, reopening
+                                                            to the mirror.  */
 } virDomainSnapshotDeleteFlags;

 int virDomainSnapshotDelete(virDomainSnapshotPtr snapshot,
diff --git a/src/libvirt.c b/src/libvirt.c
index ad50815..cd7469a 100644
--- a/src/libvirt.c
+++ b/src/libvirt.c
@@ -2693,6 +2693,9 @@ error:
  * @flags will override what state gets saved into the file.  These
  * two flags are mutually exclusive.
+ * Some hypervisors may prevent this call if there is a current
+ * mirrored snapshot.
+ *
  * A save file can be inspected or modified slightly with
  * virDomainSaveImageGetXMLDesc() and virDomainSaveImageDefineXML().
@@ -17089,12 +17092,14 @@ virDomainSnapshotGetConnect(virDomainSnapshotPtr snapshot)
  * not exist, the hypervisor may validate that reverting to the
  * snapshot appears to be possible (for example, disk images have
  * snapshot contents by the requested name).  Not all hypervisors
- * support these flags.
+ * support these flags; this might also be forbidden if there is a
+ * current mirrored snapshot.
  * If @flags includes VIR_DOMAIN_SNAPSHOT_CREATE_NO_METADATA, then the
  * domain's disk images are modified according to @xmlDesc, but then
  * the just-created snapshot has its metadata deleted.  This flag is
+ * incompatible with VIR_DOMAIN_SNAPSHOT_CREATE_REDEFINE, and may
+ * also prevent any @xmlDesc that tries to create a mirrored snapshot.
  * If @flags includes VIR_DOMAIN_SNAPSHOT_CREATE_HALT, then the domain
  * will be inactive after the snapshot completes, regardless of whether
@@ -17704,6 +17709,9 @@ error:
  * inactive snapshots with a @flags request to start the domain after
  * the revert.
+ * Some hypervisors may prevent reverting to snapshots if there is an
+ * active mirrored snapshot.
+ *
  * Returns 0 if the creation is successful, -1 on error.
@@ -17770,6 +17778,25 @@ error:
  * libvirt metadata to track snapshots, then this flag is silently
  * ignored.
+ * If the domain has a current mirrored snapshot (that is, if the XML
+ * given to virDomainSnapshotCreateXML() included <mirror> elements for
+ * a disk), then the caller must specify how to end the mirroring before
+ * the snapshot can be deleted.  In this situation, @snap must be the
+ * current mirrored snapshot, and @flags must contain either
+ * VIR_DOMAIN_SNAPSHOT_DELETE_MIRROR_ABORT to abandon the mirror while
+ * keeping the primary external file, or contain
+ * VIR_DOMAIN_SNAPSHOT_DELETE_MIRROR_PIVOT to reopen the storage device
+ * using just the mirror, and abandon the primary external file.  Note
+ * that while virDomainSnapshotCreateXML can create mirrors atomically,
+ * the deletion process might not be atomic; in this case, the operation
+ * will fail, but only after updating the snapshot object to record
+ * which mirrors were successfully reopened.  If atomicity is important
+ * when using mirrored snapshots to perform live storage migration, it
+ * is recommended to migrate only one disk per snapshot.  After using
+ * a mirrored snapshot to perform a storage migration, the caller may
+ * also want to use virDomainBlockRebase() to reduce the length of the
+ * backing chain that was lengthened by the snapshot process.
+ *
  * Returns 0 if the selected snapshot(s) were successfully deleted,
  * -1 on error.
@@ -17803,6 +17830,12 @@ virDomainSnapshotDelete(virDomainSnapshotPtr snapshot,
                             "mutually exclusive"));
         goto error;
+        virLibDomainError(VIR_ERR_INVALID_ARG,
+                          _("delete mirror flags are mutually exclusive"));
+        goto error;
+    }

     if (conn->driver->domainSnapshotDelete) {
         int ret = conn->driver->domainSnapshotDelete(snapshot, flags);
diff --git a/tools/virsh.c b/tools/virsh.c
index e521933..d0cdba5 100644
--- a/tools/virsh.c
+++ b/tools/virsh.c
@@ -16110,6 +16110,7 @@ vshParseSnapshotDiskspec(vshControl *ctl, virBufferPtr buf, const char *str)
     char *snapshot = NULL;
     char *driver = NULL;
     char *file = NULL;
+    char *mirror = NULL;
     char *spec = vshStrdup(ctl, str);
     char *tmp = spec;
     size_t len = strlen(str);
@@ -16133,6 +16134,8 @@ vshParseSnapshotDiskspec(vshControl *ctl, virBufferPtr buf, const char *str)
             driver = tmp + strlen("driver=");
         else if (!file && STRPREFIX(tmp, "file="))
             file = tmp + strlen("file=");
+        else if (!mirror && STRPREFIX(tmp, "mirror="))
+            mirror = tmp + strlen("mirror=");
             goto cleanup;
@@ -16140,12 +16143,12 @@ vshParseSnapshotDiskspec(vshControl *ctl, virBufferPtr buf, const char *str)
     virBufferEscapeString(buf, "    <disk name='%s'", name);
     if (snapshot)
         virBufferAsprintf(buf, " snapshot='%s'", snapshot);
-    if (driver || file) {
+    if (driver || file || mirror) {
         virBufferAddLit(buf, ">\n");
         if (driver)
             virBufferAsprintf(buf, "      <driver type='%s'/>\n", driver);
-        if (file)
-            virBufferEscapeString(buf, "      <source file='%s'/>\n", file);
+        virBufferEscapeString(buf, "      <source file='%s'/>\n", file);
+        virBufferEscapeString(buf, "      <mirror file='%s'/>\n", mirror);
         virBufferAddLit(buf, "    </disk>\n");
     } else {
         virBufferAddLit(buf, "/>\n");
@@ -17182,6 +17185,10 @@ static const vshCmdOptDef opts_snapshot_delete[] = {
     {"children-only", VSH_OT_BOOL, 0, N_("delete children but not snapshot")},
     {"metadata", VSH_OT_BOOL, 0,
      N_("delete only libvirt metadata, leaving snapshot contents behind")},
+    {"mirror-abort", VSH_OT_BOOL, 0,
+     N_("abort a mirror while removing snapshot")},
+    {"mirror-pivot", VSH_OT_BOOL, 0,
+     N_("pivot to the mirror before removing snapshot")},
     {NULL, 0, 0, NULL}

@@ -17211,6 +17218,10 @@ cmdSnapshotDelete(vshControl *ctl, const vshCmd *cmd)
     if (vshCommandOptBool(cmd, "metadata"))
+    if (vshCommandOptBool(cmd, "mirror-abort"))
+    if (vshCommandOptBool(cmd, "mirror-pivot"))

     /* XXX If we wanted, we could emulate DELETE_CHILDREN_ONLY even on
      * older servers that reject the flag, by manually computing the
diff --git a/tools/virsh.pod b/tools/virsh.pod
index 0e7617b..cb121a5 100644
--- a/tools/virsh.pod
+++ b/tools/virsh.pod
@@ -2430,12 +2430,12 @@ is specified, the snapshot will not include vm state.
 The I<--disk-only> flag is used to request a disk-only snapshot.  When
 this flag is in use, the command can also take additional I<diskspec>
 arguments to add <disk> elements to the xml.  Each <diskspec> is in the
-form B<disk[,snapshot=type][,driver=type][,file=name]>.  To include a
-literal comma in B<disk> or in B<file=name>, escape it with a second
-comma.  A literal I<--diskspec> must preceed each B<diskspec> unless
-all three of I<domain>, I<name>, and I<description> are also present.
-For example, a diskspec of "vda,snapshot=external,file=/path/to,,new"
-results in the following XML:
+form B<disk[,snapshot=type][,driver=type][,file=name][,mirror=name]>.
+To include a literal comma in B<disk>, B<file=name>, or B<mirror=name>,
+escape it with a second comma.  A literal I<--diskspec> must preceed
+each B<diskspec> unless all three of I<domain>, I<name>, and
+I<description> are also present. For example, a diskspec of
+"vda,snapshot=external,file=/path/to,,new" results in the following XML:
   <disk name='vda' snapshot='external'>
     <source file='/path/to,new'/>
@@ -2578,7 +2578,7 @@ with an inactive snapshot that is combined with the I<--start> or
 I<--pause> flag.

 =item B<snapshot-delete> I<domain> {I<snapshot> | I<--current>} [I<--metadata>]
-[{I<--children> | I<--children-only>}]
+[{I<--children> | I<--children-only>}] [{I<--mirror-abort> | I<--mirror-pivot>}]

 Delete the snapshot for the domain named I<snapshot>, or the current
 snapshot with I<--current>.  If this snapshot
@@ -2593,6 +2593,13 @@ maintained by libvirt, while leaving the snapshot contents intact for
 access by external tools; otherwise deleting a snapshot also removes
 the data contents from that point in time.

+If the snapshot is mirrored (that is, the <domainsnapshot> XML used to
+create the snapshot included an external <mirror> designation for use
+in live migration of storage), then this command will fail unless the
+current snapshot is being deleted, and either the I<--mirror-abort> or
+I<--mirror-pivot> flag is present to control which half of the mirror
+is kept active.


[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]