openstack/openstack-manuals
Code Issues Proposed changes

Merge "Add documentation for Xen via libvirt to config-reference"

Browse Source
This commit is contained in:
Jenkins
2015-07-15 05:00:51 +00:00
committed by Gerrit Code Review
parent 15d965da75 bb15ae4df4
commit 83f4fa820c
6 changed files with 255 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
doc/common/section_kvm_enable.xml
View File

@@ -76,7 +76,7 @@
use a different hypervisor, such as <link
xlink:href="http://docs.openstack.org/trunk/config-reference/content/qemu.html"
>QEMU</link> or <link
xlink:href="http://docs.openstack.org/trunk/config-reference/content/introduction-to-xen.html"
xlink:href="http://docs.openstack.org/trunk/config-reference/content/xen_libvirt.html"
>Xen</link>.</para>
<para>These procedures help you load the kernel modules for
Intel-based and AMD-based processors if they do not load

6
doc/config-reference/compute/section_compute-configure-xen.xml → doc/config-reference/compute/section_compute-configure-xapi.xml
View File

@@ -2,8 +2,8 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="section_compute-configure-xen">
<title>Xen configuration reference</title>
xml:id="section_compute-configure-xapi">
<title>XenAPI configuration reference</title>
<para>
The following section discusses some commonly changed options when
using the XenAPI driver. The table below provides a complete reference
@@ -38,7 +38,7 @@ connection_password = <replaceable>your_password</replaceable></programlisting>
The agent is a piece of software that runs on the instances, and
communicates with OpenStack. In case of the XenAPI driver, the
agent communicates with OpenStack through XenStore (see
<link xlink:href="http://wiki.xen.org/wiki/XenStore">the Xen Wiki</link>
<link xlink:href="http://wiki.xenproject.org/wiki/XenStore">the Xen Project Wiki</link>
for more information on XenStore).
</para>
<para>

12
doc/config-reference/compute/section_compute-hypervisors.xml
View File

@@ -49,8 +49,13 @@
host.</para>
</listitem>
<listitem>
<para><link xlink:href="http://www.xen.org">Xen</link> -
XenServer, Xen Cloud Platform (XCP), use to run Linux
<para><link xlink:href="http://www.xenproject.org">Xen (using libvirt)</link> -
Xen Project Hypervisor using libvirt as management interface into <systemitem
class="service">nova-compute</systemitem> to run Linux, Windows, FreeBSD
and NetBSD virtual machines.</para>
</listitem> <listitem>
<para><link xlink:href="http://www.xenserver.org">XenServer</link> -
XenServer, Xen Cloud Platform (XCP) and other XAPI based Xen variants runs Linux
or Windows virtual machines. You must install the
<systemitem class="service"
>nova-compute</systemitem> service in a
@@ -84,7 +89,8 @@
</section>
<xi:include href="section_hypervisor_kvm.xml"/>
<xi:include href="section_hypervisor_qemu.xml"/>
<xi:include href="section_introduction-to-xen.xml"/>
<xi:include href="section_hypervisor_xen_api.xml"/>
<xi:include href="section_hypervisor_xen_libvirt.xml"/>
<xi:include href="section_hypervisor_lxc.xml"/>
<xi:include href="section_hypervisor_vmware.xml"/>
<xi:include href="section_hypervisor_hyper-v.xml"/>

38
doc/config-reference/compute/section_introduction-to-xen.xml → doc/config-reference/compute/section_hypervisor_xen_api.xml
View File

