Add Getting Started guide to repo

Convert the Getting Started wiki page to ReStructuredText format and add it
to the repository. Also add a script that will extract the shell commands
from the document and run them, so we can use it as an integration test.

The script can be run using the command:
    > bash -c "$(./tools/rst2script.sed docs/GettingStarted.rst)"

Related: #84

Signed-off-by: Zane Bitter <>
This commit is contained in:
Zane Bitter 2012-05-11 18:54:38 +02:00
parent 6539794166
commit 95e5ed0670
2 changed files with 287 additions and 0 deletions

docs/GettingStarted.rst Normal file
View File

@ -0,0 +1,249 @@
Getting Started With Heat
This file is a ReStructuredText document, but can be converted to a script
using the accompanying rst2script.sed script. Any blocks that are indented by
4 spaces (including comment blocks) will appear in the script. To document
code that should not appear in the script, use an indent of less than 4
spaces. (Using a Quoted instead of Indented Literal block also works.)
To include code in the script that should not appear in the output, make it
a comment block.
# Exit on error
set -e
Install heat from source
Clone the heat repository_ from GitHub at git:// and install::
sudo python install
.. _repository:
Install Openstack
Installing OpenStack on Fedora 16
Note: on Fedora 16 you have to enable the `Preview Repository`_ to install the required OpenStack Essex release.
A script called "``openstack``" in the tools directory of the repository will install and start OpenStack for you on Fedora 16/17::
./tools/openstack install
If you use this method, you will need to manually create a guest network. How this is done depends on your environment. An example network create operation:
sudo nova-manage network create demonet ${SUBNET} 1 256 --bridge=demonetbr0
Where ``${SUBNET}`` is of the form ````. The network range here, must *not* be one used on your existing physical network. It should be a range dedicated for the network that OpenStack will configure. So if ```` clashes with your local network, pick another subnet.
If you wish to set up OpenStack manually on Fedora, read `Getting Started With OpenStack On Fedora`_.
.. _Getting Started With OpenStack on Fedora:
.. _Preview Repository:
Installing OpenStack on other Distributions
* There is a `Debian packaging team for OpenStack`_.
* There are instructions for `installing OpenStack on Ubuntu`_.
* Various other distributions may have packaging teams or Getting Started guides available.
.. _Debian packaging team for OpenStack:
.. _installing OpenStack on Ubuntu:
Download Fedora 16 DVD and copy it to libvirt images location
sudo cp Downloads/Fedora-16-x86_64-DVD.iso /var/lib/libvirt/images
Source the keystone credentials created with tools/openstack
source ~/.openstack/keystonerc
Note: these credentials will be required for all future steps.
Allocate Floating IP Addresses to OpenStack
If you want to use templates that depend on ``AWS::EC2::EIP`` or ``AWS::EC2::EIPAssociation`` (multi-instance stacks often do, single-instance less often but it's still possible), see the wiki page on `Configuring Floating IPs`_.
.. _Configuring Floating IPs:
Setup the MySQL database for Heat
./bin/heat-db-setup rpm
Note: the first argument is either ``rpm`` for RPM-based distros (such as Fedora) or ``deb`` for Debian-based distros (such as Ubuntu).
Register heat with keystone
sudo -E ./tools/heat-keystone-service
Note: The ``-E`` option to ``sudo`` preserves the environment, specifically the keystone credentials, when ``heat-keystone-service`` is run as root. This script needs to run as root in order to read the admin password.
Register a SSH key-pair with OpenStack Nova
This is for Heat to associate with the virtual machines.
nova keypair-add --pub_key ~/.ssh/ ${USER}_key
Install Oz
Verify that Oz_ is installed ::
sudo yum -y install oz
Oz is used below to create the JEOS.
.. _Oz:
Create a JEOS
sudo -E heat jeos_create F16 x86_64 cfntools
Note: The ``-E`` option to ``sudo`` preserves the environment, specifically the keystone credentials, when ``jeos_create`` is run as root.
Note: ``jeos_create`` must be run as root in order to create the cfntools disk image.
Note: If you want to enable debugging output from Oz, add '``-d``' (debugging) to the ``jeos_create`` command.
Verify JEOS registration
Check that there is a ``F16-x86_64-cfntools`` JEOS in glance:
glance index
$GLANCE_INDEX | grep -q "F16-x86_64-cfntools"
Launch the Heat services
sudo -E bash -c 'heat-api & heat-engine &'
sleep 5
Launch a Wordpress instance
heat -d create wordpress --template-file=templates/WordPress_Single_Instance.template --parameters="InstanceType=m1.xlarge;DBUsername=${USER};DBPassword=verybadpass;KeyName=${USER}_key"
List stacks
heat list
List stack events
heat events_list wordpress
Describe the ``wordpress`` stack
heat describe wordpress
Verify instance creation
Because the software takes some time to install from the repository, it may be a few minutes before the Wordpress intance is in a running state. One way to check is to login via ssh and ``tail -f /var/log/yum.log``. Once mysql-server installs, the instance should be ready to go.
# Wait for instance to start
while ((retries++ < 24)) && ! $HEAT_DESCRIBE | grep -q "$DONE_STATUS"; do
echo "Waiting for instance to become ACTIVE..." >&2
sleep 5
WebsiteURL=$($HEAT_DESCRIBE | sed -e '/"OutputKey": "WebsiteURL"/,/}/ {' \
-e '/"OutputValue":/ {' \
-e 's/[^:]*": "//' \
-e 's/",\?[[:space:]]*$//' \
-e p -e '}' -e '}' -e d)
sleep 120
Point web browser at the location given by the ``WebsiteURL`` Output as shown by ``heat describe``)::
wget ${WebsiteURL}
Delete the instance when done
heat delete wordpress
heat list
Note: This operation will show no running stack.
Other Templates
Check out the ``Wordpress_2_Instances_with_EBS_EIP.template``. This uses a few different APIs in OpenStack nova, such as the Volume API, the Floating IP API and the Security Groups API, as well as the general nova launching and monitoring APIs.
If you encounter issues running heat, see if the solution to the issue is documented on the Troubleshooting_ wiki page. If not, let us know about the problem in the #heat IRC channel on freenode.
.. _Troubleshooting:
echo; echo 'Success!'

tools/rst2script.sed Executable file
View File

@ -0,0 +1,38 @@
#!/bin/sed -nrf
# Skip over the ".." line that starts a comment block.
/^\.{2}[[:space:]]*$/ n
# Loop through the block until a non-indented line is found.
# Append indented lines to the hold space.
: indent
/^ {4}/ {
s/^ {4}//
$ b endblock
b indent
# Loop through to the end of the block.
# Clear the hold space if unindented lines are present.
/^[[:space:]]*$/! {
$ d
b nonindent
# Print the contents of the hold space (if any) and clear it.
: endblock
/./ {
a \