Merge lp:~ewanmellor/nova/xenapi into lp:~hudson-openstack/nova/trunk

[Ewan Mellor]

Added documentation for the nova.virt connection interface, a note about the need to chmod the objectstore script, and a reference for the XenAPI module.

Added documentation for the nova.virt connection interface, a note about the need to chmod the objectstore script, and a reference for the XenAPI module.

[Jay Pipes (jaypipes)]

Documentation++

review: Approve

[Soren Hansen (soren)]

Yay for more documentation.

[Soren Hansen (soren)]

review: Approve

[OpenStack Infra (hudson-openstack)]

The attempt to merge lp:~ewanmellor/nova/xenapi into lp:nova failed.Below is the output from the failed tests.

nova.tests.access_unittest
  AccessTestCase
    test_001_allow_all ... [OK]
    test_002_allow_none ... [OK]
    test_003_allow_project_manager ... [OK]
    test_004_allow_sys_and_net ... [OK]
    test_005_allow_sys_no_pm ... [OK]
nova.tests.api_unittest
  ApiEc2TestCase
    test_describe_instances ... [OK]
    test_get_all_key_pairs ... [OK]
nova.tests.auth_unittest
  AuthTestCase
    test_001_can_create_users ... [OK]
    test_002_can_get_user ... [OK]
    test_003_can_retreive_properties ... [OK]
    test_004_signature_is_valid ... [OK]
    test_005_can_get_credentials ... [OK]
    test_006_test_key_storage ... [OK]
    test_007_test_key_generation ... [OK]
    test_008_can_list_key_pairs ... [OK]
    test_009_can_delete_key_pair ... [OK]
    test_010_can_list_users ... [OK]
    test_101_can_add_user_role ... [OK]
    test_199_can_remove_user_role ... [OK]
    test_201_can_create_project ... [OK]
    test_202_user1_is_project_member ... [OK]
    test_203_user2_is_not_project_member ... [OK]
    test_204_user1_is_project_manager ... [OK]
    test_205_user2_is_not_project_manager ... [OK]
    test_206_can_add_user_to_project ... [OK]
    test_207_can_remove_user_from_project ... [OK]
    test_208_can_remove_add_user_with_role ... [OK]
    test_209_can_generate_x509 ... [OK]
    test_210_can_add_project_role ... [OK]
    test_211_can_list_project_roles ... [OK]
    test_212_can_remove_project_role ... [OK]
    test_214_can_retrieve_project_by_user ... [OK]
    test_299_can_delete_project ... [OK]
    test_999_can_delete_users ... [OK]
nova.tests.cloud_unittest
  CloudTestCase
    test_console_output ... [OK]
    test_instance_update_state ... [OK]
    test_run_instances ... ...

[Jay Pipes (jaypipes)]

grr...

non-deterministic testing--

setting to approve again...this is just docs, shouldn't be any test failures. :(

=== modified file 'doc/source/getting.started.rst'
--- doc/source/getting.started.rst	2010-07-25 01:06:22 +0000
+++ doc/source/getting.started.rst	2010-08-13 13:39:41 +0000
@@ -40,6 +40,7 @@
 
 * M2Crypto: python library interface for openssl
 * curl
