diff --git a/doc/source/changes.rst b/doc/source/changes.rst deleted file mode 100644 index 19fce0fd52..0000000000 --- a/doc/source/changes.rst +++ /dev/null @@ -1,12 +0,0 @@ -======= -Changes -======= - -Recent Changes What's been happening? -===================================== - -These are the commits to DevStack for the last six months. For the -complete list see `the DevStack project in -Gerrit `__. - -%GIT_LOG% diff --git a/doc/source/configuration.rst b/doc/source/configuration.rst index f3e4896296..3c77f4d793 100644 --- a/doc/source/configuration.rst +++ b/doc/source/configuration.rst @@ -62,8 +62,7 @@ appear in the file will be used. 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 ` are available. +exists it will be used instead to preserve backward-compatibility. :: @@ -84,6 +83,76 @@ Also note that the ``localrc`` section is sourced as a shell script 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 @@ Configuration Notes .. 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 @@ use the v3 API. It is possible to setup keystone without v2 API, by doing: :: 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 diff --git a/doc/source/exerciserc.rst b/doc/source/exerciserc.rst deleted file mode 100644 index dacae2ecf2..0000000000 --- a/doc/source/exerciserc.rst +++ /dev/null @@ -1,42 +0,0 @@ -============================== -exerciserc - Exercise Settings -============================== - -``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. - -ACTIVE\_TIMEOUT - Max time to wait while vm goes from build to active state - - :: - - ACTIVE_TIMEOUT==30 - -ASSOCIATE\_TIMEOUT - Max time to wait for proper IP association and dis-association. - - :: - - ASSOCIATE_TIMEOUT=15 - -BOOT\_TIMEOUT - Max time till the vm is bootable - - :: - - BOOT_TIMEOUT=30 - -RUNNING\_TIMEOUT - Max time from run instance command until it is running - - :: - - RUNNING_TIMEOUT=$(($BOOT_TIMEOUT + $ACTIVE_TIMEOUT)) - -TERMINATE\_TIMEOUT - Max time to wait for a vm to terminate - - :: - - TERMINATE_TIMEOUT=30 diff --git a/doc/source/index.rst b/doc/source/index.rst index c79b2ce0c7..c4a7c59fe5 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -1,8 +1,16 @@ -DevStack - an OpenStack Community Production -============================================ +DevStack +======== .. image:: assets/images/logo-blue.png +DevStack is a series of extensible scripts used to quickly bring up a +complete OpenStack environment. It is used interactively as a +development environment and as the basis for much of the OpenStack +project's functional testing. + +The source is available at +``__. + .. toctree:: :glob: :maxdepth: 1 @@ -12,7 +20,6 @@ DevStack - an OpenStack Community Production plugins plugin-registry faq - changes hacking Quick Start @@ -147,11 +154,6 @@ Plugins :doc:`Extending DevStack with new features ` -Recent Changes --------------- - -:doc:`An incomplete summary of recent changes ` - FAQ --- @@ -162,94 +164,3 @@ Contributing :doc:`Pitching in to make DevStack a better place ` -Code -==== - -*A look at the bits that make it all go* - -Scripts -------- - -* `stack.sh `__ - The main script -* `functions `__ - DevStack-specific functions -* `functions-common `__ - Functions shared with other projects -* `lib/apache `__ -* `lib/ceph `__ -* `lib/cinder `__ -* `lib/database `__ -* `lib/dstat `__ -* `lib/glance `__ -* `lib/heat `__ -* `lib/horizon `__ -* `lib/infra `__ -* `lib/keystone `__ -* `lib/ldap `__ -* `lib/neutron-legacy `__ -* `lib/nova `__ -* `lib/oslo `__ -* `lib/rpc\_backend `__ -* `lib/swift `__ -* `lib/tempest `__ -* `lib/tls `__ -* `lib/trove `__ -* `unstack.sh `__ -* `clean.sh `__ -* `run\_tests.sh `__ - -* `extras.d/60-ceph.sh `__ -* `extras.d/70-tuskar.sh `__ -* `extras.d/80-tempest.sh `__ - -* `inc/ini-config `__ -* `inc/meta-config `__ -* `inc/python `__ - -* `pkg/elasticsearch.sh `_ - -Configuration -------------- - -.. toctree:: - :glob: - :maxdepth: 1 - - local.conf - stackrc - openrc - exerciserc - -Tools ------ - -* `tools/build\_docs.sh `__ -* `tools/build\_venv.sh `__ -* `tools/create-stack-user.sh `__ -* `tools/create\_userrc.sh `__ -* `tools/fixup\_stuff.sh `__ -* `tools/info.sh `__ -* `tools/install\_pip.sh `__ -* `tools/install\_prereqs.sh `__ -* `tools/make\_cert.sh `__ -* `tools/upload\_image.sh `__ - -Samples -------- - -* `local.sh `__ - -Exercises ---------- - -* `exercise.sh `__ -* `exercises/aggregates.sh `__ -* `exercises/boot\_from\_volume.sh `__ -* `exercises/bundle.sh `__ -* `exercises/client-args.sh `__ -* `exercises/client-env.sh `__ -* `exercises/euca.sh `__ -* `exercises/floating\_ips.sh `__ -* `exercises/horizon.sh `__ -* `exercises/neutron-adv-test.sh `__ -* `exercises/sec\_groups.sh `__ -* `exercises/swift.sh `__ -* `exercises/volumes.sh `__ diff --git a/doc/source/local.conf.rst b/doc/source/local.conf.rst deleted file mode 100644 index a1ca60a75d..0000000000 --- a/doc/source/local.conf.rst +++ /dev/null @@ -1,9 +0,0 @@ -========================== -local.conf - User Settings -========================== - -``local.conf`` is a user-maintained settings file that is sourced in -``stackrc``. It contains a section that replaces the historical -``localrc`` file. See the description of -:doc:`local.conf ` for more details about the mechanics -of the file. diff --git a/doc/source/openrc.rst b/doc/source/openrc.rst deleted file mode 100644 index d28b5680c6..0000000000 --- a/doc/source/openrc.rst +++ /dev/null @@ -1,68 +0,0 @@ -===================================== -openrc - User Authentication Settings -===================================== - -``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/project 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 diff --git a/doc/source/stackrc.rst b/doc/source/stackrc.rst deleted file mode 100644 index 81d4b80b8a..0000000000 --- a/doc/source/stackrc.rst +++ /dev/null @@ -1,66 +0,0 @@ -=========================== -stackrc - DevStack Settings -=========================== - -``stackrc`` is the primary configuration file for DevStack. It contains -all of the settings that control the services started and the -repositories used to download the source for those services. ``stackrc`` -sources the ``localrc`` section of ``local.conf`` to perform the default -overrides. - -DATABASE\_TYPE - Select the database backend to use. The default is ``mysql``, - ``postgresql`` is also available. -ENABLED\_SERVICES - Specify which services to launch. These generally correspond to - screen tabs. The default includes: Glance (API and Registry), - Keystone, Nova (API, Certificate, Object Store, Compute, Network, - Scheduler, Certificate Authentication), Cinder - (Scheduler, API, Volume), Horizon, MySQL, RabbitMQ, Tempest. - - :: - - ENABLED_SERVICES=g-api,g-reg,key,n-api,n-crt,n-cpu,n-net,n-cond,c-sch,c-api,c-vol,n-sch,n-cauth,horizon,rabbit,tempest,$DATABASE_TYPE - - Other services that are not enabled by default can be enabled in - ``localrc``. For example, to add Swift, use the following service - names: - - :: - - enable_service s-proxy s-object s-container s-account - - A service can similarly be disabled: - - :: - - disable_service horizon - -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 diff --git a/tools/build_docs.sh b/tools/build_docs.sh deleted file mode 100755 index 7dc492e2a4..0000000000 --- a/tools/build_docs.sh +++ /dev/null @@ -1,100 +0,0 @@ -#!/usr/bin/env bash - -# **build_docs.sh** - Build the docs for DevStack -# -# - Install shocco if not found on ``PATH`` and ``INSTALL_SHOCCO`` is set -# - Clone ``MASTER_REPO`` branch ``MASTER_BRANCH`` -# - Re-creates ``doc/build/html`` directory from existing repo + new generated script docs - -# Usage: -## build_docs.sh [-o ] -## -o Write the static HTML output to -## (Note that will be deleted and re-created to ensure it is clean) - -# Defaults -# -------- - -HTML_BUILD=doc/build/html - -# Keep track of the DevStack directory -TOP_DIR=$(cd $(dirname "$0")/.. && pwd) - -# Uses this shocco branch: https://github.com/dtroyer/shocco/tree/rst_support -SHOCCO=${SHOCCO:-shocco} -if ! which shocco; then - if [[ ! -x $TOP_DIR/shocco/shocco ]]; then - if [[ -z "$INSTALL_SHOCCO" ]]; then - echo "shocco not found in \$PATH, please set environment variable SHOCCO" - exit 1 - fi - echo "Installing local copy of shocco" - if ! which pygmentize; then - sudo pip install Pygments - fi - if ! which rst2html.py; then - sudo pip install docutils - fi - git clone -b rst_support https://github.com/dtroyer/shocco shocco - cd shocco - ./configure - make || exit - cd .. - fi - SHOCCO=$TOP_DIR/shocco/shocco -fi - -# Process command-line args -while getopts o: c; do - case $c in - o) HTML_BUILD=$OPTARG - ;; - esac -done -shift `expr $OPTIND - 1` - - -# Processing -# ---------- - -# Ensure build dir exists -mkdir -p $HTML_BUILD - -# Get fully qualified dirs -FQ_HTML_BUILD=$(cd $HTML_BUILD && pwd) - -# Insert automated bits -GLOG=$(mktemp gitlogXXXX) -echo "
    " >$GLOG -git log \ - --pretty=format:'
  • %s - Commit %h %cd
    • ' \ - --date=short \ - --since '6 months ago' | grep -v Merge >>$GLOG -echo "
