openstack/openstack-manuals
Code Issues Proposed changes

Clean up End User Guide - sentence style headings and other edits

Browse Source 
Closes-Bug: #1249837

backport: none

Change-Id: Ie5068452b8596b0625e680ddd6f4eb6851e41927
author: diane fleming
This commit is contained in:
Diane Fleming
2013-11-10 17:33:19 -06:00
parent daa3371a14
commit 5ab33d32b3
12 changed files with 920 additions and 751 deletions
Download Patch File Download Diff File Expand all files Collapse all files

468
doc/common/section_cinder_cli_manage_volumes.xml
View File

@@ -3,42 +3,55 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="cli_manage_volumes">
<?dbhtml stop-chunking?>
<?dbhtml stop-chunking?>
<title>Manage volumes</title>
<para>A volume is a detachable block storage device, similar to a
USB hard drive. You can attach a volume to only one instance.
To create and manage volumes, you use a combination of nova
and cinder client commands.</para>
<para os="adminuser">For general user information about how to create and manage volumes, see
the <link xlink:href="http://docs.openstack.org/user-guide/content/"><citetitle>OpenStack End User Guide</citetitle></link>.
</para>
<para os="enduser">This example creates a volume named
<literal>my-new-volume</literal> based on an image.</para>
<literal>my-new-volume</literal> based on an image.</para>
<section xml:id="cli_migrate_volumes" os="adminuser">
<title>Migrate a volume</title>
<para>As an administrator, you can migrate a volume with its data from one location to
another in a manner that is transparent to users and workloads. Only detached volumes
<para>As an administrator, you can migrate a volume with its
data from one location to another in a manner that is
transparent to users and workloads. Only detached volumes
with no snapshots can be migrated.</para>
<para>Possible use cases for migrating data include:
<itemizedlist>
<listitem><para>To bring down a physical storage device for maintenance without interferring with workloads.</para></listitem>
<listitem><para>To modify the properties of a volume.</para></listitem>
<listitem><para>To free up space in a thinly-provisioned back-end.</para></listitem>
<para>Possible use cases for data migration: <itemizedlist>
<listitem>
<para>Bring down a physical storage device for
maintenance without disrupting
workloads.</para>
</listitem>
<listitem>
<para>Modify the properties of a volume.</para>
</listitem>
<listitem>
<para>Free up space in a thinly-provisioned back
end.</para>
</listitem>
</itemizedlist></para>
<para>Migrate a volume, as follows:</para>
<screen><prompt>$</prompt> <userinput>cinder migrate <replaceable>volumeID</replaceable> <replaceable>destinationHost</replaceable> --force-host-copy=<replaceable>True|False</replaceable></userinput></screen>
<para>Where <literal>--force-host-copy=True</literal> forces the generic host-based
migration mechanism and bypasses any driver optimizations.</para>
<note><para>If the volume is in use, has snapshots, the specified host destination cannot accept the
volume, or if the user is not an administrator, the migration will fail.</para></note>
<para>Where <literal>--force-host-copy=True</literal> forces
the generic host-based migration mechanism and bypasses
any driver optimizations.</para>
<note>
<para>If the volume is in use or has snapshots, the
specified host destination cannot accept the
volume.</para>
<para>If the user is not an administrator, the migration
fails.</para>
</note>
</section>
<section xml:id="cli_list_volumes" os="enduser"><title>Create a volume</title><procedure>
<step>
<para>List images, and note the ID of the image to use for
your volume:</para>
<screen><prompt>$</prompt> <userinput>nova image-list</userinput></screen>
<screen><?db-font-size 65%?><computeroutput>
+--------------------------------------+---------------------------------+--------+--------------------------------------+
<section xml:id="cli_list_volumes" os="enduser">
<title>Create a volume</title>
<procedure>
<step>
<para>List images, and note the ID of the image to use
for your volume:</para>
<screen><prompt>$</prompt> <userinput>nova image-list</userinput></screen>
<screen><?db-font-size 65%?><computeroutput>+--------------------------------------+---------------------------------+--------+--------------------------------------+
| ID | Name | Status | Server |
+--------------------------------------+---------------------------------+--------+--------------------------------------+
| 397e713c-b95b-4186-ad46-6126863ea0a9 | cirros-0.3.1-x86_64-uec | ACTIVE | |
@@ -47,14 +60,13 @@
| 7e5142af-1253-4634-bcc6-89482c5f2e8a | myCirrosImage | ACTIVE | 84c6e57d-a6b1-44b6-81eb-fcb36afd31b5 |
| 89bcd424-9d15-4723-95ec-61540e8a1979 | mysnapshot | ACTIVE | f51ebd07-c33d-4951-8722-1df6aa8afaa4 |
+--------------------------------------+---------------------------------+--------+--------------------------------------+</computeroutput></screen>
</step>
<step>
<para>List the availability zones, and note the ID of the
availability zone in which to create your
</step>
<step>
<para>List the availability zones, and note the ID of
the availability zone in which to create your
volume:</para>
<screen><prompt>$</prompt> <userinput>nova availability-zone-list</userinput></screen>
<screen><?db-font-size 65%?><computeroutput>
+-----------------------+----------------------------------------+
<screen><prompt>$</prompt> <userinput>nova availability-zone-list</userinput></screen>
<screen><?db-font-size 65%?><computeroutput>+-----------------------+----------------------------------------+
| Name | Status |
+-----------------------+----------------------------------------+
| internal | available |
@@ -68,13 +80,12 @@
| |- devstack-grizzly | |
| | |- nova-compute | enabled :-) 2013-07-25T16:50:39.000000 |
+-----------------------+----------------------------------------+</computeroutput></screen>
</step>
<step>
<para>Create a volume with 8 GBs of space. Specify the
availability zone and image, as follows:</para>
<screen><prompt>$</prompt> <userinput>cinder create 8 --display-name my-new-volume --image-id 397e713c-b95b-4186-ad46-6126863ea0a9 --availability-zone nova</userinput></screen>
<screen><?db-font-size 65%?><computeroutput>
+---------------------+--------------------------------------+
</step>
<step>
<para>Create a volume with 8 GBs of space. Specify the
availability zone and image:</para>
<screen><prompt>$</prompt> <userinput>cinder create 8 --display-name my-new-volume --image-id 397e713c-b95b-4186-ad46-6126863ea0a9 --availability-zone nova</userinput></screen>
<screen><?db-font-size 65%?><computeroutput>+---------------------+--------------------------------------+
| Property | Value |
+---------------------+--------------------------------------+
| attachments | [] |
@@ -92,31 +103,31 @@
| status | creating |
| volume_type | None |
+---------------------+--------------------------------------+</computeroutput></screen>
</step>
<step>
<para>To verify that your volume was created successfully,
list the available volumes:</para>
<screen><prompt>$</prompt> <userinput>cinder list</userinput></screen>
<screen><?db-font-size 65%?><computeroutput>
+--------------------------------------+-----------+-----------------+------+-------------+----------+-------------+
</step>
<step>
<para>To verify that your volume was created
successfully, list the available volumes:</para>
<screen><prompt>$</prompt> <userinput>cinder list</userinput></screen>
<screen><?db-font-size 65%?><computeroutput>+--------------------------------------+-----------+-----------------+------+-------------+----------+-------------+
| ID | Status | Display Name | Size | Volume Type | Bootable | Attached to |
+--------------------------------------+-----------+-----------------+------+-------------+----------+-------------+
| 573e024d-5235-49ce-8332-be1576d323f8 | available | my-new-volume | 8 | None | true | |
| bd7cf584-45de-44e3-bf7f-f7b50bf235e3 | available | my-bootable-vol | 8 | None | true | |
+--------------------------------------+-----------+-----------------+------+-------------+----------+-------------+</computeroutput></screen>
<para>If your volume was created successfully, its status
is <literal>available</literal>. If its status is
<literal>error</literal>, you might have
<para>If your volume was created successfully, its
status is <literal>available</literal>. If its
status is <literal>error</literal>, you might have
exceeded your quota.</para>
</step>
</procedure>
</section>
<section xml:id="cli_attach_volume" os="enduser"><title>Attach a volume to an instance</title>
<procedure> <step>
<para>Attach your volume to a server:</para>
<screen><prompt>$</prompt> <userinput>nova volume-attach 84c6e57d-a6b1-44b6-81eb-fcb36afd31b5 573e024d-5235-49ce-8332-be1576d323f8 /dev/vdb</userinput></screen>
<screen><?db-font-size 65%?><computeroutput>
+----------+--------------------------------------+
</step>
</procedure>
</section>
<section xml:id="cli_attach_volume" os="enduser">
<title>Attach a volume to an instance</title>
<procedure>
<step>
<para>Attach your volume to a server:</para>
<screen><prompt>$</prompt> <userinput>nova volume-attach 84c6e57d-a6b1-44b6-81eb-fcb36afd31b5 573e024d-5235-49ce-8332-be1576d323f8 /dev/vdb</userinput></screen>
<screen><?db-font-size 65%?><computeroutput>+----------+--------------------------------------+
| Property | Value |
+----------+--------------------------------------+
| device | /dev/vdb |
@@ -124,13 +135,12 @@
| id | 573e024d-5235-49ce-8332-be1576d323f8 |
| volumeId | 573e024d-5235-49ce-8332-be1576d323f8 |
+----------+--------------------------------------+</computeroutput></screen>
<para>Note the ID of your volume.</para>
</step>
<step>
<para>Show information for your volume:</para>
<screen><prompt>$</prompt> <userinput>cinder show 573e024d-5235-49ce-8332-be1576d323f8</userinput></screen>
<screen><?db-font-size 65%?><computeroutput>
+------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
<para>Note the ID of your volume.</para>
</step>
<step>
<para>Show information for your volume:</para>
<screen><prompt>$</prompt> <userinput>cinder show 573e024d-5235-49ce-8332-be1576d323f8</userinput></screen>
<screen><?db-font-size 65%?><computeroutput>+------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Property | Value |
+------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| attachments | [{u'device': u'/dev/vdb', u'server_id': u'84c6e57d-a6b1-44b6-81eb-fcb36afd31b5', u'id': u'573e024d-5235-49ce-8332-be1576d323f8', u'volume_id': u'573e024d-5235-49ce-8332-be1576d323f8'}] |
@@ -150,125 +160,140 @@
| volume_image_metadata | {u'kernel_id': u'df430cc2-3406-4061-b635-a51c16e488ac', u'image_id': u'397e713c-b95b-4186-ad46-6126863ea0a9', u'ramdisk_id': u'3cf852bd-2332-48f4-9ae4-7d926d50945e', u'image_name': u'cirros-0.3.1-x86_64-uec'} |
| volume_type | None |
+------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+</computeroutput></screen>
<para>The output shows that the volume is attached to the
server with ID
<para>The output shows that the volume is attached to
the server with ID
<literal>84c6e57d-a6b1-44b6-81eb-fcb36afd31b5</literal>,
is in the nova availability zone, and is
bootable.</para>
</step>
</procedure></section>
<section xml:id="cli_extend_volumes" os="enduser"><title>Resize a volume</title>
<procedure>
<step>
<para>To resize your volume, you must first detach it from the server.</para>
<para>To detach the volume from your server, pass the
server ID and volume ID to the command, as
follows:</para>
<screen><prompt>$</prompt> <userinput>nova volume-detach 84c6e57d-a6b1-44b6-81eb-fcb36afd31b5 573e024d-5235-49ce-8332-be1576d323f8</userinput></screen>
<para>The <command>volume-detach</command> command does not return any output.</para>
</step>
<step>
<para>List volumes:</para>
<screen><prompt>$</prompt> <userinput>cinder list</userinput></screen>
<screen><?db-font-size 65%?><computeroutput>
+--------------------------------------+-----------+-----------------+------+-------------+----------+-------------+
</step>
</procedure>
</section>
<section xml:id="cli_extend_volumes" os="enduser">
<title>Resize a volume</title>
<procedure>
<step>
<para>To resize your volume, you must first detach it
from the server.</para>
<para>To detach the volume from your server, pass the
server ID and volume ID to the command:</para>
<screen><prompt>$</prompt> <userinput>nova volume-detach 84c6e57d-a6b1-44b6-81eb-fcb36afd31b5 573e024d-5235-49ce-8332-be1576d323f8</userinput></screen>
<para>The <command>volume-detach</command> command
does not return any output.</para>
</step>
<step>
<para>List volumes:</para>
<screen><prompt>$</prompt> <userinput>cinder list</userinput></screen>
<screen><?db-font-size 65%?><computeroutput>+--------------------------------------+-----------+-----------------+------+-------------+----------+-------------+
| ID | Status | Display Name | Size | Volume Type | Bootable | Attached to |
+--------------------------------------+-----------+-----------------+------+-------------+----------+-------------+
| 573e024d-5235-49ce-8332-be1576d323f8 | available | my-new-volume | 8 | None | true | |
| bd7cf584-45de-44e3-bf7f-f7b50bf235e3 | available | my-bootable-vol | 8 | None | true | |
+--------------------------------------+-----------+-----------------+------+-------------+----------+-------------+</computeroutput></screen>
<para>Note that the volume is now available.</para>
</step>
<step>
<para>Now you can resize the volume, by passing the volume id and the new size (a value greater than the old one) as parameters, as follows:</para>
<screen><prompt>$</prompt> <userinput>cinder extend <replaceable>573e024d-5235-49ce-8332-be1576d323f8</replaceable> <replaceable>10</replaceable></userinput></screen>
<para>The <command>extend</command> command does not return any output.</para>
</step>
</procedure></section>
<section xml:id="cli_delete_volumes" os="enduser"><title>Delete a volume</title>
<procedure>
<step>
<para>To delete your volume, you must first detach it from
the server.</para>
<para>To detach the volume from your server and check for the list of existing volumes, see steps 1 and 2 mentioned in <link linkend="cli_extend_volumes">Resize a volume</link> procedure.</para>
</step>
<step>
<para>Now you can delete the volume, as follows:</para>
<screen><prompt>$</prompt> <userinput>cinder delete my-new-volume</userinput></screen>
<para>The delete command does not return any output.</para>
</step>
<step>
<para>List the volumes again, and note that the status of
your volume is <literal>deleting</literal>:</para>
<screen><prompt>$</prompt> <userinput>cinder list</userinput></screen>
<screen><?db-font-size 65%?><computeroutput>
+--------------------------------------+-----------+-----------------+------+-------------+----------+-------------+
<para>Note that the volume is now available.</para>
</step>
<step>
<para>Resize the volume by passing the volume ID and
the new size (a value greater than the old one) as
parameters:</para>
<screen><prompt>$</prompt> <userinput>cinder extend <replaceable>573e024d-5235-49ce-8332-be1576d323f8</replaceable> <replaceable>10</replaceable></userinput></screen>
<para>The <command>extend</command> command does not
return any output.</para>
</step>
</procedure>
</section>
<section xml:id="cli_delete_volumes" os="enduser">
<title>Delete a volume</title>
<procedure>
<step>
<para>To delete your volume, you must first detach it
from the server.</para>
<para>To detach the volume from your server and check
for the list of existing volumes, see steps 1 and
2 mentioned in <xref linkend="cli_extend_volumes"
/>.</para>
</step>
<step>
<para>Delete the volume:</para>
<screen><prompt>$</prompt> <userinput>cinder delete my-new-volume</userinput></screen>
<para>The delete command does not return any
output.</para>
</step>
<step>
<para>List the volumes again, and note that the status
of your volume is
<literal>deleting</literal>:</para>
<screen><prompt>$</prompt> <userinput>cinder list</userinput></screen>
<screen><?db-font-size 65%?><computeroutput>+--------------------------------------+-----------+-----------------+------+-------------+----------+-------------+
| ID | Status | Display Name | Size | Volume Type | Bootable | Attached to |
+--------------------------------------+-----------+-----------------+------+-------------+----------+-------------+
| 573e024d-5235-49ce-8332-be1576d323f8 | deleting | my-new-volume | 8 | None | true | |
| bd7cf584-45de-44e3-bf7f-f7b50bf235e3 | available | my-bootable-vol | 8 | None | true | |
+--------------------------------------+-----------+-----------------+------+-------------+----------+-------------+</computeroutput></screen>
<para>When the volume is fully deleted, it disappears from
the list of volumes:</para>
<screen><prompt>$</prompt> <userinput>cinder list</userinput></screen>
<screen><?db-font-size 65%?><computeroutput>
+--------------------------------------+-----------+-----------------+------+-------------+----------+-------------+
<para>When the volume is fully deleted, it disappears
from the list of volumes:</para>
<screen><prompt>$</prompt> <userinput>cinder list</userinput></screen>
<screen><?db-font-size 65%?><computeroutput>+--------------------------------------+-----------+-----------------+------+-------------+----------+-------------+
| ID | Status | Display Name | Size | Volume Type | Bootable | Attached to |
+--------------------------------------+-----------+-----------------+------+-------------+----------+-------------+
| bd7cf584-45de-44e3-bf7f-f7b50bf235e3 | available | my-bootable-vol | 8 | None | true | |
+--------------------------------------+-----------+-----------------+------+-------------+----------+-------------+</computeroutput></screen>
</step>
</procedure></section>
</step>
</procedure>
</section>
<section xml:id="cli_transfer_volumes" os="enduser">
<title>Transfer volumes</title>
<para>A volume can be transferred from one owner to another using the <command>cinder
transfer*</command> commands. The basic process is:</para>
<para>
<orderedlist>
<listitem>
<para>The volume donor (or original owner) creates a transfer request, then
sends the created transfer ID and authorisation key to the volume
recipient.</para>
</listitem>
<listitem>
<para>The volume recipient (or new owner) accepts the transfer using the ID and
key.</para>
</listitem>
</orderedlist>
</para>
<title>Transfer a volume</title>
<para>You can transfer a volume from one owner to another by
using the <command>cinder transfer*</command> commands.
The volume donor, or original owner, creates a transfer
request and sends the created transfer ID and
authorization key to the volume recipient. The volume
recipient, or new owner, accepts the transfer by using the
ID and key.</para>
<para>Use cases include:</para>
<para>
<itemizedlist>
<listitem>
<para>Creating a custom bootable volume or a volume with a large data set, and then
transferring it to the end customer.</para>
<para>Create a custom bootable volume or a volume
with a large data set and transfer it to the
end customer.</para>
</listitem>
<listitem>
<para>For bulk import of data to the cloud, the data ingress system can create a new
Block Storage volume, copy the data from the physical device, and then transfer
ownership of the device to the end user.</para>
<para>For bulk import of data to the cloud, the
data ingress system creates a new Block
Storage volume, copies data from the physical
device, and transfers device ownership to the
end user.</para>
</listitem>
</itemizedlist>
</para>
<procedure>
<section xml:id="create_volume_transfer">
<title>Create a volume transfer request</title>
<step><para>While logged in as the volume donor, list available volumes:</para>
<screen><prompt>$</prompt> <userinput>cinder list</userinput>
<computeroutput>+--------------------------------------+-----------+--------------+------+-------------+----------+-------------+
<procedure>
<step>
<para>While logged in as the volume donor, list
available volumes:</para>
<screen><prompt>$</prompt> <userinput>cinder list</userinput></screen>
<screen><computeroutput>+--------------------------------------+-----------+--------------+------+-------------+----------+-------------+
| ID | Status | Display Name | Size | Volume Type | Bootable | Attached to |
+--------------------------------------+-----------+--------------+------+-------------+----------+-------------+
| 72bfce9f-cacf-477a-a092-bf57a7712165 | error | None | 1 | None | false | |
| a1cdace0-08e4-4dc7-b9dc-457e9bcfe25f | available | None | 1 | None | false | |
+--------------------------------------+-----------+--------------+------+-------------+----------+-------------+</computeroutput></screen>
</step>
<step><para>As the volume donor, request a volume transfer authorization code for a specific volume, as
follows:</para>
<screen><prompt>$</prompt> <userinput>cinder transfer-create <replaceable>volumeID</replaceable></userinput></screen>
<para>The volume must be in an ‘available’ state or the request will be denied. If the
transfer request is valid in the database (that is, it has not expired or been
deleted), the volume is placed in an ‘awaiting transfer’ state. For example:</para>
<screen><prompt>$</prompt> <userinput>cinder transfer-create a1cdace0-08e4-4dc7-b9dc-457e9bcfe25f</userinput>
<computeroutput>+------------+--------------------------------------+
</step>
<step>
<para>As the volume donor, request a volume
transfer authorization code for a specific
volume:</para>
<screen><prompt>$</prompt> <userinput>cinder transfer-create <replaceable>volumeID</replaceable></userinput></screen>
<para>The volume must be in an ‘available’ state
or the request will be denied. If the transfer
request is valid in the database (that is, it
has not expired or been deleted), the volume
is placed in an <literal>awaiting
transfer</literal> state. For
example:</para>
<screen><prompt>$</prompt> <userinput>cinder transfer-create a1cdace0-08e4-4dc7-b9dc-457e9bcfe25f</userinput></screen>
<screen><computeroutput>+------------+--------------------------------------+
| Property | Value |
+------------+--------------------------------------+
| auth_key | b2c8e585cbc68a80 |
@@ -277,38 +302,55 @@
| name | None |
| volume_id | a1cdace0-08e4-4dc7-b9dc-457e9bcfe25f |
+------------+--------------------------------------+</computeroutput></screen>
<note><para>Optionally, you can specify a name for the transfer using the <code>--display-name
<replaceable>displayName</replaceable></code> option.</para></note>
</step>
<step><para>Send the volume transfer ID and authorisation key to the new owner (for example, by
email).</para></step>
<step><para>View pending transfers, as follows:</para>
<screen><prompt>$</prompt> <userinput>cinder transfer-list</userinput>
<computeroutput>+--------------------------------------+--------------------------------------+------+
<note>
<para>Optionally, you can specify a name for
the transfer by using the
<code>--display-name
<replaceable>displayName</replaceable></code>
parameter.</para>
</note>
</step>
<step>
<para>Send the volume transfer ID and
authorization key to the new owner (for
example, by email).</para>
</step>
<step>
<para>View pending transfers:</para>
<screen><prompt>$</prompt> <userinput>cinder transfer-list</userinput></screen>
<screen><computeroutput>+--------------------------------------+--------------------------------------+------+
| ID | VolumeID | Name |
+--------------------------------------+--------------------------------------+------+
| 6e4e9aa4-bed5-4f94-8f76-df43232f44dc | a1cdace0-08e4-4dc7-b9dc-457e9bcfe25f | None |
+--------------------------------------+--------------------------------------+------+</computeroutput></screen>
</step>
<step><para>After the volume recipient (or new owner) has accepted the transfer, you can see that the
transfer is no longer available:</para>
<screen><prompt>$</prompt> <userinput>cinder transfer-list</userinput>
<computeroutput>+----+-----------+------+
</step>
<step>
<para>After the volume recipient, or new owner,
accepts the transfer, you can see that the
transfer is no longer available:</para>
<screen><prompt>$</prompt> <userinput>cinder transfer-list</userinput></screen>
<screen><computeroutput>+----+-----------+------+
| ID | Volume ID | Name |
+----+-----------+------+
+----+-----------+------+</computeroutput></screen>
</step>
</procedure>
<procedure>
</step>
</procedure>
</section>
<section xml:id="accept_volume_transfer">
<title>Accept a volume transfer request</title>
<step><para>As the volume recipient, you must first obtain the transfer ID and authorization key from the
original owner.
</para></step>
<step><para>Display the transfer request details using the ID, as follows:</para>
<screen><prompt>$</prompt> <userinput>cinder transfer-show <replaceable>transferID</replaceable></userinput></screen>
<para>For example:</para>
<screen><prompt>$</prompt> <userinput>cinder transfer-show 6e4e9aa4-bed5-4f94-8f76-df43232f44dc</userinput>
<computeroutput>+------------+--------------------------------------+
<procedure>
<step>
<para>As the volume recipient, you must first
obtain the transfer ID and authorization key
from the original owner.</para>
</step>
<step>
<para>Display the transfer request details using
the ID:</para>
<screen><prompt>$</prompt> <userinput>cinder transfer-show <replaceable>transferID</replaceable></userinput></screen>
<para>For example:</para>
<screen><prompt>$</prompt> <userinput>cinder transfer-show 6e4e9aa4-bed5-4f94-8f76-df43232f44dc</userinput></screen>
<screen><computeroutput>+------------+--------------------------------------+
| Property | Value |
+------------+--------------------------------------+
| created_at | 2013-10-14T15:20:10.000000 |
@@ -316,60 +358,74 @@
| name | None |
| volume_id | a1cdace0-08e4-4dc7-b9dc-457e9bcfe25f |
+------------+--------------------------------------+</computeroutput></screen>
</step>
<step><para>Accept the request, as follows:</para>
<screen><prompt>$</prompt> <userinput>cinder transfer-accept <replaceable>transferID</replaceable> <replaceable>authKey</replaceable></userinput></screen>
<para>For example:</para>
<screen><prompt>$</prompt> <userinput>cinder transfer-accept 6e4e9aa4-bed5-4f94-8f76-df43232f44dc b2c8e585cbc68a80</userinput>
<computeroutput>+-----------+--------------------------------------+
</step>
<step>
<para>Accept the request:</para>
<screen><prompt>$</prompt> <userinput>cinder transfer-accept <replaceable>transferID</replaceable> <replaceable>authKey</replaceable></userinput></screen>
<para>For example:</para>
<screen><prompt>$</prompt> <userinput>cinder transfer-accept 6e4e9aa4-bed5-4f94-8f76-df43232f44dc b2c8e585cbc68a80</userinput></screen>
<screen><computeroutput>+-----------+--------------------------------------+
| Property | Value |
+-----------+--------------------------------------+
| id | 6e4e9aa4-bed5-4f94-8f76-df43232f44dc |
| name | None |
| volume_id | a1cdace0-08e4-4dc7-b9dc-457e9bcfe25f |
+-----------+--------------------------------------+</computeroutput></screen>
<note><para>If you do not have sufficient quota for the transfer, the transfer is refused.</para></note>
</step>
</procedure>
<procedure>
<title>Delete a transfer</title>
<step><para>List available volumes and their status, as follows:</para>
<screen><prompt>$</prompt> <userinput>cinder list</userinput>
<computeroutput>+--------------------------------------+-------------------+--------------+------+-------------+----------+-------------+
<note>
<para>If you do not have a sufficient quota
for the transfer, the transfer is
refused.</para>
</note>
</step>
</procedure>
</section>
<section xml:id="delete_transfer">
<title>Delete a volume transfer</title>
<procedure>
<step>
<para>List available volumes and their
statuses:</para>
<screen><prompt>$</prompt> <userinput>cinder list</userinput></screen>
<screen><computeroutput>+--------------------------------------+-------------------+--------------+------+-------------+----------+-------------+
| ID | Status | Display Name | Size | Volume Type | Bootable | Attached to |
+--------------------------------------+-------------------+--------------+------+-------------+----------+-------------+
| 72bfce9f-cacf-477a-a092-bf57a7712165 | error | None | 1 | None | false | |
| a1cdace0-08e4-4dc7-b9dc-457e9bcfe25f | awaiting-transfer | None | 1 | None | false | |
+--------------------------------------+-------------------+--------------+------+-------------+----------+-------------+</computeroutput></screen>
</step>
<step><para>Find the matching transfer ID:</para>
<screen><prompt>$</prompt> <userinput>cinder transfer-list</userinput>
<computeroutput>+--------------------------------------+--------------------------------------+------+
</step>
<step>
<para>Find the matching transfer ID:</para>
<screen><prompt>$</prompt> <userinput>cinder transfer-list</userinput></screen>
<screen><computeroutput>+--------------------------------------+--------------------------------------+------+
| ID | VolumeID | Name |
+--------------------------------------+--------------------------------------+------+
| a6da6888-7cdf-4291-9c08-8c1f22426b8a | a1cdace0-08e4-4dc7-b9dc-457e9bcfe25f | None |
+--------------------------------------+--------------------------------------+------+</computeroutput></screen>
</step>
<step><para>Delete the volume, as follows:</para>
<screen><prompt>$</prompt> <userinput>cinder transfer-delete <replaceable>transferID</replaceable></userinput></screen>
<para>For example:</para>
<screen><prompt>$</prompt> <userinput>cinder transfer-delete a6da6888-7cdf-4291-9c08-8c1f22426b8a</userinput></screen>
</step>
<step><para>You can now see that the transfer list is empty, and the volume is once more available for
transfer:</para>
<screen><prompt>$</prompt> <userinput>cinder transfer-list</userinput>
<computeroutput>+----+-----------+------+
</step>
<step>
<para>Delete the volume:</para>
<screen><prompt>$</prompt> <userinput>cinder transfer-delete <replaceable>transferID</replaceable></userinput></screen>
<para>For example:</para>
<screen><prompt>$</prompt> <userinput>cinder transfer-delete a6da6888-7cdf-4291-9c08-8c1f22426b8a</userinput></screen>
</step>
<step>
<para>The transfer list is now empty and the
volume is again available for transfer:</para>
<screen><prompt>$</prompt> <userinput>cinder transfer-list</userinput></screen>
<screen><computeroutput>+----+-----------+------+
| ID | Volume ID | Name |
+----+-----------+------+
+----+-----------+------+</computeroutput>
<prompt>$</prompt> <userinput>cinder list</userinput>
<computeroutput>+--------------------------------------+-----------+--------------+------+-------------+----------+-------------+
+----+-----------+------+</computeroutput></screen>
<screen><prompt>$</prompt> <userinput>cinder list</userinput></screen>
<screen><computeroutput>+--------------------------------------+-----------+--------------+------+-------------+----------+-------------+
| ID | Status | Display Name | Size | Volume Type | Bootable | Attached to |
+--------------------------------------+-----------+--------------+------+-------------+----------+-------------+
| 72bfce9f-cacf-477a-a092-bf57a7712165 | error | None | 1 | None | false | |
| a1cdace0-08e4-4dc7-b9dc-457e9bcfe25f | available | None | 1 | None | false | |
+--------------------------------------+-----------+--------------+------+-------------+----------+-------------+</computeroutput></screen>
</step>
</procedure>
</step>
</procedure>
</section>
</section>
</section>

