[Spec] Refactoring Rally Cleanup, Part II

This adds technical details for the existing "Refactoring Rally
Cleanup" spec.

Change-Id: I7a761eee2d245d30ab7f41fee0eb3d1f825bf0b1
Implements: blueprint cleanup-refactoring

doc/specs/in-progress/cleanup_refactoring.rst

@@ -56,6 +56,75 @@ https://review.openstack.org/201545
 * Resources created by contexts are deleted when the environment is
   not necessary by the context class `cleanup()`.
 
+Specifically, there are three cases we need to be able to handle:
+
+* Cleanup of all resources created by a single subtask run;
+* Cleanup of all resources created by contexts; and
+* Cleanup of all resources, possibly (or probably) out-of-band.
+
+In each case, this can be handled by matching resource names with a
+subset of plugins. For instance, to clean up scenario resources, we
+will do something like:
+
+.. code-block:: python
+
+    scenarios = [cls for cls in discover.itersubclasses(scenario.Scenario)
+                 if issubclass(cls, utils.RandomNameGeneratorMixin)]
+    for resource in resource_manager.list():
+        manager = resource_manager_cls(raw_resource=resource, ...)
+        if utils.name_matches_object(resource_manager.name, scenarios,
+                                     task_id=task_id):
+            manager.delete()
+
+This is pseudocode that hides much of the complexity of our current
+cleanup process, but it demonstrates the basic idea:
+
+#. Generate a list of subclasses to delete resources for. In this case
+   we use ``rally.task.scenario.Scenario``, but for context cleanup it
+   would be ``rally.task.context.Context``, and for global cleanup it
+   would be ``rally.common.plugin.plugin.Plugin``. In all three cases
+   we would only delete resources for plugins that have
+   ``rally.common.utils.RandomNameGeneratorMixin`` as a superclass;
+   this lets us easily perform global cleanup without needing to worry
+   about which plugin subclasses might implement
+   ``RandomNameGeneratorMixin``.
+#. For each resource manager, list resources.
+#. If the resource name matches the list of possible patterns gleaned
+   from the set of classes, delete it.
+
+A fair bit of functionality will need to be added to support this:
+
+* ``rally.plugins.openstack.context.cleanup.manager.cleanup()`` will
+  need to accept a keyword argument specifying the type of
+  cleanup. This should be a superclass that will be used to discover
+  the subclasses to delete resources for. It will be passed to
+  ``rally.plugins.openstack.context.cleanup.manager.SeekAndDestroy``,
+  which will also need to accept the argument and generate the list of
+  classes.
+* ``rally.plugins.openstack.context.cleanup.base``,
+  ``rally.plugins.openstack.context.cleanup.manager`` and
+  ``rally.plugins.openstack.context.cleanup.resources`` need to be
+  moved out of the context space, since they will be used not only by
+  the cleanup context to do scenario cleanup, but also to do
+  out-of-band cleanup of all resources.
+* A new function, ``name()``, will need to be added to
+  ``rally.plugins.openstack.context.cleanup.base.ResourceManager``
+  so that we can determine the name of a resource in order to match it.
+* A ``task_id`` keyword argument will be added to
+  ``name_matches_object`` and ``name_matches_pattern`` in order to
+  ensure that we only match names from the currently-running
+  task. This will need to be passed along starting with
+  ``rally.plugins.openstack.context.cleanup.manager.cleanup()``, and
+  added as a keyword argument to every intermediate function.
+
+Additionally, a new top-level command will be added::
+
+    rally cleanup [--deployment <deployment>] [--task <uuid>]
+
+This will invoke cleanup of all resources, either for a specific task,
+or for any rally-created resource at all, regardless of task ID. This
+will not be ``rally task cleanup`` because it can be run with or
+without a task.
 
 Alternatives
 ------------
@@ -92,22 +161,23 @@ Other contributors:
 Work Items
 ----------
 
-* Consider how to deal resources which don't be named by
-  generate_random_name(). For example, Neutron ports which are created as
-  side-effect of other resources (routers, networks, servers) don't have
-  resource names. In this case, ports always have an "owner" so cleanup should
-  check port's owner's name. And what about floating IPs?
-  (Needed by use cases 1, 2, 3, 4, 5)
-
-* Add name prefix filter for deleting resource which has specified prefix.
-  (Needed by use cases 1, 2, 3, 4, 5)
-
-* Add ability to specify the filter to be used for handling more than
-  one prefix.
-  (Needed by use cases 3, 5)
-
-* Support negative filter which deletes unmatched resources.
-  (Needed by use cases 3, 5)
+#. Consider how to deal resources which don't be named by
+   generate_random_name(). For example, Neutron ports which are
+   created as side-effect of other resources (routers, networks,
+   servers) don't have resource names. In this case, ports always have
+   an "owner" so cleanup should check port's owner's name. And what
+   about floating IPs?  (Needed by use cases 1, 2, 3, 4, 5)
+#. Modify ``name_matches_{object,pattern}`` to accept a task ID.
+#. Add ``name()`` functions to all ``ResourceManager`` subclasses.
+#. Move
+   ``rally.plugins.openstack.context.cleanup.manager.{base,manager,resources}``
+   to ``rally.plugins.openstack.cleanup``.
+#. Modify ``rally.plugins.openstack.cleanup.manager.cleanup()`` to
+   accept a task ID and a superclass, pass them along to
+   ``SeekAndDestroy``, and generally Do The Right Thing with them.
+#. Create the ``rally cleanup`` command.
+#. Support negative filter which deletes unmatched resources. (Needed
+   by use cases 3, 5)
 
 
 Dependencies