openstack-manuals/doc/common/section_cli_cinder_manage_volumes.xml
Christian Berendt 6feaaf116f Standardize usage of client arguments (common)
Like documented at https://wiki.openstack.org/wiki/Documentation/Conventions#Client_arguments:_.22--option_ARGUMENT.22
we prefer to use '--option ARGUMENT'.

Change-Id: I4ea2c16a384726429d583d5eb6f03aeec3ca514c
2014-09-09 15:43:44 +02:00

417 lines
31 KiB
XML

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE section [
<!ENTITY % openstack SYSTEM "entities/openstack.ent">
%openstack;
]>
<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 <command>nova</command> and <command>cinder</command>
client commands.</para>
<section xml:id="cli_migrate_volumes" audience="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. You can migrate only
detached volumes with no snapshots.</para>
<para>Possible use cases for data migration include:</para>
<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>Migrate a volume with the <command>cinder migrate</command> command, as shown in the following example:</para>
<screen><prompt>$</prompt> <userinput>cinder migrate <replaceable>volumeID</replaceable> <replaceable>destinationHost</replaceable> --force-host-copy <replaceable>True|False</replaceable></userinput></screen>
<para>In this example, <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. If the user
is not an administrator, the migration fails.</para>
</note>
</section>
<section xml:id="cli_list_volumes" audience="enduser">
<title>Create a volume</title>
<para>This example creates a my-new-volume volume based on an image.</para>
<procedure>
<step>
<para>List images, and note the ID of the image that you want 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.2-x86_64-uec | ACTIVE | |
| df430cc2-3406-4061-b635-a51c16e488ac | cirros-0.3.2-x86_64-uec-kernel | ACTIVE | |
| 3cf852bd-2332-48f4-9ae4-7d926d50945e | cirros-0.3.2-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 you want 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 | |
| | |- 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 | |
| | |- nova-compute | enabled :-) 2013-07-25T16:50:39.000000 |
+-----------------------+----------------------------------------+</computeroutput></screen>
</step>
<step>
<para>Create a volume with 8&nbsp;GB of space, and 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 | [] |
| 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" audience="enduser">
<title>Attach a volume to an instance</title>
<procedure>
<step>
<para>Attach your volume to a server, specifying the server ID and the volume ID:</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>
<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>
<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 |
| 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.2-x86_64-uec'} |
| volume_type | None |
+------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+</computeroutput></screen>
</step>
</procedure>
</section>
<section xml:id="cli_extend_volumes" audience="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 following 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>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 573e024d-5235-49ce-8332-be1576d323f8 10</userinput></screen>
<para>The <command>extend</command> command does not
return any output.</para>
</step>
</procedure>
</section>
<section xml:id="cli_delete_volumes" audience="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 in <xref
linkend="cli_extend_volumes"/>.</para>
</step>
<step>
<para>Delete the volume using either the volume name or ID:</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" audience="enduser">
<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>
<note>
<para>The procedure for volume transfer is intended for tenants (both the volume donor and recipient) within the same cloud.</para>
</note>
<para>Use cases include:</para>
<itemizedlist>
<listitem>
<para>Create a custom bootable volume or a volume with a large data set and transfer it to a customer.</para>
</listitem>
<listitem>
<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>
<section xml:id="create_volume_transfer">
<title>Create a volume transfer request</title>
<procedure>
<step>
<para>While logged in as the volume donor, list the 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:</para>
<screen><prompt>$</prompt> <userinput>cinder transfer-create <replaceable>volumeID</replaceable></userinput></screen>
<para>The volume must be in an <literal>available</literal> 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>
<para>The output shows the volume transfer ID in the <literal>id</literal> row and the authorization
key.</para>
<screen><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 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,
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>
</section>
<section xml:id="accept_volume_transfer">
<title>Accept a volume transfer request</title>
<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 by 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 |
| id | 6e4e9aa4-bed5-4f94-8f76-df43232f44dc |
| name | None |
| volume_id | a1cdace0-08e4-4dc7-b9dc-457e9bcfe25f |
+------------+--------------------------------------+</computeroutput></screen>
</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 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></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:</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>Verify that transfer list is now empty and that the volume is again available for transfer:</para>
<screen><prompt>$</prompt> <userinput>cinder transfer-list</userinput></screen>
<screen><computeroutput>+----+-----------+------+
| ID | Volume ID | Name |
+----+-----------+------+
+----+-----------+------+</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>
</section>
</section>
<xi:include href="section_cli_cinder_read-only-volumes.xml"/>
</section>