heat/docs/GettingStarted.rst

Getting Started With Heat

Get Heat

Clone the heat repository from GitHub at git://github.com/heat-api/heat.git. Note that OpenStack must be installed before heat.

Install OpenStack

Installing OpenStack on Fedora 16 and 17

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

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.

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.

Install OZ

It is recommended to install the latest upstream oz, as this supports Fedora 17 (and Ubuntu U10/U12) guests:

git clone https://github.com/clalancette/oz.git
pushd oz
rm -f ~/rpmbuild/RPMS/noarch/oz-*
make rpm
sudo yum localinstall -y ~/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

Install heat from source

In the heat directory, run the install script:

sudo ./install.sh

Configure the Metadata server

The Heat Metadata server must be configured to bind to the IP address of the host machine on the Nova network created above (demonetbr0). This allows the launched instances to access the metadata server.

Edit the file /etc/heat/heat-metadata.conf to change the bind_host value from the default 0.0.0.0 to the correct IP address:

sudo sed -i -e "/^bind_host *=/ s/0\.0\.0\.0/${BIND_IP}/" /etc/heat/heat-metadata.conf

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.

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

Download and install heat_jeos via git

Download heat_jeos via git

git clone git://github.com/heat-api/heat-jeos.git
pushd heat-jeos
sudo python setup.py install
popd

Create a JEOS with heat_jeos tools

sudo -E heat-jeos -y create F16-x86_64-cfntools-jeos --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.

Verify JEOS registration

Check that there is a F16-x86_64-cfntools JEOS in glance:

glance index

Launch the Heat services

sudo -E bash -c 'heat-api & heat-engine & heat-metadata &'

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 event-list wordpress

Describe the wordpress stack

heat describe wordpress

After a few seconds, the StackStatus should change from CREATE_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. 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.

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