diff --git a/specs/version0.5/housekeeping-manager-interface.rst b/specs/version0.5/housekeeping-manager-interface.rst new file mode 100755 index 0000000000..97d04588cf --- /dev/null +++ b/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 + +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 +==========