Cleanup some details about the accounts files

This commit cleans up some details in the accounts.yaml sample file
and the tempest configuration guide to provide missing details about
how to create and use an accounts file. Specifically it adds more
detailed comments to the sample file about each section, and in the
config guide it removes obsolete sections and adds some missing
details.

Change-Id: Ic11335fe1215ab0625ea2308ccc75d22a284c432
Closes-Bug: #1447851

doc/source/configuration.rst

@@ -91,8 +91,8 @@ isolation. This option will not have any effect when set and tempest is not
 configured to use tenant isolation.
 
 
-Locking Test Accounts
-"""""""""""""""""""""
+Locking Test Accounts (aka accounts.yaml or accounts file)
+""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 For a long time using tenant isolation was the only method available if you
 wanted to enable parallel execution of tempest tests. However this was
 insufficient for certain use cases because of the admin credentials requirement
@@ -103,11 +103,6 @@ test accounts each test class will reserve a set of credentials from the
 accounts.yaml before executing any of its tests so that each class is isolated
 like in tenant isolation.
 
-Currently, this mechanism has some limitations, mostly around networking. The
-locking test accounts provider will only work with a single flat network as
-the default for each tenant/project. If another network configuration is used
-in your cloud you might face unexpected failures.
-
 To enable and use locking test accounts you need do a few things:
 
  #. Create a accounts.yaml file which contains the set of pre-existing
@@ -120,9 +115,14 @@ To enable and use locking test accounts you need do a few things:
  #. Provide tempest with the location of you accounts.yaml file with the
     test_accounts_file option in the auth section
 
+It is worth pointing out that each set of credentials in the accounts.yaml
+should have a unique tenant. This is required to provide proper isolation
+to the tests using the credentials, and failure to do this will likely cause
+unexpected failures in some tests.
 
-Non-locking test accounts
-"""""""""""""""""""""""""
+
+Non-locking test accounts (aka credentials config options)
+""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
 When Tempest was refactored to allow for locking test accounts, the original
 non-tenant isolated case was converted to internally work similarly to the
 accounts.yaml file. This mechanism was then called the non-locking test accounts

etc/accounts.yaml.sample

@@ -1,4 +1,7 @@
 # The number of accounts required can be estimated as CONCURRENCY x 2
+# It is expected that each user provided here will be in a different tenant.
+# This is required to provide isolation between test for running in parallel
+#
 # Valid fields for credentials are defined in the descendants of
 # auth.Credentials - see KeystoneV[2|3]Credentials.CONF_ATTRIBUTES
 
@@ -28,6 +31,9 @@
      - 'reseller_admin'
      - 'operator'
 
+# Networks can be specified to tell tempest which network it should use when
+# creating servers with an account
+
 - username: 'admin_user_1'
   tenant_name: 'admin_tenant_1'
   password: 'test_password'