openstack/openstack-manuals
Code Issues Proposed changes

XenAPI: Cleanup install instructions

Browse Source 
* Removed plugin installation through creating a supplemental pack as the
scripts used to build the pack are no longer part of compute.
* Removed references to XCP, Kronos.
* Amend XenServer download links.
* Remove references to DevStack.
* Remove boot from iso instructions as they are not tested.
* Formatted the sources
* Update links to XenServer 6.2

Partial-Bug: 1021224

Change-Id: I02d2906d1d5d697dfe709b4e2cc532f0f89983d9
This commit is contained in:
Mate Lakat
2014-12-10 09:54:07 +01:00
parent ef83f260d7
commit 8bacea0a6f
4 changed files with 156 additions and 246 deletions
Download Patch File Download Diff File Expand all files Collapse all files

25
doc/config-reference/compute/section_xapi-ami-setup.xml
View File

@@ -6,17 +6,20 @@
xml:id="xapi-ami-setup">
<?dbhtml stop-chunking?>
<title>Prepare for AMI type images</title>
<para>To support AMI type images in your OpenStack installation,
you must create a <filename>/boot/guest</filename> directory
inside Dom0. The OpenStack VM extracts the kernel and ramdisk
from the AKI and ARI images puts them in this location.</para>
<para>OpenStack maintains the contents of this directory and its
size should not increase during normal operation. However, in
case of power failures or accidental shutdowns, some files
might be left over. To prevent these files from filling the
Dom0 disk, set up this directory as a symlink that points to a
subdirectory of the local SR.</para>
<para>Run these commands in Dom0 to achieve this setup:</para>
<para>
To support AMI type images in your OpenStack installation, you must
create the <filename>/boot/guest</filename> directory on dom0. One of
the OpenStack XAPI plugins will extract the kernel and ramdisk from
AKI and ARI images and put them to that directory.
</para>
<para>
OpenStack maintains the contents of this directory and its size should
not increase during normal operation. However, in case of power
failures or accidental shutdowns, some files might be left over. To
prevent these files from filling up dom0's filesystem, set up this
directory as a symlink that points to a subdirectory of the local SR.
</para>
<para>Run these commands in dom0 to achieve this setup:</para>
<screen><prompt>#</prompt> <userinput>LOCAL_SR=$(xe sr-list name-label="Local storage" --minimal)</userinput>
<prompt>#</prompt> <userinput>LOCALPATH="/var/run/sr-mount/$LOCAL_SR/os-guest-kernels"</userinput>
<prompt>#</prompt> <userinput>mkdir -p "$LOCALPATH"</userinput>

93
doc/config-reference/compute/section_xapi-install-plugins.xml
View File

