From babf25ccdcafc05cf8d1b8e9c362d556bbd35dfb Mon Sep 17 00:00:00 2001
From: "Chris St. Pierre" <chris.a.st.pierre@gmail.com>
Date: Tue, 14 Jul 2015 07:44:03 -0500
Subject: [PATCH] [spec] Consistent resource names

Name resources consistently to improve cleanup and make Rally more
generic.

Change-Id: I2888b9874c695a6616576c22f3ea218901911b5d
---
 .../in-progress/consistent_resource_names.rst | 125 ++++++++++++++++++
 1 file changed, 125 insertions(+)
 create mode 100644 doc/specs/in-progress/consistent_resource_names.rst

diff --git a/doc/specs/in-progress/consistent_resource_names.rst b/doc/specs/in-progress/consistent_resource_names.rst
new file mode 100644
index 0000000000..097a1c6f14
--- /dev/null
+++ b/doc/specs/in-progress/consistent_resource_names.rst
@@ -0,0 +1,125 @@
+..
+ This work is licensed under a Creative Commons Attribution 3.0 Unported
+ License.
+
+ http://creativecommons.org/licenses/by/3.0/legalcode
+
+=========================
+Consistent Resource Names
+=========================
+
+To facilitate better cleanup of ephemeral resources created by Rally,
+random resource names need to be consistently used across all
+scenarios and all plugins. Additionally, to support Rally's use
+against systems other than OpenStack, plugins need greater control
+over both the format and the list of characters used in generating
+resource names.
+
+Problem description
+===================
+
+Currently we use a few different cleanup mechanisms, some of which
+(Keystone) use resource names, while most others use tenant
+membership. As a result, if Rally is interrupted before cleanup
+completes it may not be possible to know which resources were created
+by Rally (and thus should be cleaned up after the fact).
+
+Random names are generated from a fairly limited set of digits and
+ASCII letters. This should be configurable by each plugin, along with
+all other parts of the random name, in order to support benchmarking
+systems other than OpenStack, which may have different naming
+restrictions.
+
+Finally, each Rally task should include some consistent element in its
+resource names, distinct from other Rally tasks, to support multiple
+independent Rally runs and cleanup.
+
+Proposed change
+===============
+
+Random names will consist of three components:
+
+* A random element derived from the task ID that is the same for all
+  random names in the task;
+* A random element that should be different for all names in the task;
+  and
+* Any amount of formatting as determined by the plugin.
+
+The format of the random name will be given by a class variable,
+``RESOURCE_NAME_FORMAT``, on each scenario and context plugin. This
+variable is a ``mktemp(1)``-like string that describes the format; the
+default for scenario plugins will be::
+
+    RESOURCE_NAME_FORMAT = "s_rally_XXXXXXXX_XXXXXXXX"
+
+And for context plugins::
+
+    RESOURCE_NAME_FORMAT = "c_rally_XXXXXXXX_XXXXXXXX"
+
+The format must have two separate sets of at least three consecutive
+'X's. (That is, they must match:
+``^.*(?<!X)X{3,}(?!X).*(?<!X)X{3,}(?!X)``. This marks a slight
+departure from ``mktemp(1)``, which requires a single set of three or
+more 'X's at the end.) Three 'X's is likely dangerously few --
+offering only 1000 unique names per task -- but necessary in order to
+support systems with eight-character name limits.
+
+Another variable will control the allowed characters in the random
+portions. The default will be::
+
+    RESOURCE_NAME_ALLOWED_CHARACTERS = \
+        "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789"
+
+We will attempt to use the task ID, stripped of dashes, for the first
+random portion. If ``RESOURCE_NAME_ALLOWED_CHARACTERS`` does not allow
+all of the characters in the task ID (lowercase letters and digits),
+then we will use a random string generated from the allowed
+characters, with the pRNG seeded with the task ID.
+
+Alternatives
+------------
+
+The resources could be recorded as they are created to a database or
+file, and then that information used to perform cleanup later. This is
+insufficient for recovering from a massive Rally failure, though, so
+while it would be simpler in many ways, it does not meet the
+requirements for out-of-band cleanup. It also doesn't support the two
+other goals of this spec -- broader application support and multiple
+concurrent runs -- both of which would still require most of the work
+described herein. It would also not scale well for distributed load
+generation.
+
+The format and allowed characters could be configured in
+``rally.conf``, but this does not permit a single Rally installation
+to be used for multiple applications with divergent naming
+requirements, and it offloads responsibility for understanding naming
+limitations to the Rally user, not the plugin author.
+
+Implementation
+==============
+
+Assignee(s)
+-----------
+
+Primary assignee:
+  stpierre aka Chris St. Pierre
+
+Other contributors:
+  rvasilets aka Roman Vasilets
+  wtakase aka Wataru Takase
+
+Work Items
+----------
+
+* Overhaul `rally.common.utils.generate_random_name()` and
+  `rally.task.scenarios.base.Scenario._generate_random_name()`. Early
+  proof of concept that implements some of the points in this spec:
+  https://review.openstack.org/#/c/184888/
+
+* Find and fix resources that are created without
+  generate_random_name().
+
+Dependencies
+============
+
+None.