Merge "Add document for consistency groups"
This commit is contained in:
Jenkins
Gerrit Code Review
commit
7a500974fb
@ -0,0 +1,223 @@
|
||||
<?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="consistency-groups">
|
||||
<title>Consistency Groups</title>
|
||||
<para>Consistency group support is available in OpenStack Block Storage.
|
||||
The support is added for creating snapshots of consistency groups.
|
||||
This feature leverages the storage level consistency technology.
|
||||
It allows snapshots of multiple volumes in the same consistency group
|
||||
to be taken at the same point-in-time to ensure data consistency.
|
||||
The consistency group operations can be performed using the Block Storage
|
||||
command line.</para>
|
||||
<note><para>Only Block Storage V2 API supports consistency groups. You can
|
||||
specify <literal>--os-volume-api-version 2</literal> when using Block
|
||||
Storage command line for consistency group operations.</para></note>
|
||||
<para>Before using consistency groups, make sure the Block Storage driver
|
||||
that you are running has consistency group support by reading the
|
||||
Block Storage manual or consulting the driver maintainer. There are
|
||||
a small number of drivers that have implemented this feature. The
|
||||
default LVM driver does not support consistency groups yet because
|
||||
the consistency technology is not available at the storage level.</para>
|
||||
<para>Before using consistency groups, you must change policies for the
|
||||
consistency group APIs in the <filename>/etc/cinder/policy.json
|
||||
</filename> file. By default, the consistency group APIs are disabled.
|
||||
Enable them before running consistency group operations.</para>
|
||||
<para>Here are existing policy entries for consistency groups:</para>
|
||||
<programlisting language="ini">"consistencygroup:create": "group:nobody",
|
||||
"consistencygroup:delete": "group:nobody",
|
||||
"consistencygroup:get": "group:nobody",
|
||||
"consistencygroup:get_all": "group:nobody",
|
||||
"consistencygroup:create_cgsnapshot" : "group:nobody",
|
||||
"consistencygroup:delete_cgsnapshot": "group:nobody",
|
||||
"consistencygroup:get_cgsnapshot": "group:nobody",
|
||||
"consistencygroup:get_all_cgsnapshots": "group:nobody",</programlisting>
|
||||
<para>Change them to the following by removing <literal>group:nobody
|
||||
</literal> to enable these APIs:</para>
|
||||
<programlisting language="ini">"consistencygroup:create": "",
|
||||
"consistencygroup:delete": "",
|
||||
"consistencygroup:update": "",
|
||||
"consistencygroup:get": "",
|
||||
"consistencygroup:get_all": "",
|
||||
"consistencygroup:create_cgsnapshot" : "",
|
||||
"consistencygroup:delete_cgsnapshot": "",
|
||||
"consistencygroup:get_cgsnapshot": "",
|
||||
"consistencygroup:get_all_cgsnapshots": "",</programlisting>
|
||||
<para>Restart Block Storage API service after changing policies.</para>
|
||||
<para>The following consistency group operations are supported:</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>Create a consistency group, given volume types.</para>
|
||||
<note><para>A consistency group can support more than
|
||||
one volume type. The scheduler is responsible for finding
|
||||
a back end that can support all given volume types.</para>
|
||||
</note>
|
||||
<note><para>A consistency group can only contain volumes
|
||||
hosted by the same back end.</para></note>
|
||||
<note><para>A consistency group is empty upon its creation.
|
||||
Volumes need to be created and added to it later.</para>
|
||||
</note>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Show a consistency group.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>List consistency groups.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Create a volume and add it to a consistency group,
|
||||
given volume type and consistency group id.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Create a snapshot for a consistency group.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Show a snapshot of a consistency group.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>List consistency group snapshots.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Delete a snapshot of a consistency group.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Delete a consistency group.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>The following operations are not allowed if a volume
|
||||
is in a consistency group:</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>Volume migration.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Volume retype.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Volume deletion.</para>
|
||||
<note><para>A consistency group has to be
|
||||
deleted as a whole with all the volumes.
|
||||
</para></note>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>The following operations are not allowed if a
|
||||
volume snapshot is in a consistency group snapshot:
|
||||
</para>
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>Volume snapshot deletion.</para>
|
||||
<note><para>A consistency group snapshot has
|
||||
to be deleted as a whole with all the
|
||||
volume snapshots.</para></note>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
<para>The details of consistency group operations are shown in the
|
||||
following.</para>
|
||||
<para>Create a consistency group:</para>
|
||||
<screen>cinder consisgroup-create
|
||||
[--name name]
|
||||
[--description description]
|
||||
[--availability-zone availability-zone]
|
||||
volume-types</screen>
|
||||
<note><para>The parameter <literal>volume-types</literal> is required.
|
||||
It can be a list of names or UUIDs of volume types separated by
|
||||
commas without spaces in between. For example, <literal>
|
||||
volumetype1,volumetype2,volumetype3.</literal>.</para></note>
|
||||
<screen><prompt>$</prompt> <userinput>cinder consisgroup-create --name bronzeCG2 volume_type_1</userinput></screen>
|
||||
<para></para>
|
||||
<screen><computeroutput>+-------------------+--------------------------------------+
|
||||
| Property | Value |
|
||||
+-------------------+--------------------------------------+
|
||||
| availability_zone | nova |
|
||||
| created_at | 2014-12-29T12:59:08.000000 |
|
||||
| description | None |
|
||||
| id | 1de80c27-3b2f-47a6-91a7-e867cbe36462 |
|
||||
| name | bronzeCG2 |
|
||||
| status | creating |
|
||||
+-------------------+--------------------------------------+</computeroutput></screen>
|
||||
<para>Show a consistency group:</para>
|
||||
<screen><prompt>$</prompt> <userinput>cinder consisgroup-show 1de80c27-3b2f-47a6-91a7-e867cbe36462</userinput>
|
||||
<computeroutput>+-------------------+--------------------------------------+
|
||||
| Property | Value |
|
||||
+-------------------+--------------------------------------+
|
||||
| availability_zone | nova |
|
||||
| created_at | 2014-12-29T12:59:08.000000 |
|
||||
| description | None |
|
||||
| id | 2a6b2bda-1f43-42ce-9de8-249fa5cbae9a |
|
||||
| name | bronzeCG2 |
|
||||
| status | available |
|
||||
+-------------------+--------------------------------------+</computeroutput></screen>
|
||||
<para>List consistency groups:</para>
|
||||
<screen><prompt>$</prompt> <userinput>cinder consisgroup-list</userinput>
|
||||
<computeroutput>+--------------------------------------+-----------+-----------+
|
||||
| ID | Status | Name |
|
||||
+--------------------------------------+-----------+-----------+
|
||||
| 1de80c27-3b2f-47a6-91a7-e867cbe36462 | available | bronzeCG2 |
|
||||
| 3a2b3c42-b612-479a-91eb-1ed45b7f2ad5 | error | bronzeCG |
|
||||
+--------------------------------------+-----------+-----------+</computeroutput></screen>
|
||||
<para>Create a volume and add it to a consistency group:</para>
|
||||
<note><para>When creating a volume and adding it to a consistency
|
||||
group, a volume type and a consistency group id must be provided.
|
||||
This is because a consistency group can support more than one
|
||||
volume type.</para></note>
|
||||
<screen><prompt>$</prompt> <userinput>cinder create --volume-type volume_type_1 --name cgBronzeVol --consisgroup-id 1de80c27-3b2f-47a6-91a7-e867cbe36462 1</userinput>
|
||||
<computeroutput>+---------------------------------------+----------------------------------------+
|
||||
| Property | Value |
|
||||
+---------------------------------------+----------------------------------------+
|
||||
| attachments | [] |
|
||||
| availability_zone | nova |
|
||||
| bootable | false |
|
||||
| consistencygroup_id | 1de80c27-3b2f-47a6-91a7-e867cbe36462 |
|
||||
| created_at | 2014-12-29T13:16:47.000000 |
|
||||
| description | None |
|
||||
| encrypted | False |
|
||||
| id | 5e6d1386-4592-489f-a56b-9394a81145fe |
|
||||
| metadata | {} |
|
||||
| name | cgBronzeVol |
|
||||
| os-vol-host-attr:host | server-1@backend-1#pool-1 |
|
||||
| os-vol-mig-status-attr:migstat | None |
|
||||
| os-vol-mig-status-attr:name_id | None |
|
||||
| os-vol-tenant-attr:tenant_id | 1349b21da2a046d8aa5379f0ed447bed |
|
||||
| os-volume-replication:driver_data | None |
|
||||
| os-volume-replication:extended_status | None |
|
||||
| replication_status | disabled |
|
||||
| size | 1 |
|
||||
| snapshot_id | None |
|
||||
| source_volid | None |
|
||||
| status | creating |
|
||||
| user_id | 93bdea12d3e04c4b86f9a9f172359859 |
|
||||
| volume_type | volume_type_1 |
|
||||
+---------------------------------------+----------------------------------------+</computeroutput></screen>
|
||||
<para>Create a snapshot for a consistency group:</para>
|
||||
<screen><prompt>$</prompt> <userinput>cinder cgsnapshot-create 1de80c27-3b2f-47a6-91a7-e867cbe36462</userinput>
|
||||
<computeroutput>+---------------------+--------------------------------------+
|
||||
| Property | Value |
|
||||
+---------------------+--------------------------------------+
|
||||
| consistencygroup_id | 1de80c27-3b2f-47a6-91a7-e867cbe36462 |
|
||||
| created_at | 2014-12-29T13:19:44.000000 |
|
||||
| description | None |
|
||||
| id | d4aff465-f50c-40b3-b088-83feb9b349e9 |
|
||||
| name | None |
|
||||
| status | creating |
|
||||
+---------------------+-------------------------------------+</computeroutput></screen>
|
||||
<para>Show a snapshot of a consistency group:</para>
|
||||
<screen><prompt>$</prompt> <userinput>cinder cgsnapshot-show d4aff465-f50c-40b3-b088-83feb9b349e9</userinput></screen>
|
||||
<para>List consistency group snapshots:</para>
|
||||
<screen><prompt>$</prompt> <userinput>cinder cgsnapshot-list</userinput>
|
||||
<computeroutput>+--------------------------------------+--------+----------+
|
||||
| ID | Status | Name |
|
||||
+--------------------------------------+--------+----------+
|
||||
| 6d9dfb7d-079a-471e-b75a-6e9185ba0c38 | available | None |
|
||||
| aa129f4d-d37c-4b97-9e2d-7efffda29de0 | available | None |
|
||||
| bb5b5d82-f380-4a32-b469-3ba2e299712c | available | None |
|
||||
| d4aff465-f50c-40b3-b088-83feb9b349e9 | available | None |
|
||||
+--------------------------------------+--------+----------+</computeroutput></screen>
|
||||
<para>Delete a snapshot of a consistency group:</para>
|
||||
<screen><prompt>$</prompt> <userinput>cinder cgsnapshot-delete d4aff465-f50c-40b3-b088-83feb9b349e9</userinput></screen>
|
||||
<para>Delete a consistency group:</para>
|
||||
<note><para>The force flag is needed when there are volumes in the
|
||||
consistency group.</para></note>
|
||||
<screen><prompt>$</prompt> <userinput>cinder consisgroup-delete --force 1de80c27-3b2f-47a6-91a7-e867cbe36462</userinput></screen>
|
||||
</section>
|
||||
@ -149,6 +149,7 @@
|
||||
targets and add iSCSI initiators to the system.</para>
|
||||
</section>
|
||||
<xi:include href="blockstorage/section_volume_number_weighter.xml"/>
|
||||
<xi:include href="blockstorage/section_consistency_groups.xml"/>
|
||||
</section>
|
||||
<section xml:id="troubleshooting-cinder-install">
|
||||
<title>Troubleshoot your installation</title>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user