" >>$GLOG -sed -i~ -e $"/^.*%GIT_LOG%.*$/r $GLOG" -e $"/^.*%GIT_LOG%.*$/s/^.*%GIT_LOG%.*$//" $FQ_HTML_BUILD/changes.html -rm -f $GLOG - -# Build list of scripts to process -FILES="" -for f in $(find . \( -name .git -o -name .tox \) -prune -o \( -type f -name \*.sh -not -path \*shocco/\* -print \)); do - echo $f - FILES+="$f " - mkdir -p $FQ_HTML_BUILD/`dirname $f`; - $SHOCCO $f > $FQ_HTML_BUILD/$f.html -done -for f in $(find functions functions-common inc lib pkg samples -type f -name \* ! -name *.md ! -name *.conf); do - echo $f - FILES+="$f " - mkdir -p $FQ_HTML_BUILD/`dirname $f`; - $SHOCCO $f > $FQ_HTML_BUILD/$f.html -done -echo "$FILES" >doc/files - -# Clean up or report the temp workspace -if [[ -n REPO && -n $PUSH_REPO ]]; then - echo rm -rf $TMP_ROOT -else - if [[ -z "$TMP_ROOT" ]]; then - TMP_ROOT="$(pwd)" - fi - echo "Built docs in $HTML_BUILD" -fi diff --git a/tox.ini b/tox.ini index 4ec293939e..e8e7d7ebb8 100644 --- a/tox.ini +++ b/tox.ini @@ -17,7 +17,6 @@ whitelist_externals = bash commands = bash -c "find {toxinidir} \ -not \( -type d -name .?\* -prune \) \ -not \( -type d -name doc -prune \) \ - -not \( -type d -name shocco -prune \) \ -not \( -type f -name localrc -prune \) \ -type f \ -not -name \*~ \ @@ -48,7 +47,5 @@ deps = whitelist_externals = bash setenv = TOP_DIR={toxinidir} - INSTALL_SHOCCO=true -commands = - python setup.py build_sphinx - bash tools/build_docs.sh +commands = + python setup.py build_sphinx