Adding more comments regarding XS snapshots

5 files changed, 55 insertions, 6 deletions

diff --git a/nova/virt/fake.py b/nova/virt/fake.py
index 73e273edd..c6db66aa6 100644
--- a/nova/virt/fake.py
+++ b/nova/virt/fake.py
@@ -106,6 +106,22 @@ class FakeConnection(object):
         self.instances[instance.name] = fake_instance
         fake_instance._state = power_state.RUNNING
 
+
+    def snapshot(self, instance, name):
+        """
+        Snapshots the specified instance.
+
+        The given parameter is an instance of nova.compute.service.Instance,
+        and so the instance is being specified as instance.name.
+
+        The second parameter is the name of the snapshot.
+
+        The work will be done asynchronously.  This function returns a
+        Deferred that allows the caller to detect when it is complete.
+        """
+        pass
+
+
     def reboot(self, instance):
         """
         Reboot the specified instance.
diff --git a/nova/virt/libvirt_conn.py b/nova/virt/libvirt_conn.py
index c8d0aa306..ad1a35643 100644
--- a/nova/virt/libvirt_conn.py
+++ b/nova/virt/libvirt_conn.py
@@ -237,7 +237,7 @@ class LibvirtConnection(object):
         virt_dom.detachDevice(xml)
 
     @exception.wrap_exception
-    def snapshot(self, instance):
+    def snapshot(self, instance, name):
         """ Create snapshot from a running VM instance """
         raise NotImplementedError(
             _("Instance snapshotting is not supported for libvirt"
diff --git a/nova/virt/xenapi/vm_utils.py b/nova/virt/xenapi/vm_utils.py
index 5b1c36418..b7e20121c 100644
--- a/nova/virt/xenapi/vm_utils.py
+++ b/nova/virt/xenapi/vm_utils.py
@@ -154,6 +154,9 @@ class VMHelper():
 
     @classmethod
     def create_snapshot(cls, session, instance_id, vm_ref, label):
+        """ Creates Snapshot (Template) VM, Snapshot VBD, Snapshot VDI,
+        Snapshot VHD
+        """
         logging.debug(_("Snapshotting VM %s with label '%s'..."), vm_ref, label)
         
         #TODO(sirp): Add quiesce and VSS locking support when Windows support
@@ -189,6 +192,9 @@ class VMHelper():
 
     @classmethod
     def upload_image(cls, session, instance_id, vdi_uuids, image_name):
+        """ Requests that the Glance plugin bundle the specified VDIs and
+        push them into Glance using the specified human-friendly name.
+        """
         logging.debug(_("Asking xapi to upload %s as '%s'"),
                       vdi_uuids, image_name)
 
@@ -347,9 +353,17 @@ def scan_sr(session, instance_id, sr_ref):
 
 def wait_for_vhd_coalesce(session, instance_id, sr_ref, vdi_ref,
                           original_parent_uuid):
-    """ TODO Explain why coalescing has to occur here """
-    #NOTE(sirp): for some reason re-scan wasn't occuring automatically on 
-    # XS5.6
+    """ Spin until the parent VHD is coalesced into its parent VHD
+  
+    Before coalesce:
+        * original_parent_vhd
+            * parent_vhd
+                snapshot
+
+    Atter coalesce:
+        * parent_vhd
+            snapshot
+    """
     #TODO(sirp): we need to timeout this req after a while
 
     def _poll_vhds():
diff --git a/nova/virt/xenapi/vmops.py b/nova/virt/xenapi/vmops.py
index 787f959a5..dd6243dd5 100644
--- a/nova/virt/xenapi/vmops.py
+++ b/nova/virt/xenapi/vmops.py
@@ -88,7 +88,27 @@ class VMOps(object):
                      vm_ref)
     
     def snapshot(self, instance, name):
-        """ Create snapshot from a running VM instance """
+        """ Create snapshot from a running VM instance
+      
+        :param instance: instance to be snapshotted
+        :param name: name/label to be given to the snapshot
+
+        Steps involved in a XenServer snapshot:
+
+        1. XAPI-Snapshot: Snapshotting the instance using XenAPI. This
+            creates: Snapshot (Template) VM, Snapshot VBD, Snapshot VDI,
+            Snapshot VHD
+    
+        2. Wait-for-coalesce: The Snapshot VDI and Instance VDI both point to
+            a 'base-copy' VDI.  The base_copy is immutable and may be chained
+            with other base_copies.  If chained, the base_copies
+            coalesce together, so, we must wait for this coalescing to occur to
+            get a stable representation of the data on disk.
+
+        3. Push-to-glance: Once coalesced, we call a plugin on the XenServer
+            that will bundle the VHDs together and then push the bundle into
+            Glance.
+        """
 
         #TODO(sirp): Add quiesce and VSS locking support when Windows support
         # is added
diff --git a/nova/virt/xenapi_conn.py b/nova/virt/xenapi_conn.py
index 58ad6ca6a..816b92a0f 100644
--- a/nova/virt/xenapi_conn.py
+++ b/nova/virt/xenapi_conn.py
@@ -121,7 +121,6 @@ class XenAPIConnection(object):
         """Create VM instance"""
         self._vmops.spawn(instance)
 
-
     def snapshot(self, instance, name):
         """ Create snapshot from a running VM instance """
         self._vmops.snapshot(instance, name)