openstack-manuals/doc/common/section_cinder_cli_manage_volumes.xml
Diane Fleming ee146d0112 Updates to User Guide / Havana testing
Updates also clouddocs-maven-plugin to 1.11.1

Change-Id: Id5b325d5ad7d33f0b5e1bb1a63d9b48178aa45f4
author: diane fleming
2013-10-16 14:46:06 +02:00

376 lines
29 KiB
XML
Executable File
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"?>
<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="cli_manage_volumes">
<?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>
<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
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>
</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>
</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>
+--------------------------------------+---------------------------------+--------+--------------------------------------+
| ID | Name | Status | Server |
+--------------------------------------+---------------------------------+--------+--------------------------------------+
| 397e713c-b95b-4186-ad46-6126863ea0a9 | cirros-0.3.1-x86_64-uec | ACTIVE | |
| df430cc2-3406-4061-b635-a51c16e488ac | cirros-0.3.1-x86_64-uec-kernel | ACTIVE | |
| 3cf852bd-2332-48f4-9ae4-7d926d50945e | cirros-0.3.1-x86_64-uec-ramdisk | ACTIVE | |
| 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
volume:</para>
<screen><prompt>$</prompt> <userinput>nova availability-zone-list</userinput></screen>
<screen><?db-font-size 65%?><computeroutput>
+-----------------------+----------------------------------------+
| Name | Status |
+-----------------------+----------------------------------------+
| internal | available |
| |- devstack-grizzly | |
| | |- nova-conductor | enabled :-) 2013-07-25T16:50:44.000000 |
| | |- nova-consoleauth | enabled :-) 2013-07-25T16:50:44.000000 |
| | |- nova-scheduler | enabled :-) 2013-07-25T16:50:44.000000 |
| | |- nova-cert | enabled :-) 2013-07-25T16:50:44.000000 |
| | |- nova-network | enabled :-) 2013-07-25T16:50:44.000000 |
| nova | available |
| |- 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>
+---------------------+--------------------------------------+
| Property | Value |
+---------------------+--------------------------------------+
| attachments | [] |
| availability_zone | nova |
| bootable | false |
| created_at | 2013-07-25T17:02:12.472269 |
| display_description | None |
| display_name | my-new-volume |
| id | 573e024d-5235-49ce-8332-be1576d323f8 |
| image_id | 397e713c-b95b-4186-ad46-6126863ea0a9 |
| metadata | {} |
| size | 8 |
| snapshot_id | None |
| source_volid | None |
| 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>
+--------------------------------------+-----------+-----------------+------+-------------+----------+-------------+
| 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
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>
+----------+--------------------------------------+
| Property | Value |
+----------+--------------------------------------+
| device | /dev/vdb |
| serverId | 84c6e57d-a6b1-44b6-81eb-fcb36afd31b5 |
| 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>
+------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| 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'}] |
| availability_zone | nova |
| bootable | true |
| created_at | 2013-07-25T17:02:12.000000 |
| display_description | None |
| display_name | my-new-volume |
| id | 573e024d-5235-49ce-8332-be1576d323f8 |
| metadata | {} |
| os-vol-host-attr:host | devstack-grizzly |
| os-vol-tenant-attr:tenant_id | 66265572db174a7aa66eba661f58eb9e |
| size | 8 |
| snapshot_id | None |
| source_volid | None |
| status | in-use |
| 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
<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>
+--------------------------------------+-----------+-----------------+------+-------------+----------+-------------+
| 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>
+--------------------------------------+-----------+-----------------+------+-------------+----------+-------------+
| 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>
+--------------------------------------+-----------+-----------------+------+-------------+----------+-------------+
| 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>
<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>
<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>
</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>
</listitem>
</itemizedlist>
</para>
<procedure>
<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>+--------------------------------------+-----------+--------------+------+-------------+----------+-------------+
| 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>+------------+--------------------------------------+
| Property | Value |
+------------+--------------------------------------+
| auth_key | b2c8e585cbc68a80 |
| created_at | 2013-10-14T15:20:10.121458 |
| id | 6e4e9aa4-bed5-4f94-8f76-df43232f44dc |
| 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>+--------------------------------------+--------------------------------------+------+
| 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>+----+-----------+------+
| ID | Volume ID | Name |
+----+-----------+------+
+----+-----------+------+</computeroutput></screen>
</step>
</procedure>
<procedure>
<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>+------------+--------------------------------------+
| Property | Value |
+------------+--------------------------------------+
| created_at | 2013-10-14T15:20:10.000000 |
| id | 6e4e9aa4-bed5-4f94-8f76-df43232f44dc |
| 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>+-----------+--------------------------------------+
| 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>+--------------------------------------+-------------------+--------------+------+-------------+----------+-------------+
| 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>+--------------------------------------+--------------------------------------+------+
| 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>+----+-----------+------+
| ID | Volume ID | Name |
+----+-----------+------+
+----+-----------+------+</computeroutput>
<prompt>$</prompt> <userinput>cinder list</userinput>
<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>
</section>
</section>