Intermediate improvement of Tempest quickstart
Change-Id: I55e511b9cbfa2b1a4e5e28479916a0e825d3b7c1
diff --git a/README.rst b/README.rst
index 001404b..11ed58f 100644
--- a/README.rst
+++ b/README.rst
@@ -10,7 +10,7 @@
To run Tempest, you first need to create a configuration file that
will tell Tempest where to find the various OpenStack services and
-other testing behaviour switches.
+other testing behavior switches.
The easiest way to create a configuration file is to copy the sample
one in the ``etc/`` directory ::
@@ -19,7 +19,9 @@
$> cp etc/tempest.conf.sample etc/tempest.conf
After that, open up the ``etc/tempest.conf`` file and edit the
-variables to fit your test environment.
+configuration variables to match valid data in your environment.
+This includes your Keystone endpoint, a valid user and credentials,
+and reference data to be used in testing.
.. note::
@@ -31,7 +33,40 @@
devstack uploaded and set the image_ref value in the [environment]
section in the tempest.conf to that image UUID.
-After setting up your configuration file, you can execute the set of
-Tempest tests by using ``nosetests`` ::
+ In addition, the ``tempest/tools/conf_from_devstack`` script can also be
+ used to generate a tempest.conf based on your localrc file.
+
+Tempest is not tied to any single test runner, but Nose been the most commonly
+used tool. After setting up your configuration file, you can execute
+the set of Tempest tests by using ``nosetests`` ::
$> nosetests tempest
+
+Configuration
+-------------
+
+At present, there are three sections to be configured: nova, environment,
+and image. The nova section includes information about your Keystone endpoint,
+as well as valid credentials for a user. It also contains logical timeouts
+for certain actions. The environment section contains reference data to be
+used when testing the Compute portion of OpenStack, as well as feature flags
+for tests that may or may not work based on your hypervisor or current
+environment. Lastly, the image section contains credentials and endpoints for
+the Glance image service.
+
+Common Issues
+-------------
+
+Tempest was originally designed to primarily run against a full OpenStack
+deployment. Due to that focus, some issues may occur when running Tempest
+against devstack.
+
+Running Tempest, especially in parallel, against a devstack instance may
+cause requests to be rate limited, which will cause unexpected failures.
+Given the number of requests Tempest can make against a cluster, rate limiting
+should be disabled for all test accounts.
+
+Additionally, devstack only provides a single image which Nova can use.
+For the moment, the best solution is to provide the same image uuid for
+both image_ref and image_ref_alt. Tempest will skip tests as needed if it
+detects that both images are the same.