@@ -3,9 +3,9 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="introduction-to-xen">
xml:id="section_hypervisor_xen_xapi">
<?dbhtml stop-chunking?>
<title xml:id="introduction-to-xen.title">Xen, XAPI, XenServer</title>
<title xml:id="section_hypervisor_xen_xapi.title">XenServer (and other XAPI based Xen variants)</title>
<para>
This section describes XAPI managed hypervisors, and how to
use them with OpenStack.
@@ -17,17 +17,17 @@
<para>
A hypervisor that provides the fundamental isolation between
virtual machines. Xen is open source (GPLv2) and is managed by
Xen.org, a cross-industry organization and a Linux
Foundation Collaborative project.
</para>
<para>
Xen is a component of many different products and projects. The
hypervisor itself is very similar across all these projects,
but the way that it is managed can be different, which can
cause confusion if you're not clear which toolstack you are
using. Make sure you know what toolstack you want before you
get started.
<link xlink:href="http://www.xenproject.org">XenProject.org</link>,
a cross-industry organization and a Linux Foundation Collaborative
project.
</para>
<para>Xen is a component of many different products and projects. The hypervisor itself
is very similar across all these projects, but the way that it is managed can be
different, which can cause confusion if you're not clear which toolstack you are
using. Make sure you know what <link
xlink:href="http://wiki.xen.org/wiki/Choice_of_Toolstacks">toolstack</link> you
want before you get started. If you want to use Xen with libvirt in OpenStack Compute
refer to <xref linkend="xen_libvirt"/>.</para>
</section>
<section xml:id="terminology-xapi">
<title>XAPI</title>
@@ -96,8 +96,8 @@
XAPI toolstack onto an existing Debian-based deployment.
For more information, visit the Xen wiki
<link
xlink:href="http://wiki.xen.org/wiki/Project_Kronos">
wiki.xen.org/wiki/Project_Kronos
xlink:href="http://wiki.xenproject.org/wiki/Project_Kronos">
wiki.xenproject.org/wiki/Project_Kronos
</link>.
</para>
</section>
@@ -265,10 +265,10 @@
</listitem>
<listitem>
<para>
What is Xen? by Xen.org:
What is Xen? by XenProject.org:
<link
xlink:href="http://xen.org/files/Marketing/WhatisXen.pdf">
http://xen.org/files/Marketing/WhatisXen.pdf
xlink:href="http://www.xenproject.org/users/cloud.html">
XenProject.org > Users > Cloud
</link>
</para>
</listitem>
@@ -302,6 +302,6 @@
</itemizedlist>
</para>
</section>
<xi:include href="section_xen-install.xml"/>
<xi:include href="section_compute-configure-xen.xml"/>
<xi:include href="section_xapi-install.xml"/>
<xi:include href="section_compute-configure-xapi.xml"/>
</section>

223
doc/config-reference/compute/section_hypervisor_xen_libvirt.xml Normal file
View File

