heat docs : Update jeos building documentation

Replace references to heat-jeos with documentation describing the
use of the new heat-templates/tools/heat-jeos.sh example script

fixes bug #1171602

Change-Id: I88fd2a5667cccd79a77c4a663c782fb537279fac
This commit is contained in:
Steven Hardy 2013-04-29 18:00:19 +01:00
parent 0524aa2f09
commit 459fb9472c
4 changed files with 140 additions and 111 deletions

View File

@ -21,5 +21,6 @@ Getting Started Guides
on_fedora
on_ubuntu
on_other
jeos_building
.. update index

View File

@ -0,0 +1,113 @@
..
Licensed under the Apache License, Version 2.0 (the "License"); you may
not use this file except in compliance with the License. You may obtain
a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
License for the specific language governing permissions and limitations
under the License.
Building JEOS images for use with Heat
======================================
There are several approaches to building images which will work with heat, but one approach, using Oz wrapped in a convenience script, is documented below
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`_.
.. _guestfs shared library: http://packages.debian.org/wheezy/amd64/libguestfs0/download
.. _tools: http://packages.debian.org/wheezy/amd64/libguestfs-tools/download
.. _python libraries: http://packages.debian.org/wheezy/amd64/python-guestfs/download
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

View File

@ -70,16 +70,12 @@ If you wish to set up OpenStack manually on Fedora, read `Getting Started With O
.. _Getting Started With OpenStack on Fedora: http://fedoraproject.org/wiki/Getting_started_with_OpenStack_on_Fedora_17
.. _Preview Repository: http://fedoraproject.org/wiki/OpenStack#Preview_repository
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 or alternatively generate a JEOS image
-----------------------------------------------
It is possible to either use an image-building tool to create an image or download a prebuilt image of a desired distribution.
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.
@ -94,56 +90,14 @@ 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
---------------------------------------------------------------------------
Alternatively see JEOS image-building documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
::
If you wish to create your own JEOS image from scratch, there are a number of approaches which can be used.
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.
One approach is using the Oz image-building tool, which is documented in the `jeos building documentation`_.
.. _jeos building documentation: http://docs.openstack.org/developer/heat/getting_started/jeos_building.html
Install and Configure Heat
~~~~~~~~~~~~~~~~~~~~~~~~~~

View File

@ -123,41 +123,34 @@ Create the keystone authentication parameters
sudo -E ./bin/heat-keystone-setup
Install Oz from the upstream master location
--------------------------------------------
Download or alternatively generate a JEOS image
----------------------------------------------
It is possible to either use an image-building tool to create an image or download a prebuilt image of a desired distribution.
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 U10-x86_64-cfntools qcow2 was downloaded.
::
git clone https://github.com/clalancette/oz.git
cd oz
make deb
cd ..
sudo dpkg -i oz_*_all.deb
sudo apt-get -f install
sudo cp Downloads/U10-x86_64-cfntools.qcow2 /var/lib/libvirt/images
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.
Register with glance:
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/sdake/heat-jeos.git
cd heat-jeos
sudo python setup.py install
glance image-create --name=U10-x86_64-cfntools --disk-format=qcow2 --container-format=bare < /var/lib/libvirt/images/U10-x86_64-cfntools.qcow2
Download ISO images for various distributions
---------------------------------------------
If you just want to try a basic wordpress template, download http://releases.ubuntu.com/10.04.4/ubuntu-10.04.4-server-amd64.iso
Alternatively see JEOS image-building documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you want to try more templates, also download http://download.fedoraproject.org/pub/fedora/linux/releases/17/Fedora/x86_64/iso/Fedora-17-x86_64-DVD.iso
If you wish to create your own JEOS image from scratch, there are a number of approaches which can be used.
After download completes, copy the iso image to the location heat-jeos expects:::
One approach is using the Oz image-building tool, which is documented in the `jeos building documentation`_.
sudo cp Downloads/ubuntu-10.04.4-server-amd64.iso /var/lib/libvirt/images
.. _jeos building documentation: http://docs.openstack.org/developer/heat/getting_started/jeos_building.html
Configure your host to work with Heat
-------------------------------------
@ -183,38 +176,6 @@ 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`_, the tools_ and the `python libraries`_.
.. _guestfs shared library: http://packages.debian.org/wheezy/amd64/libguestfs0/download
.. _tools: http://packages.debian.org/wheezy/amd64/libguestfs-tools/download
.. _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
--------------------