Initial draft of compute driver spec

Address comments by TrevorV, and fix tabification.
Try to make doc8 happy.

Change-Id: Ida4aef02578cea7e2e76c9106c94d4ef633c06d6

specs/version0.5/amphora-manager-interface.rst

@@ -0,0 +1,248 @@
+..
+ This work is licensed under a Creative Commons Attribution 3.0 Unported
+ License.
+
+ http://creativecommons.org/licenses/by/3.0/legalcode
+
+==========================================
+Compute Driver Interface
+==========================================
+https://blueprints.launchpad.net/octavia/+spec/compute-driver-interface
+
+This blueprint describes how a driver will interface with Nova to
+manage the creation and deletion of amphora instances.  It will
+describe the base class and other classes required to create, delete,
+manage the execution state, and query the status of amphorae.
+
+Problem description
+===================
+The controller needs to be able to create, delete, and monitor the
+status of amphora instances.  The amphorae may be virtual machines,
+containers, bare-metal servers, or dedicated hardware load balancers.
+This interface should hide the implementation details of the amphorae
+from the caller to the maximum extent possible.
+
+This interface will provide means to specify:
+ - type (VM, Container, bare metal)
+ - flavor (provides means to specify memory and storage capacity)
+ - what else?
+
+Proposed change
+===============
+Establish an abstract base class to model the desired functionality:
+
+.. code:: python
+
+    class AmphoraComputeDriver(object):
+
+        def get_logger(self):
+
+            """ return the logger to use - this is a way to inject a
+            custom logger for testing, etc
+
+            :returns: the logger
+            """
+             raise NotImplementedError
+
+        def build(self, amphora_type = VM, amphora_flavor = None,
+                  image_id = None, keys = None, sec_groups = None,
+                  network_ids = None ):
+
+            """ build a new amphora.
+
+            :param amphora_type: The type of amphora to create.  For
+            version 0.5, only VM is supported.  In the future this
+            may support Container, BareMetal, and HWLoadBalancer.
+            :param amphora_flavor: Optionally specify a flavor.  The
+            interpretation of this parameter will depend upon the
+            amphora type and may not be applicable to all types.
+            :param image_id: ID of the base image for a VM amphora
+            :param keys: Optionally specify a list of ssh public keys
+            :param sec_groups: Optionally specify list of security
+            groups
+            :param network_ids: A list of network_ids to attach to
+            the amphora
+
+            :returns: The id of the new instance.
+
+            """
+
+            raise NotImplementedError
+
+        def delete(self, amphora_id):
+            """  delete the specified amphora
+            """
+
+            raise NotImplementedError
+
+        def status(self, amphora_id):
+
+            """ Check whether the specified amphora is up
+
+            :param amphora_id: the ID of the desired amphora
+            :returns: the nova response from the amphora
+            """
+            raise NotImplementedError
+
+        def get_amphora(self, amphora_name = None, amphora_id = None):
+            """ Try to find a amphora given its name or id
+
+            :param amphora_name: the name of the desired amphora
+            :param amphora_id: the id of the desired amphora
+            :returns: the amphora object
+            """
+            raise NotImplementedError
+
+        def start(self, amphora_id):
+            """ start the specified instance
+
+            :param amphora_id: the id of the instance to start
+            """
+
+            raise NotImplementedError
+
+        def suspend(self, amphora_id):
+            """ suspend the specified instance
+
+            :param amphora_id: the id of the instance to suspend
+            """
+
+            raise NotImplementedError
+
+        def resume(self, amphora_id):
+            """ resume the specified instance
+
+            :param amphora_id: the id of the instance to suspend
+            """
+
+            raise NotImplementedError
+
+        def stop(self, amphora_id):
+            """ stop the specified instance
+
+            :param amphora_id: the id of the instance to stop
+            """
+
+            raise NotImplementedError
+
+        def backup(self, amphora_id):
+            """ create a backup of the specified instance.  The
+            format of the backup is implementation-defined
+
+            :param amphora_id: the id of the instance to snapshot
+            """
+
+            raise NotImplementedError
+
+Exception Model
+---------------
+
+The driver is expected to raise the following well defined exceptions:
+
+* NotImplementedError - this functionality is not implemented/not supported
+* AmphoraComputeError - a super class for all other exceptions and the catch
+    all if no specific exception can be found
+
+    * AmphoraBuildError - An amphora of the specified type could
+      not be built
+    * DeleteFailed - this amphora couldn't be deleted
+
+* InstanceNotFoundError - an instance matching the desired criteria
+  could not be found
+* NotSuspendedError - resume() attempted on an instance that was not suspended
+
+
+
+Things a good driver should do:
+-------------------------------
+
+ * Non blocking operations - If an operation will take a long time to execute,
+   perform it asynchronously.  The definition of "a long time" is open to
+   interpretation, but a common UX guideline is 200 ms
+ * We might employ a circuit breaker to insulate driver
+   problems from controller problems [1]
+ * Use appropriate logging
+ * Use the preferred threading model
+
+This will be demonstrated in the Noop-driver code.
+
+
+Alternatives
+------------
+
+
+Data model impact
+-----------------
+None
+
+
+REST API impact
+---------------
+None
+
+
+Security impact
+---------------
+None
+
+
+Notifications impact
+--------------------
+None - since initial version
+
+
+Other end user impact
+---------------------
+None
+
+
+Performance Impact
+------------------
+Minimal
+
+
+Other deployer impact
+---------------------
+Deployers need to make sure to bundle the compatible
+versions of amphora, driver, controller --
+
+
+Developer impact
+----------------
+Need to write towards this clean interface.
+
+
+Implementation
+==============
+
+Assignee(s)
+-----------
+Al Miller
+
+Work Items
+----------
+* Write abstract interface
+* Write Noop driver
+* Write tests
+
+
+Dependencies
+============
+None
+
+
+Testing
+=======
+* Unit tests with tox and Noop-Driver
+* tempest tests with Noop-Driver
+
+
+Documentation Impact
+====================
+None - this is an internal interface and need not be externally
+documented.
+
+
+References
+==========
+[1] http://martinfowler.com/bliki/CircuitBreaker.html