openstack/openstack-manuals
Code Issues Proposed changes
1d75d9ec43
openstack-manuals/doc/admin-guide-cloud/ch_compute.xml
Diane Fleming ccb80d725d Renamed cli files for consistency 
Updated a typo (keystone-mange -> keystone-manage)
Updated a few capitalization errors in titles

Change-Id: I38ec2a6c53b9e3a1e1bf330b54c26f293a764d94
author: diane fleming
2014-01-06 15:06:29 -06:00

2606 lines
146 KiB
XML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<?xml version="1.0" encoding="UTF-8"?>
<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xlink="http://www.w3.org/1999/xlink"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns:html="http://www.w3.org/1999/xhtml" version="5.0"
xml:id="ch_introduction-to-openstack-compute">
<?dbhtml stop-chunking?>
<title>Compute</title>
<para>
The OpenStack Compute service allows you to control an
Infrastructure-as-a-Service (IaaS) cloud computing platform. It gives
you control over instances and networks, and allows you to manage
access to the cloud through users and projects.
</para>
<para>
Compute does not include any virtualization software. Instead, it
defines drivers that interact with underlying virtualization mechanisms
that run on your host operating system, and exposes functionality over
a web-based API.
</para>
<section xml:id="section_hypervisors">
<title>Hypervisors</title>
<para>
Compute controls hypervisors through an API server. Selecting the
best hypervisor to use can be difficult, and you must take budget,
resource constraints, supported features, and required technical
specifications into account. However, the majority of OpenStack
development is done on systems using KVM and Xen-based hypervisors.
For a detailed list of features and support across different
hypervisors, see <link xlink:href="http://wiki.openstack.org/HypervisorSupportMatrix">http://wiki.openstack.org/HypervisorSupportMatrix</link>.
</para>
<para>
You can also orchestrate clouds using multiple hypervisors in
different availability zones. The types of virtualization standards
that can be used with Compute include:
</para>
<itemizedlist>
<listitem>
<para>
<link xlink:href="https://wiki.openstack.org/wiki/Baremetal">Baremetal</link>
</para>
</listitem>
<listitem>
<para>
<link xlink:href="http://www.microsoft.com/en-us/server-cloud/hyper-v-server/default.aspx">Hyper-V</link>
</para>
</listitem>
<listitem>
<para>
<link xlink:href="http://www.linux-kvm.org/page/Main_Page">Kernel-based Virtual Machine (KVM)</link>
</para>
</listitem>
<listitem>
<para>
<link xlink:href="http://lxc.sourceforge.net/">Linux Containers (LXC)</link>
</para>
</listitem>
<listitem>
<para>
<link xlink:href="http://wiki.qemu.org/Manual">Quick Emulator (QEMU)</link>
</para>
</listitem>
<listitem>
<para>
<link xlink:href="http://user-mode-linux.sourceforge.net/">User Mode Linux (UML)</link>
</para>
</listitem>
<listitem>
<para>
<link xlink:href="http://www.vmware.com/products/vsphere-hypervisor/support.html">VMWare vSphere</link>
</para>
</listitem>
<listitem>
<para>
<link xlink:href="http://www.xen.org/support/documentation.html">Xen</link>
</para>
</listitem>
</itemizedlist>
<para>
For more information about hypervisors, see the <link xlink:href="http://docs.openstack.org/trunk/config-reference/content/section_compute-hypervisors.html">Hypervisors</link>
section in the <citetitle>OpenStack Configuration Reference</citetitle>.
</para>
</section>
<section xml:id="section_users-and-projects">
<title>Tenants, users, and roles</title>
<para>
The Compute system is designed to be used by different consumers
in the form of tenants on a shared system, and role-based access
assignments. Roles control the actions that a user is allowed to
perform.
</para>
<para>
Tenants are isolated resource containers that form the principal
organizational structure within the Compute service. They
consist of an individual VLAN, and volumes, instances, images,
keys, and users. A user can specify the tenant by appending
<literal>:project_id</literal> to their access key. If no
tenant is specified in the API request, Compute attempts to
use a tenant with the same ID as the user.
</para>
<para>
For tenants, quota controls are available to limit the:
</para>
<itemizedlist>
<listitem>
<para>number of volumes that may be launched.</para>
</listitem>
<listitem>
<para>number of processor cores and the amount of RAM
that can be allocated.</para>
</listitem>
<listitem>
<para>floating IP addresses assigned to any instance
when it launches. This allows instances to have the
same publicly accessible IP addresses.</para>
</listitem>
<listitem>
<para>fixed IP addresses assigned to the same instance
when it launches. This allows instances to have the
same publicly or privately accessible IP addresses.
</para>
</listitem>
</itemizedlist>
<para>
Roles control the actions a user is allowed to perform. By
default, most actions do not require a particular role, but
you can configure them by editing the
<filename>policy.json</filename> file for user roles. For
example, a rule can be defined so that a user must have the
<parameter>admin</parameter> role in order to be able to
allocate a public IP address.
</para>
<para>
A tenant limits users' access to particular images. Each
user is assigned a username and password. Keypairs granting
access to an instance are enabled for each user, but quotas
are set, so that each tenant can control resource consumption
across available hardware resources.
</para>
<note>
<para>
Earlier versions of OpenStack used the term
<systemitem class="service">project</systemitem> instead
of <systemitem class="service">tenant</systemitem>.
Because of this legacy terminology, some command-line
tools use <parameter>--project_id</parameter> where you
would normally expect to enter a tenant ID.
</para>
</note>
</section>
<section xml:id="section_images-and-instances">
<title>Images and instances</title>
<para>Disk images provide templates for virtual machine file systems.
The Glance service manages storage and management of images.</para>
<para>Instances are the individual virtual machines that run on
physical compute nodes. Users can launch any number of instances
from the same image. Each launched instance runs from a copy of the
base image so that any changes made to the instance do not affect
the base image. You can take snapshots of running instances to
create an image based on the current disk state of a particular
instance. The Compute services manages instances.</para>
<para>For more information about creating and troubleshooting images,
see the <link
xlink:href="http://docs.openstack.org/user-guide-admin/content/cli_manage_images.html"
>Manage Images</link> section of the <citetitle>OpenStack Admin
User Guide</citetitle>.</para>
<para>For more information about image configuration options, see the
<link
xlink:href="http://docs.openstack.org/trunk/config-reference/content/ch_configuring-openstack-image-service.html"
>Image Services</link> section of the <citetitle>OpenStack
Configuration Reference</citetitle>.</para>
<para>When you launch an instance, you must choose a
<literal>flavor</literal>, which represents a set of virtual
resources. Flavors define how many virtual CPUs an instance has and
the amount of RAM and size of its ephemeral disks. OpenStack
provides a number of predefined flavors that you can edit or add to.
Users must select from the set of available flavors defined on their
cloud.</para>
<para>For more information about flavors, see the <link
xlink:href="http://docs.openstack.org/trunk/openstack-ops/content/flavors.html"
>Flavors</link> section in the <citetitle>OpenStack Operations
Guide</citetitle>.</para>
<para>You can add and remove additional resources from running
instances, such as persistent volume storage, or public IP
addresses. The example used in this chapter is of a typical virtual
system within an OpenStack cloud. It uses the <systemitem
class="service">cinder-volume</systemitem> service, which
provides persistent block storage, instead of the ephemeral storage
provided by the selected instance flavor.</para>
<para>This diagram shows the system state prior to launching an
instance. The image store, fronted by the image service, Glance, has
a number of predefined images. Inside the cloud, a compute node
contains the available vCPU, memory, and local disk resources.
Additionally, the <systemitem class="service"
>cinder-volume</systemitem> service provides a number of
predefined volumes.</para>
<figure xml:id="initial-instance-state-figure">
<title>Base image state with no running instances</title>
<mediaobject>
<imageobject>
<imagedata fileref="../common/figures/instance-life-1.png"/>
</imageobject>
</mediaobject>
</figure>
<para>To launch an instance, select an image, a flavor, and other
optional attributes. The selected flavor provides a root volume,
labeled <literal>vda</literal> in this diagram, and additional
ephemeral storage, labeled <literal>vdb</literal>. In this example,
the <systemitem class="service">cinder-volume</systemitem> store is
mapped to the third virtual disk on this instance,
<literal>vdc</literal>.</para>
<figure xml:id="run-instance-state-figure">
<title>Instance creation from image and runtime state</title>
<mediaobject>
<imageobject>
<imagedata fileref="../common/figures/instance-life-2.png"/>
</imageobject>
</mediaobject>
</figure>
<para>The base image is copied from the image store to the local disk.
The local disk is the first disk that the instance accesses, and is
labeled <literal>vda</literal>. By using smaller images, your
instances start up faster as less data needs to be copied across
the network.</para>
<para>A new empty disk, labeled <literal>vdb</literal> is also created.
This is an empty ephemeral disk, which is destroyed when you delete
the instance.</para>
<para>The compute node is attached to the <systemitem class="service"
>cinder-volume</systemitem> using iSCSI, and maps to the
third disk, <literal>vdc</literal>. The vCPU and memory resources
are provisioned and the instance is booted from
<literal>vda</literal>. The instance runs and changes data on
the disks as indicated in red in the diagram.
<!--This isn't very accessible, need to consider rewording to explain more fully. LKB -->
</para>
<note>
<para>Some of the details in this example scenario might be
different in your environment. Specifically, you might use a
different type of back-end storage or different network
protocols. One common variant is that the ephemeral storage used
for volumes <literal>vda</literal> and <literal>vdb</literal>
could be backed by network storage rather than a local disk.</para>
</note>
<para>When the instance is deleted, the state is reclaimed with the
exception of the persistent volume. The ephemeral storage is purged,
memory and vCPU resources are released. The image remains unchanged
throughout.</para>
<figure xml:id="end-instance-state-figure">
<title>End state of image and volume after instance exits</title>
<mediaobject>
<imageobject>
<imagedata fileref="../common/figures/instance-life-3.png"/>
</imageobject>
</mediaobject>
</figure>
</section>
<section xml:id="section_system-architecture">
<title>System architecture</title>
<para>
OpenStack Compute contains several main components. The
<firstterm>cloud controller</firstterm> represents the global state
and interacts with the other components. The
<literal>API server</literal> acts as the web services
front end for the cloud controller. The
<literal>compute controller</literal> provides compute server
resources and usually also contains the Compute service.
</para>
<para>
The <literal>object store</literal> is an optional component
that provides storage services. An <literal>auth manager</literal>
provides authentication and authorization services when used
with the Compute system, or you can use the <literal>identity
service</literal> as a separate authentication service instead.
A <literal>volume controller</literal> provides fast and
permanent block-level storage for the compute servers. The
<literal>network controller</literal> provides virtual networks
to enable compute servers to interact with each other and with
the public network. The <literal>scheduler</literal> is used to
select the most suitable compute controller to host an instance.
</para>
<para>
Compute uses a messaging-based, <literal>shared nothing</literal>
architecture. All major components exist on multiple
servers, including the compute, volume, and network controllers,
and the object store or image service. The state of the entire
system is stored in a database. The cloud controller
communicates with the internal object store using HTTP, but it
communicates with the scheduler, network controller, and volume
controller using AMQP (advanced message queueing protocol). To
avoid blocking a component while waiting for a response,
Compute uses asynchronous calls, with a callback that is
triggered when a response is received.
</para>
</section>
<section xml:id="section_storage-and-openstack-compute">
<title>Block storage</title>
<para>
OpenStack provides two classes of block storage: ephemeral
storage and persistent volumes. Volumes are persistent virtualized block devices
independent of any particular instance.
</para>
<para>
Ephemeral storage is associated with a single unique instance,
and it exists only for the life of that instance. The amount
of ephemeral storage is defined by the flavor of the instance.
Generally, the root file system for an instance will be stored
on ephemeral storage. It persists across reboots of the guest
operating system, but when the instance is deleted, the
ephemeral storage is also removed.
</para>
<para>
In addition to the ephemeral root volume, all flavors except
the smallest, <filename>m1.tiny</filename>, also provide an
additional ephemeral block device of between 20 and 160GB.
These sizes can be configured to suit your environment. This is
presented as a raw block device with no partition table or
file system. Cloud-aware operating system images can discover,
format, and mount these storage devices. For example, the
<systemitem class="service">cloud-init</systemitem> package
included in Ubuntu's stock cloud images format this space as
an <filename>ext3</filename> file system and mount it on
<filename>/mnt</filename>. This is a feature of the guest
operating system you are using, and is not an OpenStack mechanism.
OpenStack only provisions the raw storage.
</para>
<para>
Persistent volumes are created by users and their size is
limited only by the user's quota and availability limits. Upon
initial creation, volumes are raw block devices without a
partition table or a file system. To partition or format
volumes, you must attach them to an instance. Once they are
attached to an instance, you can use persistent volumes in much
the same way as you would use external hard disk drive. You
can attach volumes to only one instance at a time, although you
can detach and reattach volumes to as many different instances
as you like.
</para>
<para>
Persistent volumes can be configured as bootable and used to
provide a persistent virtual instance similar to traditional
non-cloud-based virtualization systems. Typically, the
resulting instance can also still have ephemeral storage depending
on the flavor selected, but the root file system can be on the
persistent volume and its state maintained even if the instance
is shut down. For more information about this type of configuration,
see the <citetitle>OpenStack Configuration Reference</citetitle>.
</para>
<note>
<para>
Persistent volumes do not provide concurrent access from
multiple instances. That type of configuration requires a
traditional network file system like NFS or CIFS, or a cluster
file system such as GlusterFS. These systems can be built
within an OpenStack cluster or provisioned outside of it,
but OpenStack software does not provide these features.
</para>
</note>
</section>
<section xml:id="section_image-mgmt">
<title>Image management</title>
<para>The OpenStack Image service discovers, registers, and retrieves
virtual machine images. The service also includes a RESTful API
that allows you to query VM image metadata and retrieve the actual
image with HTTP requests. For more information about the API, see
the <link xlink:href="http://api.openstack.org/api-ref.html#os-images-2.0">
OpenStack API</link> or the
<link xlink:href="http://docs.openstack.org/developer/python-glanceclient/">
Python API</link>.
</para>
<para>
The OpenStack Image service can be controlled using a command line
tool. For more information about the OpenStack Image command line
tool, see the <link xlink:href="http://docs.openstack.org/user-guide/content/cli_manage_images.html">
Image Management</link> section in the <citetitle>OpenStack User Guide</citetitle>.
</para>
<para>
Virtual images that have been made available through the Image
service can be stored in a variety of ways. In order to use these
services, you must have a working installation of the Image service,
with a working endpoint, and users that have been created in the
Identity service. Additionally, you must meet the environment
variables required by the Compute and Image clients.
</para>
<para>
The Image service supports these back end stores:
</para>
<variablelist>
<varlistentry>
<term>File system</term>
<listitem>
<para>The OpenStack Image service stores virtual machine
images in the file system back-end by default. This simple
back end writes image files to the local file system.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Object Storage service</term>
<listitem>
<para>OpenStack's highly-available object storage.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>S3</term>
<listitem>
<para>Amazon’s S3 service.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>HTTP</term>
<listitem>
<para>OpenStack Image Service can read virtual machine images
that are available on the internet using HTTP. This store
is read only.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Rados block device (RBD)</term>
<listitem>
<para>Stores images inside of a Ceph storage cluster using
Ceph's RBD interface.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>GridFS</term>
<listitem>
<para>Stores images using MongoDB.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="section_instance-mgmt">
<title>Instance management tools</title>
<para>
OpenStack provides command line, web-based, and API-based
instance management tools. Additionally, a number of third party
management tools are available, using either the native API or the
provided EC2-compatible API.
</para>
<para>
The OpenStack <application>python-novaclient</application>
package provides a basic command line utility, which uses the
<command>nova</command> command. This is available as a native
package for most Linux distributions, or you can install the latest
version using the <application>pip</application> python package installer:
<programlisting language="bash">sudo pip install python-novaclient</programlisting>
</para>
<para>
For more information about <application>python-novaclient</application>
and other available command line tools, see the
<link xlink:href="http://docs.openstack.org/user-guide/content/index.html">
<citetitle>OpenStack End User Guide</citetitle></link>.
</para>
<!--
I've commented this section out as it merely repeats what's in the
End User Guide, and isn't required here. Comments welcome. LKB
<para>What follows is
the minimal introduction required to follow the
CLI example in this chapter. In case of a conflict
in <link
xlink:href="http://docs.openstack.org/user-guide/content/index.html"
><citetitle>OpenStack End User
Guide</citetitle></link> should be
considered authoritative (and a bug filed against
this section).</para>
<para>To function, the <application>nova</application>
CLI needs this information:</para>
<itemizedlist>
<listitem>
<para><literal>Authentication URL</literal>:
This can be passed as the
<parameter>&ndash;&ndash;os_auth_url</parameter>
flag or using the OS_AUTH_URL environment
variable.</para>
</listitem>
<listitem>
<para><literal>Tenant (sometimes referred to
as project) name</literal>: This can
be passed as the
<parameter>&ndash;&ndash;os_tenant_name</parameter>
flag or using the OS_TENANT_NAME
environment variable.</para>
</listitem>
<listitem>
<para><literal>User name</literal>: This can
be passed as the
<parameter>&ndash;&ndash;os_username</parameter>
flag or using the OS_USERNAME environment
variable.</para>
</listitem>
<listitem>
<para><literal>Password</literal>: This can be
passed as the
<parameter>&ndash;&ndash;os_password</parameter>
flag or using the OS_PASSWORD environment
variable.</para>
</listitem>
</itemizedlist>
<para>For example if you have your Identity Service
running on the default port (5000) on host
keystone.example.com and want to use the
<application>nova</application> cli as the
user "demouser" with the password "demopassword"
in the "demoproject" tenant you can export the
following values in your shell environment or pass
the equivalent command line args (presuming these
identities already exist):</para>
<screen><prompt>$</prompt> <userinput>export OS_AUTH_URL="http://keystone.example.com:5000/v2.0/"</userinput>
<prompt>$</prompt> <userinput>export OS_USERNAME=demouser</userinput>
<prompt>$</prompt> <userinput>export OS_PASSWORD=demopassword</userinput>
<prompt>$</prompt> <userinput>export OS_TENANT_NAME=demoproject</userinput></screen>
<para>If you use the <link
linkend="instance-mgmt-horizon">Horizon</link>
web dashboard, you can download credential files
that contain the correct values for your
particular implementation.</para>
</simplesect>-->
<!-- Commented out because it repeats information earlier in this chapter. LKB
<simplesect xml:id="instance-mgmt-horizon">
<para>
Horizon is a highly customizable and extensible OpenStack web
dashboard. For more information on Horizon, see the
<link xlink:href="http://docs.openstack.org/developer/horizon">
Horizon project site</link>.
</para>
<para>OpenStack provides a RESTful API for all functionality. Complete
API documentation is available at <link
xlink:href="http://api.openstack.org/api-ref.html">OpenStack API
Reference</link>. The <link
xlink:href="http://docs.openstack.org/api/openstack-compute/2/content/"
><citetitle>OpenStack Compute API v2 and Extensions
Reference</citetitle></link> documentation refers to
instances as <firstterm>servers</firstterm>.</para>
<para>The <link linkend="instance-mgmt-novaclient">nova cli</link> can
be made to show the API calls it is making by passing it the
<parameter>&ndash;&ndash;debug</parameter> parameter:</para>-->
<screen><prompt>#</prompt> <userinput>nova --debug list</userinput>
<?db-font-size 75%?><computeroutput>connect: (10.0.0.15, 5000)
send: 'POST /v2.0/tokens HTTP/1.1\r\nHost: 10.0.0.15:5000\r\nContent-Length: 116\r\ncontent-type: application/json\r\naccept-encoding: gzip, deflate\r\naccept: application/json\r\nuser-agent: python-novaclient\r\n\r\n{"auth": {"tenantName": "demoproject", "passwordCredentials": {"username": "demouser", "password": "demopassword"}}}'
reply: 'HTTP/1.1 200 OK\r\n'
header: Content-Type: application/json
header: Vary: X-Auth-Token
header: Date: Thu, 13 Sep 2012 20:27:36 GMT
header: Transfer-Encoding: chunked
connect: (128.52.128.15, 8774)
send: u'GET /v2/fa9dccdeadbeef23ae230969587a14bf/servers/detail HTTP/1.1\r\nHost: 10.0.0.15:8774\r\nx-auth-project-id: demoproject\r\nx-auth-token: deadbeef9998823afecc3d552525c34c\r\naccept-encoding: gzip, deflate\r\naccept: application/json\r\nuser-agent: python-novaclient\r\n\r\n'
reply: 'HTTP/1.1 200 OK\r\n'
header: X-Compute-Request-Id: req-bf313e7d-771a-4c0b-ad08-c5da8161b30f
header: Content-Type: application/json
header: Content-Length: 15
header: Date: Thu, 13 Sep 2012 20:27:36 GMT
!!removed matrix for validation!! </computeroutput></screen>
</section>
<section xml:id="instance-mgmt-ec2compat">
<title>EC2 compatibility API</title>
<para>In addition to the native compute API, OpenStack provides an
EC2-compatible API. This API allows EC2 legacy workflows built for
EC2 to work with OpenStack.</para>
<para>The <citetitle>OpenStack Configuration Reference</citetitle> lists
configuration options for customizing this compatibility API on your
OpenStack cloud.</para>
<para>Numerous third party tools and language-specific SDKs can be used
to interact with OpenStack clouds, using both native and
compatibility APIs. Some of the more popular third-party tools are:</para>
<variablelist>
<varlistentry>
<term>Euca2ools</term>
<listitem>
<para>A popular open source command line tool for
interacting with the EC2 API. This is convenient for
multi-cloud environments where EC2 is the common API, or
for transitioning from EC2-based clouds to OpenStack.
For more information, see the <link
xlink:href="http://open.eucalyptus.com/wiki/Euca2oolsGuide"
>euca2ools site</link>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Hybridfox</term>
<listitem>
<para>A Firefox browser add-on that provides a graphical
interface to many popular public and private cloud
technologies, including OpenStack. For more information,
see the <link
xlink:href="http://code.google.com/p/hybridfox/">
hybridfox site</link>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>boto</term>
<listitem>
<para>A Python library for interacting with Amazon Web
Services. It can be used to access OpenStack through the
EC2 compatibility API. For more information, see the
<link xlink:href="https://github.com/boto/boto">
boto project page on GitHub</link>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>fog</term>
<listitem>
<para>A Ruby cloud services library. It provides methods for
interacting with a large number of cloud and
virtualization platforms, including OpenStack. For more
information, see the <link
xlink:href="https://rubygems.org/gems/fog"> fog
site</link>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>php-opencloud</term>
<listitem>
<para>A PHP SDK designed to work with most OpenStack- based
cloud deployments, as well as Rackspace public cloud.
For more information, see the <link
xlink:href="http://www.php-opencloud.com">
php-opencloud site</link>.</para>
</listitem>
</varlistentry>
</variablelist>
</section>
<section xml:id="section_instance-building-blocks">
<title>Building blocks</title>
<!-- <para>There are two fundamental requirements for a
computing system, software and hardware.
Virtualization and cloud frameworks tend to blur these
lines and some of your "hardware" might actually be
"software" but conceptually you still need an
operating system and something to run it on.</para>-->
<para>
In OpenStack the base operating system is usually copied from
an image stored in the OpenStack Image service. This is the
most common case and results in an ephemeral instance that
starts from a known template state and loses all accumulated
states on shutdown. It is also possible to put an operating
system on a persistent volume in the Nova-Volume or Cinder
volume system. This gives a more traditional persistent
system that accumulates states, which are preserved across
restarts. To get a list of available images on your system run:
<screen><prompt>$</prompt> <userinput>nova image-list</userinput>
<?db-font-size 50%?><computeroutput>+--------------------------------------+-------------------------------+--------+--------------------------------------+
| ID | Name | Status | Server |
+--------------------------------------+-------------------------------+--------+--------------------------------------+
| aee1d242-730f-431f-88c1-87630c0f07ba | Ubuntu 12.04 cloudimg amd64 | ACTIVE | |
| 0b27baa1-0ca6-49a7-b3f4-48388e440245 | Ubuntu 12.10 cloudimg amd64 | ACTIVE | |
| df8d56fc-9cea-4dfd-a8d3-28764de3cb08 | jenkins | ACTIVE | |
+--------------------------------------+-------------------------------+--------+--------------------------------------+</computeroutput></screen>
</para>
<para>
The displayed image attributes are:
</para>
<variablelist>
<varlistentry>
<term><literal>ID</literal></term>
<listitem>
<para>Automatically generated UUID of the image</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>Name</literal></term>
<listitem>
<para>Free form, human-readable name for image</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>Status</literal></term>
<listitem>
<para>The status of the image. Images marked
<literal>ACTIVE</literal> are available for use.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>Server</literal></term>
<listitem>
<para>For images that are created as snapshots of running
instances, this is the UUID of the instance the snapshot
derives from. For uploaded images, this field is blank.</para>
</listitem>
</varlistentry>
</variablelist>
<para>
Virtual hardware templates are called <literal>flavors</literal>.
The default installation provides five flavors. By default,
these are configurable by admin users, however that behavior
can be changed by redefining the access controls for
<parameter>compute_extension:flavormanage</parameter> in
<filename>/etc/nova/policy.json</filename> on the
<filename>compute-api</filename> server.
</para>
<para>
For a list of flavors that are available on your system:
</para>
<screen><prompt>$</prompt> <userinput>nova flavor-list</userinput>
<computeroutput>+----+-----------+-----------+------+-----------+------+-------+-------------+
| ID | Name | Memory_MB | Disk | Ephemeral | Swap | VCPUs | RXTX_Factor |
+----+-----------+-----------+------+-----------+------+-------+-------------+
| 1 | m1.tiny | 512 | 1 | N/A | 0 | 1 | |
| 2 | m1.small | 2048 | 20 | N/A | 0 | 1 | |
| 3 | m1.medium | 4096 | 40 | N/A | 0 | 2 | |
| 4 | m1.large | 8192 | 80 | N/A | 0 | 4 | |
| 5 | m1.xlarge | 16384 | 160 | N/A | 0 | 8 | |
+----+-----------+-----------+------+-----------+------+-------+-------------+
</computeroutput></screen>
</section>
<xi:include href="../common/section_cli_nova_customize_flavors.xml"/>
<!-- <section xml:id="section_instance-creation">
<?dbhtml stop-chunking?>
<title>Instances</title>
<para>For information about launching instances through
the nova command-line client, see the <link
xlink:href="http://docs.openstack.org/user-guide/content/index.html"
><citetitle>OpenStack End User
Guide</citetitle></link>.</para>
</section>-->
<section xml:id="section_instance-scheduling-constraints">
<title>Control where instances run</title>
<para>
The <!--<xref linkend="ch_scheduling"/>-->
<citetitle>OpenStack Configuration Reference</citetitle>
provides detailed information on controlling where your
instances run, including ensuring a set of instances run on
different compute nodes for service resiliency or on the same
node for high performance inter-instance communications.
</para>
<para>
Admin users can specify an exact compute node to
run on using the command
<command>--availability-zone <replaceable>availability-zone</replaceable>:<replaceable>compute-host</replaceable></command>
</para>
</section>
<section xml:id="admin-password-injection">
<?dbhtml stop-chunking?>
<title>Admin password injection</title>
<para>You can configure Compute to generate a random administrator (root) password and
inject that password into the instance. If this feature is enabled, a user can ssh
to an instance without an ssh keypair. The random password appears in the output of
the <command>nova boot</command> command. You can also view and set the admin
password from the dashboard.</para>
<simplesect>
<title>Dashboard</title>
<para>The dashboard is configured by default to display the admin password and allow
the user to modify it.</para>
<para>If you do not want to support password injection, we
recommend disabling the password fields by editing your
Dashboard <filename>local_settings</filename> file (file
location will vary by Linux distribution, on Fedora/RHEL/CentOS: <filename>
/etc/openstack-dashboard/local_settings</filename>, on Ubuntu and Debian:
<filename>/etc/openstack-dashboard/local_settings.py</filename> and on openSUSE and SUSE Linux Enterprise Server: <filename
>/usr/share/openstack-dashboard/openstack_dashboard/local/local_settings.py</filename>)
<programlisting>OPENSTACK_HYPERVISOR_FEATURE = {
...
'can_set_password': False,
}</programlisting></para>
</simplesect>
<simplesect>
<title>Libvirt-based hypervisors (KVM, QEMU, LXC)</title>
<para>For hypervisors such as KVM that use the libvirt backend, admin password
injection is disabled by default. To enable it, set the following option in
<filename>/etc/nova/nova.conf</filename>:</para>
<para>
<programlisting>[libvirt]
inject_password=true</programlisting>
</para>
<para>When enabled, Compute will modify the password of the root account by editing
the <filename>/etc/shadow</filename> file inside of the virtual machine
instance.</para>
<note><para>Users will only be able to ssh to the instance using the admin password if:<itemizedlist>
<listitem>
<para>The virtual machine image is a Linux distribution</para>
</listitem>
<listitem>
<para>The virtual machine has been configured to allow users to ssh
as the root user. This is not the case for <link
xlink:href="http://cloud-images.ubuntu.com/">Ubuntu cloud
images</link>, which disallow ssh to the root account by
default.</para>
</listitem>
</itemizedlist></para></note>
</simplesect>
<simplesect>
<title>XenAPI (XenServer/XCP)</title>
<para>Compute uses the XenAPI agent to inject passwords into guests when using the
XenAPI hypervisor backend. The virtual machine image must be configured with the
agent for password injection to work.</para>
</simplesect>
<simplesect>
<title>Windows images (all hypervisors)</title>
<para>To support the admin password for Windows virtual machines, you must configure
the Windows image to retrieve the admin password on boot by installing an agent
such as <link xlink:href="https://github.com/cloudbase/cloudbase-init"
>cloudbase-init</link>.</para>
</simplesect>
</section>
<!-- <section xml:id="section_instance-data">
<?dbhtml stop-chunking?>
<title>Instance-specific data</title>
<para>For each instance, you can specify certain data including authorized_keys, key
injection, user-data, metadata service, and file injection.</para>
<para>For information, see the <link
xlink:href="http://docs.openstack.org/user-guide/content/"
><citetitle>OpenStack End User
Guide</citetitle></link>.</para>
</section>
<section xml:id="section_instance-networking">
<?dbhtml stop-chunking?>
<title>Instance networking</title>
<para>For information, see the <link
xlink:href="http://docs.openstack.org/user-guide/content/index.html"
><citetitle>OpenStack End User
Guide</citetitle></link>.</para>
</section>-->
<xi:include href="../common/section_cli_nova_volumes.xml"/>
<section xml:id="section_networking-nova">
<title>Networking with nova-network</title>
<para>Understanding the networking configuration options helps
you design the best configuration for your Compute
instances.</para>
<section xml:id="section_networking-options">
<title>Networking options</title>
<para>This section offers a brief overview of each concept in
networking for Compute. With the Grizzly release, you can choose
to either install and configure <systemitem class="service"
>nova-network</systemitem> for networking between VMs or use
the Networking service (neutron) for networking. To configure
Compute networking options with Neutron, see the <xref
linkend="ch_networking"/>.</para>
<para>For each VM instance, Compute assigns to it a private IP
address. (Currently, Compute with <systemitem class="service"
>nova-network</systemitem> only supports Linux bridge
networking that enables the virtual interfaces to connect to the
outside network through the physical interface.)</para>
<para>The network controller with <systemitem class="service"
>nova-network</systemitem> provides virtual networks to
enable compute servers to interact with each other and with the
public network.</para>
<para>Currently, Compute with <systemitem class="service"
>nova-network</systemitem> supports these kinds of networks,
implemented in different “Network Manager” types: <itemizedlist>
<listitem>
<para>Flat Network Manager</para>
</listitem>
<listitem>
<para>Flat DHCP Network Manager</para>
</listitem>
<listitem>
<para>VLAN Network Manager</para>
</listitem>
</itemizedlist></para>
<para>These networks can co-exist in a cloud system. However,
because you can't yet select the type of network for a given
project, you cannot configure more than one type of network in a
given Compute installation.</para>
<note>
<para>All networking options require network connectivity to be
already set up between OpenStack physical nodes. OpenStack
does not configure any physical network interfaces.
OpenStack automatically creates all network bridges (for
example, br100) and VM virtual interfaces.</para>
<para>All machines must have a <emphasis role="italic"
>public</emphasis> and <emphasis role="italic"
>internal</emphasis> network interface (controlled by
the options: <literal>public_interface</literal> for the
public interface, and <literal>flat_interface</literal> and
<literal>vlan_interface</literal> for the internal
interface with flat / VLAN managers).</para>
<para>The internal network interface is used for communication
with VMs, it shouldn't have an IP address attached to it
before OpenStack installation (it serves merely as a fabric
where the actual endpoints are VMs and dnsmasq). Also, the
internal network interface must be put in <emphasis
role="italic">promiscuous mode</emphasis>, because it
must receive packets whose target MAC address is of the
guest VM, not of the host.</para>
</note>
<para>All the network managers configure the network using <emphasis
role="italic">network drivers</emphasis>. For example, the
Linux L3 driver (<literal>l3.py</literal> and
<literal>linux_net.py</literal>), which makes use of
<literal>iptables</literal>, <literal>route</literal> and
other network management facilities, and libvirt's <link
xlink:href="http://libvirt.org/formatnwfilter.html">network
filtering facilities</link>. The driver isn't tied to any
particular network manager; all network managers use the same
driver. The driver usually initializes (creates bridges and so
on) only when the first VM lands on this host node.</para>
<para>All network managers operate in either <emphasis role="italic"
>single-host</emphasis> or <emphasis role="italic"
>multi-host</emphasis> mode. This choice greatly influences
the network configuration. In single-host mode, a single
<systemitem class="service">nova-network</systemitem> service
provides a default gateway for VMs and hosts a single DHCP
server (dnsmasq). In multi-host mode, each compute node runs its
own <systemitem class="service">nova-network</systemitem>
service. In both cases, all traffic between VMs and the outer
world flows through <systemitem class="service"
>nova-network</systemitem>. Each mode has its pros and cons.
Read more in the <link
xlink:href="http://docs.openstack.org/havana/config-reference/content/"
><citetitle>OpenStack Configuration
Reference</citetitle></link>.</para>
<para>Compute makes a distinction between <emphasis role="italic"
>fixed IPs</emphasis> and <emphasis role="italic">floating
IPs</emphasis> for VM instances. Fixed IPs are IP addresses
that are assigned to an instance on creation and stay the same
until the instance is explicitly terminated. By contrast,
floating IPs are addresses that can be dynamically associated
with an instance. A floating IP address can be disassociated and
associated with another instance at any time. A user can reserve
a floating IP for their project.</para>
<para>In <emphasis role="bold">Flat Mode</emphasis>, a network
administrator specifies a subnet. The IP addresses for VM
instances are grabbed from the subnet, and then injected into
the image on launch. Each instance receives a fixed IP address
from the pool of available addresses. A system administrator may
create the Linux networking bridge (typically named
<literal>br100</literal>, although this configurable) on the
systems running the <systemitem class="service"
>nova-network</systemitem> service. All instances of the
system are attached to the same bridge, configured manually by
the network administrator.</para>
<para>
<note>
<para>The configuration injection currently only works on
Linux-style systems that keep networking configuration
in <filename>/etc/network/interfaces</filename>.</para>
</note>
</para>
<para>In <emphasis role="bold">Flat DHCP Mode</emphasis>, OpenStack
starts a DHCP server (dnsmasq) to pass out IP addresses to VM
instances from the specified subnet in addition to manually
configuring the networking bridge. IP addresses for VM instances
are grabbed from a subnet specified by the network
administrator.</para>
<para>Like Flat Mode, all instances are attached to a single bridge
on the compute node. In addition a DHCP server is running to
configure instances (depending on single-/multi-host mode,
alongside each <systemitem class="service"
>nova-network</systemitem>). In this mode, Compute does a
bit more configuration in that it attempts to bridge into an
ethernet device (<literal>flat_interface</literal>, eth0 by
default). It also runs and configures dnsmasq as a DHCP server
listening on this bridge, usually on IP address 10.0.0.1 (see
<link linkend="section_dnsmasq">DHCP server:
dnsmasq</link>). For every instance, nova allocates a fixed IP
address and configure dnsmasq with the MAC/IP pair for the VM.
For example, dnsmasq doesn't take part in the IP address
allocation process, it only hands out IPs according to the
mapping done by nova. Instances receive their fixed IPs by doing
a dhcpdiscover. These IPs are <emphasis role="italic"
>not</emphasis> assigned to any of the host's network
interfaces, only to the VM's guest-side interface.</para>
<para>In any setup with flat networking, the host(-s) with
nova-network on it is (are) responsible for forwarding traffic
from the private network. Compute can determine the NAT entries
for each network, though sometimes NAT is not used, such as when
configured with all public IPs or a hardware router is used (one
of the HA options). Such host(-s) needs to have
<literal>br100</literal> configured and physically connected
to any other nodes that are hosting VMs. You must set the
<literal>flat_network_bridge</literal> option or create
networks with the bridge parameter in order to avoid raising an
error. Compute nodes have iptables/ebtables entries created for
each project and instance to protect against IP/MAC address
spoofing and ARP poisoning.</para>
<note>
<para>In single-host Flat DHCP mode you <emphasis role="italic"
>will</emphasis> be able to ping VMs through their fixed
IP from the nova-network node, but you <emphasis
role="italic">cannot</emphasis> ping them from the
compute nodes. This is expected behavior.</para>
</note>
<para><emphasis role="bold">VLAN Network Mode is the default
mode</emphasis> for OpenStack Compute. In this mode, Compute
creates a VLAN and bridge for each project. For multiple machine
installation, the VLAN Network Mode requires a switch that
supports VLAN tagging (IEEE 802.1Q). The project gets a range of
private IPs that are only accessible from inside the VLAN. In
order for a user to access the instances in their project, a
special VPN instance (code named cloudpipe) needs to be created.
Compute generates a certificate and key for the user to access
the VPN and starts the VPN automatically. It provides a private
network segment for each project's instances that can be
accessed through a dedicated VPN connection from the Internet.
In this mode, each project gets its own VLAN, Linux networking
bridge, and subnet.</para>
<para>The subnets are specified by the network administrator, and
are assigned dynamically to a project when required. A DHCP
Server is started for each VLAN to pass out IP addresses to VM
instances from the subnet assigned to the project. All instances
belonging to one project are bridged into the same VLAN for that
project. OpenStack Compute creates the Linux networking bridges
and VLANs when required.</para>
</section>
<section xml:id="section_dnsmasq">
<title>DHCP server: dnsmasq</title>
<para>The Compute service uses <link
xlink:href="http://www.thekelleys.org.uk/dnsmasq/doc.html"
>dnsmasq</link> as the DHCP server when running
with either that Flat DHCP Network Manager or the VLAN
Network Manager. The <systemitem class="service"
>nova-network</systemitem> service is responsible
for starting up dnsmasq processes.</para>
<para>The behavior of dnsmasq can be customized by
creating a dnsmasq configuration file. Specify the
config file using the
<literal>dnsmasq_config_file</literal>
configuration option. For example:
<programlisting language="ini">dnsmasq_config_file=/etc/dnsmasq-nova.conf</programlisting>
See the <link
xlink:href="http://docs.openstack.org/havana/config-reference/content/"
><citetitle> OpenStack Configuration
Reference</citetitle></link> for an example of
how to change the behavior of dnsmasq using a dnsmasq
configuration file. The dnsmasq documentation has a
more comprehensive <link
xlink:href="http://www.thekelleys.org.uk/dnsmasq/docs/dnsmasq.conf.example"
>dnsmasq configuration file example</link>.</para>
<para>Dnsmasq also acts as a caching DNS server for
instances. You can explicitly specify the DNS server
that dnsmasq should use by setting the
<literal>dns_server</literal> configuration option
in <filename>/etc/nova/nova.conf</filename>. The
following example would configure dnsmasq to use
Google's public DNS server:
<programlisting language="ini">dns_server=8.8.8.8</programlisting></para>
<para>Dnsmasq logging output goes to the syslog (typically
<filename>/var/log/syslog</filename> or
<filename>/var/log/messages</filename>, depending
on Linux distribution). The dnsmasq logging output can
be useful for troubleshooting if VM instances boot
successfully but are not reachable over the
network.</para>
<para>A network administrator can run <code>nova-manage
fixed reserve
--address=<replaceable>x.x.x.x</replaceable></code>
to specify the starting point IP address (x.x.x.x) to
reserve with the DHCP server. This reservation only
affects which IP address the VMs start at, not the
fixed IP addresses that the <systemitem
class="service">nova-network</systemitem> service
places on the bridges.</para>
</section>
<section xml:id="section_metadata-service">
<title>Metadata service</title>
<simplesect>
<title>Introduction</title>
<para>The Compute service uses a special metadata
service to enable virtual machine instances to
retrieve instance-specific data. Instances access
the metadata service at
<literal>http://169.254.169.254</literal>. The
metadata service supports two sets of APIs: an
OpenStack metadata API and an EC2-compatible API.
Each of the APIs is versioned by date.</para>
<para>To retrieve a list of supported versions for the
OpenStack metadata API, make a GET request to
<programlisting>http://169.254.169.254/openstack</programlisting>
For example:</para>
<para><screen><prompt>$</prompt> <userinput>curl http://169.254.169.254/openstack</userinput>
<computeroutput>2012-08-10
latest</computeroutput></screen>
To retrieve a list of supported versions for the
EC2-compatible metadata API, make a GET request to
<programlisting>http://169.254.169.254</programlisting></para>
<para>For example:</para>
<screen><prompt>$</prompt> <userinput>curl http://169.254.169.254</userinput>
<computeroutput>1.0
2007-01-19
2007-03-01
2007-08-29
2007-10-10
2007-12-15
2008-02-01
2008-09-01
2009-04-04
latest</computeroutput></screen>
<para>If you write a consumer for one of these APIs,
always attempt to access the most recent API
version supported by your consumer first, then
fall back to an earlier version if the most recent
one is not available.</para>
</simplesect>
<simplesect>
<title>OpenStack metadata API</title>
<para>Metadata from the OpenStack API is distributed
in JSON format. To retrieve the metadata, make a
GET request to:</para>
<programlisting>http://169.254.169.254/openstack/2012-08-10/meta_data.json</programlisting>
<para>For example:</para>
<screen><prompt>$</prompt> <userinput>curl http://169.254.169.254/openstack/2012-08-10/meta_data.json</userinput>
<computeroutput>{"uuid": "d8e02d56-2648-49a3-bf97-6be8f1204f38", "availability_zone": "nova", "hostname": "test.novalocal", "launch_index": 0, "meta": {"priority": "low", "role": "webserver"}, "public_keys": {"mykey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDYVEprvtYJXVOBN0XNKVVRNCRX6BlnNbI+USLGais1sUWPwtSg7z9K9vhbYAPUZcq8c/s5S9dg5vTHbsiyPCIDOKyeHba4MUJq8Oh5b2i71/3BISpyxTBH/uZDHdslW2a+SrPDCeuMMoss9NFhBdKtDkdG9zyi0ibmCP6yMdEX8Q== Generated by Nova\n"}, "name": "test"}</computeroutput></screen>
<para>Here is the same content after having run
through a JSON pretty-printer:</para>
<programlisting language="json">{
"availability_zone": "nova",
"hostname": "test.novalocal",
"launch_index": 0,
"meta": {
"priority": "low",
"role": "webserver"
},
"name": "test",
"public_keys": {
"mykey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDYVEprvtYJXVOBN0XNKVVRNCRX6BlnNbI+USLGais1sUWPwtSg7z9K9vhbYAPUZcq8c/s5S9dg5vTHbsiyPCIDOKyeHba4MUJq8Oh5b2i71/3BISpyxTBH/uZDHdslW2a+SrPDCeuMMoss9NFhBdKtDkdG9zyi0ibmCP6yMdEX8Q== Generated by Nova\n"
},
"uuid": "d8e02d56-2648-49a3-bf97-6be8f1204f38"
}</programlisting>
<para>Instances also retrieve user data (passed as the
<literal>user_data</literal> parameter in the
API call or by the <literal>--user_data</literal>
flag in the <command>nova boot</command> command)
through the metadata service, by making a GET
request to:
<programlisting>http://169.254.169.254/openstack/2012-08-10/user_data</programlisting>
For example:</para>
<para>
<screen><prompt>$</prompt> <userinput>curl http://169.254.169.254/openstack/2012-08-10/user_data</userinput><computeroutput>#!/bin/bash
echo 'Extra user data here'</computeroutput></screen>
</para>
</simplesect>
<simplesect>
<title>EC2 metadata API</title>
<para>The metadata service has an API that is
compatible with version 2009-04-04 of the <link
xlink:href="http://docs.amazonwebservices.com/AWSEC2/2009-04-04/UserGuide/AESDG-chapter-instancedata.html"
>Amazon EC2 metadata service</link>; virtual
machine images that are designed for EC2 work
properly with OpenStack.</para>
<para>The EC2 API exposes a separate URL for each
metadata. You can retrieve a listing of these
elements by making a GET query to:</para>
<programlisting>http://169.254.169.254/2009-04-04/meta-data/</programlisting>
<para>For example:</para>
<screen><prompt>$</prompt> <userinput>curl http://169.254.169.254/2009-04-04/meta-data/</userinput><computeroutput>ami-id
ami-launch-index
ami-manifest-path
block-device-mapping/
hostname
instance-action
instance-id
instance-type
kernel-id
local-hostname
local-ipv4
placement/
public-hostname
public-ipv4
public-keys/
ramdisk-id
reservation-id
security-groups</computeroutput></screen>
<screen><prompt>$</prompt> <userinput>curl http://169.254.169.254/2009-04-04/meta-data/block-device-mapping/</userinput><computeroutput>ami</computeroutput></screen>
<screen><prompt>$</prompt> <userinput>curl http://169.254.169.254/2009-04-04/meta-data/placement/</userinput>
<computeroutput>availability-zone</computeroutput></screen>
<screen><prompt>$</prompt> <userinput>curl http://169.254.169.254/2009-04-04/meta-data/public-keys/</userinput>
<computeroutput>0=mykey</computeroutput></screen>
<para>Instances can retrieve the public SSH key
(identified by keypair name when a user requests a
new instance) by making a GET request to:</para>
<programlisting>http://169.254.169.254/2009-04-04/meta-data/public-keys/0/openssh-key</programlisting>
<para>For example:</para>
<screen><prompt>$</prompt> <userinput>curl http://169.254.169.254/2009-04-04/meta-data/public-keys/0/openssh-key</userinput>
<computeroutput>ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDYVEprvtYJXVOBN0XNKVVRNCRX6BlnNbI+USLGais1sUWPwtSg7z9K9vhbYAPUZcq8c/s5S9dg5vTHbsiyPCIDOKyeHba4MUJq8Oh5b2i71/3BISpyxTBH/uZDHdslW2a+SrPDCeuMMoss9NFhBdKtDkdG9zyi0ibmCP6yMdEX8Q== Generated by Nova</computeroutput></screen>
<para>Instances can retrieve user data by making a GET
request to:</para>
<programlisting>http://169.254.169.254/2009-04-04/user-data</programlisting>
<para>For example:</para>
<screen><prompt>$</prompt> <userinput>curl http://169.254.169.254/2009-04-04/user-data</userinput>
<computeroutput>#!/bin/bash
echo 'Extra user data here'</computeroutput></screen>
</simplesect>
<simplesect>
<title>Run the metadata service</title>
<para>The metadata service is implemented by either
the <systemitem class="service"
>nova-api</systemitem> service or the
<systemitem class="service"
>nova-api-metadata</systemitem> service. (The
<systemitem class="service"
>nova-api-metadata</systemitem> service is
generally only used when running in multi-host
mode, see the <link
xlink:href="http://docs.openstack.org/havana/config-reference/content/"
><citetitle>OpenStack Configuration
Reference</citetitle></link> for details).
If you are running the <systemitem class="service"
>nova-api</systemitem> service, you must have
<literal>metadata</literal> as one of the
elements of the list of the
<literal>enabled_apis</literal> configuration
option in
<filename>/etc/nova/nova.conf</filename>. The
default <literal>enabled_apis</literal>
configuration setting includes the metadata
service, so you should not need to modify
it.</para>
<para>To enable instances to reach the metadata
service, the <systemitem class="service"
>nova-network</systemitem> service configures
iptables to NAT port <literal>80</literal> of the
<literal>169.254.169.254</literal> address to
the IP address specified in
<option>metadata_host</option> (default
<literal>$my_ip</literal>, which is the IP
address of the <systemitem class="service"
>nova-network</systemitem> service) and port
specified in <option>metadata_port</option>
(default <literal>8775</literal>) in
<filename>/etc/nova/nova.conf</filename>.</para>
<warning>
<para>The <literal>metadata_host</literal>
configuration option must be an IP address,
not a host name.</para>
</warning>
<note>
<para>The default Compute service settings assume
that the <systemitem class="service"
>nova-network</systemitem> service and the
<systemitem class="service"
>nova-api</systemitem> service are running
on the same host. If this is not the case, you
must make this change in the
<filename>/etc/nova/nova.conf</filename>
file on the host running the <systemitem
class="service">nova-network</systemitem>
service:</para>
<para>Set the <literal>metadata_host</literal>
configuration option to the IP address of the
host where the <systemitem class="service"
>nova-api</systemitem> service
runs.</para>
</note>
<xi:include href="../common/tables/nova-metadata.xml"
/>
</simplesect>
</section>
<section xml:id="section_enable-ping-and-ssh-on-vms">
<title>Enable ping and SSH on VMs</title>
<para>Be sure you enable access to your VMs by using the
<command>euca-authorize</command> or <command>nova
secgroup-add-rule</command> command. These
commands enable you to <command>ping</command> and
<command>ssh</command> to your VMs:</para>
<note>
<para>You must run these commands as root only if the
credentials used to interact with <systemitem
class="service">nova-api</systemitem> are in
<filename>/root/.bashrc</filename>. If the EC2
credentials are the <filename>.bashrc</filename>
file for another user, you must run these commands
as the user.</para>
</note>
<para>Run <command>nova</command> commands:</para>
<screen><prompt>$</prompt> <userinput>nova secgroup-add-rule default icmp -1 -1 0.0.0.0/0</userinput>
<prompt>$</prompt> <userinput>nova secgroup-add-rule default tcp 22 22 0.0.0.0/0</userinput> </screen>
<para>Using euca2ools:</para>
<screen><prompt>$</prompt> <userinput>euca-authorize -P icmp -t -1:-1 -s 0.0.0.0/0 default</userinput>
<prompt>$</prompt> <userinput>euca-authorize -P tcp -p 22 -s 0.0.0.0/0 default</userinput> </screen>
<para>If you still cannot ping or SSH your instances after
issuing the <command>nova secgroup-add-rule</command>
commands, look at the number of
<literal>dnsmasq</literal> processes that are
running. If you have a running instance, check to see
that TWO <literal>dnsmasq</literal> processes are
running. If not, perform this as root:</para>
<screen><prompt>#</prompt> <userinput>killall dnsmasq</userinput>
<prompt>#</prompt> <userinput>service nova-network restart</userinput> </screen>
</section>
<section xml:id="section_remove-network-from-project">
<title>Remove a network from a project</title>
<para>You cannot remove a network that has already been
associated to a project by simply deleting it.</para>
<para>To determine the project ID you must have admin
rights. You can disassociate the project from the
network with a scrub command and the project ID as the
final parameter:</para>
<screen><prompt>$</prompt> <userinput>nova-manage project scrub --project=<replaceable>&lt;id></replaceable></userinput> </screen>
</section>
<section xml:id="section_use-multi-nics">
<title>Multiple interfaces for your instances
(multinic)</title>
<?dbhtml stop-chunking?>
<para>The multi-nic feature allows you to plug more than
one interface to your instances, making it possible to
make several use cases available: <itemizedlist>
<listitem>
<para>SSL Configurations (VIPs)</para>
</listitem>
<listitem>
<para>Services failover/ HA</para>
</listitem>
<listitem>
<para>Bandwidth Allocation</para>
</listitem>
<listitem>
<para>Administrative/ Public access to your
instances</para>
</listitem>
</itemizedlist> Each VIF is representative of a
separate network with its own IP block. Every network
mode introduces it's own set of changes regarding the
mulitnic usage: <figure>
<title>multinic flat manager</title>
<mediaobject>
<imageobject>
<imagedata scale="40"
fileref="../common/figures/SCH_5007_V00_NUAC-multi_nic_OpenStack-Flat-manager.jpg"
/>
</imageobject>
</mediaobject>
</figure>
<figure>
<title>multinic flatdhcp manager</title>
<mediaobject>
<imageobject>
<imagedata scale="40"
fileref="../common/figures/SCH_5007_V00_NUAC-multi_nic_OpenStack-Flat-DHCP-manager.jpg"
/>
</imageobject>
</mediaobject>
</figure>
<figure>
<title>multinic VLAN manager</title>
<mediaobject>
<imageobject>
<imagedata scale="40"
fileref="../common/figures/SCH_5007_V00_NUAC-multi_nic_OpenStack-VLAN-manager.jpg"
/>
</imageobject>
</mediaobject>
</figure>
</para>
<section xml:id="using-multiple-nics-usage">
<title>Use the multinic feature</title>
<para>In order to use the multinic feature, first
create two networks, and attach them to your
project:
<screen><prompt>$</prompt> <userinput>nova network-create first-net --fixed-range-v4=20.20.0.0/24 --project-id=$your-project</userinput>
<prompt>$</prompt> <userinput>nova network-create second-net --fixed-range-v4=20.20.10.0/24 --project-id=$your-project</userinput> </screen>
Now every time you spawn a new instance, it gets
two IP addresses from the respective DHCP servers: <screen><prompt>$</prompt> <userinput>nova list</userinput>
<computeroutput>+-----+------------+--------+----------------------------------------+
| ID | Name | Status | Networks |
+-----+------------+--------+----------------------------------------+
| 124 | Server 124 | ACTIVE | network2=20.20.0.3; private=20.20.10.14|
+-----+------------+--------+----------------------------------------+</computeroutput></screen>
<note>
<para>Make sure to power up the second
interface on the instance, otherwise that
last won't be reachable through its second
IP. Here is an example of how to setup the
interfaces within the instance (this is
the configuration that needs to be applied
inside the image):</para>
<para><filename>/etc/network/interfaces</filename>
<programlisting># The loopback network interface
auto lo
iface lo inet loopback
auto eth0
iface eth0 inet dhcp
auto eth1
iface eth1 inet dhcp</programlisting></para>
</note></para>
<note>
<para>If the Virtual Network Service Neutron is
installed, it is possible to specify the
networks to attach to the respective
interfaces by using the
<literal>--nic</literal> flag when
invoking the <literal>nova</literal> command:
<screen><prompt>$</prompt> <userinput>nova boot --image ed8b2a37-5535-4a5f-a615-443513036d71 --flavor 1 --nic net-id= &lt;id of first network&gt; --nic net-id= &lt;id of first network&gt; test-vm1</userinput></screen>
</para>
</note>
</section>
</section>
<section xml:id="section_network-troubleshoot">
<title>Troubleshoot Networking</title>
<simplesect>
<title>Cannot reach floating IPs</title>
<para>If you cannot reach your instances through the
floating IP address, make sure the default
security group allows ICMP (ping) and SSH (port
22), so that you can reach the instances:</para>
<screen><prompt>$</prompt> <userinput>nova secgroup-list-rules default</userinput>
<computeroutput>+-------------+-----------+---------+-----------+--------------+
| IP Protocol | From Port | To Port | IP Range | Source Group |
+-------------+-----------+---------+-----------+--------------+
| icmp | -1 | -1 | 0.0.0.0/0 | |
| tcp | 22 | 22 | 0.0.0.0/0 | |
+-------------+-----------+---------+-----------+--------------+</computeroutput> </screen>
<para>Ensure the NAT rules have been added to iptables
on the node that nova-network is running on, as
root:</para>
<screen><prompt>#</prompt> <userinput>iptables -L -nv</userinput>
<computeroutput>-A nova-network-OUTPUT -d 68.99.26.170/32 -j DNAT --to-destination 10.0.0.3</computeroutput></screen>
<screen><prompt>#</prompt> <userinput>iptables -L -nv -t nat</userinput>
<computeroutput>-A nova-network-PREROUTING -d 68.99.26.170/32 -j DNAT --to-destination10.0.0.3
-A nova-network-floating-snat -s 10.0.0.3/32 -j SNAT --to-source 68.99.26.170</computeroutput></screen>
<para>Check that the public address, in this example
"68.99.26.170", has been added to your public
interface: You should see the address in the
listing when you enter "ip addr" at the command
prompt.</para>
<screen><prompt>$</prompt> <userinput>ip addr</userinput>
<computeroutput>2: eth0: &lt;BROADCAST,MULTICAST,UP,LOWER_UP&gt; mtu 1500 qdisc mq state UP qlen 1000
link/ether xx:xx:xx:17:4b:c2 brd ff:ff:ff:ff:ff:ff
inet 13.22.194.80/24 brd 13.22.194.255 scope global eth0
inet 68.99.26.170/32 scope global eth0
inet6 fe80::82b:2bf:fe1:4b2/64 scope link
valid_lft forever preferred_lft forever</computeroutput></screen>
<para>Note that you cannot SSH to an instance with a
public IP from within the same server as the
routing configuration won't allow it.</para>
<para>You can use <command>tcpdump</command> to
identify if packets are being routed to the
inbound interface on the compute host. If the
packets are reaching the compute hosts but the
connection is failing, the issue may be that the
packet is being dropped by reverse path filtering.
Try disabling reverse path filtering on the
inbound interface. For example, if the inbound
interface is <literal>eth2</literal>, as
root:</para>
<screen><prompt>#</prompt> <userinput>sysctl -w net.ipv4.conf.<replaceable>eth2</replaceable>.rp_filter=0</userinput></screen>
<para>If this solves your issue, add this line to
<filename>/etc/sysctl.conf</filename> so that
the reverse path filter is disabled the next time
the compute host reboots:
<programlisting language="ini">net.ipv4.conf.rp_filter=0</programlisting></para>
</simplesect>
<simplesect>
<title>Disable firewall</title>
<para>To help debug networking issues with reaching
VMs, you can disable the firewall by setting the
following option in
<filename>/etc/nova/nova.conf</filename>:</para>
<programlisting language="ini">firewall_driver=nova.virt.firewall.NoopFirewallDriver</programlisting>
<para>We strongly recommend you remove this line to
re-enable the firewall once your networking issues
have been resolved.</para>
</simplesect>
<simplesect>
<title>Packet loss from instances to nova-network
server (VLANManager mode)</title>
<para>If you can SSH to your instances but you find
that the network interactions to your instance is
slow, or if you find that running certain
operations are slower than they should be (for
example, <command>sudo</command>), then there may
be packet loss occurring on the connection to the
instance.</para>
<para>Packet loss can be caused by Linux networking
configuration settings related to bridges. Certain
settings can cause packets to be dropped between
the VLAN interface (for example,
<literal>vlan100</literal>) and the associated
bridge interface (for example,
<literal>br100</literal>) on the host running
the <systemitem class="service"
>nova-network</systemitem> service.</para>
<para>One way to check if this is the issue in your
setup is to open up three terminals and run the
following commands:</para>
<para>In the first terminal, on the host running
nova-network, use <command>tcpdump</command> to
monitor DNS-related traffic (UDP, port 53) on the
VLAN interface. As root:</para>
<screen><prompt>#</prompt> <userinput>tcpdump -K -p -i vlan100 -v -vv udp port 53</userinput></screen>
<para>In the second terminal, also on the host running
nova-network, use <command>tcpdump</command> to
monitor DNS-related traffic on the bridge
interface. As root:</para>
<screen><prompt>#</prompt> <userinput>tcpdump -K -p -i br100 -v -vv udp port 53</userinput></screen>
<para>In the third terminal, SSH inside of the
instance and generate DNS requests by using the
<command>nslookup</command> command:</para>
<screen><prompt>$</prompt> <userinput>nslookup www.google.com</userinput></screen>
<para>The symptoms may be intermittent, so try running
<command>nslookup</command> multiple times. If
the network configuration is correct, the command
should return immediately each time. If it is not
functioning properly, the command hangs for
several seconds.</para>
<para>If the <command>nslookup</command> command
sometimes hangs, and there are packets that appear
in the first terminal but not the second, then the
problem may be due to filtering done on the
bridges. Try to disable filtering, as root:</para>
<screen><prompt>#</prompt> <userinput>sysctl -w net.bridge.bridge-nf-call-arptables=0</userinput>
<prompt>#</prompt> <userinput>sysctl -w net.bridge.bridge-nf-call-iptables=0</userinput>
<prompt>#</prompt> <userinput>sysctl -w net.bridge.bridge-nf-call-ip6tables=0</userinput></screen>
<para>If this solves your issue, add this line to
<filename>/etc/sysctl.conf</filename> so that
these changes take effect the next time the host
reboots:</para>
<programlisting language="ini">net.bridge.bridge-nf-call-arptables=0
net.bridge.bridge-nf-call-iptables=0
net.bridge.bridge-nf-call-ip6tables=0</programlisting>
</simplesect>
<simplesect>
<title>KVM: Network connectivity works initially, then
fails</title>
<para>Some administrators have observed an issue with
the KVM hypervisor where instances running Ubuntu
12.04 sometimes loses network connectivity after
functioning properly for a period of time. Some
users have reported success with loading the
vhost_net kernel module as a workaround for this
issue (see <link
xlink:href="https://bugs.launchpad.net/ubuntu/+source/libvirt/+bug/997978/"
>bug #997978</link>) . This kernel module may
also <link
xlink:href="http://www.linux-kvm.org/page/VhostNet"
>improve network performance on KVM</link>. To
load the kernel module, as root:</para>
<screen><prompt>#</prompt> <userinput>modprobe vhost_net</userinput></screen>
<note>
<para>Loading the module has no effect on running
instances.</para>
</note>
</simplesect>
</section>
</section>
<section xml:id="section_block-storage-volumes">
<title>Volumes</title>
<para>The Block Storage Service provides persistent block
storage resources that OpenStack Compute instances can
consume.</para>
<para>See the <citetitle>OpenStack Configuration
Reference</citetitle> for information about
configuring volume drivers and creating and attaching
volumes to server instances.</para>
</section>
<section xml:id="section_compute-system-admin">
<title>System administration</title>
<para>By understanding how the different installed nodes
interact with each other you can administer the Compute
installation. Compute offers many ways to install using
multiple servers but the general idea is that you can have
multiple compute nodes that control the virtual servers
and a cloud controller node that contains the remaining
Compute services.</para>
<para>The Compute cloud works through the interaction of a
series of daemon processes named nova-* that reside
persistently on the host machine or machines. These
binaries can all run on the same machine or be spread out
on multiple boxes in a large deployment. The
responsibilities of Services, Managers, and Drivers, can
be a bit confusing at first. Here is an outline the
division of responsibilities to make understanding the
system a little bit easier.</para>
<para>Currently, Services are <systemitem class="service"
>nova-api</systemitem>, <systemitem class="service"
>nova-objectstore</systemitem> (which can be replaced
with Glance, the OpenStack Image Service), <systemitem
class="service">nova-compute</systemitem>, and
<systemitem class="service">nova-network</systemitem>.
Managers and Drivers are specified by configuration
options and loaded using utils.load_object(). Managers are
responsible for a certain aspect of the system. It is a
logical grouping of code relating to a portion of the
system. In general other components should be using the
manager to make changes to the components that it is
responsible for.</para>
<itemizedlist>
<listitem>
<para><systemitem class="service"
>nova-api</systemitem>. Receives xml requests
and sends them to the rest of the system. It is a
wsgi app that routes and authenticate requests. It
supports the EC2 and OpenStack APIs. There is a
<filename>nova-api.conf</filename> file
created when you install Compute.</para>
</listitem>
<listitem>
<para><systemitem class="service"
>nova-objectstore</systemitem>: The
<systemitem class="service"
>nova-objectstore</systemitem> service is an
ultra simple file-based storage system for images
that replicates most of the S3 API. It can be
replaced with OpenStack Image Service and a simple
image manager or use OpenStack Object Storage as
the virtual machine image storage facility. It
must reside on the same node as <systemitem
class="service"
>nova-compute</systemitem>.</para>
</listitem>
<listitem>
<para><systemitem class="service"
>nova-compute</systemitem>. Responsible for
managing virtual machines. It loads a Service
object which exposes the public methods on
ComputeManager through Remote Procedure Call
(RPC).</para>
</listitem>
<listitem>
<para><systemitem class="service"
>nova-network</systemitem>. Responsible for
managing floating and fixed IPs, DHCP, bridging
and VLANs. It loads a Service object which exposes
the public methods on one of the subclasses of
NetworkManager. Different networking strategies
are available to the service by changing the
network_manager configuration option to
FlatManager, FlatDHCPManager, or VlanManager
(default is VLAN if no other is specified).</para>
</listitem>
</itemizedlist>
<section xml:id="section_compute-service-arch">
<title>Compute service architecture</title>
<para>These basic categories describe the service
architecture and what's going on within the cloud
controller.</para>
<simplesect>
<title>API server</title>
<para>At the heart of the cloud framework is an API
server. This API server makes command and control
of the hypervisor, storage, and networking
programmatically available to users in realization
of the definition of cloud computing.</para>
<para>The API endpoints are basic HTTP web services
which handle authentication, authorization, and
basic command and control functions using various
API interfaces under the Amazon, Rackspace, and
related models. This enables API compatibility
with multiple existing tool sets created for
interaction with offerings from other vendors.
This broad compatibility prevents vendor
lock-in.</para>
</simplesect>
<simplesect>
<title>Message queue</title>
<para>A messaging queue brokers the interaction
between compute nodes (processing), the networking
controllers (software which controls network
infrastructure), API endpoints, the scheduler
(determines which physical hardware to allocate to
a virtual resource), and similar components.
Communication to and from the cloud controller is
by HTTP requests through multiple API
endpoints.</para>
<para>A typical message passing event begins with the
API server receiving a request from a user. The
API server authenticates the user and ensures that
the user is permitted to issue the subject
command. Availability of objects implicated in the
request is evaluated and, if available, the
request is routed to the queuing engine for the
relevant workers. Workers continually listen to
the queue based on their role, and occasionally
their type host name. When such listening produces
a work request, the worker takes assignment of the
task and begins its execution. Upon completion, a
response is dispatched to the queue which is
received by the API server and relayed to the
originating user. Database entries are queried,
added, or removed as necessary throughout the
process.</para>
</simplesect>
<simplesect>
<title>Compute worker</title>
<para>Compute workers manage computing instances on
host machines. The API dispatches commands to
compute workers to complete these tasks:</para>
<itemizedlist>
<listitem>
<para>Run instances</para>
</listitem>
<listitem>
<para>Terminate instances</para>
</listitem>
<listitem>
<para>Reboot instances</para>
</listitem>
<listitem>
<para>Attach volumes</para>
</listitem>
<listitem>
<para>Detach volumes</para>
</listitem>
<listitem>
<para>Get console output</para>
</listitem>
</itemizedlist>
</simplesect>
<simplesect>
<title>Network Controller</title>
<para>The Network Controller manages the networking
resources on host machines. The API server
dispatches commands through the message queue,
which are subsequently processed by Network
Controllers. Specific operations include:</para>
<itemizedlist>
<listitem>
<para>Allocate fixed IP addresses</para>
</listitem>
<listitem>
<para>Configuring VLANs for projects</para>
</listitem>
<listitem>
<para>Configuring networks for compute
nodes</para>
</listitem>
</itemizedlist>
</simplesect>
</section>
<section xml:id="section_manage-compute-users">
<title>Manage Compute users</title>
<para>Access to the Euca2ools (ec2) API is controlled by
an access and secret key. The user’s access key needs
to be included in the request, and the request must be
signed with the secret key. Upon receipt of API
requests, Compute verifies the signature and runs
commands on behalf of the user.</para>
<para>To begin using Compute, you must create a user with
the Identity Service.</para>
</section>
<section xml:id="section_manage-the-cloud">
<title>Manage the cloud</title>
<para>A system administrator can use these tools to manage
a cloud; the nova client, the
<command>nova-manage</command> command, and the
<command>Euca2ools</command> commands.</para>
<para>The <command>nova-manage</command> command can only
be run by cloud administrators. Both nova client and
euca2ools can be used by all users, though specific
commands might be restricted by Role Based Access
Control in the Identity Service.</para>
<procedure>
<title>To use the nova command-line tool</title>
<step>
<para>Installing the python-novaclient gives you a
<code>nova</code> shell command that
enables Compute API interactions from the
command line. You install the client, and then
provide your user name and password, set as
environment variables for convenience, and
then you can have the ability to send commands
to your cloud on the command-line.</para>
<para>To install python-novaclient, download the
tarball from <link
xlink:href="http://pypi.python.org/pypi/python-novaclient/2.6.3#downloads"
>http://pypi.python.org/pypi/python-novaclient/2.6.3#downloads</link>
and then install it in your favorite python
environment.</para>
<screen><prompt>$</prompt> <userinput>curl -O http://pypi.python.org/packages/source/p/python-novaclient/python-novaclient-2.6.3.tar.gz</userinput>
<prompt>$</prompt> <userinput>tar -zxvf python-novaclient-2.6.3.tar.gz</userinput>
<prompt>$</prompt> <userinput>cd python-novaclient-2.6.3</userinput>
<prompt>$</prompt> <userinput>sudo python setup.py install</userinput></screen>
</step>
<step>
<para>Now that you have installed the
python-novaclient, confirm the installation by
entering:</para>
<screen><prompt>$</prompt> <userinput>nova help</userinput><computeroutput>usage: nova [--debug] [--os-username OS_USERNAME] [--os-password OS_PASSWORD]
[--os-tenant-name_name OS_TENANT_NAME] [--os-auth-url OS_AUTH_URL]
[--os-region-name OS_REGION_NAME] [--service-type SERVICE_TYPE]
[--service-name SERVICE_NAME] [--endpoint-type ENDPOINT_TYPE]
[--version VERSION]
&lt;subcommand&gt; ...</computeroutput></screen>
</step>
<step>
<para>This command returns a list of nova commands
and parameters. Set the required parameters as
environment variables to make running commands
easier. You can add
<parameter>--os-username</parameter>, for
example, on the nova command, or set it as
environment variables:</para>
<screen><prompt>$</prompt> <userinput>export OS_USERNAME=joecool</userinput>
<prompt>$</prompt> <userinput>export OS_PASSWORD=coolword</userinput>
<prompt>$</prompt> <userinput>export OS_TENANT_NAME=coolu</userinput> </screen>
</step>
<step>
<para>Using the Identity Service, you are supplied
with an authentication endpoint, which nova
recognizes as the
<literal>OS_AUTH_URL</literal>.</para>
<para>
<screen><prompt>$</prompt> <userinput>export OS_AUTH_URL=http://hostname:5000/v2.0</userinput>
<prompt>$</prompt> <userinput>export NOVA_VERSION=1.1</userinput></screen>
</para>
</step>
</procedure>
<procedure>
<title>To use the nova-manage command</title>
<para>The nova-manage command may be used to perform
many essential functions for administration and
ongoing maintenance of nova, such as network
creation or user manipulation.</para>
<step>
<para>The man page for nova-manage has a good
explanation for each of its functions, and is
recommended reading for those starting out.
Access it by running:</para>
<screen><prompt>$</prompt> <userinput>man nova-manage</userinput> </screen>
</step>
<step>
<para>For administrators, the standard pattern for
executing a nova-manage command is:</para>
<screen><prompt>$</prompt> <userinput>nova-manage category command <replaceable>[args]</replaceable></userinput></screen>
</step>
<step>
<para>For example, to obtain a list of all
projects:</para>
<screen><prompt>$</prompt> <userinput>nova-manage project list</userinput></screen>
</step>
<step>
<para>Run without arguments to see a list of
available command categories:</para>
<screen><prompt>$</prompt> <userinput>nova-manage</userinput></screen>
</step>
<step>
<para>You can also run with a category argument
such as user to see a list of all commands in
that category:</para>
<screen><prompt>$</prompt> <userinput>nova-manage service</userinput></screen>
</step>
</procedure>
<simplesect>
<title>Use the euca2ools commands</title>
<para>For a command-line interface to EC2 API calls,
use the euca2ools command line tool. See <link
xlink:href="http://open.eucalyptus.com/wiki/Euca2oolsGuide_v1.3"
>http://open.eucalyptus.com/wiki/Euca2oolsGuide_v1.3</link></para>
</simplesect>
</section>
<xi:include
href="../common/section_cli_nova_usage_statistics.xml"/>
<section xml:id="section_manage-logs">
<title>Manage logs</title>
<simplesect>
<title>Logging module</title>
<para>Add this line to the
<filename>/etc/nova/nova.conf</filename> file
to specify a configuration file to change the
logging behavior. To change the logging level,
such as <literal>DEBUG</literal>,
<literal>INFO</literal>,
<literal>WARNING</literal>,
<literal>ERROR</literal>):
<programlisting language="ini">log-config=/etc/nova/logging.conf</programlisting></para>
<para>The log config file is an ini-style config file
which must contain a section called
<literal>logger_nova</literal>, which controls
the behavior of the logging facility in the
<literal>nova-*</literal> services. The file
must contain a section called
<literal>logger_nova</literal>, for
example:<programlisting language="ini">[logger_nova]
level = INFO
handlers = stderr
qualname = nova</programlisting></para>
<para>This example sets the debugging level to
<literal>INFO</literal> (which less verbose
than the default <literal>DEBUG</literal>
setting). See the <link
xlink:href="http://docs.python.org/release/2.7/library/logging.html#configuration-file-format"
>Python documentation on logging configuration
file format </link>for more details on this
file, including the meaning of the
<literal>handlers</literal> and
<literal>quaname</literal> variables. See
<link
xlink:href="http://git.openstack.org/cgit/openstack/nova/plain/etc/nova/logging_sample.conf"
>etc/nova/logging_sample.conf</link> in the
openstack/nova repository on GitHub for an example
<filename>logging.conf</filename> file with
various handlers defined.</para>
</simplesect>
<simplesect>
<title>Syslog</title>
<para>You can configure OpenStack Compute services to
send logging information to syslog. This is useful
if you want to use rsyslog, which forwards the
logs to a remote machine. You need to separately
configure the Compute service (Nova), the Identity
Service (Keystone), the Image Service (Glance),
and, if you are using it, the Block Storage
Service (Cinder) to send log messages to syslog.
To do so, add these lines to:</para>
<itemizedlist>
<listitem>
<para><filename>/etc/nova/nova.conf</filename></para>
</listitem>
<listitem>
<para><filename>/etc/keystone/keystone.conf</filename></para>
</listitem>
<listitem>
<para><filename>/etc/glance/glance-api.conf</filename></para>
</listitem>
<listitem>
<para><filename>/etc/glance/glance-registry.conf</filename></para>
</listitem>
<listitem>
<para><filename>/etc/cinder/cinder.conf</filename></para>
</listitem>
</itemizedlist>
<programlisting language="ini">verbose = False
debug = False
use_syslog = True
syslog_log_facility = LOG_LOCAL0</programlisting>
<para>In addition to enabling syslog, these settings
also turn off more verbose output and debugging
output from the log.<note>
<para>While the example above uses the same
local facility for each service
(<literal>LOG_LOCAL0</literal>, which
corresponds to syslog facility
<literal>LOCAL0</literal>), we
recommend that you configure a separate
local facility for each service, as this
provides better isolation and more
flexibility. For example, you may want to
capture logging info at different severity
levels for different services. Syslog
allows you to define up to seven local
facilities, <literal>LOCAL0, LOCAL1, ...,
LOCAL7</literal>. See the syslog
documentation for more details.</para>
</note></para>
</simplesect>
<simplesect>
<title>Rsyslog</title>
<para>Rsyslog is a useful tool for setting up a
centralized log server across multiple machines.
We briefly describe the configuration to set up an
rsyslog server; a full treatment of rsyslog is
beyond the scope of this document. We assume
rsyslog has already been installed on your hosts,
which is the default on most Linux
distributions.</para>
<para>This example shows a minimal configuration for
<filename>/etc/rsyslog.conf</filename> on the
log server host, which receives the log
files:</para>
<programlisting># provides TCP syslog reception
$ModLoad imtcp
$InputTCPServerRun 1024</programlisting>
<para>Add to <filename>/etc/rsyslog.conf</filename> a
filter rule on which looks for a host name. The
example below use
<replaceable>compute-01</replaceable> as an
example of a compute host
name:<programlisting>:hostname, isequal, "<replaceable>compute-01</replaceable>" /mnt/rsyslog/logs/compute-01.log</programlisting></para>
<para>On the compute hosts, create a file named
<filename>/etc/rsyslog.d/60-nova.conf</filename>,
with this
content.<programlisting># prevent debug from dnsmasq with the daemon.none parameter
*.*;auth,authpriv.none,daemon.none,local0.none -/var/log/syslog
# Specify a log level of ERROR
local0.error @@172.20.1.43:1024</programlisting></para>
<para>Once you have created this file, restart your
rsyslog daemon. Error-level log messages on the
compute hosts should now be sent to your log
server.</para>
</simplesect>
</section>
<xi:include href="section_rootwrap.xml"/>
<section xml:id="section_live-migration-usage">
<title>Migration</title>
<para>Before starting migrations, review the <link
xlink:href="http://docs.openstack.org/havana/config-reference/content/configuring-openstack-compute-basics.html#section_configuring-compute-migrations"
>Configure migrations</link> section in
<citetitle>OpenStack Configuration
Reference</citetitle>.</para>
<para>Migration provides a scheme to migrate running
instances from one OpenStack Compute server to another
OpenStack Compute server.</para>
<procedure>
<title>To migrate instances</title>
<step>
<para>Look at the running instances, to get the ID
of the instance you wish to migrate.</para>
<screen><prompt>#</prompt> <userinput>nova list</userinput>
<computeroutput><![CDATA[+--------------------------------------+------+--------+-----------------+
| ID | Name | Status |Networks |
+--------------------------------------+------+--------+-----------------+
| d1df1b5a-70c4-4fed-98b7-423362f2c47c | vm1 | ACTIVE | private=a.b.c.d |
| d693db9e-a7cf-45ef-a7c9-b3ecb5f22645 | vm2 | ACTIVE | private=e.f.g.h |
+--------------------------------------+------+--------+-----------------+]]></computeroutput></screen>
</step>
<step>
<para>Look at information associated with that
instance - our example is vm1 from
above.</para>
<screen><prompt>#</prompt> <userinput>nova show d1df1b5a-70c4-4fed-98b7-423362f2c47c</userinput>
<computeroutput><![CDATA[+-------------------------------------+----------------------------------------------------------+
| Property | Value |
+-------------------------------------+----------------------------------------------------------+
...
| OS-EXT-SRV-ATTR:host | HostB |
...
| flavor | m1.tiny |
| id | d1df1b5a-70c4-4fed-98b7-423362f2c47c |
| name | vm1 |
| private network | a.b.c.d |
| status | ACTIVE |
...
+-------------------------------------+----------------------------------------------------------+]]></computeroutput></screen>
<para>In this example, vm1 is running on
HostB.</para>
</step>
<step>
<para>Select the server to migrate instances
to.</para>
<screen><prompt>#</prompt> <userinput>nova-manage service list</userinput>
<computeroutput><![CDATA[HostA nova-scheduler enabled :-) None
HostA nova-network enabled :-) None
HostB nova-compute enabled :-) None
HostC nova-compute enabled :-) None]]></computeroutput></screen>
<para>In this example, HostC can be picked up
because <systemitem class="service"
>nova-compute</systemitem> is running on
it.</para>
</step>
<step>
<para>Ensure that HostC has enough resource for
migration.</para>
<screen><prompt>#</prompt> <userinput>nova-manage service describe_resource HostC</userinput>
<computeroutput><![CDATA[HOST PROJECT cpu mem(mb) hdd
HostC(total) 16 32232 878
HostC(used_now) 13 21284 442
HostC(used_max) 13 21284 442
HostC p1 5 10240 150
HostC p2 5 10240 150
.....]]></computeroutput></screen>
<itemizedlist>
<listitem>
<para><emphasis role="bold"
>cpu:</emphasis>the number of
cpu</para>
</listitem>
<listitem>
<para><emphasis role="bold"
>mem(mb):</emphasis>total amount of
memory (MB)</para>
</listitem>
<listitem>
<para><emphasis role="bold"
>hdd:</emphasis>total amount of
space for NOVA-INST-DIR/instances
(GB)</para>
</listitem>
<listitem>
<para><emphasis role="bold">1st line shows
</emphasis>total amount of resource
physical server has.</para>
</listitem>
<listitem>
<para><emphasis role="bold">2nd line shows
</emphasis>current used
resource.</para>
</listitem>
<listitem>
<para><emphasis role="bold">3rd line shows
</emphasis>maximum used
resource.</para>
</listitem>
<listitem>
<para><emphasis role="bold">4th line and
under</emphasis> shows the resource
for each project.</para>
</listitem>
</itemizedlist>
</step>
<step>
<para>Use the <command>nova
live-migration</command> command to
migrate the instances.</para>
<screen><prompt>#</prompt> <userinput>nova live-migration d1df1b5a-70c4-4fed-98b7-423362f2c47c HostC</userinput><computeroutput><![CDATA[Migration of d1df1b5a-70c4-4fed-98b7-423362f2c47c initiated.]]></computeroutput></screen>
<para>Make sure instances are migrated
successfully with <command>nova
list</command>. If instances are still running
on HostB, check log files (src/dest
<systemitem class="service"
>nova-compute</systemitem> and <systemitem
class="service"
>nova-scheduler</systemitem>) to determine
why. <note>
<para>While the nova command is called
<command>live-migration</command>,
under the default Compute
configuration options the instances
are suspended before migration.</para>
<para>See <link
xlink:href="http://docs.openstack.org/havana/config-reference/content/configuring-openstack-compute-basics.html"
>Configure migrations</link> in
<citetitle>OpenStack Configuration
Reference</citetitle> for more
details.</para>
</note>
</para>
</step>
</procedure>
</section>
<section xml:id="section_nova-compute-node-down">
<title>Recover from a failed compute node</title>
<para>If you have deployed Compute with a shared file
system, you can quickly recover from a failed compute
node. Of the two methods covered in these sections,
the evacuate API is the preferred method even in the
absence of shared storage. The evacuate API provides
many benefits over manual recovery, such as
re-attachment of volumes and floating IPs.</para>
<xi:include href="../common/section_cli_nova_evacuate.xml"/>
<section xml:id="nova-compute-node-down-manual-recovery">
<title>Manual recovery</title>
<para>For KVM/libvirt compute node recovery, see the
previous section. Use this procedure for other
hypervisors.</para>
<procedure>
<title>To work with host information</title>
<step>
<para>Identify the vms on the affected hosts,
using tools such as a combination of
<literal>nova list</literal> and
<literal>nova show</literal> or
<literal>euca-describe-instances</literal>.
Here's an example using the EC2 API -
instance i-000015b9 that is running on
node np-rcc54:</para>
<programlisting>i-000015b9 at3-ui02 running nectarkey (376, np-rcc54) 0 m1.xxlarge 2012-06-19T00:48:11.000Z 115.146.93.60</programlisting>
</step>
<step>
<para>You can review the status of the host by
using the nova database. Some of the
important information is highlighted
below. This example converts an EC2 API
instance ID into an OpenStack ID - if you
used the <literal>nova</literal> commands,
you can substitute the ID directly. You
can find the credentials for your database
in
<filename>/etc/nova.conf</filename>.</para>
<programlisting>SELECT * FROM instances WHERE id = CONV('15b9', 16, 10) \G;
*************************** 1. row ***************************
created_at: 2012-06-19 00:48:11
updated_at: 2012-07-03 00:35:11
deleted_at: NULL
...
id: 5561
...
power_state: 5
vm_state: shutoff
...
hostname: at3-ui02
host: np-rcc54
...
uuid: 3f57699a-e773-4650-a443-b4b37eed5a06
...
task_state: NULL
...</programlisting>
</step>
</procedure>
<procedure>
<title>To recover the VM</title>
<step>
<para>Armed with the information of VMs on the
failed host, determine to which compute
host the affected VMs should move. Run the
following database command to move the VM
to np-rcc46:</para>
<programlisting>UPDATE instances SET host = 'np-rcc46' WHERE uuid = '3f57699a-e773-4650-a443-b4b37eed5a06'; </programlisting>
</step>
<step>
<para>Next, if using a hypervisor that relies
on libvirt (such as KVM) it is a good idea
to update the
<literal>libvirt.xml</literal> file
(found in
<literal>/var/lib/nova/instances/[instance
ID]</literal>). The important changes
to make are to change the
<literal>DHCPSERVER</literal> value to
the host ip address of the Compute host
that is the VMs new home, and update the
VNC IP if it isn't already
<literal>0.0.0.0</literal>.</para>
</step>
<step>
<para>Next, reboot the VM:</para>
<screen><prompt>$</prompt> <userinput>nova reboot --hard 3f57699a-e773-4650-a443-b4b37eed5a06</userinput></screen>
</step>
<step>
<para>In theory, the above database update and
<literal>nova reboot</literal> command
are all that is required to recover the
VMs from a failed host. However, if
further problems occur, consider looking
at recreating the network filter
configuration using
<literal>virsh</literal>, restarting
the Compute services or updating the
<literal>vm_state</literal> and
<literal>power_state</literal> in the
Compute database.</para>
</step>
</procedure>
</section>
</section>
<section xml:id="section_nova-uid-mismatch">
<title>Recover from a UID/GID mismatch</title>
<para>When running OpenStack compute, using a shared file
system or an automated configuration tool, you could
encounter a situation where some files on your compute
node are using the wrong UID or GID. This causes a
raft of errors, such as being unable to live migrate,
or start virtual machines.</para>
<para>This basic procedure runs on <systemitem
class="service">nova-compute</systemitem> hosts,
based on the KVM hypervisor, that could help to
restore the situation:</para>
<procedure>
<title>To recover from a UID/GID mismatch</title>
<step>
<para>Make sure you don't use numbers that are
already used for some other user/group.</para>
</step>
<step>
<para>Set the nova uid in
<filename>/etc/passwd</filename> to the
same number in all hosts (for example,
112).</para>
</step>
<step>
<para>Set the libvirt-qemu uid in
<filename>/etc/passwd</filename> to the
same number in all hosts (for example,
119).</para>
</step>
<step>
<para>Set the nova group in
<filename>/etc/group</filename> file to
the same number in all hosts (for example,
120).</para>
</step>
<step>
<para>Set the libvirtd group in
<filename>/etc/group</filename> file to
the same number in all hosts (for example,
119).</para>
</step>
<step>
<para>Stop the services on the compute
node.</para>
</step>
<step>
<para>Change all the files owned by user nova or
by group nova. For example:</para>
<programlisting language="bash">find / -uid 108 -exec chown nova {} \; # note the 108 here is the old nova uid before the change
find / -gid 120 -exec chgrp nova {} \;</programlisting>
</step>
<step>
<para>Repeat the steps for the libvirt-qemu owned
files if those were needed to change.</para>
</step>
<step>
<para>Restart the services.</para>
</step>
<step>
<para>Now you can run the <command>find</command>
command to verify that all files using the
correct identifiers.</para>
</step>
</procedure>
</section>
<section xml:id="section_nova-disaster-recovery-process">
<title>Compute disaster recovery process</title>
<para>In this section describes how to manage your cloud
after a disaster, and how to easily back up the
persistent storage volumes. Backups <emphasis
role="bold">are</emphasis> mandatory, even outside
of disaster scenarios.</para>
<para>For reference, you can find a DRP definition at
<link
xlink:href="http://en.wikipedia.org/wiki/Disaster_Recovery_Plan"
>http://en.wikipedia.org/wiki/Disaster_Recovery_Plan</link>.</para>
<simplesect>
<title>A- The disaster recovery process
presentation</title>
<para>A disaster could happen to several components of
your architecture: a disk crash, a network loss, a
power cut, and so on. In this example, assume the
following set up:</para>
<orderedlist>
<listitem>
<para>A cloud controller (nova-api,
nova-objecstore, nova-network)</para>
</listitem>
<listitem>
<para>A compute node (<systemitem
class="service"
>nova-compute</systemitem>)</para>
</listitem>
<listitem>
<para>A Storage Area Network used by
<systemitem class="service"
>cinder-volumes</systemitem> (aka
SAN)</para>
</listitem>
</orderedlist>
<para>The disaster example is the worst one: a power
loss. That power loss applies to the three
components. <emphasis role="italic">Let's see what
runs and how it runs before the
crash</emphasis>:</para>
<itemizedlist>
<listitem>
<para>From the SAN to the cloud controller, we
have an active iscsi session (used for the
"cinder-volumes" LVM's VG).</para>
</listitem>
<listitem>
<para>From the cloud controller to the compute
node we also have active iscsi sessions
(managed by <systemitem class="service"
>cinder-volume</systemitem>).</para>
</listitem>
<listitem>
<para>For every volume an iscsi session is
made (so 14 ebs volumes equals 14
sessions).</para>
</listitem>
<listitem>
<para>From the cloud controller to the compute
node, we also have iptables/ ebtables
rules which allows the access from the
cloud controller to the running
instance.</para>
</listitem>
<listitem>
<para>And at least, from the cloud controller
to the compute node ; saved into database,
the current state of the instances (in
that case "running" ), and their volumes
attachment (mount point, volume id, volume
status, and so on.)</para>
</listitem>
</itemizedlist>
<para>Now, after the power loss occurs and all
hardware components restart, the situation is as
follows:</para>
<itemizedlist>
<listitem>
<para>From the SAN to the cloud, the ISCSI
session no longer exists.</para>
</listitem>
<listitem>
<para>From the cloud controller to the compute
node, the ISCSI sessions no longer exist.
</para>
</listitem>
<listitem>
<para>From the cloud controller to the compute
node, the iptables and ebtables are
recreated, since, at boot, nova-network
reapply the configurations.</para>
</listitem>
<listitem>
<para>From the cloud controller, instances
turn into a shutdown state (because they
are no longer running)</para>
</listitem>
<listitem>
<para>Into the database, data was not updated
at all, since Compute could not have
guessed the crash.</para>
</listitem>
</itemizedlist>
<para>Before going further, and to prevent the admin
to make fatal mistakes,<emphasis role="bold"> the
instances won't be lost</emphasis>, because no
"<command role="italic">destroy</command>" or
"<command role="italic">terminate</command>"
command was invoked, so the files for the
instances remain on the compute node.</para>
<para>Perform these tasks in that exact order.</para>
<para><emphasis role="underline">Any extra step would
be dangerous at this stage</emphasis> :</para>
<para>
<orderedlist>
<listitem>
<para>Get the current relation from a
volume to its instance, so that you
can recreate the attachment.</para>
</listitem>
<listitem>
<para>Update the database to clean the
stalled state. (After that, you cannot
perform the first step).</para>
</listitem>
<listitem>
<para>Restart the instances. In other
words, go from a shutdown to running
state.</para>
</listitem>
<listitem>
<para>After the restart, you can reattach
the volumes to their respective
instances.</para>
</listitem>
<listitem>
<para>That step, which is not a mandatory
one, exists in an SSH into the
instances to reboot them.</para>
</listitem>
</orderedlist>
</para>
</simplesect>
<simplesect>
<title>B - Disaster recovery</title>
<procedure>
<title>To perform disaster recovery</title>
<step>
<title>Get the instance-to-volume
relationship</title>
<para>You must get the current relationship
from a volume to its instance, because we
re-create the attachment.</para>
<para>You can find this relationship by
running <command>nova
volume-list</command>. Note that nova
client includes the ability to get volume
information from cinder.</para>
</step>
<step>
<title>Update the database</title>
<para>Update the database to clean the stalled
state. You must restore for every volume,
uses these queries to clean up the
database:</para>
<screen><prompt>mysql></prompt> <userinput>use cinder;</userinput>
<prompt>mysql></prompt> <userinput>update volumes set mountpoint=NULL;</userinput>
<prompt>mysql></prompt> <userinput>update volumes set status="available" where status &lt;&gt;"error_deleting";</userinput>
<prompt>mysql></prompt> <userinput>update volumes set attach_status="detached";</userinput>
<prompt>mysql></prompt> <userinput>update volumes set instance_id=0;</userinput></screen>
<para>Then, when you run <command>nova
volume-list</command> commands, all
volumes appear.</para>
</step>
<step>
<title>Restart instances</title>
<para>You can restart the instances through a
simple <command>nova reboot
<replaceable>$instance</replaceable></command>
</para>
<para>At that stage, depending on your image,
some instances completely reboot and
become reachable, while others stop on the
"plymouth" stage.</para>
</step>
<step>
<title>DO NOT reboot a second time</title>
<para>Do not reboot the ones that are stopped
at that stage (<emphasis role="italic">see
the fourth step</emphasis>). In fact
it depends on whether you added an
<filename>/etc/fstab</filename> entry
for that volume. Images built with the
<package>cloud-init</package> package
remain in a pending state, while others
skip the missing volume and start. (More
information is available on <link
xlink:href="https://help.ubuntu.com/community/CloudInit"
>help.ubuntu.com</link>.) The idea of
that stage is only to ask nova to reboot
every instance, so the stored state is
preserved.</para>
</step>
<step>
<title>Reattach volumes</title>
<para>After the restart, you can reattach the
volumes to their respective instances. Now
that nova has restored the right status,
it is time to perform the attachments
through a <command>nova
volume-attach</command></para>
<para>This simple snippet uses the created
file:</para>
<programlisting language="bash">#!/bin/bash
while read line; do
volume=`echo $line | $CUT -f 1 -d " "`
instance=`echo $line | $CUT -f 2 -d " "`
mount_point=`echo $line | $CUT -f 3 -d " "`
echo "ATTACHING VOLUME FOR INSTANCE - $instance"
nova volume-attach $instance $volume $mount_point
sleep 2
done &lt; $volumes_tmp_file</programlisting>
<para>At that stage, instances that were
pending on the boot sequence (<emphasis
role="italic">plymouth</emphasis>)
automatically continue their boot, and
restart normally, while the ones that
booted see the volume.</para>
</step>
<step>
<title>SSH into instances</title>
<para>If some services depend on the volume,
or if a volume has an entry into fstab, it
could be good to simply restart the
instance. This restart needs to be made
from the instance itself, not through
nova. So, we SSH into the instance and
perform a reboot:</para>
<screen><prompt>#</prompt> <userinput>shutdown -r now</userinput></screen>
</step>
</procedure>
<para>By completing this procedure, you can
successfully recover your cloud.</para>
<para>Follow these guidelines:</para>
<itemizedlist>
<listitem>
<para>Use the <parameter>
errors=remount</parameter> parameter
in the <filename>fstab</filename> file,
which prevents data corruption.</para>
<para>The system would lock any write to the
disk if it detects an I/O error. This
configuration option should be added into
the <systemitem class="service"
>cinder-volume</systemitem> server
(the one which performs the ISCSI
connection to the SAN), but also into the
instances' <filename>fstab</filename>
file.</para>
</listitem>
<listitem>
<para>Do not add the entry for the SAN's disks
to the <systemitem class="service"
>cinder-volume</systemitem>'s
<filename>fstab</filename>
file.</para>
<para>Some systems hang on that step, which
means you could lose access to your
cloud-controller. To re-run the session
manually, you would run the following
command before performing the mount:
<screen><prompt>#</prompt> <userinput>iscsiadm -m discovery -t st -p $SAN_IP $ iscsiadm -m node --target-name $IQN -p $SAN_IP -l</userinput></screen></para>
</listitem>
<listitem>
<para>For your instances, if you have the
whole <filename>/home/</filename>
directory on the disk, instead of emptying
the <filename>/home</filename> directory
and map the disk on it, leave a user's
directory with the user's bash files and
the <filename>authorized_keys</filename>
file.</para>
<para>This enables you to connect to the
instance, even without the volume
attached, if you allow only connections
through public keys.</para>
</listitem>
</itemizedlist>
</simplesect>
<simplesect>
<title>C - Scripted DRP</title>
<procedure>
<title>To use scripted DRP</title>
<para>You can download from <link
xlink:href="https://github.com/Razique/BashStuff/blob/master/SYSTEMS/OpenStack/SCR_5006_V00_NUAC-OPENSTACK-DRP-OpenStack.sh"
>here</link> a bash script which performs
these steps:</para>
<step>
<para>The "test mode" allows you to perform
that whole sequence for only one
instance.</para>
</step>
<step>
<para>To reproduce the power loss, connect to
the compute node which runs that same
instance and close the iscsi session.
<emphasis role="underline">Do not
detach the volume through
<command>nova
volume-detach</command></emphasis>,
but instead manually close the iscsi
session.</para>
</step>
<step>
<para>In this example, the iscsi session is
number 15 for that instance:</para>
<screen><prompt>$</prompt> <userinput>iscsiadm -m session -u -r 15</userinput></screen>
</step>
<step>
<para>Do not forget the <literal>-r</literal>
flag. Otherwise, you close ALL
sessions.</para>
</step>
</procedure>
</simplesect>
</section>
</section>
<xi:include href="../common/section_support-compute.xml"/>
</chapter>
View Git Blame Copy Permalink