openstack/openstack-manuals
Code Issues Proposed changes
ed3e1664e6
openstack-manuals/doc/admin-guide-cloud/blockstorage/section_consistency_groups.xml
Xing Yang aee628806c Add document for consistency groups 
Consistency group support was added to Cinder in Juno, but
document has not been provided. This patch is to add document
on how to use the consistency group feature.

Backport: Juno

Change-Id: I99c380027fc854674c3ec6b87336f5a920155dac
Closes-Bug: #1400392
2014-12-30 22:41:59 -05:00

224 lines
13 KiB
XML
Raw Blame History

<?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>
View Git Blame Copy Permalink