4
doc/common/section_nova_cli_get_console.xml
View File

@@ -4,8 +4,8 @@
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">
<title>Get a console to an instance</title>
<procedure><title>To get a console to an instance</title> <step><para>To get a VNC console to an instance, run the following
<title>Get a console to access an instance</title>
<procedure> <step><para>To get a VNC console to access an instance, run the following
command:</para> <screen><prompt>$</prompt> <userinput>nova get-vnc-console myCirrosServer xvpvnc</userinput></screen>
<para>The command returns a URL from which you can access your instance:</para>
<screen><computeroutput>+--------+------------------------------------------------------------------------------+

8
doc/common/section_nova_cli_reboot.xml
View File

@@ -3,10 +3,10 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
<title>Reboot an instance</title>
<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>
<procedure><title>To reboot a server</title> <step><para>By default, when you reboot a server, it is a soft reboot.</para>
<para>You can soft or hard reboot a running instance. A soft reboot
attempts a graceful shut down and restart of the instance. A
hard reboot power cycles the instance.</para>
<procedure> <step><para>By default, when you reboot a server, it is a soft reboot.</para>
<screen><prompt>$</prompt> <userinput>nova reboot <replaceable>SERVER</replaceable></userinput></screen></step></procedure>
<para>To perform a hard reboot, pass the <parameter>--hard</parameter>
parameter, as follows:</para><screen><prompt>$</prompt> <userinput>nova reboot --hard <replaceable>SERVER</replaceable></userinput></screen></section>

