Holiday docs and comment formatting cleanup
Change-Id: Ia4ca88c67d3b94e306a79a669805a2fa1b0dc069
diff --git a/HACKING.rst b/HACKING.rst
index e8f90c7..c4641fa 100644
--- a/HACKING.rst
+++ b/HACKING.rst
@@ -15,6 +15,16 @@
tracks the OpenStack trunk branches a separate branch is maintained for all
OpenStack releases starting with Diablo (stable/diablo).
+Contributing code to DevStack follows the usual OpenStack process as described
+in `How To Contribute`__ in the OpenStack wiki. `DevStack's LaunchPad project`__
+contains the usual links for blueprints, bugs, tec.
+
+__ contribute_
+.. _contribute: http://wiki.openstack.org/HowToContribute.
+
+__ lp_
+.. _lp: https://launchpad.net/~devstack
+
The primary script in DevStack is ``stack.sh``, which performs the bulk of the
work for DevStack's use cases. There is a subscript ``functions`` that contains
generally useful shell functions and is used by a number of the scripts in
@@ -53,8 +63,8 @@
source $TOP_DIR/openrc
``stack.sh`` is a rather large monolithic script that flows through from beginning
-to end. The process of breaking it down into project-level sub-scripts has begun
-with the introduction of ``lib/cinder`` and ``lib/ceilometer``.
+to end. The process of breaking it down into project-level sub-scripts is nearly
+complete and should make ``stack.sh`` easier to read and manage.
These library sub-scripts have a number of fixed entry points, some of which may
just be stubs. These entry points will be called by ``stack.sh`` in the
@@ -71,6 +81,12 @@
service sub-scripts. The comments in ``<>`` are meta comments describing
how to use the template and should be removed.
+In order to show the dependencies and conditions under which project functions
+are executed the top-level conditional testing for things like ``is_service_enabled``
+should be done in ``stack.sh``. There may be nested conditionals that need
+to be in the sub-script, such as testing for keystone being enabled in
+``configure_swift()``.
+
Documentation
-------------
diff --git a/exercises/quantum-adv-test.sh b/exercises/quantum-adv-test.sh
index 493e223..bc33fe8 100755
--- a/exercises/quantum-adv-test.sh
+++ b/exercises/quantum-adv-test.sh
@@ -1,10 +1,9 @@
#!/usr/bin/env bash
#
-# **quantum.sh**
+# **quantum-adv-test.sh**
-# We will use this test to perform integration testing of nova and
-# other components with Quantum.
+# Perform integration testing of Nova and other components with Quantum.
echo "*********************************************************************"
echo "Begin DevStack Exercise: $0"
@@ -14,6 +13,7 @@
# only the first error that occured.
set -o errtrace
+
trap failed ERR
failed() {
local r=$?
@@ -30,17 +30,8 @@
# an error. It is also useful for following allowing as the install occurs.
set -o xtrace
-#------------------------------------------------------------------------------
-# Quantum config check
-#------------------------------------------------------------------------------
-# Warn if quantum is not enabled
-if [[ ! "$ENABLED_SERVICES" =~ "q-svc" ]]; then
- echo "WARNING: Running quantum test without enabling quantum"
-fi
-
-#------------------------------------------------------------------------------
# Environment
-#------------------------------------------------------------------------------
+# -----------
# Keep track of the current directory
EXERCISE_DIR=$(cd $(dirname "$0") && pwd)
@@ -62,9 +53,8 @@
# Import exercise configuration
source $TOP_DIR/exerciserc
-#------------------------------------------------------------------------------
-# Test settings for quantum
-#------------------------------------------------------------------------------
+# Quantum Settings
+# ----------------
TENANTS="DEMO1"
# TODO (nati)_Test public network
@@ -106,24 +96,17 @@
DEMO1_ROUTER1_NET="demo1-net1"
DEMO2_ROUTER1_NET="demo2-net1"
-#------------------------------------------------------------------------------
-# Keystone settings.
-#------------------------------------------------------------------------------
KEYSTONE="keystone"
-#------------------------------------------------------------------------------
-# Get a token for clients that don't support service catalog
-#------------------------------------------------------------------------------
-
-# manually create a token by querying keystone (sending JSON data). Keystone
+# Manually create a token by querying keystone (sending JSON data). Keystone
# returns a token and catalog of endpoints. We use python to parse the token
# and save it.
TOKEN=`keystone token-get | grep ' id ' | awk '{print $4}'`
-#------------------------------------------------------------------------------
-# Various functions.
-#------------------------------------------------------------------------------
+# Various functions
+# -----------------
+
function foreach_tenant {
COMMAND=$1
for TENANT in ${TENANTS//,/ };do
@@ -192,10 +175,9 @@
function confirm_server_active {
local VM_UUID=$1
if ! timeout $ACTIVE_TIMEOUT sh -c "while ! nova show $VM_UUID | grep status | grep -q ACTIVE; do sleep 1; done"; then
- echo "server '$VM_UUID' did not become active!"
- false
-fi
-
+ echo "server '$VM_UUID' did not become active!"
+ false
+ fi
}
function add_tenant {
@@ -214,23 +196,15 @@
function remove_tenant {
local TENANT=$1
local TENANT_ID=$(get_tenant_id $TENANT)
-
$KEYSTONE tenant-delete $TENANT_ID
}
function remove_user {
local USER=$1
local USER_ID=$(get_user_id $USER)
-
$KEYSTONE user-delete $USER_ID
}
-
-
-#------------------------------------------------------------------------------
-# "Create" functions
-#------------------------------------------------------------------------------
-
function create_tenants {
source $TOP_DIR/openrc admin admin
add_tenant demo1 demo1 demo1
@@ -383,9 +357,9 @@
delete_all
}
-#------------------------------------------------------------------------------
-# Test functions.
-#------------------------------------------------------------------------------
+# Test functions
+# --------------
+
function test_functions {
IMAGE=$(get_image_id)
echo $IMAGE
@@ -400,9 +374,9 @@
echo $NETWORK_ID
}
-#------------------------------------------------------------------------------
-# Usage and main.
-#------------------------------------------------------------------------------
+# Usage and main
+# --------------
+
usage() {
echo "$0: [-h]"
echo " -h, --help Display help message"
@@ -473,10 +447,9 @@
fi
}
+# Kick off script
+# ---------------
-#-------------------------------------------------------------------------------
-# Kick off script.
-#-------------------------------------------------------------------------------
echo $*
main $*
diff --git a/lib/ceilometer b/lib/ceilometer
index aa1b396..76ab254 100644
--- a/lib/ceilometer
+++ b/lib/ceilometer
@@ -1,9 +1,9 @@
# lib/ceilometer
-# Install and start Ceilometer service
+# Install and start **Ceilometer** service
+
# To enable, add the following to localrc
# ENABLED_SERVICES+=ceilometer-acompute,ceilometer-acentral,ceilometer-collector,ceilometer-api
-
# Dependencies:
# - functions
# - OS_AUTH_URL for auth in api
@@ -12,12 +12,12 @@
# stack.sh
# ---------
-# install_XXX
-# configure_XXX
-# init_XXX
-# start_XXX
-# stop_XXX
-# cleanup_XXX
+# install_ceilometer
+# configure_ceilometer
+# init_ceilometer
+# start_ceilometer
+# stop_ceilometer
+# cleanup_ceilometer
# Save trace setting
XTRACE=$(set +o | grep xtrace)
@@ -27,17 +27,18 @@
# Defaults
# --------
-# set up default directories
+# Set up default directories
CEILOMETER_DIR=$DEST/ceilometer
+CEILOMETER_CONF_DIR=/etc/ceilometer
+CEILOMETER_CONF=$CEILOMETER_CONF_DIR/ceilometer.conf
+CEILOMETER_API_LOG_DIR=/var/log/ceilometer-api
+
# Support potential entry-points console scripts
if [ -d $CEILOMETER_DIR/bin ] ; then
CEILOMETER_BIN_DIR=$CEILOMETER_DIR/bin
else
CEILOMETER_BIN_DIR=/usr/local/bin
fi
-CEILOMETER_CONF_DIR=/etc/ceilometer
-CEILOMETER_CONF=$CEILOMETER_CONF_DIR/ceilometer.conf
-CEILOMETER_API_LOG_DIR=/var/log/ceilometer-api
# cleanup_ceilometer() - Remove residual data files, anything left over from previous
# runs that a clean run would need to clean up
diff --git a/lib/cinder b/lib/cinder
index dadc8f1..701effd 100644
--- a/lib/cinder
+++ b/lib/cinder
@@ -1,5 +1,5 @@
# lib/cinder
-# Install and start Cinder volume service
+# Install and start **Cinder** volume service
# Dependencies:
# - functions
diff --git a/lib/databases/mysql b/lib/databases/mysql
index 68e9adc..1c0f5eb 100644
--- a/lib/databases/mysql
+++ b/lib/databases/mysql
@@ -1,5 +1,5 @@
-# lib/mysql
-# Functions to control the configuration and operation of the MySQL database backend
+# lib/databases/mysql
+# Functions to control the configuration and operation of the **MySQL** database backend
# Dependencies:
# DATABASE_{HOST,USER,PASSWORD} must be defined
diff --git a/lib/databases/postgresql b/lib/databases/postgresql
index e1463c5..04db714 100644
--- a/lib/databases/postgresql
+++ b/lib/databases/postgresql
@@ -1,5 +1,5 @@
-# lib/postgresql
-# Functions to control the configuration and operation of the PostgreSQL database backend
+# lib/databases/postgresql
+# Functions to control the configuration and operation of the **PostgreSQL** database backend
# Dependencies:
# DATABASE_{HOST,USER,PASSWORD} must be defined
diff --git a/lib/glance b/lib/glance
index 8ba04b3..dff247a 100644
--- a/lib/glance
+++ b/lib/glance
@@ -1,5 +1,5 @@
# lib/glance
-# Functions to control the configuration and operation of the Glance service
+# Functions to control the configuration and operation of the **Glance** service
# Dependencies:
# ``functions`` file
@@ -25,8 +25,6 @@
# Defaults
# --------
-# <define global variables here that belong to this project>
-
# Set up default directories
GLANCE_DIR=$DEST/glance
GLANCECLIENT_DIR=$DEST/python-glanceclient
@@ -141,7 +139,6 @@
iniset $GLANCE_CACHE_CONF DEFAULT admin_password $SERVICE_PASSWORD
cp -p $GLANCE_DIR/etc/policy.json $GLANCE_POLICY_JSON
-
}
# init_glance() - Initialize databases, etc.
diff --git a/lib/heat b/lib/heat
index 43115cb..a6f7286 100644
--- a/lib/heat
+++ b/lib/heat
@@ -1,5 +1,6 @@
# lib/heat
-# Install and start Heat service
+# Install and start **Heat** service
+
# To enable, add the following to localrc
# ENABLED_SERVICES+=,heat,h-api-cfn,h-api-cw,h-eng
@@ -8,12 +9,14 @@
# stack.sh
# ---------
-# install_XXX
-# configure_XXX
-# init_XXX
-# start_XXX
-# stop_XXX
-# cleanup_XXX
+# install_heatclient
+# install_heat
+# configure_heatclient
+# configure_heat
+# init_heat
+# start_heat
+# stop_heat
+# cleanup_heat
# Save trace setting
XTRACE=$(set +o | grep xtrace)
@@ -57,7 +60,7 @@
HEAT_API_HOST=${HEAT_API_HOST:-$SERVICE_HOST}
HEAT_API_PORT=${HEAT_API_PORT:-8004}
- # cloudformation api
+ # Cloudformation API
HEAT_API_CFN_CONF=$HEAT_CONF_DIR/heat-api-cfn.conf
cp $HEAT_DIR/etc/heat/heat-api-cfn.conf $HEAT_API_CFN_CONF
iniset $HEAT_API_CFN_CONF DEFAULT debug True
@@ -86,7 +89,7 @@
iniset $HEAT_API_CFN_PASTE_INI filter:ec2authtoken auth_uri $KEYSTONE_SERVICE_PROTOCOL://$KEYSTONE_SERVICE_HOST:$KEYSTONE_SERVICE_PORT/v2.0
iniset $HEAT_API_CFN_PASTE_INI filter:ec2authtoken keystone_ec2_uri $KEYSTONE_SERVICE_PROTOCOL://$KEYSTONE_SERVICE_HOST:$KEYSTONE_SERVICE_PORT/v2.0/ec2tokens
- # openstack api
+ # OpenStack API
HEAT_API_CONF=$HEAT_CONF_DIR/heat-api.conf
cp $HEAT_DIR/etc/heat/heat-api.conf $HEAT_API_CONF
iniset $HEAT_API_CONF DEFAULT debug True
@@ -139,7 +142,7 @@
iniset $HEAT_ENGINE_CONF DEFAULT rpc_backend heat.openstack.common.rpc.impl_qpid
fi
- # cloudwatch api
+ # Cloudwatch API
HEAT_API_CW_CONF=$HEAT_CONF_DIR/heat-api-cloudwatch.conf
cp $HEAT_DIR/etc/heat/heat-api-cloudwatch.conf $HEAT_API_CW_CONF
iniset $HEAT_API_CW_CONF DEFAULT debug True
diff --git a/lib/keystone b/lib/keystone
index 4dddedb..34f3372 100644
--- a/lib/keystone
+++ b/lib/keystone
@@ -8,7 +8,6 @@
# ``SERVICE_TOKEN``
# ``S3_SERVICE_PORT`` (template backend only)
-
# ``stack.sh`` calls the entry points in this order:
#
# install_keystone
@@ -27,8 +26,6 @@
# Defaults
# --------
-# <define global variables here that belong to this project>
-
# Set up default directories
KEYSTONE_DIR=$DEST/keystone
KEYSTONE_CONF_DIR=${KEYSTONE_CONF_DIR:-/etc/keystone}
diff --git a/lib/nova b/lib/nova
index 5224d4d..594195e 100644
--- a/lib/nova
+++ b/lib/nova
@@ -1,5 +1,5 @@
# lib/nova
-# Functions to control the configuration and operation of the XXXX service
+# Functions to control the configuration and operation of the **Nova** service
# Dependencies:
# ``functions`` file
diff --git a/lib/swift b/lib/swift
index 713b38c..8934264 100644
--- a/lib/swift
+++ b/lib/swift
@@ -1,5 +1,5 @@
# lib/swift
-# Functions to control the configuration and operation of the swift service
+# Functions to control the configuration and operation of the **Swift** service
# Dependencies:
# ``functions`` file
@@ -23,10 +23,7 @@
# Defaults
# --------
-# <define global variables here that belong to this project>
-
# Set up default directories
-
SWIFT_DIR=$DEST/swift
SWIFTCLIENT_DIR=$DEST/python-swiftclient
SWIFT_AUTH_CACHE_DIR=${SWIFT_AUTH_CACHE_DIR:-/var/cache/swift}
@@ -71,6 +68,7 @@
CONTAINER_PORT_BASE=6011
ACCOUNT_PORT_BASE=6012
+
# Entry Points
# ------------
@@ -293,7 +291,6 @@
sudo chown -R $USER:adm ${swift_log_dir}
sed "s,%SWIFT_LOGDIR%,${swift_log_dir}," $FILES/swift/rsyslog.conf | sudo \
tee /etc/rsyslog.d/10-swift.conf
-
}
# configure_swiftclient() - Set config files, create data dirs, etc
diff --git a/lib/tempest b/lib/tempest
index 337be75..190d77f 100644
--- a/lib/tempest
+++ b/lib/tempest
@@ -1,4 +1,5 @@
# lib/tempest
+# Install and configure Tempest
# Dependencies:
# ``functions`` file
@@ -23,33 +24,29 @@
#
# install_tempest
# configure_tempest
-# init_tempest
-## start_tempest
-## stop_tempest
-## cleanup_tempest
# Save trace setting
XTRACE=$(set +o | grep xtrace)
set +o xtrace
+
# Defaults
# --------
-# <define global variables here that belong to this project>
-
# Set up default directories
-NOVA_SOURCE_DIR=$DEST/nova
TEMPEST_DIR=$DEST/tempest
TEMPEST_CONF_DIR=$TEMPEST_DIR/etc
TEMPEST_CONF=$TEMPEST_CONF_DIR/tempest.conf
+NOVA_SOURCE_DIR=$DEST/nova
+
BUILD_INTERVAL=3
BUILD_TIMEOUT=400
+
# Entry Points
# ------------
-
# configure_tempest() - Set config files, create data dirs, etc
function configure_tempest() {
local image_lines
@@ -66,7 +63,7 @@
local public_network_id
local tenant_networks_reachable
- #TODO(afazekas):
+ # TODO(afazekas):
# sudo python setup.py deploy
# This function exits on an error so that errors don't compound and you see
@@ -74,7 +71,7 @@
errexit=$(set +o | grep errexit)
set -o errexit
- #Save IFS
+ # Save IFS
ifs=$IFS
# Glance should already contain images to be used in tempest
@@ -240,7 +237,6 @@
$errexit
}
-
# install_tempest() - Collect source and prepare
function install_tempest() {
git_clone $TEMPEST_REPO $TEMPEST_DIR $TEMPEST_BRANCH