Remove shocco docs and other cleanups
This is a fairly opinionated change to do some spring cleaning on the
documentation.
The current output of shocco as rendered at [1] is completely broken.
I can not see that it is worth us maintaining this. Honestly, the
github page does a better job at showing the scripts with a bit of
formatting. The "changes" page is similarly useless today. cgit or
github show allow browsing of changes in the repo better. Both are
removed along with support scripts.
When you currently hit the first page, it gives no clue as to what
DevStack actually is. Add a paragraph explaining that, and link to
the cgit for easy source browsing.
stackrc.rst is not necessary; the stuff about database backends is
already discussed in configuration.rst; move the things about service
repos into a section of configuration.rst.
The discussion in openrc.rst is moved into the configuration.rst file.
localrc.conf.rst was just a paragraph pointing back to
configuration.rst; this is removed.
The variables described in exercise.rst are moved into a separate
section of configuration.rst
[1] http://docs.openstack.org/developer/devstack/#scripts
Change-Id: Ie7f4b265368f1d10a8908d75e11d625b2cc39e7c
diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst
index f3e4896..3c77f4d 100644
--- a/doc/source/configuration.rst
+++ b/doc/source/configuration.rst
@@ -62,8 +62,7 @@
A specific meta-section ``local|localrc`` is used to provide a default
``localrc`` file (actually ``.localrc.auto``). This allows all custom
settings for DevStack to be contained in a single file. If ``localrc``
-exists it will be used instead to preserve backward-compatibility. More
-details on the :doc:`contents of local.conf <local.conf>` are available.
+exists it will be used instead to preserve backward-compatibility.
::
@@ -84,6 +83,76 @@
fragment and MUST conform to the shell requirements, specifically no
whitespace around ``=`` (equals).
+openrc
+======
+
+``openrc`` configures login credentials suitable for use with the
+OpenStack command-line tools. ``openrc`` sources ``stackrc`` at the
+beginning (which in turn sources the ``localrc`` section of
+``local.conf``) in order to pick up ``HOST_IP`` and/or ``SERVICE_HOST``
+to use in the endpoints. The values shown below are the default values.
+
+OS\_PROJECT\_NAME (OS\_TENANT\_NAME)
+ Keystone has
+ standardized the term *project* as the entity that owns resources. In
+ some places references still exist to the previous term
+ *tenant* for this use. Also, *project\_name* is preferred to
+ *project\_id*. OS\_TENANT\_NAME remains supported for compatibility
+ with older tools.
+
+ ::
+
+ OS_PROJECT_NAME=demo
+
+OS\_USERNAME
+ In addition to the owning entity (project), OpenStack calls the entity
+ performing the action *user*.
+
+ ::
+
+ OS_USERNAME=demo
+
+OS\_PASSWORD
+ Keystone's default authentication requires a password be provided.
+ The usual cautions about putting passwords in environment variables
+ apply, for most DevStack uses this may be an acceptable tradeoff.
+
+ ::
+
+ OS_PASSWORD=secret
+
+HOST\_IP, SERVICE\_HOST
+ Set API endpoint host using ``HOST_IP``. ``SERVICE_HOST`` may also
+ be used to specify the endpoint, which is convenient for some
+ ``local.conf`` configurations. Typically, ``HOST_IP`` is set in the
+ ``localrc`` section.
+
+ ::
+
+ HOST_IP=127.0.0.1
+ SERVICE_HOST=$HOST_IP
+
+OS\_AUTH\_URL
+ Authenticating against an OpenStack cloud using Keystone returns a
+ *Token* and *Service Catalog*. The catalog contains the endpoints
+ for all services the user/tenant has access to - including Nova,
+ Glance, Keystone and Swift.
+
+ ::
+
+ OS_AUTH_URL=http://$SERVICE_HOST:5000/v2.0
+
+KEYSTONECLIENT\_DEBUG, NOVACLIENT\_DEBUG
+ Set command-line client log level to ``DEBUG``. These are commented
+ out by default.
+
+ ::
+
+ # export KEYSTONECLIENT_DEBUG=1
+ # export NOVACLIENT_DEBUG=1
+
+
+
.. _minimal-configuration:
Minimal Configuration
@@ -145,6 +214,37 @@
.. contents::
:local:
+Service Repos
+-------------
+
+The Git repositories used to check out the source for each service are
+controlled by a pair of variables set for each service. ``*_REPO``
+points to the repository and ``*_BRANCH`` selects which branch to
+check out. These may be overridden in ``local.conf`` to pull source
+from a different repo for testing, such as a Gerrit branch
+proposal. ``GIT_BASE`` points to the primary repository server.
+
+ ::
+
+ NOVA_REPO=$GIT_BASE/openstack/nova.git
+ NOVA_BRANCH=master
+
+To pull a branch directly from Gerrit, get the repo and branch from
+the Gerrit review page:
+
+ ::
+
+ git fetch https://review.openstack.org/p/openstack/nova refs/changes/50/5050/1 && git checkout FETCH_HEAD
+
+ The repo is the stanza following ``fetch`` and the branch is the
+ stanza following that:
+
+ ::
+
+ NOVA_REPO=https://review.openstack.org/p/openstack/nova
+ NOVA_BRANCH=refs/changes/50/5050/1
+
+
Installation Directory
----------------------
@@ -640,3 +740,40 @@
::
ENABLE_IDENTITY_V2=False
+
+Exercises
+~~~~~~~~~
+
+``exerciserc`` is used to configure settings for the exercise scripts.
+The values shown below are the default values. These can all be
+overridden by setting them in the ``localrc`` section.
+
+* Max time to wait while vm goes from build to active state
+
+ ::
+
+ ACTIVE_TIMEOUT==30
+
+* Max time to wait for proper IP association and dis-association.
+
+ ::
+
+ ASSOCIATE_TIMEOUT=15
+
+* Max time till the vm is bootable
+
+ ::
+
+ BOOT_TIMEOUT=30
+
+* Max time from run instance command until it is running
+
+ ::
+
+ RUNNING_TIMEOUT=$(($BOOT_TIMEOUT + $ACTIVE_TIMEOUT))
+
+* Max time to wait for a vm to terminate
+
+ ::
+
+ TERMINATE_TIMEOUT=30