openstack/openstack-manuals
Code Issues Proposed changes

Adds note about block size settings to accomodate custom block sizes

Browse Source 
Change-Id: I6bc4c09066855d82bd5f17ba40ce1909b7443c99
Closes-bug: 1197449
This commit is contained in:
annegentle
2013-09-24 13:13:20 -05:00
parent 7b9a6fdc4d
commit 610f4a88c8
2 changed files with 189 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
doc/config-reference/block-storage/section_block-storage-overview.xml
View File

@@ -40,7 +40,7 @@
back-end devices themselves.</para>
</listitem>
<listitem>
<para><emphasis role="bold">cinder-backup</emphasis>
<para><systemitem class="service">cinder-backup</systemitem>
Provides a means to back up a Cinder Volume to
OpenStack Object Store (SWIFT).</para>
</listitem>
@@ -58,7 +58,8 @@
implementation, the OpenStack Block Storage service
also provides the means to add support for other
storage devices to be utilized such as external Raid
Arrays or other storage appliances.</para>
Arrays or other storage appliances. These backend storage devices
may have custom block sizes when using KVM or QEMU as the hypervisor.</para>
</listitem>
<listitem>
<para><emphasis role="bold">Users and Tenants

186
doc/user-guide/section_cinder_cli_manage_volumes.xml Normal file
View File

@@ -0,0 +1,186 @@
<?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">
<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>This example creates a volume named
<literal>my-volume</literal> based on an image.</para>
<procedure>
<title>To list volumes</title>
<step>
<para>To determine which image to use for your volume,
list images:</para>
<screen><prompt>$</prompt> <userinput><?db-font-size 75%?>nova image-list</userinput></screen>
<screen><computeroutput><?db-font-size 65%?>+--------------------------------------+---------------------------------+--------+--------------------------------------+
| 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>
<para>Note the ID of the image that you want to
use.</para>
</step>
<step>
<para>To determine which availability zone are available
in which to create your volume, list the availability
zones:</para>
<screen><prompt>$</prompt> <userinput><?db-font-size 75%?>nova availability-zone-list</userinput></screen>
<screen><computeroutput><?db-font-size 65%?>+-----------------------+----------------------------------------+
| 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>
<para>Note the name of an available availability zone that
you want to use.</para>
</step>
<step>
<para>Create a volume with 8 GBs of space in the desired
availability zone and based on the desired image, as
follows:</para>
<screen><prompt>$</prompt> <userinput><?db-font-size 75%?>cinder create 8 --display-name my-new-volume --image-id 397e713c-b95b-4186-ad46-6126863ea0a9 --availability-zone nova</userinput></screen>
<screen><computeroutput><?db-font-size 65%?>+---------------------+--------------------------------------+
| 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><?db-font-size 75%?>cinder list</userinput></screen>
<screen><computeroutput><?db-font-size 65%?>+--------------------------------------+-----------+-----------------+------+-------------+----------+-------------+
| 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 tried to
create a volume outside of your quota.</para>
</step>
<step>
<para>Attach your volume to a server:</para>
<screen><prompt>$</prompt> <userinput><?db-font-size 75%?>nova volume-attach 84c6e57d-a6b1-44b6-81eb-fcb36afd31b5 573e024d-5235-49ce-8332-be1576d323f8 /dev/vdb</userinput></screen>
<screen><computeroutput><?db-font-size 65%?>+----------+--------------------------------------+
| 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.<note>
<para>If you see any I/O errors when attaching a volume, it is possible that the backend driver needs to be
configured for a custom block size, or that you are running an older version of libvirt. (Version 0.10.2+
is required for backends, such as SolidFire, that set a custom block size). Block Storage supports custom
block sizes on KVM and QEMU.</para>
</note></para>
</step>
<step>
<para>Show information for your volume:</para>
<screen><prompt>$</prompt> <userinput><?db-font-size 75%?>cinder show 573e024d-5235-49ce-8332-be1576d323f8</userinput></screen>
<screen><computeroutput><?db-font-size 65%?><?db-fontsize 75%?>+------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| 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>From the output, you can see 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>
<step>
<para>To delete 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><?db-font-size 75%?>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><?db-font-size 75%?>cinder list</userinput></screen>
<screen><computeroutput><?db-font-size 65%?>+--------------------------------------+-----------+-----------------+------+-------------+----------+-------------+
| 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 delete the volume, as follows:</para>
<screen><prompt>$</prompt> <userinput><?db-font-size 75%?>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><?db-font-size 75%?>cinder list</userinput></screen>
<screen><computeroutput><?db-font-size 65%?>+--------------------------------------+-----------+-----------------+------+-------------+----------+-------------+
| 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><?db-font-size 75%?>cinder list</userinput></screen>
<screen><computeroutput><?db-font-size 65%?>+--------------------------------------+-----------+-----------------+------+-------------+----------+-------------+
| 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>