Heat/GettingStartedUsingMasterOnUbuntu

NOTE (7/24/2014): this document is no longer maintained, Ubuntu users should refer to the documentation here: http://docs.openstack.org/developer/heat/getting_started/on_ubuntu.html

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 Essex or Folsom, 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:

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

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:

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.
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 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

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

Install Oz from the upstream master location
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.

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:

Create SSH key and add it to the Nova sshkey list
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)

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:

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
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.

Describe the wordpress stack
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::

Delete the instance when done
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.