Interface specification for housekeeping manager

This specification defines the housekeeping manager and related classes.
It will describe how pools of resources will be managed so that they
contain appropriate numbers of elements.

Change-Id: I7b17b92b2bca1b0aa696e39d955df49e7cda6f0d

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

@@ -0,0 +1,201 @@
+..
+ This work is licensed under a Creative Commons Attribution 3.0 Unported
+ License.
+
+ http://creativecommons.org/licenses/by/3.0/legalcode
+
+==========================================
+Housekeeping Manager Specification
+==========================================
+https://blueprints.launchpad.net/octavia/+spec/housekeeping-manager
+
+Problem description
+===================
+
+The Housekeeping Manager will manage the spare amphora pool and the
+teardown of amphorae that are no longer needed. On a configurable
+interval the Housekeeping Manager will check the Octavia database to
+identify the required cleanup and maintenance actions required. The
+amphora-lifecycle-management specification details the Create and
+Deactivate amphora sequences the Housekeeping Manager will follow.
+
+
+Proposed change
+===============
+The housekeeping manager will run as a daemon process which will
+perform the following actions:
+
+* Read the following from the configuration file
+
+  * housekeeping_interval: The time (in seconds) that the
+    housekeeping manager will sleep before running its checks
+    again.
+  * spare_amphora_pool_size: The desired number of spare amphorae.
+  * maximum_deploying_amphora_count: The maximum number of amphorae
+    that may be deployed simultaneously.
+  * maximum_preserved_amphora_count: How many deactivated amphorae to
+    preserve.  0 means delete, 1 or greater means keep up to that many
+    amphorae for future diagnostics.  Only amphorae in the ERROR and
+    PRESERVE states are eligible to be preserved.  TODO: Right now
+    there is no PRESERVE state, for this to work we would need to
+    define one in the amphora spec.
+  * preservation_scheme
+
+    * "keep": keep all preserved amphorae
+    * "cycle": maintain a queue of preserved amphorae, deleting the
+      oldest one when a new amphora is preserved.
+
+  * preservation_method: Preservation must take into account the
+    possibility that amphorae instantiated in the future may reuse MAC
+    addresses.
+
+    * "unplug": Disconnect the virtual NICs from the amphora
+    * "snapshot":  Take a snapshot of the amphora, then stop it
+
+* Get the spare pool size
+
+  * Log the spare pool size
+  * If the spare pool size is less than the spare pool target
+    capacity, initiate creation of appropriate number of amphorae.
+
+* Obtain the list of deactivated amphorae and schedule their removal.
+  If preservation_count > 0, and there are fewer than that many
+  amphorae in the preserved pool, preserve the amphora.  After the
+  preserved pool size reaches preservation_count, use
+  preservation_scheme to determine whether to keep newly failed
+  amphorae.
+
+* Sleep for the time specified by housekeeping_interval.
+
+* Return to the top
+
+Establish a base class to model the desired functionality:
+
+.. code:: python
+
+
+    class HousekeepingManager(object):
+
+    """ Class to manage the spare amphora pool.  This class should do
+    very little actual work, its main job is to monitor the spare pool
+    and schedule creation of new amphrae and removal of used amphrae.
+    By default, used amphorae will be deleted, but they may optionally
+    be preserved for future analysis.
+    """
+
+        def get_spare_amphora_size(self):
+            """ Return the target capacity of the spare pool """
+            raise NotImplementedError
+
+        def get_ready_spare_amphora_count(self):
+            """ Return the number of available amphorae in the spare pool
+            """
+            raise NotImplementedError
+
+        def create_amphora(self, num_to_create = 1):
+            """ Schedule the creation of the specified number of amphorae
+            to be added to the spare pool."""
+            raise NotImplementedError
+
+        def remove_amphora(self, amphora_ids):
+            """ Schedule the removal of the amphorae specified by
+            amphora_ids."""
+            raise NotImplementedError
+
+Exception Model
+---------------
+
+The manager is expected to raise or pass along the following
+well-defined exceptions:
+
+* NotImplementedError - this functionality is not implemented/not supported
+* AmphoraDriverError - a super class for all other exceptions and the catch
+    all if no specific exception can be found
+    * NotFoundError - this amphora couldn't be found/ was deleted by nova
+    * UnauthorizedException - the driver can't access the amphora
+    * UnavailableException - the amphora is temporary unavailable
+    * DeleteFailed - this load balancer couldn't be deleted
+
+Alternatives
+------------
+
+Data model impact
+-----------------
+
+Requires the addition of the housekeeping_interval, spare_pool_size,
+spare_amphora_pool_size, maximum_preserved_amphora_count,
+preservation_scheme, and preservation_method to the config.
+
+
+REST API impact
+---------------
+
+None.
+
+Security impact
+---------------
+
+Must follow standard practices for database access.
+
+Notifications impact
+--------------------
+
+Other deployer impact
+---------------------
+
+Other end user impact
+---------------------
+
+There should be no end-user-visible impact.
+
+Performance Impact
+------------------
+
+The housekeeping_interval and spare_pool_size parameters will be
+adjustible by the operator in order to balance resource usage against
+performance.
+
+
+Developer impact
+----------------
+
+Developers of other modules need to be aware that amphorae may be
+created, deleted, or saved for diagonsis by this daemon.
+
+
+Implementation
+==============
+
+Assignee(s)
+-----------
+Al Miller <ajmiller>
+
+Work Items
+----------
+* Write abstract interface
+* Write Noop driver
+* Write tests
+
+
+Dependencies
+============
+Amphora driver
+Config manager
+
+
+
+Testing
+=======
+* Unit tests with tox and Noop-Driver
+* tempest tests with Noop-Driver
+
+
+Documentation Impact
+====================
+None - we won't document the interface for 0.5. If that changes
+we need to write an interface documentation so
+3rd party drivers know what we expect.
+
+
+References
+==========