@@ -5,19 +5,24 @@
version="5.0"
xml:id="xapi-install-plugins">
<?dbhtml stop-chunking?>
<title>Install the XenAPI plug-ins</title>
<para>When you use Xen as the hypervisor for OpenStack Compute,
you can install a Python script (or any executable) on the
host side, and call that through the XenAPI. These scripts are
called plug-ins. The XenAPI plug-ins live in the nova code
repository. These plug-ins have to be copied to the Dom0 for
the hypervisor, to the appropriate directory, where xapi can
find them. There are several options for the installation. The
important thing is to ensure that the version of the plug-ins
are in line with the nova installation by only installing
plug-ins from a matching nova repository.</para>
<title>Install XAPI plug-ins</title>
<para>
When you use a XAPI managed hypervisor, you can install a Python script
(or any executable) on the host side, and execute that through XenAPI.
These scripts are called plug-ins. The OpenStack related XAPI plug-ins
live in OpenStack Compute's code repository. These plug-ins have to be
copied to dom0's filesystem, to the appropriate directory, where XAPI
can find them. It is important to ensure that the version of the
plug-ins are in line with the OpenStack Compute installation you are
using.
</para>
<para>
The plugins should typically be copied from the Nova installation
running in the Compute's DomU, but if you want to download the latest
version the following procedure can be used.
</para>
<section xml:id="manual_install">
<title>Manually install the plug-in</title>
<title>Manually installing the plug-ins</title>
<procedure>
<step>
<para>Create temporary files/directories:</para>
@@ -25,70 +30,26 @@
<prompt>$</prompt> <userinput>NOVA_SOURCES=$(mktemp -d)</userinput></screen>
</step>
<step>
<para>Get the source from GitHub. The example assumes
the master branch is used. Amend the URL to match
the version being used:</para>
<screen><prompt>$</prompt> <userinput>wget -qO "$NOVA_ZIPBALL" https://github.com/openstack/nova/archive/master.zip</userinput>
<para>
Get the source from GitHub. The example assumes the master
branch is used, and the XenServer host is accessible
as xenserver. Match those parameters to your setup.
</para>
<screen><prompt>$</prompt> <userinput>NOVA_URL=https://github.com/openstack/nova/archive/master.zip</userinput>
<prompt>$</prompt> <userinput>wget -qO "$NOVA_ZIPBALL" "$NOVA_URL"</userinput>
<prompt>$</prompt> <userinput>unzip "$NOVA_ZIPBALL" -d "$NOVA_SOURCES"</userinput></screen>
<para>(Alternatively) To use the official Ubuntu
packages, use the following commands to get the
nova code base:</para>
<screen><prompt>$</prompt> <userinput>( cd $NOVA_SOURCES &amp;&amp; apt-get source python-nova --download-only )</userinput>
<prompt>$</prompt> <userinput>( cd $NOVA_SOURCES &amp;&amp; for ARCHIVE in *.tar.gz; do tar -xzf $ARCHIVE; done )</userinput></screen>
</step>
<step>
<para>Copy the plug-ins to the hypervisor:</para>
<screen><prompt>$</prompt> <userinput>PLUGINPATH=$(find $NOVA_SOURCES -path '*/xapi.d/plugins' -type d -print)</userinput>
<prompt>$</prompt> <userinput>tar -czf - -C "$PLUGINPATH" ./ | ssh root@xenserver tar -xozf - -C /etc/xapi.d/plugins/</userinput></screen>
<prompt>$</prompt> <userinput>tar -czf - -C "$PLUGINPATH" ./ |</userinput>
<prompt>&gt;</prompt> <userinput>ssh root@xenserver tar -xozf - -C /etc/xapi.d/plugins/</userinput></screen>
</step>
<step>
<para>Remove the temporary files/directories:</para>
<para>Remove temporary files/directories:</para>
<screen><prompt>$</prompt> <userinput>rm "$NOVA_ZIPBALL"</userinput>
<prompt>$</prompt> <userinput>rm -rf "$NOVA_SOURCES"</userinput> </screen>
</step>
</procedure>
</section>
<section xml:id="packaged_install">
<title>Package a XenServer supplemental pack</title>
<para>Follow these steps to produce a supplemental pack from
the nova sources, and package it as a XenServer
supplemental pack.</para>
<procedure>
<step>
<para>Create RPM packages. Given you have the nova
sources. Use one of the methods in <xref
linkend="manual_install"/>:</para>
<screen><prompt>$</prompt> <userinput>cd nova/plugins/xenserver/xenapi/contrib</userinput>
<prompt>$</prompt> <userinput>./build-rpm.sh</userinput></screen>
<para>These commands leave an
<filename>.rpm</filename> file in the
<filename>rpmbuild/RPMS/noarch/</filename>
directory.</para>
</step>
<step>
<para>Pack the RPM packages to a Supplemental Pack,
using the XenServer DDK (the following command
should be issued on the XenServer DDK virtual
appliance, after the produced rpm file has been
copied over):</para>
<screen><prompt>$</prompt> <userinput>/usr/bin/build-supplemental-pack.sh \</userinput>
<prompt>&gt;</prompt> <userinput>--output=output_directory \</userinput>
<prompt>&gt;</prompt> <userinput>--vendor-code=novaplugin \</userinput>
<prompt>&gt;</prompt> <userinput>--vendor-name=openstack \</userinput>
<prompt>&gt;</prompt> <userinput>--label=novaplugins \</userinput>
<prompt>&gt;</prompt> <userinput>--text="nova plugins" \</userinput>
<prompt>&gt;</prompt> <userinput>--version=0 \</userinput>
<prompt>&gt;</prompt> <userinput>full_path_to_rpmfile</userinput></screen>
<para>This command produces an
<filename>.iso</filename> file in the output
directory specified. Copy that file to the
hypervisor.</para>
</step>
<step>
<para>Install the Supplemental Pack. Log in to the
hypervisor, and issue:</para>
<screen><prompt>#</prompt> <userinput>xe-install-supplemental-pack path_to_isofile</userinput></screen>
</step>
</procedure>
</section>
</section>

