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…
Reference in New Issue
Block a user