Renamed db_update to model_update, and lots more documentation

3 files changed, 37 insertions, 19 deletions

diff --git a/nova/volume/driver.py b/nova/volume/driver.py
index f172e2fdc..687bc99d0 100644
--- a/nova/volume/driver.py
+++ b/nova/volume/driver.py
@@ -91,7 +91,8 @@ class VolumeDriver(object):
                                   % FLAGS.volume_group)
 
     def create_volume(self, volume):
-        """Creates a logical volume."""
+        """Creates a logical volume. Can optionally return a Dictionary of
+        changes to the volume object to be persisted."""
         if int(volume['size']) == 0:
             sizestr = '100M'
         else:
@@ -126,7 +127,8 @@ class VolumeDriver(object):
         raise NotImplementedError()
 
     def create_export(self, context, volume):
-        """Exports the volume."""
+        """Exports the volume. Can optionally return a Dictionary of changes
+        to the volume object to be persisted."""
         raise NotImplementedError()
 
     def remove_export(self, context, volume):
@@ -225,7 +227,14 @@ class FakeAOEDriver(AOEDriver):
 
 
 class ISCSIDriver(VolumeDriver):
-    """Executes commands relating to ISCSI volumes."""
+    """Executes commands relating to ISCSI volumes. We make use of model
+    provider properties as follows:
+    provider_location - if present, contains the iSCSI target information
+    in the same format as an ietadm discovery
+    i.e. '<target iqn>,<target portal> <target name>'
+    provider_auth - if present, contains a space-separated triple:
+    '<auth method> <auth username> <auth password>'.  CHAP is the only
+    auth_method in use at the moment."""
 
     def ensure_export(self, context, volume):
         """Synchronously recreates an export for a logical volume."""
@@ -313,7 +322,16 @@ class ISCSIDriver(VolumeDriver):
 
     def _get_iscsi_properties(self, volume):
         """Gets iscsi configuration, ideally from saved information in the
-        volume entity, but falling back to discovery if need be."""
+        volume entity, but falling back to discovery if need be. The
+        properties are:
+            target_discovered - boolean indicating whether discovery was used,
+            target_iqn - the IQN of the iSCSI target,
+            target_portal - the portal of the iSCSI target,
+            and auth_method, auth_username and auth_password
+                - the authentication details. Right now, either
+                auth_method is not present meaning no authentication, or
+                auth_method == 'CHAP' meaning use CHAP with the specified
+                credentials."""
 
         properties = {}
 
diff --git a/nova/volume/manager.py b/nova/volume/manager.py
index 7193ece14..3e8bc16b3 100644
--- a/nova/volume/manager.py
+++ b/nova/volume/manager.py
@@ -107,14 +107,14 @@ class VolumeManager(manager.Manager):
             vol_size = volume_ref['size']
             LOG.debug(_("volume %(vol_name)s: creating lv of"
                     " size %(vol_size)sG") % locals())
-            db_update = self.driver.create_volume(volume_ref)
-            if db_update:
-                self.db.volume_update(context, volume_ref['id'], db_update)
+            model_update = self.driver.create_volume(volume_ref)
+            if model_update:
+                self.db.volume_update(context, volume_ref['id'], model_update)
 
             LOG.debug(_("volume %s: creating export"), volume_ref['name'])
-            db_update = self.driver.create_export(context, volume_ref)
-            if db_update:
-                self.db.volume_update(context, volume_ref['id'], db_update)
+            model_update = self.driver.create_export(context, volume_ref)
+            if model_update:
+                self.db.volume_update(context, volume_ref['id'], model_update)
         except Exception:
             self.db.volume_update(context,
                                   volume_ref['id'], {'status': 'error'})
diff --git a/nova/volume/san.py b/nova/volume/san.py
index 911ad096f..09192bc9f 100644
--- a/nova/volume/san.py
+++ b/nova/volume/san.py
@@ -485,12 +485,12 @@ class HpSanISCSIDriver(SanISCSIDriver):
         cluster_vip = self._cliq_get_cluster_vip(cluster_name)
         iscsi_portal = cluster_vip + ":3260," + cluster_interface
 
-        db_update = {}
-        db_update['provider_location'] = ("%s %s" %
-                                          (iscsi_portal,
-                                           iscsi_iqn))
+        model_update = {}
+        model_update['provider_location'] = ("%s %s" %
+                                             (iscsi_portal,
+                                              iscsi_iqn))
 
-        return db_update
+        return model_update
 
     def delete_volume(self, volume):
         """Deletes a volume."""
@@ -517,7 +517,7 @@ class HpSanISCSIDriver(SanISCSIDriver):
 
         is_shared = 'permission.authGroup' in volume_info
 
-        db_update = {}
+        model_update = {}
 
         should_export = False
 
@@ -551,10 +551,10 @@ class HpSanISCSIDriver(SanISCSIDriver):
 
             self._cliq_run_xml("assignVolumeChap", cliq_args)
 
-            db_update['provider_auth'] = ("CHAP %s %s" %
-                                          (chap_username, chap_password))
+            model_update['provider_auth'] = ("CHAP %s %s" %
+                                             (chap_username, chap_password))
 
-        return db_update
+        return model_update
 
     def remove_export(self, context, volume):
         """Removes an export for a logical volume."""