openstack/openstack-manuals
Code Issues Proposed changes
ae6ef70788
openstack-manuals/doc/training-guides/module001-ch006-overview-horizon-cli.xml
Don Domingo 5fca287eb5 Apply service name conventions for Block Storage 
There are several instances of "Block Storage Service" in the
upstream documentation. As was recently clarified in the docs
mailing list, these should be "Block Storage service". This patch
applies the fix.

Change-Id: I591c100ab031b75f1c0d27d45f53e32401a26e30
Partial-Bug: #1217503
2014-03-26 15:31:17 +10:00

2546 lines
100 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:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="module001-ch006-overview-horizon-cli">
<title>Overview Horizon and OpenStack CLI</title>
<para><guilabel>How can I use an OpenStack cloud?</guilabel></para>
<para>As an OpenStack cloud end user, you can provision your own
resources within the limits set by administrators. The examples
in this guide show you how to complete these tasks by using the
OpenStack dashboard and command-line clients. The dashboard,
also known as horizon, is a Web-based graphical interface. The
command-line clients let you run simple commands to create and
manage resources in a cloud and automate tasks by using scripts.
Each of the core OpenStack projects has its own command-line
client.</para>
<para>You can modify these examples for your specific use
cases.</para>
<para>In addition to these ways of interacting with a cloud, you
can access the OpenStack APIs indirectly through cURLcommands
or open SDKs, or directly through the APIs. You can automate
access or build tools to manage resources and services by using
the native OpenStack APIs or the EC2 compatibility API.</para>
<para>To use the OpenStack APIs, it helps to be familiar with
HTTP/1.1, RESTful web services, the OpenStack services, and JSON
or XML data serialization formats.</para>
<para><guilabel>OpenStack dashboard</guilabel></para>
<para>As a cloud end user, the OpenStack dashboard lets you to
provision your own resources within the limits set by
administrators. You can modify these examples to create other
types and sizes of server instances.</para>
<para><guilabel>Overview</guilabel></para>
<para>The following requirements must be fulfilled to access the
OpenStack dashboard:</para>
<itemizedlist>
<listitem>
<para>The cloud operator has set up an OpenStack
cloud.</para>
</listitem>
<listitem>
<para>You have a recent Web browser that supports HTML5. It
must have cookies and JavaScript enabled. To use the VNC
client for the dashboard, which is based on noVNC, your
browser must support HTML5 Canvas and HTML5 WebSockets.
For more details and a list of browsers that support
noVNC, see<link
xlink:href="https://github.com/kanaka/noVNC/blob/master/README.md"
></link><link
xlink:href="https://github.com/kanaka/noVNC/blob/master/README.md"
>https://github.com/kanaka/noVNC/blob/master/README.md</link>,
and<link
xlink:href="https://github.com/kanaka/noVNC/wiki/Browser-support"
></link><link
xlink:href="https://github.com/kanaka/noVNC/wiki/Browser-support"
>https://github.com/kanaka/noVNC/wiki/Browser-support</link>,
respectively.</para>
</listitem>
</itemizedlist>
<para>Learn how to log in to the dashboard and get a short
overview of the interface.</para>
<para><guilabel>Log in to the dashboard</guilabel></para>
<para>To log in to the dashboard</para>
<orderedlist>
<listitem>
<para>Ask your cloud operator for the following
information:</para>
</listitem>
</orderedlist>
<itemizedlist>
<listitem>
<para>The hostname or public IP address from which you can
access the dashboard.</para>
</listitem>
<listitem>
<para>The dashboard is available on the node that has the
nova-dashboard server role.</para>
</listitem>
<listitem>
<para>The username and password with which you can log in to
the dashboard.</para>
</listitem>
</itemizedlist>
<orderedlist>
<listitem>
<para>Open a Web browser that supports HTML5. Make sure that
JavaScript and cookies are enabled.</para>
</listitem>
<listitem>
<para>As a URL, enter the host name or IP address that you
got from the cloud operator.</para>
</listitem>
<listitem>
<para><link xlink:href="https://ip_address_or_hostname/"
>https://IP_ADDRESS_OR_HOSTNAME/</link></para>
</listitem>
<listitem>
<para>On the dashboard log in page, enter your user name and
password and click Sign In.</para>
</listitem>
</orderedlist>
<para>After you log in, the following page appears:</para>
<figure>
<title>OpenStack Dashboard - Overview</title>
<mediaobject>
<imageobject>
<imagedata fileref="figures/image14.png"/>
</imageobject>
</mediaobject>
</figure>
<para>The top-level row shows the username that you logged in
with. You can also access Settingsor Sign Outof the Web
interface.</para>
<para>If you are logged in as an end user rather than an admin
user, the main screen shows only the Projecttab.</para>
<para><guilabel>OpenStack dashboard – Project tab</guilabel></para>
<para>This tab shows details for the projects, or projects, of
which you are a member.</para>
<para>Select a project from the drop-down list on the left-hand
side to access the following categories:</para>
<para><emphasis role="bold">Overview</emphasis></para>
<para>Shows basic reports on the project.</para>
<para><emphasis role="bold">Instances</emphasis></para>
<para>Lists instances and volumes created by users of the
project.</para>
<para>From here, you can stop, pause, or reboot any instances or
connect to them through virtual network computing
(VNC).</para>
<para><emphasis role="bold">Volumes</emphasis></para>
<para>Lists volumes created by users of the project.</para>
<para>From here, you can create or delete volumes.</para>
<para><emphasis role="bold">Images &amp;
Snapshots</emphasis></para>
<para>Lists images and snapshots created by users of the
project, plus any images that are publicly available. Includes
volume snapshots. From here, you can create and delete images
and snapshots, and launch instances from images and
snapshots.</para>
<para><emphasis role="bold">Access &amp;
Security</emphasis></para>
<para>On the<emphasis role="bold"> Security
Groupstab</emphasis>, you can list, create, and delete security
groups and edit rules for security groups.</para>
<para>On the <emphasis role="bold">Keypairstab</emphasis>, you
can list, create, and import keypairs, and delete keypairs.</para>
<para>On the <emphasis role="bold">Floating IPstab</emphasis>,
you can allocate an IP address to or release it from a
project.</para>
<para>On the <emphasis role="bold">API Accesstab</emphasis>, you
can list the API endpoints.</para>
<para><guilabel>Manage images</guilabel></para>
<para>During setup of OpenStack cloud, the cloud operator sets
user permissions to manage images. Image upload and management
might be restricted to only cloud administrators or cloud
operators. Though you can complete most tasks with the OpenStack
dashboard, you can manage images through only the glance and
nova clients or the Image Service and Compute APIs.</para>
<para><guilabel>Set up access and security</guilabel></para>
<para>Before you launch a virtual machine, you can add security
group rules to enable users to ping and SSH to the instances. To
do so, you either add rules to the default security group or add a
security group with rules. For information, see<link
xlink:href="http://docs.openstack.org/user-guide/content/security_groups_add_rule.html"
>the section called “Add security group rules”</link>.</para>
<para>Keypairs are SSH credentials that are injected into images
when they are launched. For this to work, the image must contain
the cloud-init package. For information, see<link
xlink:href="http://docs.openstack.org/user-guide/content/keypair_add.html"
>the section called “Add keypairs”</link>.</para>
<para><guilabel>Add security group rules</guilabel></para>
<para>The following procedure shows you how to add rules to the
default security group.</para>
<para>To add rules to the default security group</para>
<orderedlist>
<listitem>
<para>Log in to the OpenStack dashboard.</para>
</listitem>
<listitem>
<para>If you are a member of multiple projects, select a
project from the drop-down list at the top of the
Projecttab.</para>
</listitem>
<listitem>
<para>Click the Access &amp; Securitycategory.</para>
</listitem>
<listitem>
<para>The dashboard shows the security groups that are
available for this project.</para>
</listitem>
</orderedlist>
<figure>
<title>OpenStack Dashboard - Security Groups</title>
<mediaobject>
<imageobject>
<imagedata fileref="figures/image25.png"/>
</imageobject>
</mediaobject>
</figure>
<orderedlist>
<listitem>
<para>Select the default security group and click Edit
Rules.</para>
</listitem>
<listitem>
<para>The Security Group Rulespage appears:</para>
</listitem>
</orderedlist>
<figure>
<title>OpenStack Dashboard - Security Group Rules</title>
<mediaobject>
<imageobject>
<imagedata fileref="figures/image15.png"/>
</imageobject>
</mediaobject>
</figure>
<orderedlist>
<listitem>
<para>Add a TCP rule</para>
</listitem>
<listitem>
<para>Click Add Rule.</para>
</listitem>
<listitem>
<para>The Add Rulewindow appears.</para>
</listitem>
</orderedlist>
<orderedlist>
<listitem>
<para>In the IP Protocollist, select TCP.</para>
</listitem>
<listitem>
<para>In the Openlist, select Port.</para>
</listitem>
<listitem>
<para>In the Portbox, enter 22.</para>
</listitem>
<listitem>
<para>In the Sourcelist, select CIDR.</para>
</listitem>
<listitem>
<para>In the CIDRbox, enter 0.0.0.0/0.</para>
</listitem>
<listitem>
<para>Click Add.</para>
</listitem>
<listitem>
<para>Port 22 is now open for requests from any IP
address.</para>
</listitem>
<listitem>
<para>If you want to accept requests from a particular range
of IP addresses, specify the IP address block in the
CIDRbox.</para>
</listitem>
</orderedlist>
<orderedlist>
<listitem>
<para>Add an ICMP rule</para>
</listitem>
<listitem>
<para>Click Add Rule.</para>
</listitem>
<listitem>
<para>The Add Rulewindow appears.</para>
</listitem>
</orderedlist>
<orderedlist>
<listitem>
<para>In the IP Protocollist, select ICMP.</para>
</listitem>
<listitem>
<para>In the Typebox, enter -1.</para>
</listitem>
<listitem>
<para>In the Codebox, enter -1.</para>
</listitem>
<listitem>
<para>In the Sourcelist, select CIDR.</para>
</listitem>
<listitem>
<para>In the CIDRbox, enter 0.0.0.0/0.</para>
</listitem>
<listitem>
<para>Click Add.</para>
</listitem>
</orderedlist>
<para><guilabel>Add keypairs</guilabel></para>
<para>Create at least one keypair for each project. If you have
generated a keypair with an external tool, you can import it
into OpenStack. The keypair can be used for multiple instances
that belong to a project.</para>
<para>To add a keypair</para>
<orderedlist>
<listitem>
<para>Log in to the OpenStack dashboard.</para>
</listitem>
<listitem>
<para>If you are a member of multiple projects, select a
project from the drop-down list at the top of the
Projecttab.</para>
</listitem>
<listitem>
<para>Click the Access &amp; Securitycategory.</para>
</listitem>
<listitem>
<para>Click the Keypairstab. The dashboard shows the
keypairs that are available for this project.</para>
</listitem>
<listitem>
<para>To add a keypair</para>
</listitem>
<listitem>
<para>Click Create Keypair.</para>
</listitem>
<listitem>
<para>The Create Keypairwindow appears.</para>
</listitem>
</orderedlist>
<orderedlist>
<listitem>
<para>In the Keypair Namebox, enter a name for your
keypair.</para>
</listitem>
<listitem>
<para>Click Create Keypair.</para>
</listitem>
<listitem>
<para>Respond to the prompt to download the keypair.</para>
</listitem>
</orderedlist>
<orderedlist>
<listitem>
<para>To import a keypair</para>
</listitem>
<listitem>
<para>Click Import Keypair.</para>
</listitem>
<listitem>
<para>The Import Keypairwindow appears.</para>
</listitem>
</orderedlist>
<orderedlist>
<listitem>
<para>In the Keypair Namebox, enter the name of your
keypair.</para>
</listitem>
<listitem>
<para>In the Public Keybox, copy the public key.</para>
</listitem>
<listitem>
<para>Click Import Keypair.</para>
</listitem>
</orderedlist>
<orderedlist>
<listitem>
<para>Save the *.pem file locally and change its permissions
so that only you can read and write to the file:</para>
</listitem>
<listitem>
<para>$ chmod 0600 MY_PRIV_KEY.pem</para>
</listitem>
<listitem>
<para>Use the ssh-addcommand to make the keypair known to
SSH:</para>
</listitem>
<listitem>
<para>$ ssh-add MY_PRIV_KEY.pem</para>
</listitem>
</orderedlist>
<para>The public key of the keypair is registered in the Nova
database.</para>
<para>The dashboard lists the keypair in the Access &amp;
Securitycategory.</para>
<para><guilabel>Launch instances</guilabel></para>
<para>Instances are virtual machines that run inside the cloud.
You can launch an instance directly from one of the available
OpenStack images or from an image that you have copied to a
persistent volume. The OpenStack Image Service provides a pool
of images that are accessible to members of different
projects.</para>
<para><guilabel>Launch an instance from an image</guilabel></para>
<para>When you launch an instance from an image, OpenStack
creates a local copy of the image on the respective compute
node where the instance is started.</para>
<para>To launch an instance from an image</para>
<orderedlist>
<listitem>
<para>Log in to the OpenStack dashboard.</para>
</listitem>
<listitem>
<para>If you are a member of multiple projects, select a
project from the drop-down list at the top of the
Projecttab.</para>
</listitem>
<listitem>
<para>Click the Images &amp; Snapshotcategory.</para>
</listitem>
<listitem>
<para>The dashboard shows the images that have been uploaded
to OpenStack Image Service and are available for this
project.</para>
</listitem>
<listitem>
<para>Select an image and click Launch.</para>
</listitem>
<listitem>
<para>In the Launch Imagewindow, specify the
following:</para>
</listitem>
</orderedlist>
<orderedlist>
<listitem>
<para>Enter an instance name to assign to the virtual
machine.</para>
</listitem>
<listitem>
<para>From the Flavordrop-down list, select the size of the
virtual machine to launch.</para>
</listitem>
<listitem>
<para>Select a keypair.</para>
</listitem>
<listitem>
<para>In case an image uses a static root password or a
static key set (neither is recommended), you do not need
to provide a keypair to launch the instance.</para>
</listitem>
<listitem>
<para>In Instance Count, enter the number of virtual
machines to launch from this image.</para>
</listitem>
<listitem>
<para>Activate the security groups that you want to assign
to the instance.</para>
</listitem>
<listitem>
<para>Security groups are a kind of cloud firewall that
define which incoming network traffic should be forwarded to
instances. For details, see<link
xlink:href="http://docs.openstack.org/user-guide/content/security_groups_add_rule.html"
>the section called “Add security group
rules”</link>.</para>
</listitem>
<listitem>
<para>If you have not created any specific security groups,
you can only assign the instance to the default security
group.</para>
</listitem>
<listitem>
<para>If you want to boot from volume, click the respective
entry to expand its options. Set the options as described
in<link
xlink:href="http://docs.openstack.org/user-guide/content/dashboard_launch_instances.html#dashboard_launch_instances_from_volume"
></link><link
xlink:href="http://docs.openstack.org/user-guide/content/dashboard_launch_instances.html#dashboard_launch_instances_from_volume"
>the section called “Launch an instance from a
volume”</link>.</para>
</listitem>
</orderedlist>
<orderedlist>
<listitem>
<para>Click Launch Instance. The instance is started on any
of the compute nodes in the cloud.</para>
</listitem>
</orderedlist>
<para>After you have launched an instance, switch to the
Instancescategory to view the instance name, its (private or
public) IP address, size, status, task, and power
state.</para>
<para>Figure 5. OpenStack dashboard – Instances</para>
<para>If you did not provide a keypair, security groups, or
rules so far, by default the instance can only be accessed
from inside the cloud through VNC at this point. Even pinging
the instance is not possible. To access the instance through a
VNC console, see<link
xlink:href="http://docs.openstack.org/user-guide/content/instance_console.html"
></link><link
xlink:href="http://docs.openstack.org/user-guide/content/instance_console.html"
>the section called “Get a console to an
instance”</link>.</para>
<para><guilabel>Launch an instance from a volume</guilabel></para>
<para>You can launch an instance directly from an image that has
been copied to a persistent volume.</para>
<para>In that case, the instance is booted from the volume,
which is provided by nova-volume, through iSCSI.</para>
<para>For preparation details, see<link
xlink:href="http://docs.openstack.org/user-guide/content/dashboard_manage_volumes.html#create_or_delete_volumes"
></link><link
xlink:href="http://docs.openstack.org/user-guide/content/dashboard_manage_volumes.html#create_or_delete_volumes"
>the section called “Create or delete a
volume”</link>.</para>
<para>To boot an instance from the volume, especially note the
following steps:</para>
<itemizedlist>
<listitem>
<para>To be able to select from which volume to boot, launch
an instance from an arbitrary image. The image you select
does not boot. It is replaced by the image on the volume
that you choose in the next steps.</para>
</listitem>
<listitem>
<para>In case you want to boot a Xen image from a volume,
note the following requirement: The image you launch in
must be the same type, fully virtualized or
paravirtualized, as the one on the volume.</para>
</listitem>
<listitem>
<para>Select the volume or volume snapshot to boot
from.</para>
</listitem>
<listitem>
<para>Enter a device name. Enter vda for KVM images or xvda
for Xen images.</para>
</listitem>
</itemizedlist>
<para></para>
<para>To launch an instance from a volume</para>
<para>You can launch an instance directly from one of the images
available through the OpenStack Image Service or from an image
that you have copied to a persistent volume. When you launch
an instance from a volume, the procedure is basically the same
as when launching an instance from an image in OpenStack Image
Service, except for some additional steps.</para>
<orderedlist>
<listitem>
<para>Create a volume as described in<link
xlink:href="http://docs.openstack.org/user-guide/content/dashboard_manage_volumes.html#create_or_delete_volumes"
></link><link
xlink:href="http://docs.openstack.org/user-guide/content/dashboard_manage_volumes.html#create_or_delete_volumes"
>the section called “Create or delete a
volume”</link>.</para>
</listitem>
<listitem>
<para>It must be large enough to store an unzipped
image.</para>
</listitem>
<listitem>
<para>Create an image.</para>
</listitem>
<listitem>
<para>For details, see <link
xlink:href="http://docs.openstack.org/image-guide/content/ch_creating_images_manually.html"
>Creating images manually</link> in the
<citetitle>OpenStack Virtual Machine Image Guide</citetitle>.
</para>
</listitem>
<listitem>
<para>Launch an instance.</para>
</listitem>
<listitem>
<para>Attach the volume to the instance as described in<link
xlink:href="http://docs.openstack.org/user-guide/content/dashboard_manage_volumes.html#attach_volumes_to_instances"
></link><link
xlink:href="http://docs.openstack.org/user-guide/content/dashboard_manage_volumes.html#attach_volumes_to_instances"
>the section called “Attach volumes to
instances”</link>.</para>
</listitem>
<listitem>
<para>Assuming that the attached volume is mounted as
/dev/vdb, use one of the following commands to copy the
image to the attached volume:</para>
</listitem>
</orderedlist>
<itemizedlist>
<listitem>
<para>For a raw image:</para>
</listitem>
<listitem>
<para>$ cat IMAGE &gt;/dev/null</para>
</listitem>
<listitem>
<para>Alternatively, use dd.</para>
</listitem>
<listitem>
<para>For a non-raw image:</para>
</listitem>
<listitem>
<para>$ qemu-img convert -O raw IMAGE /dev/vdb</para>
</listitem>
<listitem>
<para>For a *.tar.bz2 image:</para>
</listitem>
<listitem>
<para>$ tar xfjO IMAGE &gt;/dev/null</para>
</listitem>
</itemizedlist>
<orderedlist>
<listitem>
<para>Only detached volumes are available for booting.
Detach the volume.</para>
</listitem>
<listitem>
<para>To launch an instance from the volume, continue
with<link
xlink:href="http://docs.openstack.org/user-guide/content/dashboard_launch_instances.html#dashboard_launch_instances_from_image"
></link><link
xlink:href="http://docs.openstack.org/user-guide/content/dashboard_launch_instances.html#dashboard_launch_instances_from_image"
>the section called “Launch an instance from an
image”</link>.</para>
</listitem>
<listitem>
<para>You can launch an instance directly from one of the
images available through the OpenStack Image Service. When
you do that, OpenStack creates a local copy of the image
on the respective compute node where the instance is
started.</para>
</listitem>
<listitem>
<para>SSH in to your instance</para>
</listitem>
</orderedlist>
<para>To SSH into your instance, you use the downloaded keypair
file.</para>
<para>To SSH into your instance</para>
<orderedlist>
<listitem>
<para>Copy the IP address for your instance.</para>
</listitem>
<listitem>
<para>Use the SSH command to make a secure connection to the
instance. For example:</para>
</listitem>
<listitem>
<para>$ ssh -i MyKey.pem ubuntu@10.0.0.2</para>
</listitem>
<listitem>
<para>A prompt asks, "Are you sure you want to continue
connection (yes/no)?" Type yes and you have successfully
connected.</para>
</listitem>
</orderedlist>
<para><guilabel>Manage instances</guilabel></para>
<para><guilabel>Create instance snapshots</guilabel></para>
<figure>
<title>OpenStack Dashboard- Instances</title>
<mediaobject>
<imageobject>
<imagedata fileref="figures/image00.png"/>
</imageobject>
</mediaobject>
</figure>
<para>To create instance snapshots</para>
<orderedlist>
<listitem>
<para>Log in to the OpenStack dashboard.</para>
</listitem>
<listitem>
<para>If you are a member of multiple projects, select a
project from the drop-down list at the top of the
Projecttab.</para>
</listitem>
<listitem>
<para>Click the Instancescategory.</para>
</listitem>
<listitem>
<para>The dashboard lists the instances that are available
for this project.</para>
</listitem>
<listitem>
<para>Select the instance of which to create a snapshot.
From the Actionsdrop-down list, select Create
Snapshot.</para>
</listitem>
<listitem>
<para>In the Create Snapshotwindow, enter a name for the
snapshot. Click Create Snapshot. The dashboard shows the
instance snapshot in the Images &amp;
Snapshotscategory.</para>
</listitem>
<listitem>
<para>To launch an instance from the snapshot, select the
snapshot and click Launch. Proceed with<link
xlink:href="http://docs.openstack.org/user-guide/content/dashboard_launch_instances.html#dashboard_launch_instances_from_image"
></link><link
xlink:href="http://docs.openstack.org/user-guide/content/dashboard_launch_instances.html#dashboard_launch_instances_from_image"
>the section called “Launch an instance from an
image”</link>.</para>
</listitem>
</orderedlist>
<para><guilabel>Control the state of an instance</guilabel></para>
<para>To control the state of an instance</para>
<orderedlist>
<listitem>
<para>Log in to the OpenStack dashboard.</para>
</listitem>
<listitem>
<para>If you are a member of multiple projects, select a
project from the drop-down list at the top of the
Projecttab.</para>
</listitem>
<listitem>
<para>Click the Instancescategory.</para>
</listitem>
<listitem>
<para>The dashboard lists the instances that are available
for this project.</para>
</listitem>
<listitem>
<para>Select the instance for which you want to change the
state.</para>
</listitem>
<listitem>
<para>In the Moredrop-down list in the Actionscolumn,
select the state.</para>
</listitem>
<listitem>
<para>Depending on the current state of the instance, you
can choose to pause, un-pause, suspend, resume, soft or
hard reboot, or terminate an instance.</para>
</listitem>
</orderedlist>
<figure>
<title>OpenStack Dashboard : Actions</title>
<mediaobject>
<imageobject>
<imagedata fileref="figures/image30.png"/>
</imageobject>
</mediaobject>
</figure>
<para><guilabel>Track usage</guilabel></para>
<para>Use the dashboard's Overviewcategory to track usage of
instances for each project.</para>
<figure>
<title>OpenStack Dashboard - Track Usage</title>
<mediaobject>
<imageobject>
<imagedata fileref="figures/image14.png"/>
</imageobject>
</mediaobject>
</figure>
<para>You can track costs per month by showing metrics like
number of VCPUs, disks, RAM, and uptime of all your
instances.</para>
<para>To track usage</para>
<orderedlist>
<listitem>
<para>If you are a member of multiple projects, select a
project from the drop-down list at the top of the
Projecttab.</para>
</listitem>
<listitem>
<para>Select a month and click Submitto query the instance
usage for that month.</para>
</listitem>
<listitem>
<para>Click Download CSV Summaryto download a CVS
summary.</para>
</listitem>
</orderedlist>
<para><guilabel>Manage volumes</guilabel></para>
<para>Volumes are block storage devices that you can attach to
instances. They allow for persistent storage as they can be
attached to a running instance, or detached and attached to
another instance at any time.</para>
<para>In contrast to the instance's root disk, the data of volumes
is not destroyed when the instance is deleted.</para>
<para><guilabel>Create or delete a volume</guilabel></para>
<para>To create or delete a volume</para>
<orderedlist>
<listitem>
<para>Log in to the OpenStack dashboard.</para>
</listitem>
<listitem>
<para>If you are a member of multiple projects, select a
Projectfrom the drop-down list at the top of the
tab.</para>
</listitem>
<listitem>
<para>Click the Volumescategory.</para>
</listitem>
<listitem>
<para>To create a volume</para>
</listitem>
</orderedlist>
<orderedlist>
<listitem>
<para>Click Create Volume.</para>
</listitem>
<listitem>
<para>In the window that opens, enter a name to assign to a
volume, a description (optional), and define the size in
GBs.</para>
</listitem>
<listitem>
<para>Confirm your changes.</para>
</listitem>
<listitem>
<para>The dashboard shows the volume in the
Volumescategory.</para>
</listitem>
</orderedlist>
<orderedlist>
<listitem>
<para>To delete one or multiple volumes</para>
</listitem>
</orderedlist>
<orderedlist>
<listitem>
<para>Activate the checkboxes in front of the volumes that
you want to delete.</para>
</listitem>
<listitem>
<para>Click Delete Volumesand confirm your choice in the
pop-up that appears.</para>
</listitem>
<listitem>
<para>A message indicates whether the action was
successful.</para>
</listitem>
</orderedlist>
<para>After you create one or more volumes, you can attach them
to instances.</para>
<para>You can attach a volume to one instance at a time.</para>
<para>View the status of a volume in the Instances &amp;
Volumescategory of the dashboard: the volume is either
available or In-Use.</para>
<para><guilabel>Attach volumes to instances</guilabel></para>
<para>To attach volumes to instances</para>
<orderedlist>
<listitem>
<para>Log in to OpenStack dashboard.</para>
</listitem>
<listitem>
<para>If you are a member of multiple projects, select a
Projectfrom the drop-down list at the top of the
tab.</para>
</listitem>
<listitem>
<para>Click the Volumescategory.</para>
</listitem>
<listitem>
<para>Select the volume to add to an instance and click Edit
Attachments.</para>
</listitem>
<listitem>
<para>In the Manage Volume Attachmentswindow, select an
instance.</para>
</listitem>
<listitem>
<para>Enter a device name under which the volume should be
accessible on the virtual machine.</para>
</listitem>
<listitem>
<para>Click Attach Volumeto confirm your changes. The
dashboard shows the instance to which the volume has been
attached and the volume's device name.</para>
</listitem>
<listitem>
<para>Now you can log in to the instance, mount the disk,
format it, and use it.</para>
</listitem>
<listitem>
<para>To detach a volume from an instance</para>
</listitem>
</orderedlist>
<orderedlist>
<listitem>
<para>Select the volume and click Edit Attachments.</para>
</listitem>
<listitem>
<para>Click Detach Volumeand confirm your changes.</para>
</listitem>
<listitem>
<para>A message indicates whether the action was
successful.</para>
</listitem>
</orderedlist>
<para><guilabel>OpenStack command-line clients</guilabel></para>
<para><guilabel>Overview</guilabel></para>
<para>You can use the OpenStack command-line clients to run
simple commands that make API calls and automate tasks by
using scripts. Internally, each client command runs cURL
commands that embed API requests. The OpenStack APIs are
RESTful APIs that use the HTTP protocol, including methods,
URIs, media types, and response codes.</para>
<para>These open-source Python clients run on Linux or Mac OS X
systems and are easy to learn and use. Each OpenStack service
has its own command-line client. On some client commands, you
can specify a debugparameter to show the underlying API
request for the command. This is a good way to become familiar
with the OpenStack API calls.</para>
<para>The following command-line clients are available for the
respective services' APIs:</para>
<para>cinder(python-cinderclient)</para>
<para>Client for the Block Storage service API. Use to create
and manage volumes.</para>
<para>glance(python-glanceclient)</para>
<para>Client for the Image Service API. Use to create and manage
images.</para>
<para>keystone(python-keystoneclient)</para>
<para>Client for the Identity Service API. Use to create and
manage users, tenants, roles, endpoints, and
credentials.</para>
<para>nova(python-novaclient)</para>
<para>Client for the Compute API and its extensions. Use to
create and manage images, instances, and flavors.</para>
<para>neutron(python-neutronclient)</para>
<para>Client for the Networking API. Use to configure networks
for guest servers. This client was previously known as
neutron.</para>
<para>swift(python-swiftclient)</para>
<para>Client for the Object Storage API. Use to gather
statistics, list items, update metadata, upload, download and
delete files stored by the object storage service. Provides
access to a swift installation for ad hoc processing.</para>
<para>heat(python-heatclient)</para>
<para>Client for the Orchestration API. Use to launch stacks
from templates, view details of running stacks including
events and resources, and update and delete stacks.</para>
<para><guilabel>Install the OpenStack command-line clients</guilabel></para>
<para>To install the clients, install the prerequisite software
and the Python package for each OpenStack client.</para>
<para><guilabel>Install the clients</guilabel></para>
<para>Use pipto install the OpenStack clients on a Mac OS X
or Linux system. It is easy and ensures that you get the
latest version of the client from the<link
xlink:href="http://pypi.python.org/pypi"></link><link
xlink:href="http://pypi.python.org/pypi">Python Package
Index</link>. Also, piplets you update or remove a
package. After you install the clients, you must source an
openrc file to set required environment variables before you
can request OpenStack services through the clients or the
APIs.</para>
<para>To install the clients</para>
<orderedlist>
<listitem>
<para>You must install each client separately.</para>
</listitem>
<listitem>
<para>Run the following command to install or update a
client package:</para>
<screen><prompt>#</prompt> <userinput>pip install [--update] python-&lt;project>client</userinput></screen>
<para>Where &lt;project> is the project name and has one
of the following values:</para>
<itemizedlist>
<listitem>
<para>nova. Compute API and extensions.</para>
</listitem>
<listitem>
<para>neutron. Networking API.</para>
</listitem>
<listitem>
<para>keystone. Identity Service API.</para>
</listitem>
<listitem>
<para>glance. Image Service API.</para>
</listitem>
<listitem>
<para>swift. Object Storage API.</para>
</listitem>
<listitem>
<para>cinder. Block Storage service API.</para>
</listitem>
<listitem>
<para>heat. Orchestration API.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>For example, to install the nova client, run the
following command:</para>
<screen><prompt>#</prompt> <userinput>pip install python-novaclient</userinput></screen>
</listitem>
<listitem>
<para>To update the nova client, run the following
command:</para>
<screen><prompt>#</prompt> <userinput>pip install --upgrade python-novaclient</userinput></screen>
</listitem>
<listitem>
<para>To remove the nova client, run the following
command:</para>
<screen><prompt>#</prompt> <userinput>pip uninstall python-novaclient</userinput></screen>
</listitem>
<listitem>
<para>Before you can issue client commands, you must
download and source the openrc file to set environment
variables. Proceed to<link
xlink:href="http://docs.openstack.org/user-guide/content/cli_openrc.html"
>the section called “OpenStack RC file”</link>.</para>
</listitem>
</orderedlist>
<para><guilabel>Get the version for a client</guilabel></para>
<para>After you install an OpenStack client, you can search for
its version number, as follows:</para>
<para>$ pip freeze | grep python-</para>
<para>python-glanceclient==0.4.0python-keystoneclient==0.1.2-e
git+https://github.com/openstack/python-novaclient.git@077cc0bf22e378c4c4b970f2331a695e440a939f#egg=python_novaclient-devpython-neutronclient==0.1.1python-swiftclient==1.1.1</para>
<para>You can also use the yolk -lcommand to see which version of
the client is installed:</para>
<para>$ yolk -l | grep python-novaclient</para>
<para>python-novaclient - 2.6.10.27 - active development
(/Users/your.name/src/cloud-servers/src/src/python-novaclient)python-novaclient
- 2012.1 - non-active</para>
<para><guilabel>OpenStack RC file</guilabel></para>
<para>To set the required environment variables for the OpenStack
command-line clients, you must download and source an
environment file, openrc.sh. It is project-specific and contains
the credentials used by OpenStack Compute, Image, and Identity
services.</para>
<para>When you source the file and enter the password, environment
variables are set for that shell. They allow the commands to
communicate to the OpenStack services that run in the
cloud.</para>
<para>You can download the file from the OpenStack dashboard as an
administrative user or any other user.</para>
<para>To download the OpenStack RC file</para>
<orderedlist>
<listitem>
<para>Log in to the OpenStack dashboard.</para>
</listitem>
<listitem>
<para>On the Projecttab, select the project for which you
want to download the OpenStack RC file.</para>
</listitem>
<listitem>
<para>Click Access &amp; Security. Then, click Download
OpenStack RC Fileand save the file.</para>
</listitem>
<listitem>
<para>Copy the openrc.sh file to the machine from where you
want to run OpenStack commands.</para>
</listitem>
<listitem>
<para>For example, copy the file to the machine from where you
want to upload an image with a glance client command.</para>
</listitem>
<listitem>
<para>On any shell from where you want to run OpenStack
commands, source the openrc.sh file for the respective
project.</para>
</listitem>
<listitem>
<para>In this example, we source the demo-openrc.sh file for
the demo project:</para>
</listitem>
<listitem>
<para>$ source demo-openrc.sh</para>
</listitem>
<listitem>
<para>When you are prompted for an OpenStack password, enter
the OpenStack password for the user who downloaded the
openrc.sh file.</para>
</listitem>
<listitem>
<para>When you run OpenStack client commands, you can override
some environment variable settings by using the options that
are listed at the end of the nova helpoutput. For example,
you can override the OS_PASSWORD setting in the openrc.sh
file by specifying a password on a nova command, as
follows:</para>
</listitem>
<listitem>
<para>$ nova --password &lt;password> image-list</para>
</listitem>
<listitem>
<para>Where password is your password.</para>
</listitem>
</orderedlist>
<para><guilabel>Manage images</guilabel></para>
<para>During setup of OpenStack cloud, the cloud operator sets
user permissions to manage images.</para>
<para>Image upload and management might be restricted to only
cloud administrators or cloud operators.</para>
<para>After you upload an image, it is considered golden and you
cannot change it.</para>
<para>You can upload images through the glance client or the Image
Service API. You can also use the nova client to list images,
set and delete image metadata, delete images, and take a
snapshot of a running instance to create an image.</para>
<para><guilabel>Manage images with the glance client</guilabel></para>
<para>To list or get details for images</para>
<orderedlist>
<listitem>
<para>To list the available images:</para>
</listitem>
<listitem>
<para>$ glance image-list</para>
</listitem>
<listitem>
<para>You can use grep to filter the list, as
follows:</para>
</listitem>
<listitem>
<para>$ glance image-list | grep 'cirros'</para>
</listitem>
<listitem>
<para>To get image details, by name or ID:</para>
</listitem>
<listitem>
<para>$ glance image-show myCirrosImage</para>
</listitem>
</orderedlist>
<para>To add an image</para>
<itemizedlist>
<listitem>
<para>The following example uploads a CentOS 6.3 image in
qcow2 format and configures it for public access:</para>
</listitem>
<listitem>
<para>$glance image-create --name centos63-image
--disk-format=qcow2 --container-format=bare
--is-public=True ./centos63.qcow2</para>
</listitem>
</itemizedlist>
<para>To create an image</para>
<orderedlist>
<listitem>
<para>Write any buffered data to disk.</para>
</listitem>
<listitem>
<para>For more information, see the<link
xlink:href="http://docs.openstack.org/trunk/openstack-ops/content/snapsnots.html"
>Taking Snapshots</link> in the OpenStack Operations
Guide.</para>
</listitem>
<listitem>
<para>To create the image, list instances to get the server
ID:</para>
</listitem>
<listitem>
<para>$ nova list</para>
</listitem>
<listitem>
<para>In this example, the server is named myCirrosServer.
Use this server to create a snapshot, as follows:</para>
</listitem>
<listitem>
<para>$ nova image-create myCirrosServer
myCirrosImage</para>
</listitem>
<listitem>
<para>The command creates a qemu snapshot and automatically
uploads the image to your repository. Only the tenant that
creates the image has access to it.</para>
</listitem>
<listitem>
<para>Get details for your image to check its status:</para>
</listitem>
<listitem>
<para>$ nova image-show IMAGE</para>
</listitem>
<listitem>
<para>The image status changes from SAVING to ACTIVE. Only
the tenant who creates the image has access to it.</para>
</listitem>
</orderedlist>
<para>To launch an instance from your image</para>
<itemizedlist>
<listitem>
<para>To launch an instance from your image, include the
image ID and flavor ID, as follows:</para>
</listitem>
<listitem>
<para>$ nova boot newServer --image
7e5142af-1253-4634-bcc6-89482c5f2e8a --flavor 3</para>
</listitem>
</itemizedlist>
<para><guilabel>Troubleshoot image creation</guilabel></para>
<itemizedlist>
<listitem>
<para>You cannot create a snapshot from an instance that
has an attached volume. Detach the volume, create the
image, and re-mount the volume.</para>
</listitem>
<listitem>
<para>Make sure the version of qemu you are using is
version 0.14 or greater. Older versions of qemu result
in an "unknown option -s" error message in the
nova-compute.log.</para>
</listitem>
<listitem>
<para>Examine the /var/log/nova-api.log and
/var/log/nova-compute.log log files for error
messages.</para>
</listitem>
</itemizedlist>
<para><guilabel>Set up access and security for instances</guilabel></para>
<para>When you launch a virtual machine, you can inject a key
pair, which provides SSH access to your instance. For this to
work, the image must contain the cloud-init package. Create at
least one key pair for each project. If you generate a keypair
with an external tool, you can import it into OpenStack. You can
use the key pair for multiple instances that belong to that
project. In case an image uses a static root password or a
static key set – neither is recommended – you must not provide a
key pair when you launch the instance.</para>
<para>A security group is a named collection of network access
rules that you use to limit the types of traffic that have
access to instances. When you launch an instance, you can assign
one or more security groups to it. If you do not create security
groups, new instances are automatically assigned to the default
security group, unless you explicitly specify a different
security group. The associated rules in each security group
control the traffic to instances in the group. Any incoming
traffic that is not matched by a rule is denied access by
default. You can add rules to or remove rules from a security
group. You can modify rules for the default and any other
security group.</para>
<para>You must modify the rules for the default security group
because users cannot access instances that use the default group
from any IP address outside the cloud.</para>
<para>You can modify the rules in a security group to allow access
to instances through different ports and protocols. For example,
you can modify rules to allow access to instances through SSH,
to ping them, or to allow UDP traffic – for example, for a DNS
server running on an instance. You specify the following
parameters for rules:</para>
<itemizedlist>
<listitem>
<para>Source of traffic. Enable traffic to instances from
either IP addresses inside the cloud from other group
members or from all IP addresses.</para>
</listitem>
<listitem>
<para>Protocol. Choose TCP for SSH, ICMP for pings, or
UDP.</para>
</listitem>
<listitem>
<para>Destination port on virtual machine. Defines a port
range. To open a single port only, enter the same value
twice. ICMP does not support ports: Enter values to define
the codes and types of ICMP traffic to be allowed.</para>
</listitem>
</itemizedlist>
<para>Rules are automatically enforced as soon as you create or
modify them.</para>
<para>You can also assign a floating IP address to a running
instance to make it accessible from outside the cloud. You
assign a floating IP address to an instance and attach a block
storage device, or volume, for persistent storage.</para>
<para><guilabel>Add or import keypairs</guilabel></para>
<para>To add a key</para>
<para>You can generate a keypair or upload an existing public
key.</para>
<orderedlist>
<listitem>
<para>To generate a keypair, run the following
command:</para>
</listitem>
<listitem>
<para>$ nova keypair-add KEY_NAME &gt; MY_KEY.pem</para>
</listitem>
<listitem>
<para>The command generates a keypair named KEY_NAME, writes
the private key to the MY_KEY.pem file, and registers the
public key at the Nova database.</para>
</listitem>
<listitem>
<para>To set the permissions of the MY_KEY.pem file, run the
following command:</para>
</listitem>
<listitem>
<para>$ chmod 600 MY_KEY.pem</para>
</listitem>
<listitem>
<para>The command changes the permissions of the MY_KEY.pem
file so that only you can read and write to it.</para>
</listitem>
</orderedlist>
<para>To import a key</para>
<orderedlist>
<listitem>
<para>If you have already generated a keypair with the
public key located at ~/.ssh/id_rsa.pub, run the following
command to upload the public key:</para>
</listitem>
<listitem>
<para>$ nova keypair-add --pub_key ~/.ssh/id_rsa.pub
KEY_NAME</para>
</listitem>
<listitem>
<para>The command registers the public key at the Nova
database and names the keypair KEY_NAME.</para>
</listitem>
<listitem>
<para>List keypairs to make sure that the uploaded keypair
appears in the list:</para>
</listitem>
<listitem>
<para>$ nova keypair-list</para>
</listitem>
</orderedlist>
<para><guilabel>Configure security groups and rules</guilabel></para>
<para>To configure security groups</para>
<orderedlist>
<listitem>
<para>To list all security groups</para>
</listitem>
<listitem>
<para>To list security groups for the current project,
including descriptions, enter the following
command:</para>
</listitem>
<listitem>
<para>$ nova secgroup-list</para>
</listitem>
<listitem>
<para>To create a security group</para>
</listitem>
<listitem>
<para>To create a security group with a specified name and
description, enter the following command:</para>
</listitem>
<listitem>
<para>$ nova secgroup-create SEC_GROUP_NAME
GROUP_DESCRIPTION</para>
</listitem>
<listitem>
<para>To delete a security group</para>
</listitem>
<listitem>
<para>To delete a specified group, enter the following
command:</para>
</listitem>
<listitem>
<para>$ nova secgroup-delete SEC_GROUP_NAME</para>
</listitem>
</orderedlist>
<para>To configure security group rules</para>
<para>Modify security group rules with the nova
secgroup-*-rulecommands.</para>
<orderedlist>
<listitem>
<para>On a shell, source the OpenStack RC file. For details,
see<link
xlink:href="http://docs.openstack.org/user-guide/content/cli_openrc.html"
></link><link
xlink:href="http://docs.openstack.org/user-guide/content/cli_openrc.html"
>the section called “OpenStack RC file”</link>.</para>
</listitem>
<listitem>
<para>To list the rules for a security group</para>
</listitem>
<listitem>
<para>$ nova secgroup-list-rules SEC_GROUP_NAME</para>
</listitem>
<listitem>
<para>To allow SSH access to the instances</para>
</listitem>
<listitem>
<para>Choose one of the following sub-steps:</para>
</listitem>
</orderedlist>
<orderedlist>
<listitem>
<para>Add rule for all IPs</para>
</listitem>
<listitem>
<para>Either from all IP addresses (specified as IP subnet
in CIDR notation as 0.0.0.0/0):</para>
</listitem>
<listitem>
<para>$ nova secgroup-add-rule SEC_GROUP_NAME tcp 22 22
0.0.0.0/0</para>
</listitem>
</orderedlist>
<orderedlist>
<listitem>
<para>Add rule for security groups</para>
</listitem>
<listitem>
<para>Alternatively, you can allow only IP addresses from
other security groups (source groups) to access the
specified port:</para>
</listitem>
<listitem>
<para>$ nova secgroup-add-group-rule --ip_proto tcp
--from_port 22 \ --to_port 22 SEC_GROUP_NAME
SOURCE_GROUP_NAME</para>
</listitem>
</orderedlist>
<orderedlist>
<listitem>
<para>To allow pinging the instances</para>
</listitem>
<listitem>
<para>Choose one of the following sub-steps:</para>
</listitem>
</orderedlist>
<orderedlist>
<listitem>
<para>To allow pinging from IPs</para>
</listitem>
<listitem>
<para>Specify all IP addresses as IP subnet in CIDR
notation: 0.0.0.0/0. This command allows access to all
codes and all types of ICMP traffic, respectively:</para>
</listitem>
<listitem>
<para>$ nova secgroup-add-rule SEC_GROUP_NAME icmp -1 -1
0.0.0.0/0</para>
</listitem>
<listitem>
<para>To allow pinging from other security groups</para>
</listitem>
<listitem>
<para>To allow only members of other security groups (source
groups) to ping instances:</para>
</listitem>
<listitem>
<para>$ nova secgroup-add-group-rule --ip_proto icmp
--from_port -1 \ --to_port -1 SEC_GROUP_NAME
SOURCE_GROUP_NAME</para>
</listitem>
</orderedlist>
<orderedlist>
<listitem>
<para>To allow access through UDP port</para>
</listitem>
<listitem>
<para>To allow access through a UDP port, such as allowing
access to a DNS server that runs on a VM, complete one of
the following sub-steps:</para>
</listitem>
</orderedlist>
<orderedlist>
<listitem>
<para>To allow UDP access from IPs</para>
</listitem>
<listitem>
<para>Specify all IP addresses as IP subnet in CIDR
notation: 0.0.0.0/0.</para>
</listitem>
<listitem>
<para>$ nova secgroup-add-rule SEC_GROUP_NAME udp 53 53
0.0.0.0/0</para>
</listitem>
<listitem>
<para>To allow UDP access</para>
</listitem>
<listitem>
<para>To allow only IP addresses from other security groups
(source groups) to access the specified port:</para>
</listitem>
<listitem>
<para>$ nova secgroup-add-group-rule --ip_proto udp
--from_port 53 \ --to_port 53 SEC_GROUP_NAME
SOURCE_GROUP_NAME</para>
</listitem>
</orderedlist>
<orderedlist>
<listitem>
<para>To delete a security group rule, specify the same
arguments that you used to create the rule.</para>
</listitem>
<listitem>
<para>To delete the security rule that you created in<link
xlink:href="http://docs.openstack.org/user-guide/content/configure_security_groups_rules.html#sec_group_rule_add"
>Step 3.a</link>:</para>
</listitem>
<listitem>
<para>$ nova secgroup-delete-rule SEC_GROUP_NAME tcp 22 22
0.0.0.0/0</para>
</listitem>
<listitem>
<para>To delete the security rule that you created in<link
xlink:href="http://docs.openstack.org/user-guide/content/configure_security_groups_rules.html#sec_group_rule_add_alt"
>Step 3.b</link>:</para>
</listitem>
<listitem>
<para>$ nova secgroup-delete-group-rule --ip_proto tcp
--from_port 22 \ --to_port 22 SEC_GROUP_NAME
SOURCE_GROUP_NAME</para>
</listitem>
</orderedlist>
<para><guilabel>Launch instances</guilabel></para>
<para>Instances are virtual machines that run inside the
cloud.</para>
<para>Before you can launch an instance, you must gather
parameters such as the image and flavor from which you want to
launch your instance.</para>
<para>You can launch an instance directly from one of the
available OpenStack images or from an image that you have copied
to a persistent volume. The OpenStack Image Service provides a
pool of images that are accessible to members of different
projects.</para>
<para><guilabel>Gather parameters to launch an instance</guilabel></para>
<para>To launch an instance, you must specify the following
parameters:</para>
<itemizedlist>
<listitem>
<para>The instance source, which is an image or snapshot.
Alternatively, you can boot from a volume, which is block
storage, to which you've copied an image or
snapshot.</para>
</listitem>
<listitem>
<para>The image or snapshot, which represents the operating
system.</para>
</listitem>
<listitem>
<para>A name for your instance.</para>
</listitem>
<listitem>
<para>The flavor for your instance, which defines the
compute, memory, and storage capacity of nova computing
instances. A flavor is an available hardware configuration
for a server. It defines the "size" of a virtual server
that can be launched. For more details and a list of
default flavors available, see Section 1.5, "Managing
Flavors," (⇽ User Guide for Administrators ).</para>
</listitem>
<listitem>
<para>User Data is a special key in the metadata service
which holds a file that cloud aware applications within
the guest instance can access. For example the<link
xlink:href="https://help.ubuntu.com/community/CloudInit"
>cloudinit</link>system is an open source package from
Ubuntu that handles early initialization of a cloud
instance that makes use of this user data.</para>
</listitem>
<listitem>
<para>Access and security credentials, which include one or
both of the following credentials:</para>
</listitem>
</itemizedlist>
<itemizedlist>
<listitem>
<para>A key-pair for your instance, which are SSH
credentials that are injected into images when they are
launched. For this to work, the image must contain the
cloud-init package. Create at least one keypair for each
project. If you already have generated a key-pair with an
external tool, you can import it into OpenStack. You can
use the keypair for multiple instances that belong to that
project. For details, refer to Section 1.5.1, Creating or
Importing Keys.</para>
</listitem>
<listitem>
<para>A security group, which defines which incoming network
traffic is forwarded to instances. Security groups hold a
set of firewall policies, known as security group rules.
For details, see xx.</para>
</listitem>
</itemizedlist>
<itemizedlist>
<listitem>
<para>If needed, you can assign a floating (public) IP
addressto a running instance and attach a block storage
device, or volume, for persistent storage. For details,
see Section 1.5.3, Managing IP Addresses and Section 1.7,
Managing Volumes.</para>
</listitem>
</itemizedlist>
<para>After you gather the parameters you need to launch an
instance, you can launch it from an<link
xlink:href="http://docs.openstack.org/user-guide/content/launch_from_image"
>image</link>or a<link
xlink:href="http://docs.openstack.org/user-guide/content/boot_from_volume"
>volume</link>.</para>
<para>To gather the parameters to launch an instance</para>
<orderedlist>
<listitem>
<para>On a shell, source the OpenStack RC file.</para>
</listitem>
<listitem>
<para>List the available flavors:</para>
</listitem>
<listitem>
<para>$ nova flavor-list</para>
</listitem>
<listitem>
<para>Note the ID of the flavor that you want to use for
your instance.</para>
</listitem>
<listitem>
<para>List the available images:</para>
</listitem>
<listitem>
<para>$ nova image-list</para>
</listitem>
<listitem>
<para>You can also filter the image list by using grep to
find a specific image, like this:</para>
</listitem>
<listitem>
<para>$ nova image-list | grep 'kernel'</para>
</listitem>
<listitem>
<para>Note the ID of the image that you want to boot your
instance from.</para>
</listitem>
<listitem>
<para>List the available security groups:</para>
</listitem>
</orderedlist>
<para>$ nova secgroup-list --all-tenants</para>
<orderedlist>
<listitem>
<para>If you have not created any security groups, you can
assign the instance to only the default security
group.</para>
</listitem>
<listitem>
<para>You can also list rules for a specified security
group:</para>
</listitem>
<listitem>
<para>$ nova secgroup-list-rules default</para>
</listitem>
<listitem>
<para>In this example, the default security group has been
modified to allow HTTP traffic on the instance by
permitting TCP traffic on Port 80.</para>
</listitem>
<listitem>
<para>List the available keypairs.</para>
</listitem>
<listitem>
<para>$ nova keypair-list</para>
</listitem>
<listitem>
<para>Note the name of the keypair that you use for SSH
access.</para>
</listitem>
</orderedlist>
<para><guilabel>Launch an instance from an image</guilabel></para>
<para>Use this procedure to launch an instance from an
image.</para>
<para>To launch an instance from an image</para>
<orderedlist>
<listitem>
<para>Now you have all parameters required to launch an
instance, run the following command and specify the server
name, flavor ID, and image ID. Optionally, you can provide
a key name for access control and security group for
security. You can also include metadata key and value
pairs. For example you can add a description for your
server by providing the --meta description="My
Server"parameter.</para>
</listitem>
<listitem>
<para>You can pass user data in a file on your local system
and pass it at instance launch by using the flag
--user-data &lt;user-data-file&gt;.</para>
</listitem>
<listitem>
<para>$ nova boot --flavor FLAVOR_ID --image IMAGE_ID
--key_name KEY_NAME --user-data mydata.file \
--security_group SEC_GROUP NAME_FOR_INSTANCE --meta
KEY=VALUE --meta KEY=VALUE</para>
</listitem>
<listitem>
<para>The command returns a list of server properties,
depending on which parameters you provide.</para>
</listitem>
<listitem>
<para>A status of BUILD indicates that the instance has
started, but is not yet online.</para>
</listitem>
<listitem>
<para>A status of ACTIVE indicates that your server is
active.</para>
</listitem>
<listitem>
<para>Copy the server ID value from the id field in the
output. You use this ID to get details for or delete your
server.</para>
</listitem>
<listitem>
<para>Copy the administrative password value from the
adminPass field. You use this value to log into your
server.</para>
</listitem>
<listitem>
<para>Check if the instance is online:</para>
</listitem>
<listitem>
<para>$ nova list</para>
</listitem>
<listitem>
<para>This command lists all instances of the project you
belong to, including their ID, their name, their status,
and their private (and if assigned, their public) IP
addresses.</para>
</listitem>
<listitem>
<para>If the status for the instance is ACTIVE, the instance
is online.</para>
</listitem>
<listitem>
<para>To view the available options for the nova
listcommand, run the following command:</para>
</listitem>
<listitem>
<para>$ nova help list</para>
</listitem>
<listitem>
<para>If you did not provide a keypair, security groups, or
rules, you can only access the instance from inside the
cloud through VNC. Even pinging the instance is not
possible.</para>
</listitem>
</orderedlist>
<para><guilabel>Launch an instance from a volume</guilabel></para>
<para>After you<link
xlink:href="http://docs.openstack.org/user-guide/content/create_volume_from_image"
>create a bootable volume</link>, you<link
xlink:href="http://docs.openstack.org/user-guide/content/boot_from_volume.html#launch_image_from_volume"
>launch an instance from the volume</link>.</para>
<para>To launch an instance from a volume</para>
<orderedlist>
<listitem>
<para>To create a bootable volume</para>
</listitem>
<listitem>
<para>To create a volume from an image, run the following
command:</para>
</listitem>
<listitem>
<para># cinder create --image-id
397e713c-b95b-4186-ad46-6126863ea0a9 --display-name
my-bootable-vol 8</para>
</listitem>
<listitem>
<para>Optionally, to configure your volume, see the
Configuring Image Service and Storage for Computechapter
in the OpenStack Configuration Reference.</para>
</listitem>
<listitem>
<para>To list volumes</para>
</listitem>
<listitem>
<para>Enter the following command:</para>
</listitem>
<listitem>
<para>$ nova volume-list</para>
</listitem>
<listitem>
<para>Copy the value in the ID field for your volume.</para>
</listitem>
</orderedlist>
<orderedlist>
<listitem>
<para>To launch an instance</para>
</listitem>
<listitem>
<para>Enter the nova boot command with the
--block_device_mapping parameter, as follows:</para>
</listitem>
<listitem>
<para>$ nova boot --flavor &lt;flavor&gt;
--block_device_mapping
&lt;dev_name&gt;=&lt;id&gt;:&lt;type&gt;:&lt;size&gt;:&lt;delete_on_terminate&gt;
&lt;name&gt;</para>
</listitem>
<listitem>
<para>The command arguments are:</para>
</listitem>
<listitem>
<para>--flavor flavor</para>
</listitem>
<listitem>
<para>The flavor ID.</para>
</listitem>
<listitem>
<para>--block_device_mapping dev-
name=id:type:size:delete-on-terminate</para>
</listitem>
</orderedlist>
<itemizedlist>
<listitem>
<para>dev-name. A device name where the volume is attached
in the system at /dev/dev_name. This value is typically
vda.</para>
</listitem>
<listitem>
<para>id. The ID of the volume to boot from, as shown in the
output of nova volume-list.</para>
</listitem>
<listitem>
<para>type. Either snap or any other value, including a
blank string. snap means that the volume was created from
a snapshot.</para>
</listitem>
<listitem>
<para>size. The size of the volume, in GBs. It is safe to
leave this blank and have the Compute service infer the
size.</para>
</listitem>
<listitem>
<para>delete-on-terminate. A boolean that indicates whether
the volume should be deleted when the instance is
terminated. You can specify</para>
</listitem>
</itemizedlist>
<itemizedlist>
<listitem>
<para>True or 1</para>
</listitem>
<listitem>
<para>False or 0</para>
</listitem>
</itemizedlist>
<para>name</para>
<orderedlist>
<listitem>
<para>The name for the server.</para>
</listitem>
<listitem>
<para>For example, you might enter the following command to
boot from a volume with ID
bd7cf584-45de-44e3-bf7f-f7b50bf235e. The volume is not
deleted when the instance is terminated:</para>
</listitem>
<listitem>
<para>$ nova boot --flavor 2 --image
397e713c-b95b-4186-ad46-6126863ea0a9
--block_device_mapping
vda=bd7cf584-45de-44e3-bf7f-f7b50bf235e3:::0
myInstanceFromVolume</para>
</listitem>
<listitem>
<para>Now when you list volumes, you can see that the volume
is attached to a server:</para>
</listitem>
<listitem>
<para>$ nova volume-list</para>
</listitem>
<listitem>
<para>Additionally, when you list servers, you see the
server that you booted from a volume:</para>
</listitem>
<listitem>
<para>$ nova list</para>
</listitem>
</orderedlist>
<para><guilabel>Manage instances and hosts</guilabel></para>
<para>Instances are virtual machines that run inside the
cloud.</para>
<para><guilabel>Manage IP addresses</guilabel></para>
<para>Each instance can have a private, or fixed, IP address and
a public, or floating, one.</para>
<para>Private IP addresses are used for communication between
instances, and public ones are used for communication with the
outside world.</para>
<para>When you launch an instance, it is automatically assigned
a private IP address that stays the same until you explicitly
terminate the instance. Rebooting an instance has no effect on
the private IP address.</para>
<para>A pool of floating IPs, configured by the cloud operator,
is available in OpenStack Compute.</para>
<para>You can allocate a certain number of these to a project:
The maximum number of floating IP addresses per project is
defined by the quota.</para>
<para>You can add a floating IP address from this set to an
instance of the project. Floating IP addresses can be
dynamically disassociated and associated with other instances
of the same project at any time.</para>
<para>Before you can assign a floating IP address to an
instance, you first must allocate floating IPs to a project.
After floating IP addresses have been allocated to the current
project, you can assign them to running instances.</para>
<para>One floating IP address can be assigned to only one
instance at a time. Floating IP addresses can be managed with
the nova *floating-ip-*commands, provided by the
python-novaclient package.</para>
<para>To list pools with floating IP addresses</para>
<itemizedlist>
<listitem>
<para>To list all pools that provide floating IP
addresses:</para>
</listitem>
<listitem>
<para>$ nova floating-ip-pool-list</para>
</listitem>
</itemizedlist>
<para>To allocate a floating IP address to the current
project</para>
<itemizedlist>
<listitem>
<para>The output of the following command shows the freshly
allocated IP address:</para>
</listitem>
<listitem>
<para>$ nova floating-ip-pool-list</para>
</listitem>
<listitem>
<para>If more than one pool of IP addresses is available,
you can also specify the pool from which to allocate the
IP address:</para>
</listitem>
<listitem>
<para>$ floating-ip-create POOL_NAME</para>
</listitem>
</itemizedlist>
<para>To list floating IP addresses allocated to the current
project</para>
<itemizedlist>
<listitem>
<para>If an IP is already associated with an instance, the
output also shows the IP for the instance, thefixed IP
address for the instance, and the name of the pool that
provides the floating IP address.</para>
</listitem>
<listitem>
<para>$ nova floating-ip-list</para>
</listitem>
</itemizedlist>
<para>To release a floating IP address from the current
project</para>
<itemizedlist>
<listitem>
<para>The IP address is returned to the pool of IP addresses
that are available for all projects. If an IP address is
currently assigned to a running instance, it is
automatically disassociated from the instance.</para>
</listitem>
<listitem>
<para>$ nova floating-ip-delete FLOATING_IP</para>
</listitem>
</itemizedlist>
<para>To assign a floating IP address to an instance</para>
<itemizedlist>
<listitem>
<para>To associate an IP address with an instance, one or
multiple floating IP addresses must be allocated to the
current project. Check this with:</para>
</listitem>
<listitem>
<para>$ nova floating-ip-list</para>
</listitem>
<listitem>
<para>In addition, you must know the instance's name (or
ID). To look up the instances that belong to the current
project, use the nova list command.</para>
</listitem>
<listitem>
<para>$ nova add-floating-ip INSTANCE_NAME_OR_ID
FLOATING_IP</para>
</listitem>
<listitem>
<para>After you assign the IP with nova add-floating-ipand
configure security group rules for the instance, the
instance is publicly available at the floating IP
address.</para>
</listitem>
</itemizedlist>
<para>To remove a floating IP address from an instance</para>
<itemizedlist>
<listitem>
<para>To remove a floating IP address from an instance, you
must specify the same arguments that you used to assign
the IP.</para>
</listitem>
<listitem>
<para>$ nova remove-floating-ip INSTANCE_NAME_OR_ID
FLOATING_IP</para>
</listitem>
</itemizedlist>
<para><guilabel>Change the size of your
server</guilabel></para>
<para>You change the size of a server by changing its
flavor.</para>
<para>To change the size of your server</para>
<orderedlist>
<listitem>
<para>List the available flavors:</para>
</listitem>
<listitem>
<para>$ nova flavor-list</para>
</listitem>
<listitem>
<para>Show information about your server, including its
size:</para>
</listitem>
<listitem>
<para>$ nova show myCirrosServer</para>
</listitem>
<listitem>
<para>The size of the server is m1.small (2).</para>
</listitem>
<listitem>
<para>To resize the server, pass the server ID and the
desired flavor to the nova resizecommand. Include the
--poll parameter to report the resize progress.</para>
</listitem>
<listitem>
<para>$ nova resize myCirrosServer 4 --poll</para>
</listitem>
<listitem>
<para>Instance resizing... 100% completeFinished</para>
</listitem>
<listitem>
<para>Show the status for your server:</para>
</listitem>
<listitem>
<para>$ nova list</para>
</listitem>
<listitem>
<para>When the resize completes, the status becomes
VERIFY_RESIZE. To confirm the resize:</para>
</listitem>
<listitem>
<para>$ nova resize-confirm
6beefcf7-9de6-48b3-9ba9-e11b343189b3</para>
</listitem>
<listitem>
<para>The server status becomes ACTIVE.</para>
</listitem>
<listitem>
<para>If the resize fails or does not work as expected, you
can revert the resize:</para>
</listitem>
<listitem>
<para>$ nova resize-revert
6beefcf7-9de6-48b3-9ba9-e11b343189b3</para>
</listitem>
<listitem>
<para>The server status becomes ACTIVE.</para>
</listitem>
</orderedlist>
<para><guilabel>Stop and start an instance</guilabel></para>
<para>Use one of the following methods to stop and start an
instance.</para>
<para><guilabel>Pause and un-pause an instance</guilabel></para>
<para>To pause and un-pause a server</para>
<itemizedlist>
<listitem>
<para>To pause a server, run the following command:</para>
</listitem>
<listitem>
<para>$ nova pause SERVER</para>
</listitem>
<listitem>
<para>This command stores the state of the VM in RAM. A
paused instance continues to run in a frozen
state.</para>
</listitem>
<listitem>
<para>To un-pause the server, run the following
command:</para>
</listitem>
<listitem>
<para>$ nova unpause SERVER</para>
</listitem>
</itemizedlist>
<para><guilabel>Suspend and resume an instance</guilabel></para>
<para>To suspend and resume a server</para>
<para>Administrative users might want to suspend an
infrequently used instance or to perform system
maintenance.</para>
<orderedlist>
<listitem>
<para>When you suspend an instance, its VM state is stored
on disk, all memory is written to disk, and the virtual
machine is stopped. Suspending an instance is similar to
placing a device in hibernation; memory and vCPUs become
available.</para>
</listitem>
<listitem>
<para>To initiate a hypervisor-level suspend operation,
run the following command:</para>
</listitem>
<listitem>
<para>$ nova suspend SERVER</para>
</listitem>
<listitem>
<para>To resume a suspended server:</para>
</listitem>
<listitem>
<para>$ nova resume SERVER</para>
</listitem>
</orderedlist>
<para><guilabel>Reboot an instance</guilabel></para>
<para>You can perform a soft or hard reboot of a running
instance. A soft reboot attempts a graceful shutdown and
restart of the instance. A hard reboot power cycles the
instance.</para>
<para>To reboot a server</para>
<itemizedlist>
<listitem>
<para>By default, when you reboot a server, it is a soft
reboot.</para>
</listitem>
<listitem>
<para>$ nova reboot SERVER</para>
</listitem>
</itemizedlist>
<para>To perform a hard reboot, pass the --hard parameter, as
follows:</para>
<para>$ nova reboot --hard SERVER</para>
<para><guilabel>Evacuate instances</guilabel></para>
<para>If a cloud compute node fails due to a hardware
malfunction or another reason, you can evacuate instances to
make them available again.</para>
<para>You can choose evacuation parameters for your use
case.</para>
<para>To preserve user data on server disk, you must configure
shared storage on the target host. Also, you must validate
that the current VM host is down. Otherwise the evacuation
fails with an error.</para>
<para>To evacuate your server</para>
<orderedlist>
<listitem>
<para>To find a different host for the evacuated instance,
run the following command to lists hosts:</para>
</listitem>
<listitem>
<para>$ nova host-list</para>
</listitem>
<listitem>
<para>You can pass the instance password to the command by
using the --password &lt;pwd> option. If you do not
specify a password, one is generated and printed after the
command finishes successfully. The following command
evacuates a server without shared storage:</para>
</listitem>
<listitem>
<para>$ nova evacuate evacuated_server_name host_b</para>
</listitem>
<listitem>
<para>The command evacuates an instance from a down host to
a specified host. The instance is booted from a new disk,
but preserves its configuration including its ID, name,
uid, IP address, and so on. The command returns a
password:</para>
</listitem>
<listitem>
<para>To preserve the user disk data on the evacuated
server, deploy OpenStack Compute with shared
filesystem.</para>
</listitem>
<listitem>
<para>$ nova evacuate evacuated_server_name host_b
--on-shared-storage</para>
</listitem>
</orderedlist>
<para><guilabel>Delete an instance</guilabel></para>
<para>When you no longer need an instance, you can delete
it.</para>
<para>To delete an instance</para>
<orderedlist>
<listitem>
<para>List all instances:</para>
</listitem>
<listitem>
<para>$ nova list</para>
</listitem>
<listitem>
<para>Use the following command to delete the newServer
instance, which is in ERROR state:</para>
</listitem>
<listitem>
<para>$ nova delete newServer</para>
</listitem>
<listitem>
<para>The command does not notify that your server was
deleted.</para>
</listitem>
<listitem>
<para>Instead, run the nova list command:</para>
</listitem>
<listitem>
<para>$ nova list</para>
</listitem>
<listitem>
<para>The deleted instance does not appear in the
list.</para>
</listitem>
</orderedlist>
<para><guilabel>Get a console to an instance</guilabel></para>
<para>To get a console to an instance</para>
<para>To get a VNC console to an instance, run the following
command:</para>
<para>$ nova get-vnc-console myCirrosServer xvpvnc</para>
<para>The command returns a URL from which you can access your
instance:</para>
<para><guilabel>Manage bare metal nodes</guilabel></para>
<para>If you use the bare metal driver, you must create a bare
metal node and add a network interface to it. You then launch
an instance from a bare metal image. You can list and delete
bare metal nodes. When you delete a node, any associated
network interfaces are removed. You can list and remove
network interfaces that are associated with a bare metal
node.</para>
<para>Commands</para>
<itemizedlist>
<listitem>
<para>baremetal-interface-add</para>
</listitem>
<listitem>
<para>Adds a network interface to a bare metal node.</para>
</listitem>
<listitem>
<para>baremetal-interface-list</para>
</listitem>
<listitem>
<para>Lists network interfaces associated with a bare metal
node.</para>
</listitem>
<listitem>
<para>baremetal-interface-remove</para>
</listitem>
<listitem>
<para>Removes a network interface from a bare metal
node.</para>
</listitem>
<listitem>
<para>baremetal-node-create</para>
</listitem>
<listitem>
<para>Creates a bare metal node.</para>
</listitem>
<listitem>
<para>baremetal-node-delete</para>
</listitem>
<listitem>
<para>Removes a bare metal node and any associated
interfaces.</para>
</listitem>
<listitem>
<para>baremetal-node-list</para>
</listitem>
<listitem>
<para>Lists available bare metal nodes.</para>
</listitem>
<listitem>
<para>baremetal-node-show</para>
</listitem>
<listitem>
<para>Shows information about a bare metal node.</para>
</listitem>
</itemizedlist>
<para>To manage bare metal nodes</para>
<orderedlist>
<listitem>
<para>Create a bare metal node.</para>
</listitem>
<listitem>
<para>$ nova baremetal-node-create --pm_address=1.2.3.4
--pm_user=ipmi --pm_password=ipmi $(hostname -f) 1 512 10
aa:bb:cc:dd:ee:ff</para>
</listitem>
<listitem>
<para>Add network interface information to the node:</para>
</listitem>
<listitem>
<para>$ nova baremetal-interface-add 1
aa:bb:cc:dd:ee:ff</para>
</listitem>
<listitem>
<para>Launch an instance from a bare metal image:</para>
</listitem>
<listitem>
<para>$ nova boot --image my-baremetal-image --flavor
my-baremetal-flavor test</para>
</listitem>
<listitem>
<para>|... wait for instance to become active ...</para>
</listitem>
<listitem>
<para>You can list bare metal nodes and interfaces. When a
node is in use, its status includes the UUID of the
instance that runs on it:</para>
</listitem>
<listitem>
<para>$ nova baremetal-node-list</para>
</listitem>
<listitem>
<para>Show details about a bare metal node:</para>
</listitem>
<listitem>
<para>$ nova baremetal-node-show 1</para>
</listitem>
</orderedlist>
<para><guilabel>Show usage statistics for hosts and instances</guilabel></para>
<para>You can show basic statistics on resource usage for hosts
and instances.</para>
<para>To show host usage statistics</para>
<orderedlist>
<listitem>
<para>List the hosts and the nova-related services that run
on them:</para>
</listitem>
<listitem>
<para>$ nova host-list</para>
</listitem>
<listitem>
<para>Get a summary of resource usage of all of the
instances running on the host.</para>
</listitem>
<listitem>
<para>$ nova host-describe devstack-grizzly</para>
</listitem>
<listitem>
<para>The cpu column shows the sum of the virtual CPUs for
instances running on the host.</para>
</listitem>
<listitem>
<para>The memory_mb column shows the sum of the memory (in
MB) allocated to the instances that run on the
hosts.</para>
</listitem>
<listitem>
<para>The disk_gb column shows the sum of the root and
ephemeral disk sizes (in GB) of the instances that run on
the hosts.</para>
</listitem>
</orderedlist>
<para>To show instance usage statistics</para>
<orderedlist>
<listitem>
<para>Get CPU, memory, I/O, and network statistics for an
instance.</para>
</listitem>
<listitem>
<para>First, list instances:</para>
</listitem>
<listitem>
<para>$ nova list</para>
</listitem>
<listitem>
<para>Then, get diagnostic statistics:</para>
</listitem>
<listitem>
<para>$ nova diagnostics myCirrosServer</para>
</listitem>
<listitem>
<para>Get summary statistics for each tenant:</para>
</listitem>
<listitem>
<para>$ nova usage-list</para>
</listitem>
<listitem>
<para>Usage from 2013-06-25 to 2013-07-24:</para>
</listitem>
</orderedlist>
<para><guilabel>Create and manage networks</guilabel></para>
<para>Before you run commands, set the following environment
variables:</para>
<para>export OS_USERNAME=adminexport OS_PASSWORD=passwordexport
OS_TENANT_NAME=adminexport
OS_AUTH_URL=http://localhost:5000/v2.0</para>
<para>To create and manage networks</para>
<orderedlist>
<listitem>
<para>List the extensions of the system:</para>
</listitem>
<listitem>
<para>$ neutron ext-list -c alias -c name</para>
</listitem>
<listitem>
<para>Create a network:</para>
</listitem>
<listitem>
<para>$ neutron net-create net1</para>
</listitem>
<listitem>
<para>Created a new network:</para>
</listitem>
<listitem>
<para>Create a network with specified provider network
type:</para>
</listitem>
<listitem>
<para>$ neutron net-create net2 --provider:network-type
local</para>
</listitem>
<listitem>
<para>Created a new network:</para>
</listitem>
<listitem>
<para>Just as shown previous, the unknown option
--provider:network-type is used to create a local provider
network.</para>
</listitem>
<listitem>
<para>Create a subnet:</para>
</listitem>
<listitem>
<para>$ neutron subnet-create net1 192.168.2.0/24 --name
subnet1</para>
</listitem>
<listitem>
<para>Created a new subnet:</para>
</listitem>
<listitem>
<para>In the previous command, net1 is the network name,
192.168.2.0/24 is the subnet's CIDR. They are positional
arguments. --name subnet1 is an unknown option, which
specifies the subnet's name.</para>
</listitem>
<listitem>
<para>Create a port with specified IP address:</para>
</listitem>
<listitem>
<para>$ neutron port-create net1 --fixed-ip
ip_address=192.168.2.40</para>
</listitem>
<listitem>
<para>Created a new port:</para>
</listitem>
<listitem>
<para>In the previous command, net1 is the network name, which
is a positional argument. --fixed-ip ip_address=192.168.2.40
is an option, which specifies the port's fixed IP address we
wanted.</para>
</listitem>
<listitem>
<para>Create a port without specified IP address:</para>
</listitem>
<listitem>
<para>$ neutron port-create net1</para>
</listitem>
<listitem>
<para>Created a new port:</para>
</listitem>
<listitem>
<para>We can see that the system will allocate one IP address
if we don't specify the IP address in command line.</para>
</listitem>
<listitem>
<para>Query ports with specified fixed IP addresses:</para>
</listitem>
<listitem>
<para>$ neutron port-list --fixed-ips ip_address=192.168.2.2
ip_address=192.168.2.40</para>
</listitem>
<listitem>
<para>--fixed-ips ip_address=192.168.2.2
ip_address=192.168.2.40 is one unknown option.</para>
</listitem>
<listitem>
<para>How to find unknown options?The unknown options can be
easily found by watching the output of create_xxx or
show_xxx command. For example, in the port creation command,
we see the fixed_ips fields, which can be used as an unknown
option.</para>
</listitem>
</orderedlist>
<para><guilabel>Create and manage stacks</guilabel></para>
<para>To create a stack from an example template file</para>
<orderedlist>
<listitem>
<para>To create a stack, or template, from an<link
xlink:href="https://github.com/openstack/heat-templates"
>example template file</link>, run following
command:</para>
</listitem>
<listitem>
<para>$ heat stack-create mystack
--template-file=/path/to/heat/templates/WordPress_Single_Instance.template--parameters="InstanceType=m1.large;DBUsername=wp;DBPassword=verybadpassword;KeyName=heat_key;LinuxDistribution=F17"</para>
</listitem>
<listitem>
<para>The --parameters values that you specify depend on which
parameters are defined in the template. If the template file
is hosted on a website, you can specify the URL with
--template-url parameter instead of the --template-file
parameter.</para>
</listitem>
<listitem>
<para>The command returns the following output:</para>
</listitem>
<listitem>
<para>You can also use the stack-createcommand to validate a
template file without creating a stack from it.</para>
</listitem>
<listitem>
<para>To do so, run the following command:</para>
</listitem>
<listitem>
<para>$ heat stack-create mystack
--template-file=/path/to/heat/templates/WordPress_Single_Instance.template</para>
</listitem>
<listitem>
<para>If validation fails, the response returns an error
message.</para>
</listitem>
</orderedlist>
<para>To list stacks</para>
<itemizedlist>
<listitem>
<para>To see which stacks are visible to the current user, run
the following command:</para>
</listitem>
<listitem>
<para>$ heat stack-list</para>
</listitem>
</itemizedlist>
<para>To view stack details</para>
<para>To explore the state and history of a particular stack, you
can run a number of commands.</para>
<orderedlist>
<listitem>
<para>To show the details of a stack, run the following
command:</para>
</listitem>
<listitem>
<para>$ heat stack-show mystack</para>
</listitem>
<listitem>
<para>A stack consists of a collection of resources. To list
the resources, including their status, in a stack, run the
following command:</para>
</listitem>
<listitem>
<para>$ heat resource-list mystack</para>
</listitem>
<listitem>
<para>To show the details for the specified resource in a
stack, run the following command:</para>
</listitem>
<listitem>
<para>$ heat resource-show mystack WikiDatabase</para>
</listitem>
<listitem>
<para>Some resources have associated metadata which can change
throughout the life-cycle of a resource:</para>
</listitem>
<listitem>
<para>$ heat resource-metadata mystack WikiDatabase</para>
</listitem>
<listitem>
<para>A series of events is generated during the life-cycle of
a stack. This command will display those events.</para>
</listitem>
<listitem>
<para>$ heat event-list mystack</para>
</listitem>
<listitem>
<para>To show the details for a particular event, run the
following command:</para>
</listitem>
<listitem>
<para>$ heat event-show WikiDatabase 1</para>
</listitem>
</orderedlist>
<para>To update a stack</para>
<itemizedlist>
<listitem>
<para>To update an existing stack from a modified template
file, run a command like the following command:</para>
</listitem>
<listitem>
<para>$ heat stack-update mystack
--template-file=/path/to/heat/templates/WordPress_Single_Instance_v2.template
--parameters="InstanceType=m1.large;DBUsername=wp;DBPassword=verybadpassword;KeyName=heat_key;LinuxDistribution=F17"</para>
</listitem>
<listitem>
<para>Some resources are updated in-place, while others are
replaced with new resources.</para>
</listitem>
</itemizedlist>
</chapter>
View Git Blame Copy Permalink