heat/doc/source/getting_started/on_fedora.rst

Getting Started With Heat on Fedora

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.

Install OpenStack

Installing OpenStack on Fedora 17/18

Note:

• On Fedora 17 using the Preview Repository to install the OpenStack Folsom release is recommended
• On Fedora 18 you can use the included OpenStack Folsom release or the Grizzly Preview Repository

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:

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.

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

If running OpenStack grizzly installed via tools/openstack, it is necessary to modify the default service user password:

sudo sed -i "s/verybadpass/secrete/" /etc/heat/heat-api-cfn.conf
sudo sed -i "s/verybadpass/secrete/" /etc/heat/heat-api-cloudwatch.conf
sudo sed -i "s/verybadpass/secrete/" /etc/heat/heat-api.conf

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

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:

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 &'

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