Merge "Interface specification for housekeeping manager"

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
+==========