49
doc/config-reference/compute/section_xapi-resize-setup.xml
View File

@@ -5,32 +5,37 @@
version="5.0"
xml:id="xapi-resize-setup">
<?dbhtml stop-chunking?>
<title>Modify Dom0 for resize/migration support</title>
<para>To resize servers with XenServer and XCP, you must:</para>
<title>Modify dom0 for resize/migration support</title>
<para>To resize servers with XenServer you must:</para>
<itemizedlist>
<listitem>
<para>Establish a root trust between all hypervisor nodes
of your deployment:</para>
<para>To do so, generate an ssh key-pair with the
<command>ssh-keygen</command> command. Ensure that
each of your dom0's
<filename>authorized_keys</filename> file (located
in <filename>/root/.ssh/authorized_keys</filename>)
contains the public key fingerprint (located in
<filename>/root/.ssh/id_rsa.pub</filename>).</para>
<para>
Establish a root trust between all hypervisor nodes
of your deployment:
</para>
<para>
To do so, generate an ssh key-pair with the
<command>ssh-keygen</command> command. Ensure that each of your
dom0's <filename>authorized_keys</filename> file (located in
<filename>/root/.ssh/authorized_keys</filename>) contains the
public key fingerprint (located in
<filename>/root/.ssh/id_rsa.pub</filename>).
</para>
</listitem>
<listitem>
<para>Provide an <filename>/images</filename> mount point
to the dom0 for your hypervisor:</para>
<para>Dom0 space is at a premium so creating a directory
in dom0 is potentially dangerous and likely to fail
especially when you resize large servers. The least
you can do is to symlink <filename>/images</filename>
to your local storage SR. The following instructions
work for an English-based installation of XenServer
(and XCP) and in the case of ext3-based SR (with which
the resize functionality is known to work
correctly).</para>
<para>
Provide a <filename>/images</filename> mount point to the dom0
for your hypervisor:
</para>
<para>
dom0 space is at a premium so creating a directory in dom0 is
potentially dangerous and likely to fail especially when you
resize large servers. The least you can do is to symlink
<filename>/images</filename> to your local storage SR. The
following instructions work for an English-based installation
of XenServer and in the case of ext3-based SR (with which the
resize functionality is known to work correctly).
</para>
<screen><prompt>#</prompt> <userinput>LOCAL_SR=$(xe sr-list name-label="Local storage" --minimal)</userinput>
<prompt>#</prompt> <userinput>IMG_DIR="/var/run/sr-mount/$LOCAL_SR/images"</userinput>
<prompt>#</prompt> <userinput>mkdir -p "$IMG_DIR"</userinput>

235
doc/config-reference/compute/section_xen-install.xml
View File

