Heat/GettingStartedUsingMasterOnUbuntu

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.10 (please let us know if 12.04 works for you)
There is a working OpenStack installation based on Folsom release or later
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)

Load keystone authentication into your environment and verify everything is ok.

source <keystonerc for an admin user>
keystone user-list

Install prerequisites

sudo apt-get install python-pip gcc python2.7-dev
sudo pip install extras python-heatclient

Install Heat from master

git clone git://github.com/openstack/heat.git  
cd heat
sudo ./install.sh

Modify configuration for message server

Assuming RabbitMQ is used as the message queue, the following files will need editing:

/etc/heat/heat-api.conf
/etc/heat/heat-api-cfn.conf
/etc/heat/heat-api-cloudwatch.conf
/etc/heat/heat-engine.conf

If no password has been set for RabbitMQ, the default password is guest

rpc_backend=heat.openstack.common.rpc.impl_kombu
rabbit_password=<rabbit password>

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/heat-api/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 [Ubuntu 10.04.4 Server](http://releases.ubuntu.com/10.04.4/ubuntu-10.04.4-server-amd64.iso)

If you want to try more templates, also download [Fedora 17](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](http://packages.debian.org/wheezy/amd64/libguestfs0/download), the [tools](http://packages.debian.org/wheezy/amd64/libguestfs-tools/download) and the and the [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.

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.