deb-heat/doc/source/getting_started/jeos_building.rst
Steve Baker a5807e4271 Docs for building heat-cfntools images with diskimage-builder
Change-Id: I5ec805f8800a48b798700532551f0414fc6f6be0
2013-09-15 13:19:57 +10:00

6.7 KiB

Building JEOS images for use with Heat

Heat's full functionality can only be used when launching cloud images that have the heat-cfntools package installed. This document describes some options for creating a heat-cfntools enabled image for yourself.

Building an image with diskimage-builder

diskimage-builder is a tool for customizing cloud images. tripleo-image-elements is a collection of diskimage-builder elements related to the TripleO project. It includes an element for heat-cfntools which can be used to create heat-enabled images.

Fetch the tool and elements:

git clone https://github.com/openstack/diskimage-builder.git
git clone https://github.com/openstack/tripleo-image-elements.git

To create a heat-cfntools enabled image with the current release of Fedora x86_64:

export ELEMENTS_PATH=tripleo-image-elements/elements
diskimage-builder/bin/disk-image-create vm fedora heat-cfntools -a amd64 -o fedora-heat-cfntools

The image may then be pushed to glance, e.g:

source ~/.openstack/keystonerc
glance image-create --name fedora-heat-cfntools --is-public true --disk-format qcow2 --container-format bare < fedora-heat-cfntools.qcow2

To create a heat-cfntools enabled image with the current release of Ubuntu i386:

export ELEMENTS_PATH=tripleo-image-elements/elements
diskimage-builder/bin/disk-image-create vm ubuntu heat-cfntools -a i386 -o ubuntu-heat-cfntools

If you are creating your own images you should consider creating golden images which contain all the packages required for the stacks that you launch. You can do this by writing your own diskimage-builder elements and invoking those elements in the call to disk-image-create.

This means that the resulting heat templates only need to modify configuration files. This will speed stack launch time and reduce the risk of a transient package download failure causing the stack launch to fail.

Building an image with Oz

Another approach to building a heat-cfntools enabled image is to use Oz wrapped in a convenience script.

The example below demonstrates how to build an F17 image, but there are Oz tdl templates for several other distributions provided in heat-templates/jeos

Get heat-templates

Clone the heat-templates repository from GitHub at git://github.com/openstack/heat-templates.git

Note Oz does not work in virt on virt situations. In this case, it is recommended that the prebuilt images are used.

Download OS install DVD and copy it to libvirt images location

sudo cp Downloads/Fedora-17-x86_64-DVD.iso /var/lib/libvirt/images

Install Oz (RPM distros)

We recommend cloning oz from the latest master. Support for building guests based on recent distributions is not available in the version of Oz shipped with many distros.

On Fedora and other RPM-based distros:

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.

Install Oz (DEB distros)

We recommend cloning oz from the latest master. The debian packaging is broken in older versions and support for building guests based on recent distributions is not available in the version of Oz shipped with many distros.

On Fedora and other RPM-based distros:

On Debian, Ubuntu and other deb based distros:

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.

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.

Create a JEOS with heat-jeos.sh script

heat-templates/tools contains a convenience wrapper for Oz which demonstrates how to create a JEOS:

cd heat-templates/tools
sudo ./heat-jeos.sh ../jeos/F17-x86_64-cfntools.tdl F17-x86_64-cfntools

Note: the second argument is the name as defined inside the TDL, so it may not necessarily match the filename

Note: heat-jeos.sh must be run as root in order to create the disk image.

Register the image with glance

On successful completion, the heat-jeos.sh script will generate a qcow2 image under /var/lib/libvirt/images/

The image may then be pushed to glance, e.g:

source ~/.openstack/keystonerc
glance add name=F17-x86_64-cfntools is_public=true disk_format=qcow2 container_format=bare < /var/lib/libvirt/images/F17-x86_64-cfntools.qcow2