68
doc/common/section_nova_cli_startstop.xml
View File

@@ -1,36 +1,44 @@
<?xml version="1.0" encoding="UTF-8"?>
<section
xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xml:id="nova_cli_stop_start">
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="nova_cli_stop_start">
<title>Stop and start an instance</title>
<para>Use one of the following methods to stop and start an
instance.</para>
<section xml:id="pause_server"><title>Pause and un-pause an instance</title><procedure xml:id="nova_cli_pause_unpause">
<title>To pause and un-pause a server</title>
<step> <para>To pause a server, run the following command:</para><screen><prompt>$</prompt> <userinput>nova pause <replaceable>SERVER</replaceable></userinput> </screen>
<para>This command stores the state of the VM in
RAM. A paused instance continues to run in a frozen
state.</para>
<para>To un-pause the server, run the following command:</para>
<screen><prompt>$</prompt> <userinput>nova unpause <replaceable>SERVER</replaceable></userinput> </screen>
</step>
</procedure></section>
<section xml:id="suspend_resume"><title>Suspend and resume an instance</title> <procedure xml:id="nova_cli_suspend_resume">
<title>To suspend and resume a server</title>
<para>Administrative users might want to suspend an infrequently used
instance or to perform system maintenance.</para>
<step><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><para>To initiate a hypervisor-level suspend operation,
run the following command:</para>
<section xml:id="pause_server">
<title>Pause and un-pause an instance</title>
<procedure xml:id="nova_cli_pause_unpause">
<step>
<para>To pause a server, run the following command:</para>
<screen><prompt>$</prompt> <userinput>nova pause <replaceable>SERVER</replaceable></userinput> </screen>
<para>This command stores the state of the VM in RAM. A paused
instance continues to run in a frozen state.</para>
<para>To un-pause the server, run the following
command:</para>
<screen><prompt>$</prompt> <userinput>nova unpause <replaceable>SERVER</replaceable></userinput> </screen>
</step>
</procedure>
</section>
<section xml:id="suspend_resume">
<title>Suspend and resume an instance</title>
<procedure xml:id="nova_cli_suspend_resume">
<para>Administrative users might want to suspend an infrequently
used instance or to perform system maintenance.</para>
<step>
<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>
<para>To initiate a hypervisor-level suspend operation, run
the following command:</para>
<screen><prompt>$</prompt> <userinput>nova suspend <replaceable>SERVER</replaceable></userinput></screen>
</step>
<step><para>To resume a suspended server:</para>
<screen><prompt>$</prompt> <userinput>nova resume <replaceable>SERVER</replaceable></userinput></screen>
</step>
</procedure></section>
</step>
<step>
<para>To resume a suspended server:</para>
<screen><prompt>$</prompt> <userinput>nova resume <replaceable>SERVER</replaceable></userinput></screen>
</step>
</procedure>
</section>
</section>

