402 lines
30 KiB
XML
402 lines
30 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>cinder availability-zone-list</userinput></screen>
|
|
<screen><?db-font-size 65%?><computeroutput>+------+-----------+
|
|
| Name | Status |
|
|
+------+-----------+
|
|
| nova | available |
|
|
+------+-----------+</computeroutput></screen>
|
|
</step>
|
|
<step>
|
|
<para>Create a volume with 8 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>
|
|
<note>
|
|
<para>While the <literal>auth_key</literal> property is
|
|
visible in the output of
|
|
<command>cinder transfer-create <replaceable>VOLUME_ID</replaceable></command>,
|
|
it will not be available in subsequent
|
|
<command>cinder transfer-show <replaceable>TRANSFER_ID</replaceable></command>
|
|
commands.</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>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>
|