+* XenAPI: Needed only for Xen Cloud Platform or XenServer support.  Available from http://wiki.xensource.com/xenwiki/XCP_SDK or http://community.citrix.com/cdn/xs/sdks.
 
 Vendored python libaries (don't require any installation)
 

=== modified file 'nova/virt/connection.py'
--- nova/virt/connection.py	2010-07-18 17:28:21 +0000
+++ nova/virt/connection.py	2010-08-13 13:39:41 +0000
@@ -27,6 +27,15 @@
 
 
 def get_connection(read_only=False):
+    """Returns an object representing the connection to a virtualization
+    platform.  This could be nova.virt.fake.FakeConnection in test mode,
+    a connection to KVM or QEMU via libvirt, or a connection to XenServer
+    or Xen Cloud Platform via XenAPI.
+
+    Any object returned here must conform to the interface documented by
+    FakeConnection.
+    """
+
     # TODO(termie): maybe lazy load after initial check for permissions
     # TODO(termie): check whether we can be disconnected
     t = FLAGS.connection_type

=== modified file 'nova/virt/fake.py'
--- nova/virt/fake.py	2010-07-18 17:15:12 +0000
+++ nova/virt/fake.py	2010-08-13 13:39:41 +0000
@@ -19,6 +19,7 @@
 
 """
 A fake (in-memory) hypervisor+api. Allows nova testing w/o a hypervisor.
+This module also documents the semantics of real hypervisor connections.
 """
 
 import logging
@@ -32,6 +33,38 @@
 
 
 class FakeConnection(object):
+    """
+    The interface to this class talks in terms of 'instances' (Amazon EC2 and
+    internal Nova terminology), by which we mean 'running virtual machine'
+    (XenAPI terminology) or domain (Xen or libvirt terminology).
+    
+    An instance has an ID, which is the identifier chosen by Nova to represent
+    the instance further up the stack.  This is unfortunately also called a
+    'name' elsewhere.  As far as this layer is concerned, 'instance ID' and
+    'instance name' are synonyms.
+    
+    Note that the instance ID or name is not human-readable or
+    customer-controlled -- it's an internal ID chosen by Nova.  At the
+    nova.virt layer, instances do not have human-readable names at all -- such
+    things are only known higher up the stack.
+
+    Most virtualization platforms will also have their own identity schemes,
+    to uniquely identify a VM or domain.  These IDs must stay internal to the
+    platform-specific layer, and never escape the connection interface.  The
+    platform-specific layer is responsible for keeping track of which instance
+    ID maps to which platform-specific ID, and vice versa.
+
+    In contrast, the list_disks and list_interfaces calls may return
+    platform-specific IDs.  These identify a specific virtual disk or specific
+    virtual network interface, and these IDs are opaque to the rest of Nova.
+
+    Some methods here take an instance of nova.compute.service.Instance.  This
+    is the datastructure used by nova.compute to store details regarding an
+    instance, and pass them into this layer.  This layer is responsible for
+    translating that generic datastructure into terms that are specific to the
+    virtualization platform.
+    """
+
     def __init__(self):
         self.instances = {}
 
@@ -42,20 +75,59 @@
         return cls._instance
 
     def list_instances(self):
+        """
+        Return the names of all the instances known to the virtualization
+        layer, as a list.
+        """
         return self.instances.keys()
 
     def spawn(self, instance):
+        """
+        Create a new instance/VM/domain on the virtualization platform.
+
+        The given parameter is an instance of nova.compute.service.Instance.
+        This function should use the data there to guide the creation of
+        the new instance.
+
+        Once this function successfully completes, the instance should be
+        running (power_state.RUNNING).
+
+        If this function fails, any partial instance should be completely
+        cleaned up, and the virtualization platform should be in the state
+        that it was before this call began.
+        """
+        
         fake_instance = FakeInstance()
         self.instances[instance.name] = fake_instance
         fake_instance._state = power_state.RUNNING
 
     def reboot(self, instance):
+        """
+        Reboot the specified instance.
+
+        The given parameter is an instance of nova.compute.service.Instance,
+        and so the instance is being specified as instance.name.
+        """
         pass
-       
+
     def destroy(self, instance):
+        """
+        Destroy (shutdown and delete) the specified instance.
+
+        The given parameter is an instance of nova.compute.service.Instance,
+        and so the instance is being specified as instance.name.
+        """
         del self.instances[instance.name]
 
     def get_info(self, instance_id):
+        """
+        Get a block of information about the given instance.  This is returned
+        as a dictionary containing 'state': The power_state of the instance,
+        'max_mem': The maximum memory for the instance, in KiB, 'mem': The
+        current memory the instance has, in KiB, 'num_cpu': The current number
+        of virtual CPUs the instance has, 'cpu_time': The total CPU time used
+        by the instance, in nanoseconds.
+        """
         i = self.instances[instance_id]
         return {'state': i._state,
                 'max_mem': 0,
@@ -64,15 +136,70 @@
                 'cpu_time': 0}
 
     def list_disks(self, instance_id):
+        """
+        Return the IDs of all the virtual disks attached to the specified
+        instance, as a list.  These IDs are opaque to the caller (they are
+        only useful for giving back to this layer as a parameter to
+        disk_stats).  These IDs only need to be unique for a given instance.
+        
+        Note that this function takes an instance ID, not a
+        compute.service.Instance, so that it can be called by compute.monitor.
+        """
         return ['A_DISK']
 
     def list_interfaces(self, instance_id):
+        """
+        Return the IDs of all the virtual network interfaces attached to the
+        specified instance, as a list.  These IDs are opaque to the caller
+        (they are only useful for giving back to this layer as a parameter to
+        interface_stats).  These IDs only need to be unique for a given
+        instance.
+        
+        Note that this function takes an instance ID, not a
+        compute.service.Instance, so that it can be called by compute.monitor.
+        """
         return ['A_VIF']
 
     def block_stats(self, instance_id, disk_id):
+        """
+        Return performance counters associated with the given disk_id on the
+        given instance_id.  These are returned as [rd_req, rd_bytes, wr_req,
+        wr_bytes, errs], where rd indicates read, wr indicates write, req is
+        the total number of I/O requests made, bytes is the total number of
+        bytes transferred, and errs is the number of requests held up due to a
+        full pipeline.
+
+        All counters are long integers.
+
+        This method is optional.  On some platforms (e.g. XenAPI) performance
+        statistics can be retrieved directly in aggregate form, without Nova
+        having to do the aggregation.  On those platforms, this method is
+        unused.
+        
+        Note that this function takes an instance ID, not a
+        compute.service.Instance, so that it can be called by compute.monitor.
+        """
         return [0L, 0L, 0L, 0L, null]
 
     def interface_stats(self, instance_id, iface_id):
+        """
+        Return performance counters associated with the given iface_id on the
+        given instance_id.  These are returned as [rx_bytes, rx_packets,
+        rx_errs, rx_drop, tx_bytes, tx_packets, tx_errs, tx_drop], where rx
+        indicates receive, tx indicates transmit, bytes and packets indicate
+        the total number of bytes or packets transferred, and errs and dropped
+        is the total number of packets failed / dropped.
+
+        All counters are long integers.
+
+        This method is optional.  On some platforms (e.g. XenAPI) performance
+        statistics can be retrieved directly in aggregate form, without Nova
+        having to do the aggregation.  On those platforms, this method is
+        unused.
+        
+        Note that this function takes an instance ID, not a
+        compute.service.Instance, so that it can be called by compute.monitor.
+        """
         return [0L, 0L, 0L, 0L, 0L, 0L, 0L, 0L]
 
 

=== modified file 'nova/virt/libvirt_conn.py'
--- nova/virt/libvirt_conn.py	2010-08-10 15:37:07 +0000
+++ nova/virt/libvirt_conn.py	2010-08-13 13:39:41 +0000
@@ -261,12 +261,6 @@
 
 
     def get_disks(self, instance_id):
-        """
-        Note that this function takes an instance ID, not an Instance, so
-        that it can be called by monitor.
-
-        Returns a list of all block devices for this domain.
-        """
         domain = self._conn.lookupByName(instance_id)
         # TODO(devcamcar): Replace libxml2 with etree.
         xml = domain.XMLDesc(0)
@@ -304,12 +298,6 @@
 
 
     def get_interfaces(self, instance_id):
-        """
-        Note that this function takes an instance ID, not an Instance, so
-        that it can be called by monitor.
-
-        Returns a list of all network interfaces for this instance.
-        """
         domain = self._conn.lookupByName(instance_id)
         # TODO(devcamcar): Replace libxml2 with etree.
         xml = domain.XMLDesc(0)
@@ -347,18 +335,10 @@
 
 
     def block_stats(self, instance_id, disk):
-        """
-        Note that this function takes an instance ID, not an Instance, so
-        that it can be called by monitor.
-        """
         domain = self._conn.lookupByName(instance_id)
         return domain.blockStats(disk)
 
 
     def interface_stats(self, instance_id, interface):
-        """
-        Note that this function takes an instance ID, not an Instance, so
-        that it can be called by monitor.
-        """
         domain = self._conn.lookupByName(instance_id)
         return domain.interfaceStats(interface)

=== modified file 'plugins/xenapi/README'
--- plugins/xenapi/README	2010-08-02 23:52:06 +0000
+++ plugins/xenapi/README	2010-08-13 13:39:41 +0000
@@ -1,2 +1,6 @@
 This directory contains files that are required for the XenAPI support.  They
 should be installed in the XenServer / Xen Cloud Platform domain 0.
+
+Also, you need to
+
+chmod u+x /etc/xapi.d/plugins/objectstore