@@ -0,0 +1,223 @@
<?xml version="1.0" encoding="UTF-8"?>
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="xen_libvirt">
<?dbhtml stop-chunking?>
<title>Xen via Libvirt</title>
<para>OpenStack Compute supports the Xen Project Hypervisor (or Xen). Xen can be integrated with
OpenStack Compute via the <link xlink:href="http://libvirt.org/">libvirt</link>
<link xlink:href="http://wiki.xen.org/wiki/Choice_of_Toolstacks">toolstack</link> or via the
<link xlink:href="http://xenproject.org/developers/teams/xapi.html">XAPI</link>
<link xlink:href="http://wiki.xen.org/wiki/Choice_of_Toolstacks">toolstack</link>. This
section describes how to set up OpenStack Compute with Xen and libvirt. For information on
how to set up Xen with XAPI refer to <xref linkend="section_hypervisor_xen_xapi"/>.</para>
<section xml:id="xen-libvirt-install">
<title>Installing Xen with Libvirt</title>
<para>At this stage we recommend to use the baseline that we use for the <link
xlink:href="http://wiki.xenproject.org/wiki/OpenStack_CI_Loop_for_Xen-Libvirt">Xen
Project OpenStack CI Loop</link>, which contains the most recent stability fixes to
both Xen and Libvirt.</para>
<para><link
xlink:href="http://www.xenproject.org/downloads/xen-archives/xen-45-series/xen-451.html"
>Xen 4.5.1</link> (or newer) and <link xlink:href="http://libvirt.org/sources/"
>Libvirt 1.2.15</link> (or newer) contain the most recent OpenStack improvements for
Xen. The necessary Xen changes have also been backported to the Xen 4.4.3 stable branch
(not yet released at this stage). Please check with the Linux and FreeBSD distros you
are intending to use as <link
xlink:href="http://wiki.xenproject.org/wiki/Category:Host_Install">Dom 0</link>,
whether the relevant version of Xen and Libvirt are available as installable
packages.</para>
<para>The latest releases of Xen and libvirt packages that fulfil the above minimum
requirements for the various openSUSE distributions can always be found and installed
from the <link xlink:href="https://build.opensuse.org/project/show/Virtualization">Open
Build Service</link> Virtualization project. To install these latest packages, add
the Virtualization repository to your software management stack and get the newest
packages from there. More information about the latest Xen and Libvirt packages are
avalable <link xlink:href="https://build.opensuse.org/package/show/Virtualization/xen"
>here</link> and <link
xlink:href="https://build.opensuse.org/package/show/Virtualization/libvirt"
>here</link>.</para>
<para>Alternatively, it is possible to use the Ubuntu LTS 14.04 Xen Package
<emphasis>4.4.1-0ubuntu0.14.04.4</emphasis> (Xen 4.4.1) and apply the patches
outlined <link
xlink:href="http://wiki.xenproject.org/wiki/OpenStack_CI_Loop_for_Xen-Libvirt#Baseline"
>here</link>. You can also use the Ubuntu LTS 14.04 libvirt package <emphasis>1.2.2
libvirt_1.2.2-0ubuntu13.1.7</emphasis> as baseline and update it to libvirt version
1.2.15, or 1.2.14 with the patches outlined <link
xlink:href="http://wiki.xenproject.org/wiki/OpenStack_CI_Loop_for_Xen-Libvirt#Baseline"
>here</link> applied. Note that this will require re-build these packages partly
from source.</para>
<para>For further information and latest developments, you may want to consult the Xen
Project's <link
xlink:href="http://lists.xenproject.org/cgi-bin/mailman/listinfo/wg-openstack"
>mailing lists for OpenStack related issues and questions</link>.</para>
</section>
<section xml:id="xen-libvirt-configuration">
<title>Configuring Xen with Libvirt</title>
<para>To enable Xen via libvirt, ensure the following options are set in
<filename>/etc/nova/nova.conf</filename> on all hosts running the <systemitem class="service"
>nova-compute</systemitem>
service.<programlisting language="ini">compute_driver = libvirt.LibvirtDriver
[libvirt]
virt_type = xen</programlisting></para>
</section>
<section xml:id="xen-libvirt-additional-configuration">
<title>Additional configuration options</title>
<para>Use the following as a guideline for configuring Xen for use in OpenStack:</para>
<orderedlist>
<listitem>
<para><emphasis role="bold">Dom0 Memory:</emphasis> Set it between 1GB and 4GB by
adding the following parameter to the Xen Boot Options in the <filename><link
xlink:href="http://xenbits.xen.org/docs/unstable/misc/xen-command-line.html"
>grub.conf</link></filename> file.
<programlisting language="ini">dom0_mem=1024M</programlisting></para>
<note><para>Note that the above memory limits are suggestions and should be based on
the available compute host resources. For large hosts, that will run many hundred of
instances,the chosen values may need to be higher.</para></note>
<note><para>The location of the grub.conf file depends on the host Linux
distribution that you are using. Please refer to the distro documentation for
more details (see <link xlink:href="http://wiki.xenproject.org/wiki/Category:Host_Install"
>Dom 0</link> for more resources).</para></note>
</listitem>
<listitem>
<para><emphasis role="bold">Dom0 vcpus:</emphasis> Set the virtual CPUs to 4 and
employ CPU pinning by adding the following parameters to the Xen Boot Options in the
<filename><link
xlink:href="http://xenbits.xen.org/docs/unstable/misc/xen-command-line.html"
>grub.conf</link></filename> file.
<programlisting language="ini">dom0_max_vcpus=4 dom0_vcpus_pin</programlisting></para>
<note><para>Note that the above virtual CPU limits are suggestions and should be based on
the available compute host resources. For large hosts, that will run many hundred of
instances, the suggested values may need to be higher.</para></note>
</listitem>
<listitem>
<para><emphasis role="bold">PV vs HVM guests:</emphasis> A Xen virtual machine can
be paravirtualized (PV) or hardware virtualized (HVM). The virtualization mode
determines the interaction between Xen, Dom 0, and the guest VM's kernel. PV guests
are aware of the fact that they are virtualized and will co-operate with Xen and
Dom 0. The choice of virtualization mode determines performance characteristics.
For an overview of Xen virtualization modes, see
<link xlink:href="http://wiki.xen.org/wiki/Xen_Overview#Guest_Types">
Xen Guest Types</link>.</para>
<para>In OpenStack, customer VMs may run in either PV or HVM mode. The mode is a
property of the operating system image used by the VM, and is changed by
adjusting the image metadata stored in the glance image service. The image
metadata can be changed using the nova or glance commands.
</para>
<para>
To choose one of the HVM modes (HVM, HVM with PV Drivers or PVHVM) use nova or
glance to set the vm_mode property to hvm</para>
<para>To choose one of the HVM modes (HVM, HVM with PV Drivers or PVHVM) use one of
the following two commands
<screen><prompt>$</prompt> <userinput>nova image-meta <replaceable>img-uuid</replaceable> set vm_mode=hvm</userinput></screen>
<screen><prompt>$</prompt> <userinput>glance image-update <replaceable>img-uuid</replaceable> --property vm_mode=hvm</userinput></screen>
To chose PV mode, which is supported by NetBSD, FreeBSD and Linux, useone of
the following two commands
<screen><prompt>$</prompt> <userinput>nova image-meta <replaceable>img-uuid</replaceable> set vm_mode=xen</userinput></screen>
<screen><prompt>$</prompt> <userinput>glance image-update <replaceable>img-uuid</replaceable> --property vm_mode=xen</userinput></screen>
</para>
<note><para>The default for virtualization mode in nova is PV mode.</para></note>
</listitem>
<listitem>
<para><emphasis role="bold">Image Formats:</emphasis> Xen supports raw, qcow2 and vhd
image formats. For more information on image formats, refer to the <link
xlink:href="http://docs.openstack.org/image-guide/content/ch_introduction.html"
>OpenStack Virtual Image Guide</link> and the <link
xlink:href="http://wiki.xenproject.org/wiki/Storage_options"
>Storage Options Guide on the Xen Project Wiki</link>.</para>
</listitem>
<listitem>
<para><emphasis role="bold">Image Metadata:</emphasis> In addition to the vm_mode property
discussed above, the hypervisor_type property is another important component of the image
metadata, especially if your cloud contains mixed hypervisor compute nodes. Setting the
hypervisor_type property allows the nova scheduler to select a compute node
running the specified hypervisor when launching instances of the image. Image
metadata such as vm_mode, hypervisor_type, architecture, and others can be set
when importing the image to glance. The metatdata can also be changed using the
nova or glance commands:
<screen><prompt>$</prompt> <userinput>nova image-meta <replaceable>img-uuid</replaceable> set hypervisor_type=xen vm_mode=hvm</userinput></screen>
<screen><prompt>$</prompt> <userinput>glance image-update <replaceable>img-uuid</replaceable> --property hypervisor_type=xen --property vm_mode=hvm</userinput></screen>
</para>
<para>For more more information on image metadata, refer to the <link
xlink:href="http://docs.openstack.org/image-guide/content/image-metadata.html"
>OpenStack Virtual Image Guide</link>.
</para>
</listitem>
</orderedlist>
<para>To customize the libvirt driver, use the configuration option settings documented in
<xref linkend="config_table_nova_xen"/>.
</para>
</section>
<section xml:id="xen-libvirt-troubleshoot">
<title>Troubleshoot Xen with Libvirt</title>
<itemizedlist>
<listitem>
<para><emphasis role="bold">Important Log Files:</emphasis> When an instance fails to start, or when
you come across other issues, you should first consult the following log files:
<itemizedlist>
<listitem><para><filename>/var/log/nova/compute.log</filename> (for more information refer to
<xref linkend="section_nova-logs"/>).</para></listitem>
<listitem><para><filename>/var/log/libvirt/libxl/libxl-driver.log</filename>,</para></listitem>
<listitem><para><filename>/var/log/xen/qemu-dm-${instancename}.log</filename>,</para></listitem>
<listitem><para><filename>/var/log/xen/xen-hotplug.log</filename>,</para></listitem>
<listitem><para><filename>/var/log/xen/console/guest-${instancename}</filename> (to enable see <link
xlink:href="http://wiki.xen.org/wiki/Reporting_Bugs_against_Xen#Guest_console_logs"
>Enabling Guest Console Logs</link>) and</para>
</listitem>
<listitem><para>Host Console Logs (read <link
xlink:href="http://wiki.xen.org/wiki/Reporting_Bugs_against_Xen#Host_console_logs"
>Enabling and Retrieving Host Console Logs</link>).</para>
</listitem>
</itemizedlist>
</para>
<para>If you need further help you can ask questions on the mailing lists <link
xlink:href="http://lists.xenproject.org/cgi-bin/mailman/listinfo/xen-users"
>xen-users@</link>, <link
xlink:href="http://lists.xenproject.org/cgi-bin/mailman/listinfo/wg-openstack"
>wg-openstack@</link> or <link
xlink:href="http://wiki.xen.org/wiki/Reporting_Bugs_against_Xen">raise a
bug</link> against Xen.</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="xen-libvirt-known-issues">
<title>Known issues</title>
<itemizedlist>
<listitem>
<para>Xen via libvirt is currently only supported with nova networking. A number of bugs
are currently worked on to make sure that Xen via libvirt will also work with Neutron.</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="xen-libvirt-additional-information">
<title>Additional information and resources</title>
<para>The following section contains links to other useful resources</para>
<itemizedlist>
<listitem>
<para><link
xlink:href="http://wiki.xenproject.org/wiki/OpenStack"
>wiki.xenproject.org/wiki/OpenStack</link> - OpenStack Documentation on the Xen Project wiki</para>
</listitem>
<listitem>
<para><link
xlink:href="http://wiki.xenproject.org/wiki/OpenStack_CI_Loop_for_Xen-Libvirt"
>wiki.xenproject.org/wiki/OpenStack_CI_Loop_for_Xen-Libvirt</link> - Information about the
Xen Project OpenStack CI Loop</para>
</listitem>
<listitem>
<para><link
xlink:href="http://wiki.xenproject.org/wiki/OpenStack_via_DevStack"
>wiki.xenproject.org/wiki/OpenStack_via_DevStack</link> - How to set up OpenStack via DevStack</para>
</listitem>
<listitem>
<para><link
xlink:href="http://lists.xenproject.org/cgi-bin/mailman/listinfo/wg-openstack"
>Mailing lists for OpenStack related issues and questions</link> - This list is dedicated
to coordinating bug fixes and issues across Xen, libvirt and OpenStack and the CI loop.</para>
</listitem>
</itemizedlist>
</section>
</section>

0
doc/config-reference/compute/section_xen-install.xml → doc/config-reference/compute/section_xapi-install.xml
View File