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 <zbitter@redhat.com>
This commit is contained in:
Zane Bitter
parent
6539794166
commit
95e5ed0670
249
docs/GettingStarted.rst
Normal file
249
docs/GettingStarted.rst
Normal 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.
|
||||||
|
|
||||||
|
..
|
||||||
|
#!/bin/bash
|
||||||
|
|
||||||
|
# Exit on error
|
||||||
|
set -e
|
||||||
|
|
||||||
|
Install heat from source
|
||||||
|
------------------------
|
||||||
|
|
||||||
|
Clone the heat repository_ from GitHub at git://github.com/heat-api/heat.git and install::
|
||||||
|
|
||||||
|
sudo python setup.py install
|
||||||
|
|
||||||
|
.. _repository: https://github.com/heat-api/heat
|
||||||
|
|
||||||
|
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:
|
||||||
|
|
||||||
|
..
|
||||||
|
SUBNET=10.0.0.0/24
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
sudo nova-manage network create demonet ${SUBNET} 1 256 --bridge=demonetbr0
|
||||||
|
|
||||||
|
Where ``${SUBNET}`` is of the form ``10.0.0.0/24``. 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 ``10.0.0.0/24`` 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: http://fedoraproject.org/wiki/Getting_started_with_OpenStack_on_Fedora_17
|
||||||
|
.. _Preview Repository: http://fedoraproject.org/wiki/OpenStack#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: http://wiki.openstack.org/Packaging/Debian
|
||||||
|
.. _installing OpenStack on Ubuntu: http://docs.openstack.org/bexar/openstack-compute/admin/content/ch03s02.html
|
||||||
|
|
||||||
|
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: https://github.com/heat-api/heat/wiki/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/id_rsa.pub ${USER}_key
|
||||||
|
|
||||||
|
Install Oz
|
||||||
|
----------
|
||||||
|
|
||||||
|
Verify that Oz_ is installed ::
|
||||||
|
|
||||||
|
sudo yum -y install oz
|
||||||
|
|
||||||
|
Oz is used below to create the JEOS.
|
||||||
|
|
||||||
|
.. _Oz: http://aeolusproject.org/oz.html
|
||||||
|
|
||||||
|
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=$(cat <<EOF
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
glance index
|
||||||
|
|
||||||
|
..
|
||||||
|
EOF
|
||||||
|
)
|
||||||
|
$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=$(cat <<EOF
|
||||||
|
|
||||||
|
::
|
||||||
|
|
||||||
|
heat describe wordpress
|
||||||
|
|
||||||
|
..
|
||||||
|
EOF
|
||||||
|
)
|
||||||
|
|
||||||
|
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
|
||||||
|
retries=0
|
||||||
|
DONE_STATUS='"StackStatus": "CREATE_COMPLETE"'
|
||||||
|
while ((retries++ < 24)) && ! $HEAT_DESCRIBE | grep -q "$DONE_STATUS"; do
|
||||||
|
echo "Waiting for instance to become ACTIVE..." >&2
|
||||||
|
sleep 5
|
||||||
|
done
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
Troubleshooting
|
||||||
|
===============
|
||||||
|
|
||||||
|
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: https://github.com/heat-api/heat/wiki/Troubleshooting
|
||||||
|
|
||||||
|
..
|
||||||
|
echo; echo 'Success!'
|
||||||
38
tools/rst2script.sed
Executable file
38
tools/rst2script.sed
Executable 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}//
|
||||||
|
H
|
||||||
|
$ b endblock
|
||||||
|
n
|
||||||
|
b indent
|
||||||
|
}
|
||||||
|
|
||||||
|
# Loop through to the end of the block.
|
||||||
|
# Clear the hold space if unindented lines are present.
|
||||||
|
:nonindent
|
||||||
|
/^[[:space:]]*$/! {
|
||||||
|
x
|
||||||
|
s/.*//
|
||||||
|
x
|
||||||
|
$ d
|
||||||
|
n
|
||||||
|
b nonindent
|
||||||
|
}
|
||||||
|
|
||||||
|
# Print the contents of the hold space (if any) and clear it.
|
||||||
|
: endblock
|
||||||
|
s/.*//
|
||||||
|
x
|
||||||
|
s/^\n//
|
||||||
|
/./ {
|
||||||
|
p
|
||||||
|
a \
|
||||||
|
|
||||||
|
}
|
||||||
Loading…
x
Reference in New Issue
Block a user