@@ -4,173 +4,114 @@
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="xenapi-install">
<title xml:id="xenapi-install.title">Install XenServer and
XCP</title>
<para>Before you can run OpenStack with XCP or XenServer, you must
install the software on <link
xlink:href="http://docs.vmd.citrix.com/XenServer/6.0.0/1.0/en_gb/installation.html#sys_requirements"
>an appropriate server</link>.</para>
<title xml:id="xenapi-install.title">Install XenServer</title>
<para>
Before you can run OpenStack with XenServer, you must install the
hypervisor on
<link
xlink:href="http://docs.vmd.citrix.com/XenServer/6.2.0/1.0/en_gb/installation.html#sys_requirements">
an appropriate server
</link>
.
</para>
<note>
<para>Xen is a type 1 hypervisor: When your server starts, Xen
is the first software that runs. Consequently, you must
install XenServer or XCP before you install the operating
system where you want to run OpenStack code. The OpenStack
services then run in a virtual machine that you install on
top of XenServer.</para>
<para>
Xen is a type 1 hypervisor: When your server starts, Xen is the
first software that runs. Consequently, you must install XenServer
before you install the operating system where you want to run
OpenStack code. You then install
<systemitem class="service">nova-compute</systemitem> into a
dedicated virtual machine on the host.
</para>
</note>
<para>Before you can install your system, decide whether to
install a free or paid edition of Citrix XenServer or Xen
Cloud Platform from Xen.org. Download the software from these
locations:</para>
<itemizedlist>
<listitem>
<para><link
xlink:href="http://www.citrix.com/XenServer/download"
>http://www.citrix.com/XenServer/download</link></para>
</listitem>
<listitem>
<para><link
xlink:href="http://www.xen.org/download/xcp/index.html"
>http://www.xen.org/download/xcp/index.html</link></para>
</listitem>
</itemizedlist>
<para>When you install many servers, you might find it easier to
perform <link
xlink:href="http://docs.vmd.citrix.com/XenServer/6.0.0/1.0/en_gb/installation.html#pxe_boot_install"
>PXE boot installations of XenServer or XCP</link>. You
can also package any post-installation changes that you want
to make to your XenServer by <link
xlink:href="http://docs.vmd.citrix.com/XenServer/6.0.0/1.0/en_gb/supplemental_pack_ddk.html"
>creating your own XenServer supplemental
pack</link>.</para>
<para>You can also install the <package>xcp-xenapi</package>
package on Debian-based distributions to get XCP. However,
this is not as mature or feature complete as above
distributions. This modifies your boot loader to first boot
Xen and boot your existing OS on top of Xen as Dom0. The xapi
daemon runs in Dom0. Find more details at <link
xlink:href="http://wiki.xen.org/wiki/Project_Kronos"
>http://wiki.xen.org/wiki/Project_Kronos</link>.</para>
<para>
Use the following link to download XenServer's installation media:
<itemizedlist>
<listitem>
<para>
<link
xlink:href="http://xenserver.org/open-source-virtualization-download.html">
http://xenserver.org/open-source-virtualization-download.html
</link>
</para>
</listitem>
</itemizedlist>
</para>
<para>
When you install many servers, you might find it easier to perform
<link
xlink:href="http://docs.vmd.citrix.com/XenServer/6.2.0/1.0/en_gb/installation.html#pxe_boot_install">
PXE boot installations
</link>
. You can also package any post-installation changes that you want to
make to your XenServer by following the instructions of
<link
xlink:href="http://docs.vmd.citrix.com/XenServer/6.2.0/1.0/en_gb/supplemental_pack_ddk.html">
creating your own XenServer supplemental pack
</link>
.
</para>
<important>
<para>Make sure you use the EXT type of storage repository
(SR). Features that require access to VHD files (such as
copy on write, snapshot and migration) do not work when
you use the LVM SR. Storage repository (SR) is a
XenAPI-specific term relating to the physical storage
where virtual disks are stored.</para>
<para>On the XenServer/XCP installation screen, choose the
<guilabel>XenDesktop Optimized</guilabel> option. If
you use an answer file, make sure you use
<literal>srtype="ext"</literal> in the
<option>installation</option> tag of the answer
file.</para>
<para>
Make sure you use the EXT type of storage repository (SR). Features
that require access to VHD files (such as copy on write, snapshot
and migration) do not work when you use the LVM SR. Storage
repository (SR) is a XAPI-specific term relating to the physical
storage where virtual disks are stored.
</para>
<para>
On the XenServer installation screen, choose the
<guilabel>XenDesktop Optimized</guilabel>
option. If you use an answer file, make sure you use
<literal>srtype="ext"</literal>
in the
<literal>installation</literal>
tag of the answer file.
</para>
</important>
<section xml:id="xenapi-post-install">
<title>Post-installation steps</title>
<para>Complete these steps to install OpenStack in your
XenServer system:</para>
<para>
The following steps need to be completed after the hypervisor's
installation:
</para>
<procedure>
<step>
<para>For resize and migrate functionality, complete
the changes described in the <citetitle>Configure
resize</citetitle> section in the <link
xlink:href="http://docs.openstack.org/trunk/config-reference/content/"
><citetitle>OpenStack Configuration
Reference</citetitle></link>.</para>
<para>
For resize and migrate functionality, enable password-less
SSH authentication and set up the
<literal>/images</literal>
directory on dom0.
</para>
</step>
<step>
<para>Install the VIF isolation rules to help prevent
mac and IP address spoofing.</para>
<para>
Install the XAPI plug-ins.
</para>
</step>
<step>
<para>Install the XenAPI plug-ins. See the following
section.</para>
<para>
To support AMI type images, you must set up
<literal>/boot/guest</literal>
symlink/directory in dom0.
</para>
</step>
<step>
<para>To support AMI type images, you must set up
<literal>/boot/guest</literal>
symlink/directory in Dom0. For detailed
instructions, see next section.</para>
<para>
Create a Paravirtualized virtual machine that can run
<systemitem class="service">nova-compute</systemitem>.
</para>
</step>
<step>
<para>To support resize/migration, set up an ssh trust
relation between your XenServer hosts, and ensure
<literal>/images</literal> is properly set up.
See next section for more details.</para>
</step>
<step>
<para>Create a Paravirtualized virtual machine that
can run the OpenStack compute code.</para>
</step>
<step>
<para>Install and configure the <systemitem
class="service">nova-compute</systemitem> in
the above virtual machine.</para>
<para>
Install and configure
<systemitem class="service">nova-compute</systemitem>
in the above virtual machine.
</para>
</step>
</procedure>
<para>For more information, see how DevStack performs the last
three steps for developer deployments. For more
information about DevStack, see <citetitle>Getting Started
With XenServer and Devstack</citetitle> (<link
xlink:href="https://github.com/openstack-dev/devstack/blob/master/tools/xen/README.md"
>https://github.com/openstack-dev/devstack/blob/master/tools/xen/README.md</link>).
Find more information about the first step, see
<citetitle>Multi Tenancy Networking Protections in
XenServer</citetitle> (<link
xlink:href="https://github.com/openstack/nova/blob/master/plugins/xenserver/doc/networking.rst"
>https://github.com/openstack/nova/blob/master/plugins/xenserver/doc/networking.rst</link>).
For information about how to install the XenAPI plug-ins,
see <citetitle>XenAPI README</citetitle> (<link
xlink:href="https://github.com/openstack/nova/blob/master/plugins/xenserver/xenapi/README"
>https://github.com/openstack/nova/blob/master/plugins/xenserver/xenapi/README</link>).</para>
<xi:include href="section_xapi-install-plugins.xml"/>
<xi:include href="section_xapi-ami-setup.xml"/>
<xi:include href="section_xapi-resize-setup.xml"/>
</section>
<section xml:id="xenapi-boot-from-iso">
<title>Xen boot from ISO</title>
<para>XenServer, through the XenAPI integration with
OpenStack, provides a feature to boot instances from an
ISO file. To activate the Boot From ISO feature, you must
configure the SR elements on XenServer host, as
follows:</para>
<procedure>
<step>
<para>Create an ISO-typed SR, such as an NFS ISO
library, for instance. For this, using XenCenter
is a simple method. You must export an NFS volume
from a remote NFS server. Make sure it is exported
in read-write mode.</para>
</step>
<step>
<para>On the compute host, find and record the UUID of
this ISO SR:</para>
<screen><prompt>#</prompt> <userinput>xe host-list</userinput></screen>
</step>
<step>
<para>Locate the UUID of the NFS ISO library:</para>
<screen><prompt>#</prompt> <userinput>xe sr-list content-type=iso</userinput></screen>
</step>
<step>
<para>Set the UUID and configuration. Even if an NFS
mount point is not local, you must specify
<literal>local-storage-iso</literal>.</para>
<screen><prompt>#</prompt> <userinput>xe sr-param-set uuid=[iso sr uuid] other-config:i18n-key=local-storage-iso</userinput></screen>
</step>
<step>
<para>Make sure the host-UUID from <literal>xe
pbd-list</literal> equals the UUID of the host
you found previously:</para>
<screen><prompt>#</prompt> <userinput>xe sr-uuid=[iso sr uuid]</userinput></screen>
</step>
<step>
<para>You can now add images through the OpenStack
Image Service with
<literal>disk-format=iso</literal>, and boot
them in OpenStack Compute:</para>
<screen><prompt>$</prompt> <userinput>glance image-create --name fedora_iso --disk-format iso --container-format bare &lt; Fedora-16-x86_64-netinst.iso</userinput></screen>
</step>
</procedure>
</section>
</section>