2
doc/common/section_nova_cli_terminate.xml
View File

@@ -7,7 +7,7 @@
xml:id="terminating">
<title>Delete an instance</title>
<para>When you no longer need an instance, you can delete it.</para>
<procedure><title>To delete an instance</title><step>
<procedure><step>
<para>List all instances:</para>
<screen><prompt>$</prompt> <userinput>nova list</userinput>
<computeroutput>+--------------------------------------+----------------------+--------+------------+-------------+------------------+

219
doc/common/section_user-data.xml
View File

@@ -1,111 +1,137 @@
<?xml version="1.0" encoding="UTF-8"?>
<section
xmlns="http://docbook.org/ns/docbook"
<section xmlns="http://docbook.org/ns/docbook"
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink"
version="5.0"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="user-data">
<title>Configuring instances at boot time</title>
<simplesect>
<title>Introduction</title>
<para>Users often want to do some configuration to their instances after booting. For
example, you may want to install some packages, start services, or manage the instance
using a Puppet or Chef server. When launching instances in an OpenStack cloud, there are
two technologies that work together to support automated configuration of instances at
boot time: user data and cloud-init.</para>
</simplesect>
<title>Configure instances at boot</title>
<para>When you boot instances in an OpenStack cloud, you can use
user data or <package>cloud-init</package> to automatically
configure instances at boot time. You might want to install
some packages, start services, or manage your instance by
using a Puppet or Chef server.</para>
<simplesect>
<title>User data</title>
<para>User data is the mechanism by which a user can pass information contained in a local
file to an instance at launch time. The typical use case is to pass something like a
shell script or a configuration file as user data.</para>
<para>User data is the mechanism by which a user can pass
information contained in a local file to an instance at
launch time. The typical use case is to pass something
like a shell script or a configuration file as user
data.</para>
<para>User data is sent using the <literal>--user-data
<replaceable>/path/to/filename</replaceable></literal> option when calling
<command>nova boot</command>. The following example creates a text file and then
send the contents of that file as user data to the instance.</para>
<para>
<screen><prompt>$</prompt> <userinput>echo "This is some text" > myfile.txt</userinput>
<replaceable>/path/to/filename</replaceable></literal>
option when calling <command>nova boot</command>. This
example creates a text file and sends its contents as user
data to the instance:</para>
<screen><prompt>$</prompt> <userinput>echo "This is some text" > myfile.txt</userinput>
<prompt>$</prompt> <userinput>nova boot --user-data ./myfile.txt --image myimage myinstance</userinput></screen>
</para>
<para>The instance can retrieve user data by querying the metadata service at using either
the OpenStack metadata API or the EC2 compatibility API:</para>
<para>
<screen><prompt>$</prompt> <userinput>curl http://169.254.169.254/2009-04-04/user-data</userinput>
<computeroutput>This is some text</computeroutput>
<prompt>$</prompt> <userinput>curl http://169.254.169.254/openstack/2012-08-10/user_data</userinput>
<computeroutput>This is some text</computeroutput></screen>
</para>
<para>Note that the Compute service treats user data as a blob. While the example above used
a text file, user data can be in any format.</para>
<para>The instance can get user data by querying the metadata
service through either the OpenStack metadata API or the
EC2 compatibility API:</para>
<screen><prompt>$</prompt> <userinput>curl http://169.254.169.254/2009-04-04/user-data</userinput></screen>
<screen><computeroutput>This is some text</computeroutput></screen>
<screen><prompt>$</prompt> <userinput>curl http://169.254.169.254/openstack/2012-08-10/user_data</userinput></screen>
<screen><computeroutput>This is some text</computeroutput></screen>
<note>
<para>The Compute service treats user data as a blob.
While the previous example uses a text file, user data
can be in any format.</para>
</note>
<para>For more information, see <xref linkend="config-drive"
/>.</para>
</simplesect>
<simplesect>
<title>Cloud-init</title>
<para>To do something useful with the user data, the virtual machine image must be
configured to run a service on boot that retrieves the user data from the metadata
service and take some action based on the contents of the data. The cloud-init package
was designed to do exactly this. In particular, cloud-init is compatible with the
Compute metadata service as well as the Compute config drive.</para>
<para>Note that cloud-init is not an OpenStack technology. Rather, it is a package that is
designed to support multiple cloud providers, so that the same virtual machine image can
be used in different clouds without modification. Cloud-init is an open source project,
and the source code is available on <link xlink:href="http://launchpad.net/cloud-init"
>Launchpad</link>. It is maintained by Canonical, the company which runs the Ubuntu
project. All Ubuntu cloud images come pre-installed with cloud-init. However, cloud-init
is not designed to be Ubuntu-specific, and has been successfully ported to
several other platforms including Fedora.</para>
<para>We recommend installing cloud-init on images that you create to simplify the task of
configuring your instances on boot. Even if you do not wish to use user data to
configure instance behavior at boot time, cloud-init provides useful functionality such
as copying the public key to an account (the <literal>ubuntu</literal> account by
default on Ubuntu instances, the <literal>ec2-user</literal> by default in Fedora
instances).</para>
<para>If you do not have cloud-init installed, you will need to manually configure your
image to retrieve the public key from the metadata service on boot and copy it to the
appropriate account.</para>
</simplesect>
<title><package>cloud-init</package></title>
<para>To do something useful with the user data, you must
configure the virtual machine image to run a service on
boot that gets user data from the metadata service and
takes some action based on the contents of the data. The
<package>cloud-init</package> package does exactly
this. This package is compatible with the Compute metadata
service and the Compute configuration drive.</para>
<note>
<para>The <package>cloud-init</package> package supports
multiple cloud providers. You can use the same virtual
machine image in different clouds without
modification. The <package>cloud-init</package>
package is an open source project and the source code
is available on <link
xlink:href="http://launchpad.net/cloud-init"
>Launchpad</link>. It is maintained by Canonical,
the company that runs the Ubuntu project. All Ubuntu
cloud images come pre-installed with
<package>cloud-init</package>. However,
<package>cloud-init</package> is not designed to
be Ubuntu-specific and has been successfully ported to
several other platforms including Fedora.</para>
</note>
<para>Even if you do not use user data to configure instance
behavior at boot time, install
<package>cloud-init</package> on images that you
create because this package provides useful functionality.
For example, the <package>cloud-init</package> package
enables you to copy the public key to an account (the
<literal>ubuntu</literal> account by default on Ubuntu
instances, the <literal>ec2-user</literal> by default in
Fedora instances).</para>
<para>If you do not have <package>cloud-init</package>
installed, you must manually configure your image to get
the public key from the metadata service on boot and copy
it to the appropriate account.</para>
</simplesect>
<simplesect>
<title>Cloud-init supported formats and documentation</title>
<para>We recommend taking a look at the cloud-init <link
<title><package>cloud-init</package> supported formats and
documentation</title>
<para>Look at the <package>cloud-init</package>
<link
xlink:href="http://bazaar.launchpad.net/~cloud-init-dev/cloud-init/trunk/view/head:/doc/userdata.txt"
>doc/userdata.txt</link> file the <link
xlink:href="http://bazaar.launchpad.net/~cloud-init-dev/cloud-init/trunk/files/head:/doc/examples/"
>examples</link> directory as well as the <link
xlink:href="https://help.ubuntu.com/community/CloudInit">Ubuntu community
documentation</link> for details on how to use cloud-init. We provide some basic
examples here.</para>
<para>Cloud-init supports several different input formats for user data. We briefly discuss
two commonly used formats:<itemizedlist>
>examples</link> directory and the <link
xlink:href="https://help.ubuntu.com/community/CloudInit"
>Ubuntu community documentation</link> for details
about how to use <package>cloud-init</package>. Some basic
examples are provided here.</para>
<para><package>cloud-init</package> supports several different
input formats for user data. Two commonly used formats are:<itemizedlist>
<listitem>
<para>Shell scripts (starts with <literal>#!</literal>)</para>
<para>Shell scripts (starts with
<literal>#!</literal>)</para>
</listitem>
<listitem>
<para>Cloud config files (starts with <literal>#cloud-config</literal>)</para>
<para>Cloud config files (starts with
<literal>#cloud-config</literal>)</para>
</listitem>
</itemizedlist></para>
</simplesect>
<simplesect>
<title>Running a shell script on boot</title>
<para>Assuming you have cloud-init installed, the simplest way to configure an instance on
boot is to pass a shell script as user data. The shell file must begin with
<literal>#!</literal> in order for cloud-init to recognize it as a shell script.
Here's an example of a script that creates an account called
<literal>clouduser</literal>.</para>
<para><programlisting language="bash">#!/bin/bash
adduser --disabled-password --gecos "" clouduser</programlisting>Sending
a shell script as user data has a similar effect to writing an
<filename>/etc/rc.local</filename> script: it will be executed very late in the boot
sequence as root.</para>
<title>Run a shell script on boot</title>
<para>Assuming you have <package>cloud-init</package>
installed, the simplest way to configure an instance on
boot is to pass a shell script as user data. The shell
file must begin with <literal>#!</literal> in order for
<package>cloud-init</package> to recognize it as a
shell script. This example shows a script that creates a
<literal>clouduser</literal> account:</para>
<programlisting language="bash">#!/bin/bash
adduser --disabled-password --gecos "" clouduser</programlisting>
<para>Sending a shell script as user data has a similar effect
to writing an <filename>/etc/rc.local</filename> script:
it executes very late in the boot sequence as root.</para>
</simplesect>
<simplesect><title>Cloud-config format</title>
<para>Cloud-init supports a YAML-based config format that allows the user to configure a
large number of options on a system. User data that begins with
<literal>#cloud-config</literal> will be interpreted by cloud-init as cloud-config
<simplesect>
<title>Cloud-config format</title>
<para><package>cloud-init</package> supports a YAML-based
config format that allows the user to configure a large
number of options on a system. User data that begins with
<literal>#cloud-config</literal> will be interpreted
by <package>cloud-init</package> as cloud-config
format.</para>
</simplesect>
<simplesect>
<title>Example: Setting hostname</title>
<para>This cloud-init user data example sets the hostname and the FQDN, as well as updating
<filename>/etc/hosts</filename> on the instance:</para>
<title>Example: Set the host name</title>
<para>This <package>cloud-init</package> user data example
sets the hostname and the FQDN, as well as updating
<filename>/etc/hosts</filename> on the
instance:</para>
<para>
<programlisting>#cloud-config
hostname: mynode
@@ -114,11 +140,13 @@ manage_etc_hosts: true</programlisting>
</para>
</simplesect>
<simplesect>
<title>Example: Configuring instances with Puppet</title>
<para>This cloud-init user data example, based on <link
<title>Example: Configure instances with Puppet</title>
<para>This <package>cloud-init</package> user data example,
based on <link
xlink:href="http://bazaar.launchpad.net/~cloud-init-dev/cloud-init/trunk/view/head:/doc/examples/cloud-config-puppet.txt"
>doc/examples/cloud-config-puppet.txt</link>, would configure the instance to
contact a Puppet server at puppetmaster.example.org and verify its identity using a
>doc/examples/cloud-config-puppet.txt</link>, would
configure the instance to contact a Puppet server at
puppetmaster.example.org and verify its identity using a
certificate.
<programlisting>#cloud-config
puppet:
@@ -141,13 +169,16 @@ puppet:
-----END CERTIFICATE-----</programlisting></para>
</simplesect>
<simplesect>
<title>Example: Configuring instances with Chef</title>
<para>This cloud-init user data example, based on <link
<title>Example: Configure instances with Chef</title>
<para>This <package>cloud-init</package> user data example,
based on <link
xlink:href="http://bazaar.launchpad.net/~cloud-init-dev/cloud-init/trunk/view/head:/doc/examples/cloud-config-chef.txt"
>doc/examples/cloud-config/chef.txt</link>, and intended for use in an Ubuntu image,
would add the Chef apt repository, install Chef, connect to a Chef server at
https://chefserver.example.com:4000 and install
Apache.<programlisting>#cloud-config
>doc/examples/cloud-config/chef.txt</link> and
intended for use in an Ubuntu image, adds the Chef apt
repository, installs Chef, connects to a Chef server at
<literal>https://chefserver.example.com:4000</literal>,
and installs
Apache:<programlisting>#cloud-config
apt_sources:
- source: "deb http://apt.opscode.com/ $RELEASE-0.10 main"
key: |

2
doc/user-guide/bk-user-guide.xml
View File

@@ -40,7 +40,7 @@
interrelated projects deliver a cloud infrastructure
solution. This guide shows OpenStack end users how to
create and manage resources in an OpenStack cloud with
the OpenStack dashboard or OpenStack client
the OpenStack dashboard and OpenStack client
commands.</para>
</abstract>
<revhistory>

24
doc/user-guide/samples/meta_data.json Normal file
View File

@@ -0,0 +1,24 @@
{
"availability_zone":"nova",
"files":[
{
"content_path":"/content/0000",
"path":"/etc/network/interfaces"
},
{
"content_path":"/content/0001",
"path":"known_hosts"
}
],
"hostname":"test.novalocal",
"launch_index":0,
"name":"test",
"meta":{
"role":"webservers",
"essential":"false"
},
"public_keys":{
"mykey":"ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDBqUfVvCSez0/Wfpd8dLLgZXV9GtXQ7hnMN+Z0OWQUyebVEHey1CXuin0uY1cAJMhUq8j98SiW+cU0sU4J3x5l2+xi1bodDm1BtFWVeLIOQINpfV1n8fKjHB+ynPpe1F6tMDvrFGUlJs44t30BrujMXBe8Rq44cCk6wqyjATA3rQ== Generated by Nova\n"
},
"uuid":"83679162-1378-4288-a2d4-70e13ec132aa"
}

33
doc/user-guide/samples/meta_data_ec2.json Normal file
View File

@@ -0,0 +1,33 @@
{
"ami-id":"ami-00000001",
"ami-launch-index":0,
"ami-manifest-path":"FIXME",
"block-device-mapping":{
"ami":"sda1",
"ephemeral0":"sda2",
"root":"/dev/sda1",
"swap":"sda3"
},
"hostname":"test.novalocal",
"instance-action":"none",
"instance-id":"i-00000001",
"instance-type":"m1.tiny",
"kernel-id":"aki-00000002",
"local-hostname":"test.novalocal",
"local-ipv4":null,
"placement":{
"availability-zone":"nova"
},
"public-hostname":"test.novalocal",
"public-ipv4":"",
"public-keys":{
"0":{
"openssh-key":"ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDBqUfVvCSez0/Wfpd8dLLgZXV9GtXQ7hnMN+Z0OWQUyebVEHey1CXuin0uY1cAJMhUq8j98SiW+cU0sU4J3x5l2+xi1bodDm1BtFWVeLIOQINpfV1n8fKjHB+ynPpe1F6tMDvrFGUlJs44t30BrujMXBe8Rq44cCk6wqyjATA3rQ== Generated by Nova\n"
}
},
"ramdisk-id":"ari-00000003",
"reservation-id":"r-7lfps8wj",
"security-groups":[
"default"
]
}

260
doc/user-guide/section_dashboard_stacks.xml
View File

@@ -10,136 +10,178 @@
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="dashboard_stacks">
<title>Launch and manage stacks</title>
<para>Heat is a service used to orchestrate multiple composite cloud applications using the AWS CloudFormation template format, through both an OpenStack-native ReST API and a CloudFormation-compatible Query API.</para>
<para>The purpose of Heat is to provide a template based orchestration for describing a cloud application by executing appropriate OpenStack API calls to generate running cloud applications, integrate other core components of OpenStack into a one-file template system. The templates allow creation of most OpenStack resource types such as instances, floating ips, volumes, security groups, users, etc.</para>
<para>Heat is a service used to orchestrate multiple composite
cloud applications using the AWS CloudFormation template
format, through both an OpenStack-native ReST API and a
CloudFormation-compatible Query API.</para>
<para>The purpose of Heat is to provide a template based
orchestration for describing a cloud application by executing
appropriate OpenStack API calls to generate running cloud
applications, integrate other core components of OpenStack
into a one-file template system. The templates allow creation
of most OpenStack resource types such as instances, floating
ips, volumes, security groups, users, etc.</para>
<section xml:id="dashboard_create_stacks">
<title>Launch a stack</title>
<procedure>
<step>
<para>Log in to the OpenStack dashboard, choose a project,
and, click the <guibutton>Stacks</guibutton> in the <guilabel>Orchestration</guilabel> category.</para>
</step>
<step>
<para>Click <guibutton>Launch Stack</guibutton> button.</para>
<para>A <guilabel>Select Template</guilabel> window opens.</para>
</step>
<step><para>Choose between the template source options from the dropdown list.</para>
<para>Your options are URL, File or Direct Input.</para>
</step>
<step><para>Enter the URL, browse to the file location or directly include the template based on your selection in the previous step.</para>
<para>The <guilabel>Launch Stack</guilabel> window opens.</para>
</step>
<step>
<para>In the <guilabel>Launch Stack</guilabel> window, specify the following
values.</para>
<informaltable rules="all" width="75%">
<col width="30%"/>
<col width="70%"/>
<tbody>
<tr>
<td><para><guilabel>Stack
Name</guilabel></para></td>
<td><para>A name to identify the stack.</para></td>
</tr>
<tr>
<td><para><guilabel>Creation Timeout (minutes)</guilabel></para></td>
<td><para>Creation Timeout in minutes.</para></td>
</tr>
<tr>
<td><para><guilabel>Rollback On Failure</guilabel></para></td>
<td><para>Check this option if you want Heat to rollback on failure.</para></td>
</tr>
<tr>
<td><para><guilabel>Password for user "demo"</guilabel></para></td>
<td><para>Password for the user logged in.</para></td>
</tr>
<tr>
<td><para><guilabel>DBUsername</guilabel></para></td>
<td><para>Database user name.</para></td>
</tr>
<tr>
<td><para><guilabel>LinuxDistribution</guilabel></para></td>
<td><para>Linux Distribution used in the stacks.</para></td>
</tr>
<tr>
<td><para><guilabel>DBRootPassword</guilabel></para></td>
<td><para>Database root password.</para></td>
</tr>
<tr>
<td><para><guilabel>KeyName</guilabel></para></td>
<td><para>Name of the keypair.</para></td>
</tr>
<tr>
<td><para><guilabel>DBName</guilabel></para></td>
<td><para>Database name.</para></td>
</tr>
<tr>
<td><para><guilabel>DBPassword</guilabel></para></td>
<td><para>Database password.</para></td>
</tr>
<tr>
<td><para><guilabel>InstanceType</guilabel></para></td>
<td><para>Flavor of the instance.</para></td>
</tr>
</tbody>
</informaltable>
</step>
<step>
<para>Click <guilabel>Launch</guilabel> to create a stack.</para>
</step>
<step>
<para>The dashboard shows the stack in the
<guilabel>Stacks</guilabel> category.</para>
</step>
</procedure>
<para>Once the stack is created, you can click on the stack name to see the following stack details:</para>
<variablelist>
<title>Launch a stack</title>
<procedure>
<step>
<para>Log in to the OpenStack dashboard, choose a
project, and, click <guibutton>Stacks</guibutton>
in the <guilabel>Orchestration</guilabel>
category.</para>
</step>
<step>
<para>Click <guibutton>Launch
Stack</guibutton>.</para>
<para/>
</step>
<step>
<para>In the <guilabel>Select Template</guilabel>
window, choose a template source option,
<guilabel>URL</guilabel>,
<guilabel>File</guilabel>, or <guilabel>Direct
Input</guilabel>, from the drop-down
list.</para>
</step>
<step>
<para>Enter the URL, browse to the file location, or
directly include the template based on your
previous selection.</para>
</step>
<step>
<para>In the <guilabel>Launch Stack</guilabel> window,
specify the following values.</para>
<informaltable rules="all" width="75%">
<col width="30%"/>
<col width="70%"/>
<tbody>
<tr>
<td><para><guilabel>Stack
Name</guilabel></para></td>
<td><para>A name to identify the
stack.</para></td>
</tr>
<tr>
<td><para><guilabel>Creation Timeout
(minutes)</guilabel></para></td>
<td><para>Creation Timeout in
minutes.</para></td>
</tr>
<tr>
<td><para><guilabel>Rollback On
Failure</guilabel></para></td>
<td><para>Check this option if you want
Heat to rollback on
failure.</para></td>
</tr>
<tr>
<td><para><guilabel>Password for user
"demo"</guilabel></para></td>
<td><para>Password for the user logged
in.</para></td>
</tr>
<tr>
<td><para><guilabel>DBUsername</guilabel></para></td>
<td><para>Database user name.</para></td>
</tr>
<tr>
<td><para><guilabel>LinuxDistribution</guilabel></para></td>
<td><para>Linux Distribution used in the
stacks.</para></td>
</tr>
<tr>
<td><para><guilabel>DBRootPassword</guilabel></para></td>
<td><para>Database root
password.</para></td>
</tr>
<tr>
<td><para><guilabel>KeyName</guilabel></para></td>
<td><para>Name of the keypair.</para></td>
</tr>
<tr>
<td><para><guilabel>DBName</guilabel></para></td>
<td><para>Database name.</para></td>
</tr>
<tr>
<td><para><guilabel>DBPassword</guilabel></para></td>
<td><para>Database password.</para></td>
</tr>
<tr>
<td><para><guilabel>InstanceType</guilabel></para></td>
<td><para>Flavor of the
instance.</para></td>
</tr>
</tbody>
</informaltable>
</step>
<step>
<para>Click <guilabel>Launch</guilabel> to create a
stack.</para>
</step>
<step>
<para>The dashboard shows the stack in the
<guilabel>Stacks</guilabel> category.</para>
</step>
</procedure>
<para>After the stack is created, click on the stack name to
see these details:</para>
<variablelist>
<varlistentry>
<term><guilabel>Topology</guilabel></term>
<listitem>
<para>Shows the topology of the stack created.</para>
<para>The topology of the stack created.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Overview</guilabel></term>
<listitem>
<para>Lists the parameters and details of the stack under the following headings, Info, Status, Outputs, Stack Paramaters and Launch Parameters.</para>
<para>The parameters and details of the stack
under the following headings:
<guilabel>Info</guilabel>,
<guilabel>Status</guilabel>,
<guilabel>Outputs</guilabel>,
<guilabel>Stack Parameters</guilabel>, and
<guilabel>Launch
Parameters</guilabel>.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Resources</guilabel></term>
<listitem>
<para>Lists the resources used by the stack.</para>
<para>The resources used by the stack.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Events</guilabel></term>
<listitem>
<para>Lists the events related to the stack.</para>
<para>The events related to the stack.</para>
</listitem>
</varlistentry>
</variablelist>
</variablelist>
</section>
<section xml:id="dashboard_delete_stacks">
<title>Delete stacks</title>
<procedure>
<step>
<para>Log in to the OpenStack dashboard.</para>
</step>
<step>
<para>On the <guilabel>Project</guilabel> tab, click the <guilabel>Stacks</guilabel> category.</para>
</step>
<step>
<para>Select the stack that you want to delete.</para>
</step>
<step>
<para>Click <guibutton>Delete Stack</guibutton>.</para>
</step>
<step>
<para>In the <guilabel>Confirm Delete Stack</guilabel> window,
click <guibutton>Delete Stack</guibutton> to confirm the
deletion. You cannot undo this action.</para>
</step>
</procedure>
</section>
<title>Delete stacks</title>
<procedure>
<step>
<para>Log in to the OpenStack dashboard.</para>
</step>
<step>
<para>On the <guilabel>Project</guilabel> tab, click
the <guilabel>Stacks</guilabel> category.</para>
</step>
<step>
<para>Select the stack that you want to delete.</para>
</step>
<step>
<para>Click <guibutton>Delete
Stack</guibutton>.</para>
</step>
<step>
<para>In the <guilabel>Confirm Delete Stack</guilabel>
window, click <guibutton>Delete Stack</guibutton>
to confirm the deletion. You cannot undo this
action.</para>
</step>
</procedure>
</section>
</section>

522
doc/user-guide/section_nova_cli_config-drive.xml
View File

@@ -3,137 +3,184 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
xml:id="config-drive">
<title>Config drive</title>
<simplesect>
<title>Introduction</title>
<para>OpenStack can be configured to write metadata to a
special configuration drive that will be attached to the
instance when it boots. The instance can retrieve any
information that would normally be available through the
<link xlink:href="http://docs.openstack.org/admin-guide-cloud/content/section_metadata-service.html">metadata
service</link> by mounting this disk and reading files
from it.</para>
<para>One use case for the config drive is to pass networking
configuration (such as, IP address, netmask, and gateway)
when DHCP is not being used to assign IP addresses to
instances. The instance's IP configuration can be
transmitted using the config drive, which can be mounted
and accessed before the instance's network settings have
been configured.</para>
<para>The config drive can be used by any guest operating
system that is capable of mounting an ISO9660 or VFAT file
system. This functionality should be available on all
modern operating systems.</para>
</simplesect>
<simplesect>
<title>Compute host requirements</title>
<para>Config drive is currently supported by the following
hypervisors: libvirt, xenserver, hyper-v and vmware.</para>
<para>To use config drive with libvirt, xenserver or vmware, the
<command>genisoimage</command> program must be
installed on each compute host. In the Ubuntu
packages, it is not installed by default (see bug
<link xlink:href="https://bugs.launchpad.net/cloud-archive/+bug/1165174">#1165174</link>).
Make sure you install this
program on each compute host before attempting to
use config drive, or an instance will not boot
properly. The path to where
<command>genisoimage</command> is installed can
be set using the <literal>mkisofs_cmd</literal> flag. If
<command>genisoimage</command> is in the path
used by nova-compute you do not need to set
the value of this flag.</para>
<para>To use config drive with hyper-v, you must set the
value of the <literal>mkisofs_cmd</literal> to the
full path to an installation of <literal>mkisofs.exe</literal>.
Additionally, you will need to set the value of the
<literal>qemu_img_cmd</literal> flag in the <literal>hyperv</literal>
configuration section to the full path to an installation
of the <literal>qemu-img</literal> command.</para>
</simplesect>
<simplesect>
<title>Image requirements</title>
<para>An image that has been built with a recent
version of the cloud-init package will be able to
automatically access metadata passed via config drive. The
current version of cloud-init as of this writing (0.7.1)
has been confirmed to work with Ubuntu, as well as
Fedora-based images such as RHEL.</para>
<para>If an image does not have the cloud-init package
installed, the image must be customized to run a script
that mounts the config drive on boot, reads the data from
the drive, and takes appropriate action such as adding the
public key to an account. See below for details on how
data is organized on the config drive.
<note>
<para>If you use Xen with a config drive, disable the
agent through the
<literal>xenapi_disable_agent</literal>
configuration parameter.</para>
</note>
</para>
</simplesect>
<simplesect>
<title>Enabling the config drive</title>
<para>To enable the config drive, pass the
<literal>--config-drive=true</literal> parameter when
calling <command>nova boot</command>. Here is a complex
example that enables the config drive as well as passing
user data, two files, and two key/value metadata pairs,
all of which are accessible from the config drive.</para>
<screen><prompt>$</prompt> <userinput>nova boot --config-drive=true --image my-image-name --key-name mykey --flavor 1 --user-data ./my-user-data.txt myinstance --file /etc/network/interfaces=/home/myuser/instance-interfaces --file known_hosts=/home/myuser/.ssh/known_hosts --meta role=webservers --meta essential=false</userinput></screen>
<para>You can also configure the Compute service to always
create a config drive by setting the following option in
<filename>/etc/nova/nova.conf</filename>:</para>
<programlisting language="ini">force_config_drive=true</programlisting>
<note>
<para>If a user passes the
<literal>--config-drive=true</literal> flag to the
<command>nova boot</command> command, an
administrator cannot disable the config drive.</para>
</note>
</simplesect>
<simplesect>
<title>Accessing the config drive from inside an
instance</title>
<para>The config drive will have a volume label of
<literal>config-2</literal>. If your guest OS supports
accessing disk by label, you should be able to mount the
config drive as the
<filename>/dev/disk/by-label/config-2</filename>
device. For
example:<screen><prompt>#</prompt> <userinput>mkdir -p /mnt/config</userinput>
<prompt>#</prompt> <userinput>mount /dev/disk/by-label/config-2 /mnt/config</userinput></screen></para>
<para>
<note>
<para>The cirros 0.3.0 test image does not have
support for the config drive. Support will be
added in version 0.3.1.</para>
</note>
</para>
<para>If your guest operating system does not use
<literal>udev</literal>, then the
<filename>/dev/disk/by-label</filename> directory will
not be present. The <command>blkid</command> command can
be used to identify the block device that corresponds to
the config drive. For example, when booting the cirros
image with the m1.tiny flavor, the device will be
<filename>/dev/vdb</filename>:</para>
<para><screen><prompt>#</prompt> <userinput>blkid -t LABEL="config-2" -odevice</userinput>
<computeroutput>/dev/vdb</computeroutput></screen>Once
identified, the device can then be mounted:</para>
<para>
<screen><prompt>#</prompt> <userinput>mkdir -p /mnt/config</userinput>
<title>Store metadata on a configuration drive</title>
<para>You can configure OpenStack to write metadata to a special
configuration drive that attaches to the instance when it
boots. The instance can mount this drive and read files from
it to get information that is normally available through the
<link
xlink:href="http://docs.openstack.org/admin-guide-cloud/content/section_metadata-service.html"
>metadata service</link>.</para>
<para>One use case for the configuration drive is to pass a
networking configuration when DHCP is not being used to assign
IP addresses to instances. For example, you might pass the IP
configuration for the instance through the configuration
drive, which the instance can mount and access before the you
configure the network settings for the instance.</para>
<para>Any modern guest operating system that is capable of
mounting an ISO9660 or VFAT file system can use the
configuration drive.</para>
<section xml:id="requirements">
<title>Requirements and guidelines</title>
<itemizedlist>
<title>Compute host requirements</title>
<listitem>
<para>The following hypervisors support the
configuration drive: libvirt, xenserver, hyper-v,
and vmware.</para>
</listitem>
<listitem>
<para>To use configuration drive with libvirt,
xenserver, or vmware, you must first install the
<package>genisoimage</package> program on each
Compute host. Otherwise, instance do not boot
properly.</para>
<para>Use the <literal>mkisofs_cmd</literal> flag to
set the path where you install the
<package>genisoimage</package> program. If
<package>genisoimage</package> is in same path
as the <systemitem role="service"
>nova-compute</systemitem> service, you do not
need to set this flag.</para>
<note>
<para>By default, Ubuntu packages do not install
this program. See bug <link
xlink:href="https://bugs.launchpad.net/cloud-archive/+bug/1165174"
>#1165174</link>.</para>
</note>
</listitem>
<listitem>
<para>To use configuration drive with hyper-v, you
must set the value of the
<literal>mkisofs_cmd</literal> to the full
path to an installation of
<literal>mkisofs.exe</literal>. Additionally,
you must set the value of the
<literal>qemu_img_cmd</literal> flag in the
<literal>hyperv</literal> configuration
section to the full path to an installation of the
<literal>qemu-img</literal> command.</para>
</listitem>
</itemizedlist>
<itemizedlist>
<title>Image requirements</title>
<listitem>
<para>An image built with a recent version of the
<package>cloud-init</package> package can
automatically access metadata passed through the
configuration drive. The
<package>cloud-init</package> package version
0.7.1 works with Ubuntu and Fedora-based images,
such as RHEL.</para>
</listitem>
<listitem>
<para>If an image does not have the
<package>cloud-init</package> package
installed, you must customize the image to run a
script that mounts the configuration drive on
boot, reads the data from the drive, and takes
appropriate action such as adding the public key
to an account. See <xref
linkend="config_drive_contents"/> for details
on how data is organized on the configuration
drive.</para>
</listitem>
<listitem>
<para>If you use Xen with a configuration drive, use
the <literal>xenapi_disable_agent</literal>
configuration parameter to disable the
agent.</para>
</listitem>
</itemizedlist>
<itemizedlist>
<title>Guidelines</title>
<listitem>
<para>Do not rely on the presence of the EC2 metadata
present in the configuration drive, as this
content might be removed in a future release. For
example, do not rely on files in the
<filename>ec2</filename> directory.</para>
</listitem>
<listitem>
<para>When you create images that access configuration
drive data and multiple directories are under the
<filename>openstack</filename> directory,
always select the highest API version by date that
your consumer supports. For example, if your guest
image supports the 2012-03-05, 2012-08-05,
2013-04-13 versions, try 2013-04-13 first and fall
back to a previous version if 2013-04-13 is not
present.</para>
</listitem>
</itemizedlist>
</section>
<section xml:id="enable_config_drive">
<title>Enable and access the configuration drive</title>
<procedure>
<step>
<para>To enable the configuration drive, pass the
<literal>--config-drive=true</literal>
parameter to the <command>nova boot</command>
command.</para>
<para>This example enables the configuration drive and
passes user data, two files, and two key/value
metadata pairs, all of which are accessible from
the configuration drive:</para>
<screen><prompt>$</prompt> <userinput>nova boot --config-drive=true --image my-image-name --key-name mykey --flavor 1 --user-data ./my-user-data.txt myinstance --file /etc/network/interfaces=/home/myuser/instance-interfaces --file known_hosts=/home/myuser/.ssh/known_hosts --meta role=webservers --meta essential=false</userinput></screen>
<para>You can also configure the Compute service to
always create a configuration drive.</para>
<para>Set this option in the
<filename>/etc/nova/nova.conf</filename>
file:</para>
<programlisting language="ini">force_config_drive=true</programlisting>
<note>
<para>If a user passes the
<literal>--config-drive=true</literal>
flag to the <command>nova boot</command>
command, an administrator cannot disable the
configuration drive.</para>
</note>
</step>
<step>
<para>The configuration drive has the
<literal>config-2</literal> volume label. If
your guest operating system supports accessing
disk by label, you can mount the configuration
drive as the
<filename>/dev/disk/by-label/config-2</filename>
device.</para>
<para>For example:</para>
<screen><prompt>#</prompt> <userinput>mkdir -p /mnt/config</userinput>
<prompt>#</prompt> <userinput>mount /dev/disk/by-label/config-2 /mnt/config</userinput></screen>
<note>
<para>The CirrOS 0.3.0 test image does not support
the configuration drive. Support will be added
in CirrOS 0.3.1.</para>
</note>
<para>If your guest operating system does not use
<literal>udev</literal>, the
<filename>/dev/disk/by-label</filename>
directory is not present.</para>
<para>You can use the <command>blkid</command> command
to identify the block device that corresponds to
the configuration drive. For example, when you
boot the CirrOS image with the
<literal>m1.tiny</literal> flavor, the device
is <filename>/dev/vdb</filename>:</para>
<screen><prompt>#</prompt> <userinput>blkid -t LABEL="config-2" -odevice</userinput></screen>
<screen><computeroutput>/dev/vdb</computeroutput></screen>
<para>Once identified, you can mount the
device:</para>
<screen><prompt>#</prompt> <userinput>mkdir -p /mnt/config</userinput>
<prompt>#</prompt> <userinput>mount /dev/vdb /mnt/config</userinput></screen>
</para>
</simplesect>
<simplesect>
<title>Contents of the config drive</title>
<para>The files that will be present in the config drive will
vary depending on the arguments that were passed to
<command>nova boot</command>. Based on the example
above, the contents of the config drive is:</para>
<screen><computeroutput>ec2/2009-04-04/meta-data.json
</step>
</procedure>
<simplesect xml:id="config_drive_contents">
<title>Configuration drive contents</title>
<para>In this example, the contents of the configuration
drive are:</para>
<screen><computeroutput>ec2/2009-04-04/meta-data.json
ec2/2009-04-04/user-data
ec2/latest/meta-data.json
ec2/latest/user-data
@@ -144,145 +191,80 @@ openstack/content/0000
openstack/content/0001
openstack/latest/meta_data.json
openstack/latest/user_data</computeroutput></screen>
</simplesect>
<simplesect>
<title>Guidelines for accessing config drive data</title>
<para>Do not rely on the presence of the EC2 metadata present
in the config drive (i.e., files under the
<filename>ec2</filename> directory), as this content
may be removed in a future release.</para>
<para>When creating images that access config drive data, if
there are multiple directories under the
<filename>openstack</filename> directory, always
select the highest API version by date that your consumer
supports. For example, if your guest image can support
versions 2012-03-05, 2012-08-05, 2013-04-13. It is best to
try 2013-04-13 first and fall back to an earlier version
if it 2013-04-13 isn't present.</para>
</simplesect>
<simplesect>
<title>Format of OpenStack metadata</title>
<para>Here is an example of the contents of
<filename>openstack/2012-08-10/meta_data.json</filename>,
<filename>openstack/latest/meta_data.json</filename>
(these two files are identical), formatted to improve
readability:</para>
<para>
<programlisting language="json">{
"availability_zone": "nova",
"files": [
{
"content_path": "/content/0000",
"path": "/etc/network/interfaces"
},
{
"content_path": "/content/0001",
"path": "known_hosts"
}
],
"hostname": "test.novalocal",
"launch_index": 0,
"name": "test",
"meta": {
"role": "webservers"
"essential": "false"
},
"public_keys": {
"mykey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDBqUfVvCSez0/Wfpd8dLLgZXV9GtXQ7hnMN+Z0OWQUyebVEHey1CXuin0uY1cAJMhUq8j98SiW+cU0sU4J3x5l2+xi1bodDm1BtFWVeLIOQINpfV1n8fKjHB+ynPpe1F6tMDvrFGUlJs44t30BrujMXBe8Rq44cCk6wqyjATA3rQ== Generated by Nova\n"
},
"uuid": "83679162-1378-4288-a2d4-70e13ec132aa"
}</programlisting>
</para>
<para>Note the effect of the <literal>--file
/etc/network/interfaces=/home/myuser/instance-interfaces</literal>
argument passed to the original <command>nova
boot</command> command. The contents of this file are
contained in the file
<filename>openstack/content/0000</filename> file on
the config drive, and the path is specified as
<filename>/etc/network/interfaces</filename> in the
<filename>meta_data.json</filename> file.</para>
</simplesect>
<simplesect>
<title>Format of EC2 metadata</title>
<para>Here is an example of the contents of
<filename>ec2/2009-04-04/meta-data.json</filename>,
<filename>latest/meta-data.json</filename> (these two
files are identical) formatted to improve
readability:</para>
<para>
<programlisting language="json">{
"ami-id": "ami-00000001",
"ami-launch-index": 0,
"ami-manifest-path": "FIXME",
"block-device-mapping": {
"ami": "sda1",
"ephemeral0": "sda2",
"root": "/dev/sda1",
"swap": "sda3"
},
"hostname": "test.novalocal",
"instance-action": "none",
"instance-id": "i-00000001",
"instance-type": "m1.tiny",
"kernel-id": "aki-00000002",
"local-hostname": "test.novalocal",
"local-ipv4": null,
"placement": {
"availability-zone": "nova"
},
"public-hostname": "test.novalocal",
"public-ipv4": "",
"public-keys": {
"0": {
"openssh-key": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAAAgQDBqUfVvCSez0/Wfpd8dLLgZXV9GtXQ7hnMN+Z0OWQUyebVEHey1CXuin0uY1cAJMhUq8j98SiW+cU0sU4J3x5l2+xi1bodDm1BtFWVeLIOQINpfV1n8fKjHB+ynPpe1F6tMDvrFGUlJs44t30BrujMXBe8Rq44cCk6wqyjATA3rQ== Generated by Nova\n"
}
},
"ramdisk-id": "ari-00000003",
"reservation-id": "r-7lfps8wj",
"security-groups": [
"default"
]
}</programlisting>
</para>
</simplesect>
<simplesect>
<title>User data</title>
<para>The files
<filename>openstack/2012-08-10/user_data</filename>,
<filename>openstack/latest/user_data</filename>,
<filename>ec2/2009-04-04/user-data</filename>, and
<filename>ec2/latest/user-data</filename>, will only
be present if the <literal>--user-data</literal> flag was
passed to <command>nova boot</command> and will contain
the contents of the user data file passed as the
argument.</para>
</simplesect>
<simplesect>
<title>Format of the config drive</title>
<para>The default format of the config drive as an ISO 9660
filesystem. To explicitly specify the ISO 9660 format,
the following line is in
<filename>/etc/nova/nova.conf</filename>:</para>
<programlisting language="ini">config_drive_format=iso9660</programlisting>
<para>By default, you cannot attach the config drive image as a CD drive
instead of a disk drive. Change this setting in
<filename>/etc/nova/nova.conf</filename> to true if you want a
CD drive attached.</para>
<programlisting language="ini">config_drive_cdrom=true</programlisting>
<para>For legacy reasons, the config drive can be configured to use VFAT
format instead of ISO 9660. It is unlikely that you would require
VFAT format, since ISO 9660 is widely supported across operating
systems. However, if you wish to use the VFAT format, add the
following line to <filename>/etc/nova/nova.conf</filename>
instead:</para>
<programlisting language="ini">config_drive_format=vfat</programlisting>
<para>If you choose VFAT, the config drive is 64 MBs.</para>
</simplesect>
<simplesect>
<title>Configuration Reference</title>
<para>The following table shows all options for the config
drive.</para>
<para>The files that appear on the configuration drive
depend on the arguments that you pass to the
<command>nova boot</command> command.</para>
</simplesect>
<simplesect xml:id="os_metadata_format">
<title>OpenStack metadata format</title>
<para>The following example shows the contents of the
<filename>openstack/2012-08-10/meta_data.json</filename>
and
<filename>openstack/latest/meta_data.json</filename>
files. These files are identical. The file contents
are formatted for readability:</para>
<programlisting language="json"><xi:include parse="text" href="samples/meta_data.json"/></programlisting>
<para>Note the effect of the <literal>--file
/etc/network/interfaces=/home/myuser/instance-interfaces</literal>
argument that was passed to the <command>nova
boot</command> command. The contents of this file
are contained in the
<filename>openstack/content/0000</filename> file
on the configuration drive, and the path is specified
as <filename>/etc/network/interfaces</filename> in the
<filename>meta_data.json</filename> file.</para>
</simplesect>
<simplesect xml:id="ec2_metadata_format">
<title>EC2 metadata format</title>
<para>The following example shows the contents of the
<filename>ec2/2009-04-04/meta-data.json</filename>,
<filename>latest/meta-data.json</filename> files.
These files are identical. The file contents are
formatted to improve readability:</para>
<programlisting language="json"><xi:include href="samples/meta_data_ec2.json" parse="text"/></programlisting>
</simplesect>
<simplesect xml:id="user_data">
<title>User data</title>
<para>The
<filename>openstack/2012-08-10/user_data</filename>,
<filename>openstack/latest/user_data</filename>,
<filename>ec2/2009-04-04/user-data</filename>, and
<filename>ec2/latest/user-data</filename> file are
present only if the <literal>--user-data</literal>
flag and the contents of the user data file are passed
to the <command>nova boot</command> command.</para>
</simplesect>
<simplesect xml:id="config_drive_format">
<title>Configuration drive format</title>
<para>The default format of the configuration drive as an
ISO 9660 file system. To explicitly specify the ISO
9660 format, add the following line to the
<filename>/etc/nova/nova.conf</filename>
file:</para>
<programlisting language="ini">config_drive_format=iso9660</programlisting>
<para>By default, you cannot attach the configuration
drive image as a CD drive instead of as a disk drive.
To attach a CD drive, add this line to the
<filename>/etc/nova/nova.conf</filename>
file:</para>
<programlisting language="ini">config_drive_cdrom=true</programlisting>
<para>For legacy reasons, you can configure the
configuration drive to use VFAT format instead of ISO
9660. It is unlikely that you would require VFAT
format because ISO 9660 is widely supported across
operating systems. However, to use the VFAT format,
add the following line to the
<filename>/etc/nova/nova.conf</filename>
file:</para>
<programlisting language="ini">config_drive_format=vfat</programlisting>
<para>If you choose VFAT, the configuration drive is 64
MBs.</para>
</simplesect>
</section>
<section xml:id="config_reference">
<title>Configuration drive reference</title>
<para>The following table shows the configuration options for
the configuration drive:</para>
<xi:include href="../common/tables/nova-configdrive.xml"/>
</simplesect>
</section>
</section>

61
doc/user-guide/section_nova_cli_floating_ips.xml
View File

@@ -4,34 +4,30 @@
xmlns:xi="http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0">
<title>Manage IP addresses</title>
<section xml:id="floating_ips_overview">
<title>Floating IP Addresses Overview</title>
<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>You can assign a floating IP address to one instance at
a time.</para>
</section>
<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>You can assign a floating IP address to one instance at a
time.</para>
<section xml:id="floating_ips_proc">
<title>List floating IP address information</title>
<procedure>
@@ -80,10 +76,9 @@
<title>Assign floating IP addresses to projects and
instances</title>
<procedure>
<title>To allocate a floating IP address to the current
project</title>
<step>
<para>If more than one pool of IP addresses is
<para>Allocate a floating IP address to the current
project. If more than one pool of IP addresses is
available, you can specify the pool from which to
allocate the IP address. In this example, the pool
name is <literal>public</literal>:</para>
@@ -121,9 +116,7 @@
<step>
<para>To remove a floating IP address from an
instance, you must specify the same arguments that
you used to assign the IP.</para>
<para>To remove a floating IP address from an
instance:</para>
you used to assign the IP:</para>
<screen><prompt>$</prompt> <userinput>nova remove-floating-ip <replaceable>INSTANCE_NAME_OR_ID</replaceable> <replaceable>FLOATING_IP</replaceable></userinput></screen>
</step>
</procedure>