more documentation

stack.sh

@@ -43,10 +43,12 @@ fi
 # as root, since apache refused to startup serve content from root user).  If
 # stack.sh is run as root, it automatically creates a stack user with
 # sudo privileges and runs as that user.
+
 if [[ $EUID -eq 0 ]]; then
    echo "You are running this script as root."
 
-   # ensure sudo
+   # since this script runs as a normal user, we need to give that user
+   # ability to run sudo
    apt-get update
    apt-get install -y sudo
 
@@ -122,6 +124,8 @@ ENABLED_SERVICES=${ENABLED_SERVICES:-g-api,g-reg,key,n-api,n-cpu,n-net,n-sch,n-v
 # an **LXC** based system.
 LIBVIRT_TYPE=${LIBVIRT_TYPE:-kvm}
 
+# nova supports pluggable schedulers.  ``SimpleScheduler`` should work in most
+# cases unless you are working on multi-zone mode.
 SCHEDULER=${SCHEDULER:-nova.scheduler.simple.SimpleScheduler}
 
 # Use the first IP unless an explicit is set by ``HOST_IP`` environment variable
@@ -133,19 +137,26 @@ fi
 # --------------------------
 
 PUBLIC_INTERFACE=${PUBLIC_INTERFACE:-eth0}
-VLAN_INTERFACE=${VLAN_INTERFACE:-$PUBLIC_INTERFACE}
-FLOATING_RANGE=${FLOATING_RANGE:-172.24.4.1/28}
 FIXED_RANGE=${FIXED_RANGE:-10.0.0.0/24}
 FIXED_NETWORK_SIZE=${FIXED_NETWORK_SIZE:-256}
+FLOATING_RANGE=${FLOATING_RANGE:-172.24.4.1/28}
 NET_MAN=${NET_MAN:-FlatDHCPManager}
 EC2_DMZ_HOST=${EC2_DMZ_HOST:-$HOST_IP}
 FLAT_NETWORK_BRIDGE=${FLAT_NETWORK_BRIDGE:-br100}
+VLAN_INTERFACE=${VLAN_INTERFACE:-$PUBLIC_INTERFACE}
+
+# Multi-host is a mode where each compute node runs its own network node.  This
+# allows network operations and routing for a VM to occur on the server that is
+# running the VM - removing a SPOF and bandwidth bottleneck.
+MULTI_HOST=${MULTI_HOST:-0}
 
 # If you are using FlatDHCP on multiple hosts, set the ``FLAT_INTERFACE``
 # variable but make sure that the interface doesn't already have an
 # ip or you risk breaking things.
 FLAT_INTERFACE=${FLAT_INTERFACE:-eth0}
 
+## FIXME(ja): should/can we check that FLAT_INTERFACE is sane?
+
 
 # MySQL & RabbitMQ
 # ----------------
@@ -186,13 +197,6 @@ ADMIN_PASSWORD=${ADMIN_PASSWORD:-`openssl rand -hex 12`}
 #
 # Openstack uses a fair number of other projects.
 
-# Seed configuration with mysql password so that apt-get install doesn't
-# prompt us for a password upon install.
-cat <<MYSQL_PRESEED | sudo debconf-set-selections
-mysql-server-5.1 mysql-server/root_password password $MYSQL_PASS
-mysql-server-5.1 mysql-server/root_password_again password $MYSQL_PASS
-mysql-server-5.1 mysql-server/start_on_boot boolean true
-MYSQL_PRESEED
 
 # install apt requirements
 sudo apt-get install -y -q `cat $FILES/apts/* | cut -d\# -f1 | grep -Ev "mysql-server|rabbitmq-server"`
@@ -252,7 +256,7 @@ cp $FILES/screenrc ~/.screenrc
 
 # Rabbit
 # ---------
-#
+
 if [[ "$ENABLED_SERVICES" =~ "rabbit" ]]; then
     # Install and start rabbitmq-server
     sudo apt-get install -y -q rabbitmq-server
@@ -262,8 +266,17 @@ fi
 
 # Mysql
 # ---------
-#
+
 if [[ "$ENABLED_SERVICES" =~ "mysql" ]]; then
+
+    # Seed configuration with mysql password so that apt-get install doesn't
+    # prompt us for a password upon install.
+    cat <<MYSQL_PRESEED | sudo debconf-set-selections
+mysql-server-5.1 mysql-server/root_password password $MYSQL_PASS
+mysql-server-5.1 mysql-server/root_password_again password $MYSQL_PASS
+mysql-server-5.1 mysql-server/start_on_boot boolean true
+MYSQL_PRESEED
+
     # Install and start mysql-server
     sudo apt-get -y -q install mysql-server
     # Update the DB to give user ‘$MYSQL_USER’@’%’ full control of the all databases:
@@ -277,22 +290,23 @@ fi
 
 # Dashboard
 # ---------
-#
-# Setup the django application to serve via apache/wsgi
+
+# Setup the django dashboard application to serve via apache/wsgi
 
 if [[ "$ENABLED_SERVICES" =~ "dash" ]]; then
 
     # Dash currently imports quantum even if you aren't using it.  Instead
     # of installing quantum we can create a simple module that will pass the
     # initial imports
-    sudo mkdir -p  $DASH_DIR/openstack-dashboard/quantum || true
-    sudo touch $DASH_DIR/openstack-dashboard/quantum/__init__.py
-    sudo touch $DASH_DIR/openstack-dashboard/quantum/client.py
+    mkdir -p  $DASH_DIR/openstack-dashboard/quantum || true
+    touch $DASH_DIR/openstack-dashboard/quantum/__init__.py
+    touch $DASH_DIR/openstack-dashboard/quantum/client.py
 
-    cd $DASH_DIR/openstack-dashboard
 
-    sudo cp $FILES/dash_settings.py local/local_settings.py
+    # ``local_settings.py`` is used to override dashboard default settings.
+    cp $FILES/dash_settings.py $DASH_DIR/openstack-dashboard/local/local_settings.py
 
+    cd $DASH_DIR/openstack-dashboard
     dashboard/manage.py syncdb
 
     # create an empty directory that apache uses as docroot
@@ -335,28 +349,42 @@ fi
 # Nova
 # ----
 
+# We are going to use the sample http middleware configuration from the keystone
+# project to launch nova.  This paste config adds the configuration required
+# for nova to validate keystone tokens - except we need to switch the config
+# to use our admin token instead (instead of the token from their sample data).
 sudo sed -e "s,999888777666,$SERVICE_TOKEN,g" -i $KEYSTONE_DIR/examples/paste/nova-api-paste.ini
 
 if [[ "$ENABLED_SERVICES" =~ "n-cpu" ]]; then
 
-    # attempt to load modules: nbd (network block device - used to manage
-    # qcow images) and kvm (hardware based virtualization).  If unable to
-    # load kvm, set the libvirt type to qemu.
+    # Virtualization Configuration
+    # ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    # attempt to load modules: network block device - used to manage qcow images
     sudo modprobe nbd || true
 
+    # Check for kvm (hardware based virtualization).  If unable to load kvm, 
+    # set the libvirt type to qemu.  Note: many systems come with hardware 
+    # virtualization disabled in BIOS.
     if [[ "$LIBVIRT_TYPE" -eq "kvm" ]]; then
+        sudo modprobe kvm || true
         if [ ! -e /dev/kvm ]; then
+            echo "WARNING: Switching to QEMU"
             LIBVIRT_TYPE=qemu
         fi
     fi
 
+    # Install and configure **LXC** if specified.  LXC is another approach to
+    # splitting a system into many smaller parts.  LXC uses cgroups and chroot
+    # to simulate multiple systems.
     if [[ "$LIBVIRT_TYPE" -eq "lxc" ]]; then
         sudo apt-get install lxc -y
+        # lxc requires cgroups to be configured on /cgroup
         sudo mkdir -p /cgroup
-        sudo mount none -t cgroup -o cpuacct,memory,devices,cpu,freezer,blkio /cgroup
         if ! grep -q cgroup /etc/fstab; then
             echo none /cgroup cgroup cpuacct,memory,devices,cpu,freezer,blkio 0 0 | sudo tee -a /etc/fstab
         fi
+        sudo mount /cgroup
     fi
 
     # User needs to be member of libvirtd group for nova-compute to use libvirt.
@@ -364,7 +392,11 @@ if [[ "$ENABLED_SERVICES" =~ "n-cpu" ]]; then
     # if kvm wasn't running before we need to restart libvirt to enable it
     sudo /etc/init.d/libvirt-bin restart
 
-    # setup nova instance directory
+
+    # Instance Storage
+    # ~~~~~~~~~~~~~~~~
+
+    # Nova stores each instance in its own directory.
     mkdir -p $NOVA_DIR/instances
 
     # if there is a partition labeled nova-instances use it (ext filesystems
@@ -375,7 +407,7 @@ if [[ "$ENABLED_SERVICES" =~ "n-cpu" ]]; then
         sudo chown -R `whoami` $NOVA_DIR/instances
     fi
 
-    # Clean out the instances directory
+    # Clean out the instances directory.
     rm -rf $NOVA_DIR/instances/*
 fi
 
@@ -419,10 +451,18 @@ if [ -n "$MULTI_HOST" ]; then
     add_nova_flag "--multi_host=$MULTI_HOST"
 fi
 
+# Nova Database
+# ~~~~~~~~~~~~~
+
+# All nova components talk to a central database.  We will need to do this step
+# only once for an entire cluster.
+
 if [[ "$ENABLED_SERVICES" =~ "mysql" ]]; then
     # (re)create nova database
     mysql -u$MYSQL_USER -p$MYSQL_PASS -e 'DROP DATABASE IF EXISTS nova;'
     mysql -u$MYSQL_USER -p$MYSQL_PASS -e 'CREATE DATABASE nova;'
+
+    # (re)create nova database
     $NOVA_DIR/bin/nova-manage db sync
 
     # create a small network
@@ -447,6 +487,7 @@ if [[ "$ENABLED_SERVICES" =~ "key" ]]; then
     sudo sed -e "s,%SQL_CONN%,$BASE_SQL_CONN/keystone,g" -i $KEYSTONE_CONF
     sudo sed -e "s,%DEST%,$DEST,g" -i $KEYSTONE_CONF
 
+    # keystone_data.sh creates our admin user and our ``SERVICE_TOKEN``.
     KEYSTONE_DATA=$KEYSTONE_DIR/bin/keystone_data.sh
     cp $FILES/keystone_data.sh $KEYSTONE_DATA
     sudo sed -e "s,%HOST_IP%,$HOST_IP,g" -i $KEYSTONE_DATA