Add Getting Started Guides the developer doc's

These have been copied from the wiki.

DocImpact
Signed-off-by: Angus Salkeld <asalkeld@redhat.com>

Change-Id: I4c93bc5a1811e674cef3c7868e7cf9a457c12dea
This commit is contained in:
Angus Salkeld 2013-04-04 15:28:04 +11:00
parent 3fb34493bf
commit 2b420437fd
8 changed files with 863 additions and 1 deletions

View File

@ -0,0 +1,25 @@
..
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Getting Started Guides
======================
.. toctree::
:maxdepth: 2
on_devstack
on_fedora
on_ubuntu
on_other
.. update index

View File

@ -0,0 +1,111 @@
..
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Heat and Devstack
=================
Heat is fully integrated into DevStack. This is a convenient way to try out or develop heat alongside the current development state of all the other OpenStack projects. Heat on DevStack works on both Ubuntu and Fedora.
These instructions assume you already have a working DevStack installation which can launch basic instances.
Configure DevStack to enable Heat
---------------------------------
Adding the following line to your `localrc` file will enable the heat services
::
ENABLED_SERVICES+=,heat,h-api,h-api-cfn,h-api-cw,h-eng
It would also be useful to automatically download and register a VM image that Heat can launch.
::
IMAGE_URLS+=",http://fedorapeople.org/groups/heat/prebuilt-jeos-images/F16-x86_64-cfntools.qcow2,http://fedorapeople.org/groups/heat/prebuilt-jeos-images/F16-i386-cfntools.qcow2"
URLs for any of [http://fedorapeople.org/groups/heat/prebuilt-jeos-images/ these prebuilt JEOS images] can be specified.
That is all the configuration that is required. When you run `./stack.sh` the Heat processes will be launched in `screen` with the labels prefixed with `h-`.
Confirming heat is responding
-----------------------------
Before any heat commands can be run, the authentication environment needs to be loaded
::
source openrc
You can confirm that Heat is running and responding with this command
::
heat list
This should return an empty line
Preparing Nova for running stacks
---------------------------------
Enabling Heat in devstack will replace the default Nova flavors with flavours that the Heat example templates expect. You can see what those flavors are by running
::
nova flavor-list
Heat needs to launch instances with a keypair, so we need to generate one
::
nova keypair-add heat_key > heat_key.priv
chmod 600 heat_key.priv
Launching a stack
-----------------
Now lets launch a stack, assuming that DEST is left as the default /opt/stack::
heat create teststack -f
/opt/stack/heat/templates/WordPress_Single_Instance.template -P "InstanceType=m1.large;DBUsername=wp;DBPassword=verybadpassword;KeyName=heat_key;LinuxDistribution=F16"
Which will respond::
+--------------------------------------+-----------+--------------------+----------------------+
| ID | Name | Status | Created |
+--------------------------------------+-----------+--------------------+----------------------+
| (uuid) | teststack | CREATE_IN_PROGRESS | (timestamp) |
+--------------------------------------+-----------+--------------------+----------------------+
List stacks
~~~~~~~~~~~
List the stacks in your tenant::
heat list
List stack events
~~~~~~~~~~~~~~~~~
List the events related to a particular stack::
heat event-list teststack
Describe the wordpress stack
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Show detailed state of a stack::
heat describe teststack
Note: After a few seconds, the stack_status should change from IN_PROGRESS to CREATE_COMPLETE.
Verify instance creation
~~~~~~~~~~~~~~~~~~~~~~~~
Because the software takes some time to install from the repository, it may be a few minutes before the Wordpress instance is in a running state.
Point a web browser at the location given by the WebsiteURL Output as shown by heat stack-show teststack::
wget ${WebsiteURL}
Delete the instance when done
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Note: The list operation will show no running stack.::
heat delete teststack
heat list

View File

@ -0,0 +1,407 @@
..
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Getting Started With Heat on Fedora
===================================
..
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
Get Heat
--------
Clone the heat repository_ from GitHub at ``git://github.com/openstack/heat.git``. Note that OpenStack must be installed before heat.
Optionally, one may wish to install Heat via RPM. Creation instructions are in the readme in the heat-rpms_ repository at ``git://github.com/heat-api/heat-rpms.git``.
.. _repository: https://github.com/openstack/heat
.. _heat-rpms: https://github.com/heat-api/heat-rpms
Install OpenStack
-----------------
Installing OpenStack on Fedora 16/17/18
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Note:
- On Fedora 16 you have to enable the `Preview Repository`_ to install the required OpenStack Essex release.
- On Fedora 17 you can use the included OpenStack Essex release, or optionally enable the `Preview Repository`_ to install the newer OpenStack Folsom release.
- On Fedora 18 you can use the included OpenStack Folsom release
A script called "``openstack``" in the tools directory of the repository will install and start OpenStack for you on Fedora::
./tools/openstack install -y -r ${MYSQL_ROOT_PASSWORD}
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.
Currently, the bridge is not created immediately upon running this command, but is actually added when Nova first requires it.
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
Download or alternatvely generate a JEOS image
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
It is possible to use either heat-jeos to create an image or download a
prebuilt image of a desired distribution.
Note heat-jeos does not work in virt on virt situations. In this case, it
is recommended that the prebuilt images are used.
Download a prebuilt image and copy to libvirt images location
-------------------------------------------------------------
Download a prebuilt image from ``http://fedorapeople.org/groups/heat/prebuilt-jeos-images/``.
Note: This example assumes F17-x86_64-cfntools qcow2 was downloaded.
::
sudo cp Downloads/F17-x86_64-cfntools.qcow2 /var/lib/libvirt/images
Register with glance:
::
glance image-create --name=F17-x86_64-cfntools --disk-format=qcow2 --container-format=bare < /var/lib/libvirt/images/F17-x86_64-cfntools.qcow2
Alternatively Download Fedora 17 DVD and copy it to libvirt images location
---------------------------------------------------------------------------
::
sudo cp Downloads/Fedora-17-x86_64-DVD.iso /var/lib/libvirt/images
Alternatively Install OZ
------------------------
It is recommended to install the latest upstream oz, as this supports Fedora 17 (and Ubuntu U10/U12) guests::
git clone -q https://github.com/clalancette/oz.git
pushd oz
rm -f ~/rpmbuild/RPMS/noarch/oz-*
make rpm
sudo yum -q -y localinstall ~/rpmbuild/RPMS/noarch/oz-*
popd
Note: In the steps above, it's only necessary to be root for the yum localinstall, it's recommended not to be root while building the rpm.
If you do not require F17/U10/U12 support, oz can be installed directly via yum::
yum install oz
Alternatively Download and install heat-jeos via git
----------------------------------------------------
Download heat-jeos via git
::
git clone -q git://github.com/sdake/heat-jeos.git
pushd heat-jeos
sudo python setup.py install
popd
Alternatively Create a JEOS with heat_jeos tools
------------------------------------------------
::
sudo -E heat-jeos -y create F17-x86_64-cfntools --register-with-glance
Note: The ``-E`` option to ``sudo`` preserves the environment, specifically the keystone credentials, when ``heat-jeos`` is run as root.
Note: ``heat-jeos`` 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 ``heat-jeos`` command.
You can run ``heat-jeos list`` to pick a different JEOS image.
Install and Configure Heat
~~~~~~~~~~~~~~~~~~~~~~~~~~
Install heat from source
------------------------
In the heat directory, run the install script::
sudo ./install.sh
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: http://wiki.openstack.org/Heat/Configuring-Floating-IPs
Setup the MySQL database for Heat
---------------------------------
::
heat-db-setup rpm -y -r ${MYSQL_ROOT_PASSWORD}
Note: the first argument is either ``rpm`` for RPM-based distros (such as Fedora) or ``deb`` for Debian-based distros (such as Ubuntu). To prompt for confirmation when e.g. installing MySQL Server, omit the ``-y`` option. Run ``heat-db-setup --help`` for detailed documentation.
Register heat with keystone
---------------------------
::
sudo -E ./bin/heat-keystone-setup
Note: The ``-E`` option to ``sudo`` preserves the environment, specifically the keystone credentials, when ``heat-keystone-setup`` 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
Verify JEOS registration
~~~~~~~~~~~~~~~~~~~~~~~~
Check that there is a ``F17-x86_64-cfntools`` JEOS in glance:
..
GLANCE_INDEX=$(cat <<EOF
::
glance index
..
EOF
)
$GLANCE_INDEX | grep -q "F17-x86_64-cfntools"
Update heat engine configuration file
-------------------------------------
The heat engine configuration file should be updated with the address of the bridge device (demonetbr0), however this device is not created by nova-network until the first instance is launched, so we assume that $BRIDGE_IP is 10.0.0.1 if $SUBNET is 10.0.0.0/24 as in the instructions above:
..
BRIDGE_IP=`echo $SUBNET | awk -F'[./]' '{printf "%d.%d.%d.%d", $1, $2, $3, or($4, 1)}'`
::
sudo sed -i -e "/heat_metadata_server_url/ s/127\.0\.0\.1/${BRIDGE_IP}/" /etc/heat/heat-engine.conf
sudo sed -i -e "/heat_waitcondition_server_url/ s/127\.0\.0\.1/${BRIDGE_IP}/" /etc/heat/heat-engine.conf
sudo sed -i -e "/heat_watch_server_url/ s/127\.0\.0\.1/${BRIDGE_IP}/" /etc/heat/heat-engine.conf
Launch the Heat services
------------------------
::
sudo -E bash -c 'heat-api-cfn & heat-engine &'
..
sleep 5
Launch a Wordpress instance
---------------------------
::
heat-cfn create wordpress --template-file=templates/WordPress_Single_Instance.template --parameters="InstanceType=m1.xlarge;DBUsername=${USER};DBPassword=verybadpass;KeyName=${USER}_key"
List stacks
-----------
::
heat-cfn list
List stack events
-----------------
::
heat-cfn event-list wordpress
Describe the ``wordpress`` stack
--------------------------------
..
HEAT_DESCRIBE=$(cat <<EOF
::
heat-cfn describe wordpress
..
EOF
)
After a few seconds, the ``StackStatus`` should change from ``CREATE_IN_PROGRESS`` to ``CREATE_COMPLETE``.
..
# Wait for Stack creation
CREATING="<StackStatus>CREATE_IN_PROGRESS</StackStatus>"
retries=24
while $HEAT_DESCRIBE | grep -q $CREATING && ((retries-- > 0))
do
echo "Waiting for Stack creation to complete..." >&2
sleep 5
done
$HEAT_DESCRIBE | grep -q "<StackStatus>CREATE_COMPLETE</StackStatus>"
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.
..
WebsiteURL=$($HEAT_DESCRIBE | sed \
-e '/<OutputKey>WebsiteURL<\/OutputKey>/,/<\/member>/ {' \
-e '/<OutputValue>/ {' \
-e 's/<OutputValue>\([^<]*\)<\/OutputValue>/\1/' \
-e p \
-e '}' -e '}' \
-e d \
)
HOST=`echo $WebsiteURL | sed -r -e 's#http://([^/]+)/.*#\1#'`
retries=9
while ! ping -q -c 1 $HOST >/dev/null && ((retries-- > 0)); do
echo "Waiting for host networking..." >&2
sleep 2
done
test $retries -ge 0
sleep 10
retries=49
while ! ssh -o PasswordAuthentication=no -o StrictHostKeyChecking=no \
-q -t -l ec2-user $HOST \
sudo grep -q mysql-server /var/log/yum.log && \
((retries-- > 0))
do
echo "Waiting for package installation..." >&2
sleep 5
done
test $retries -ge 0
echo "Pausing to wait for application startup..." >&2
sleep 60
Point a web browser at the location given by the ``WebsiteURL`` Output as shown by ``heat-cfn describe``::
wget ${WebsiteURL}
Delete the instance when done
-----------------------------
::
heat-cfn delete wordpress
heat-cfn 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.
IPtables rules
--------------
Some templates require the instances to be able to connect to the heat CFN API (for metadata update via cfn-hup and waitcondition notification via cfn-signal):
Open up port 8000 so that the guests can communicate with the heat-api-cfn server::
sudo iptables -I INPUT -p tcp --dport 8000 -j ACCEPT -i demonetbr0
Open up port 8003 so that the guests can communicate with the heat-api-cloudwatch server::
sudo iptables -I INPUT -p tcp --dport 8003 -j ACCEPT -i demonetbr0
Note the above rules will not persist across reboot, so you may wish to add them to /etc/sysconfig/iptables
Start the Heat Cloudwatch server
--------------------------------
If you wish to try any of the HA or autoscaling templates (which collect stats from instances via the CloudWatch API), it is neccessary to start the heat-api-cloudwatch server::
sudo -E bash -c 'heat-api-cloudwatch &'
Further information on using the heat cloudwatch features is available in the Using-Cloudwatch_ wiki page
.. _Using-Cloudwatch: http://wiki.openstack.org/Heat/Using-CloudWatch
Using the OpenStack Heat API
----------------------------
CloudFormation (heat-api-cfn) and a native OpenStack Heat API (heat-api) are provided. To use the recommended Heat API, a python client library is necessary. To use this library, clone the python-heatclient repository_ from GitHub at ``git://github.com/openstack/python-heatclient.git``.
Install python-heatclient from source
-------------------------------------
In the python-heatclient directory, run the install script::
sudo ./setup.py install
Note that python-heatclient may be installed on a different server than heat itself.
Note that pip can be used to install python-heatclient, but the instructions vary for each distribution. Read your distribution documentation if you wish to install with pip.
Start the OpenStack specific Heat API
-------------------------------------
When using heat-pythonclient, the OpenStack API service provided by heat must be started::
sudo bash -c 'heat-api &'
List stacks
-----------
::
heat stack-list
..
echo; echo 'Success!'

View File

@ -0,0 +1,22 @@
..
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
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

View File

@ -0,0 +1,273 @@
..
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Getting Started With Heat on Ubuntu
===================================
This guide will help to get the current git master of Heat to run on Ubuntu. It makes the following assumptions:
- The host is running Ubuntu 12.04 or 12.10
- There is a working OpenStack installation based on Folsom, Grizzly or Havana, or that one will be installed via the tools/openstack_ubuntu script described below
- Heat will be installed on the controller host of the existing OpenStack installation (or if doing a single-host evaluation, on the same host as all other OpenStack services)
Get Heat
--------
Clone the heat repository_ from GitHub at ``git://github.com/openstack/heat.git``. Note that OpenStack must be installed before heat.
.. _repository: https://github.com/openstack/heat
Install OpenStack
-----------------
Note, this section may be skipped if you already have a working OpenStack installation
Installing OpenStack on Ubuntu 12.04/12.10
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A script called openstack_ubuntu in the tools directory of the Heat repository will install and start OpenStack for you on Ubuntu:
''Note currently only tested on 12.04, if it works for you on 12.10, please let us know''
::
./tools/openstack_ubuntu install -r ${MYSQL_ROOT_PASSWORD}
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 --label=demonet --fixed_range_v4=${SUBNET} --bridge=demonetbr0 --bridge_interface=eth0
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.
The example above assumes you want to bridge with physical device ''eth0''
Currently, the bridge is not created immediately upon running this command, but is actually added when Nova first requires it.
Load keystone authentication into your environment and verify everything is ok.
-------------------------------------------------------------------------------
::
. ~/.openstack/keystonerc
keystone user-list
glance index
nova list
Note ''~/.openstack/keystonerc'' is created by tools/openstack_ubuntu, replace this step with your own credentials file for an admin user if OpenStack was installed by some other method
Install prerequisites
---------------------
::
sudo apt-get install python-pip gcc python2.7-dev
sudo apt-get install git
sudo apt-get install build-essential devscripts debhelper python-all gdebi-core
sudo apt-get install python-setuptools python-prettytable python-lxml
sudo apt-get install libguestfs*
Install python-heatclient (optional)
------------------------------------
*NOTE* If running 12.04 LTS with the packaged Openstack Essex release, do not install python-heatclient, as it will break your OpenStack installation, because it explicitly requires a version of the prettytable library (>0.6) which causes problems with the Essex cli tools (keystone/nova/glance) in 12.04 : https://bugs.launchpad.net/keystone/+bug/995976 The packaged python-prettytable (0.5 version) works OK
::
sudo pip install python-heatclient
Install Heat from master
------------------------
::
git clone git://github.com/openstack/heat.git
cd heat
sudo ./install.sh
Modify configuration for admin password
---------------------------------------
Later a keystone user called '''heat''' will be created. At this point a password for that user needs to be chosen.
The following files will need editing:
- /etc/heat/heat-api-cfn-paste.ini
- /etc/heat/heat-api-cloudwatch-paste.ini
- /etc/heat/heat-api-paste.ini
::
[filter:authtoken]
admin_password=<heat admin password>
Create the MySQL Heat database:
-------------------------------
::
sudo heat-db-setup deb -r <mysql password>
Create the keystone authentication parameters
---------------------------------------------
::
sudo -E ./bin/heat-keystone-setup
Install Oz from the upstream master location
--------------------------------------------
::
git clone https://github.com/clalancette/oz.git
cd oz
make deb
cd ..
sudo dpkg -i oz_*_all.deb
sudo apt-get -f install
Note: Select yes to "Create or update supermin appliance.". This will rebuild the guestfs appliance to work with latest updates of Ubuntu. Oz will not work properly without updating the guestfs appliance.
Note: We recommend cloning oz from the latest master. The debian packaging is broken in older versions and U10/U12 support is not available in Oz shipped with distros.
Install heat-jeos from master
-----------------------------
The heat-jeos tool builds virtual machine images for use with Heat.
::
git clone git://github.com/sdake/heat-jeos.git
cd heat-jeos
sudo python setup.py install
Download ISO images for various distributions
---------------------------------------------
If you just want to try a basic wordpress template, download http://releases.ubuntu.com/10.04.4/ubuntu-10.04.4-server-amd64.iso
If you want to try more templates, also download http://download.fedoraproject.org/pub/fedora/linux/releases/17/Fedora/x86_64/iso/Fedora-17-x86_64-DVD.iso
After download completes, copy the iso image to the location heat-jeos expects:::
sudo cp Downloads/ubuntu-10.04.4-server-amd64.iso /var/lib/libvirt/images
Configure your host to work with Heat
-------------------------------------
Create SSH key and add it to the Nova sshkey list
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
ssh-keygen -t rsa
nova keypair-add --pub_key ~/.ssh/id_rsa.pub ${USER}_key
Note: If running in a VM, modify /etc/libvirt/qemu/networks/default.xml:
change network to not conflict with host (default 192.168.122.x)
::
sudo service libvirt-bin restart
If dnsmasq is not running on the default network
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
sudo virsh net-destroy default
sudo virsh net-start default
Configure libguestfs (required by Oz) to work in latest Ubuntu 12
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Some files shipped with Ubuntu 12 are incompatible with libguestfs
used by the image creation software Oz. To allow heat-jeos to work
properly, run the following commands:
::
sudo chmod 644 /boot/vmlinuz*
sudo update-guestfs-appliance
Note: For more details see: http://permalink.gmane.org/gmane.comp.emulators.guestfs/1382
and http://libguestfs.org/guestfs-faq.1.html
Note: If you want to create F17 images, you may need a new libguestfs binary of version 1.18.0 or later. Ubuntu Precise may not have this version yet.
You can use the Debian Wheezy version including the `guestfs shared library`_, the tools_ and the `python libraries`_.
.. _guestfs shared library: http://packages.debian.org/wheezy/amd64/libguestfs0/download
.. _tools: http://packages.debian.org/wheezy/amd64/libguestfs-tools/download
.. _python libraries: http://packages.debian.org/wheezy/amd64/python-guestfs/download
Create the Heat JEOS image
--------------------------
::
sudo -E heat-jeos -y create U10-x86_64-cfntools --register-with-glance
Note: The -E option to sudo preserves the environment, specifically the keystone credentials, when heat-jeos is run as root.
Note: heat-jeos must be run as root in order to create the cfntools disk image.
Experiment with Heat
--------------------
Execute the heat api services
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
sudo heat-engine &
sudo heat-api &
sudo heat-api-cfn &
sudo heat-api-cloudwatch &
Run the debian wordpress example
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
heat stack-create wordpress --template-file=templates/WordPress_Single_Instance_deb.template --parameters="InstanceType=m1.xlarge;DBUsername=${USER};DBPassword=verybadpassword;KeyName=${USER}_key;LinuxDistribution=U10"
List stacks
~~~~~~~~~~~
::
heat stack-list
List stack events
~~~~~~~~~~~~~~~~~
::
heat event-list wordpress
Describe the wordpress stack
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
heat stack-show wordpress
Note: After a few seconds, the Status should change from IN_PROGRESS to CREATE_COMPLETE.
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.
Point a web browser at the location given by the WebsiteURL Output as shown by heat show-stack wordpress::
::
wget ${WebsiteURL}
Delete the instance when done
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
heat stack-delete wordpress
heat stack-list
Note: This operation will show no running stack.

View File

@ -17,6 +17,9 @@
.. glossary::
OpenStack
Open source software for building private and public clouds.
API server
HTTP REST API service for heat.

View File

@ -22,7 +22,7 @@ What is the purpose of the project and vision for it?
=====================================================
* Heat provides a template based orchestration for describing a cloud application
by executing appropriate OpenStack API calls to generate running cloud applications.
by executing appropriate :term:`OpenStack` API calls to generate running cloud applications.
* The software integrates other core components of OpenStack into a one-file
template system. The templates allow creation of most OpenStack resource types
(such as instances, floating ips, volumes, security groups, users, etc), as well
@ -41,6 +41,8 @@ Table of contents
:maxdepth: 2
man/index
getting_started/index
troubleshooting/index
glossary
.. update index

View File

@ -0,0 +1,19 @@
..
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
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: http://wiki.openstack.org/Heat/TroubleShooting