Merge "Add documentation for generic volume groups"
This commit is contained in:
Jenkins
Gerrit Code Review
commit
12a674512a
380
doc/admin-guide/source/blockstorage-groups.rst
Normal file
380
doc/admin-guide/source/blockstorage-groups.rst
Normal file
@ -0,0 +1,380 @@
|
||||
=====================
|
||||
Generic volume groups
|
||||
=====================
|
||||
|
||||
Generic volume group support is available in OpenStack Block Storage (cinder)
|
||||
since the Newton release. The support is added for creating group types and
|
||||
group specs, creating groups of volumes, and creating snapshots of groups.
|
||||
The group operations can be performed using the Block Storage command line.
|
||||
|
||||
A group type is a type for a group just like a volume type for a volume.
|
||||
A group type can also have associated group specs similar to extra specs
|
||||
for a volume type.
|
||||
|
||||
In cinder, there is a group construct called `consistency group`. Consistency
|
||||
groups only support consistent group snapshots and only a small number of
|
||||
drivers can support it. The following is a list of drivers that support
|
||||
consistency groups and the release when the support was added:
|
||||
|
||||
- Juno: EMC VNX
|
||||
|
||||
- Kilo: EMC VMAX, IBM (GPFS, Storwize, SVC, and XIV), ProphetStor, Pure
|
||||
|
||||
- Liberty: Dell Storage Center, EMC XtremIO, HPE 3Par and LeftHand
|
||||
|
||||
- Mitaka: EMC ScaleIO, NetApp Data ONTAP and E-Series, SolidFire
|
||||
|
||||
- Newton: CoprHD, FalconStor, Huawei
|
||||
|
||||
Consistency group cannot be extended easily to serve other purposes. A tenant
|
||||
may want to put volumes used in the same application together in a group so
|
||||
that it is easier to manage them together, and this group of volumes may or
|
||||
may not support consistent group snapshot. Generic volume group is introduced
|
||||
to solve this problem.
|
||||
|
||||
There is a plan to migrate existing consistency group operations to use
|
||||
generic volume group operations in future releases. More information can be
|
||||
found in `Cinder specs <https://github.com/openstack/cinder-specs/blob/master/specs/newton/group-snapshots.rst>`_.
|
||||
|
||||
.. note::
|
||||
|
||||
Only Block Storage V3 API supports groups. You can
|
||||
specify :option:`--os-volume-api-version 3.x` when using the `cinder`
|
||||
command line for group operations where `3.x` contains a microversion value
|
||||
for that command. The generic volume group feature was completed in several
|
||||
patches. As a result, the minimum required microversion is different for
|
||||
group types, groups, and group snapshots APIs.
|
||||
|
||||
The following group type operations are supported:
|
||||
|
||||
- Create a group type.
|
||||
|
||||
- Delete a group type.
|
||||
|
||||
- Set group spec for a group type.
|
||||
|
||||
- Unset group spec for a group type.
|
||||
|
||||
- List group types.
|
||||
|
||||
- Show a group type details.
|
||||
|
||||
- Update a group.
|
||||
|
||||
- List group types and group specs.
|
||||
|
||||
The following group and group snapshot operations are supported:
|
||||
|
||||
- Create a group, given group type and volume types.
|
||||
|
||||
.. note::
|
||||
|
||||
A group must have one group type. A group can support more than one
|
||||
volume type. The scheduler is responsible for finding a back end that
|
||||
can support the given group type and volume types.
|
||||
|
||||
A group can only contain volumes hosted by the same back end.
|
||||
|
||||
A group is empty upon its creation. Volumes need to be created and added
|
||||
to it later.
|
||||
|
||||
- Show a group.
|
||||
|
||||
- List groups.
|
||||
|
||||
- Delete a group.
|
||||
|
||||
- Modify a group.
|
||||
|
||||
- Create a volume and add it to a group.
|
||||
|
||||
- Create a snapshot for a group.
|
||||
|
||||
- Show a group snapshot.
|
||||
|
||||
- List group snapshots.
|
||||
|
||||
- Delete a group snapshot.
|
||||
|
||||
- Create a group from a group snapshot.
|
||||
|
||||
- Create a group from a source group.
|
||||
|
||||
The following operations are not allowed if a volume is in a group:
|
||||
|
||||
- Volume migration.
|
||||
|
||||
- Volume retype.
|
||||
|
||||
- Volume deletion.
|
||||
|
||||
.. note::
|
||||
|
||||
A group has to be deleted as a whole with all the volumes.
|
||||
|
||||
The following operations are not allowed if a volume snapshot is in a
|
||||
group snapshot:
|
||||
|
||||
- Volume snapshot deletion.
|
||||
|
||||
.. note::
|
||||
|
||||
A group snapshot has to be deleted as a whole with all the volume
|
||||
snapshots.
|
||||
|
||||
The details of group type operations are shown in the following. The minimum
|
||||
microversion to support group type and group specs is 3.11:
|
||||
|
||||
**Create a group type**:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
cinder --os-volume-api-version 3.11 group-type-create
|
||||
[--description DESCRIPTION]
|
||||
[--is-public IS_PUBLIC]
|
||||
NAME
|
||||
|
||||
.. note::
|
||||
|
||||
The parameter ``NAME`` is required. The
|
||||
:option:`--is-public IS_PUBLIC` determines whether the group type is
|
||||
accessible to the public. It is ``True`` by default. By default, the
|
||||
policy on privileges for creating a group type is admin-only.
|
||||
|
||||
**Show a group type**:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
cinder --os-volume-api-version 3.11 group-type-show
|
||||
GROUP_TYPE
|
||||
|
||||
.. note::
|
||||
|
||||
The parameter ``GROUP_TYPE`` is the name or UUID of a group type.
|
||||
|
||||
**List group types**:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
cinder --os-volume-api-version 3.11 group-type-list
|
||||
|
||||
.. note::
|
||||
|
||||
Only admin can see private group types.
|
||||
|
||||
**Update a group type**:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
cinder --os-volume-api-version 3.11 group-type-update
|
||||
[--name NAME]
|
||||
[--description DESCRIPTION]
|
||||
[--is-public IS_PUBLIC]
|
||||
GROUP_TYPE_ID
|
||||
|
||||
.. note::
|
||||
|
||||
The parameter ``GROUP_TYPE_ID`` is the UUID of a group type. By default,
|
||||
the policy on privileges for updating a group type is admin-only.
|
||||
|
||||
**Delete group type or types**:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
cinder --os-volume-api-version 3.11 group-type-delete
|
||||
GROUP_TYPE [GROUP_TYPE ...]
|
||||
|
||||
.. note::
|
||||
|
||||
The parameter ``GROUP_TYPE`` is name or UUID of the group type or
|
||||
group types to be deleted. By default, the policy on privileges for
|
||||
deleting a group type is admin-only.
|
||||
|
||||
**Set or unset group spec for a group type**:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
cinder --os-volume-api-version 3.11 group-type-key
|
||||
GROUP_TYPE ACTION KEY=VALUE [KEY=VALUE ...]
|
||||
|
||||
.. note::
|
||||
|
||||
The parameter ``GROUP_TYPE`` is the name or UUID of a group type. Valid
|
||||
values for the parameter ``ACTION`` are ``set`` or ``unset``.
|
||||
``KEY=VALUE`` is the group specs key and value pair to set or unset.
|
||||
For unset, specify only the key. By default, the policy on privileges
|
||||
for setting or unsetting group specs key is admin-only.
|
||||
|
||||
**List group types and group specs**:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
cinder --os-volume-api-version 3.11 group-specs-list
|
||||
|
||||
.. note::
|
||||
|
||||
By default, the policy on privileges for seeing group specs is admin-only.
|
||||
|
||||
The details of group operations are shown in the following. The minimum
|
||||
microversion to support groups operations is 3.13.
|
||||
|
||||
**Create a group**:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
cinder --os-volume-api-version 3.13 group-create
|
||||
[--name NAME]
|
||||
[--description DESCRIPTION]
|
||||
[--availability-zone AVAILABILITY_ZONE]
|
||||
GROUP_TYPE VOLUME_TYPES
|
||||
|
||||
.. note::
|
||||
|
||||
The parameters ``GROUP_TYPE`` and ``VOLUME_TYPES`` are required.
|
||||
``GROUP_TYPE`` is the name or UUID of a group type. ``VOLUME_TYPES``
|
||||
can be a list of names or UUIDs of volume types separated by commas
|
||||
without spaces in between. For example,
|
||||
``volumetype1,volumetype2,volumetype3.``.
|
||||
|
||||
**Show a group**:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
cinder --os-volume-api-version 3.13 group-show
|
||||
GROUP
|
||||
|
||||
.. note::
|
||||
|
||||
The parameter ``GROUP`` is the name or UUID of a group.
|
||||
|
||||
**List groups**:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
cinder --os-volume-api-version 3.13 group-list
|
||||
[--all-tenants [<0|1>]]
|
||||
|
||||
.. note::
|
||||
|
||||
:option:`--all-tenants` specifies whether to list groups for all tenants.
|
||||
Only admin can use this option.
|
||||
|
||||
**Create a volume and add it to a group**:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
cinder --os-volume-api-version 3.13 create
|
||||
--volume-type VOLUME_TYPE
|
||||
--group-id GROUP_ID SIZE
|
||||
|
||||
.. note::
|
||||
|
||||
When creating a volume and adding it to a group, the parameters
|
||||
``VOLUME_TYPE`` and ``GROUP_ID`` must be provided. This is because a group
|
||||
can support more than one volume type.
|
||||
|
||||
**Delete a group**:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
cinder --os-volume-api-version 3.13 group-delete
|
||||
[--delete-volumes]
|
||||
GROUP [GROUP ...]
|
||||
|
||||
.. note::
|
||||
|
||||
:option:`--delete-volumes` allows or disallows groups to be deleted
|
||||
if they are not empty. If the group is empty, it can be deleted without
|
||||
:option:`--delete-volumes`. If the group is not empty, the flag is
|
||||
required for it to be deleted. When the flag is specified, the group
|
||||
and all volumes in the group will be deleted.
|
||||
|
||||
**Modify a group**:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
cinder --os-volume-api-version 3.13 group-update
|
||||
[--name NAME]
|
||||
[--description DESCRIPTION]
|
||||
[--add-volumes UUID1,UUID2,......]
|
||||
[--remove-volumes UUID3,UUID4,......]
|
||||
GROUP
|
||||
|
||||
.. note::
|
||||
|
||||
The parameter ``UUID1,UUID2,......`` is the UUID of one or more volumes
|
||||
to be added to the group, separated by commas. Similarly the parameter
|
||||
``UUID3,UUID4,......`` is the UUID of one or more volumes to be removed
|
||||
from the group, separated by commas.
|
||||
|
||||
The details of group snapshots operations are shown in the following. The
|
||||
minimum microversion to support group snapshots operations is 3.14.
|
||||
|
||||
**Create a snapshot for a group**:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
cinder --os-volume-api-version 3.14 group-snapshot-create
|
||||
[--name NAME]
|
||||
[--description DESCRIPTION]
|
||||
GROUP
|
||||
|
||||
.. note::
|
||||
|
||||
The parameter ``GROUP`` is the name or UUID of a group.
|
||||
|
||||
**Show a group snapshot**:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
cinder --os-volume-api-version 3.14 group-snapshot-show
|
||||
GROUP_SNAPSHOT
|
||||
|
||||
.. note::
|
||||
|
||||
The parameter ``GROUP_SNAPSHOT`` is the name or UUID of a group snapshot.
|
||||
|
||||
**List group snapshots**:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
cinder --os-volume-api-version 3.14 group-snapshot-list
|
||||
[--all-tenants [<0|1>]]
|
||||
[--status STATUS]
|
||||
[--group-id GROUP_ID]
|
||||
|
||||
.. note::
|
||||
|
||||
:option:`--all-tenants` specifies whether to list group snapshots for
|
||||
all tenants. Only admin can use this option. :option:`--status STATUS`
|
||||
filters results by a status. :option:`--group-id GROUP_ID` filters
|
||||
results by a group id.
|
||||
|
||||
**Delete group snapshot**:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
cinder --os-volume-api-version 3.14 group-snapshot-delete
|
||||
GROUP_SNAPSHOT [GROUP_SNAPSHOT ...]
|
||||
|
||||
.. note::
|
||||
|
||||
The parameter ``GROUP_SNAPSHOT`` specifies the name or UUID of one or more
|
||||
group snapshots to be deleted.
|
||||
|
||||
**Create a group from a group snapshot or a source group**:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ cinder --os-volume-api-version 3.14 group-create-from-src
|
||||
[--group-snapshot GROUP_SNAPSHOT]
|
||||
[--source-group SOURCE_GROUP]
|
||||
[--name NAME]
|
||||
[--description DESCRIPTION]
|
||||
|
||||
.. note::
|
||||
|
||||
The parameter ``GROUP_SNAPSHOT`` is a name or UUID of a group snapshot.
|
||||
The parameter ``SOURCE_GROUP`` is a name or UUID of a source group.
|
||||
Either ``GROUP_SNAPSHOT`` or ``SOURCE_GROUP`` must be specified, but not
|
||||
both.
|
||||
@ -73,3 +73,4 @@ troubleshoot your installation and back up your Compute volumes.
|
||||
blockstorage-image-volume-cache.rst
|
||||
blockstorage-volume-backed-image.rst
|
||||
blockstorage-get-capabilities.rst
|
||||
blockstorage-groups.rst
|
||||
|
||||
Loading…
Reference in New Issue
Block a user