diff --git a/doc/admin-guide/source/blockstorage-groups.rst b/doc/admin-guide/source/blockstorage-groups.rst new file mode 100644 index 0000000000..476b3c21ea --- /dev/null +++ b/doc/admin-guide/source/blockstorage-groups.rst @@ -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 `_. + +.. 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. diff --git a/doc/admin-guide/source/blockstorage-manage-volumes.rst b/doc/admin-guide/source/blockstorage-manage-volumes.rst index cefa5a0e22..fc733ce454 100644 --- a/doc/admin-guide/source/blockstorage-manage-volumes.rst +++ b/doc/admin-guide/source/blockstorage-manage-volumes.rst @@ -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