openstack/cinder
Code Issues Proposed changes
c0ff458b05
cinder/api-ref/source/v3/groups.inc
Stephen Finucane a32e0b2aa6 api-ref: Improve sort, pagination parameter docs 
The various index APIs (e.g. 'GET /volumes') support two forms of sort
parameter: the legacy 'sort_key'/'sort_dir' parameters and the combined
'sort' parameter. We were documenting different parameters in different
APIs despite the fact all APIs support all parameters.

In a similar vein, the various index APIs support the same three
pagination parameters: 'offset', 'limit', and 'marker'. Once again, we
were documenting these inconsistently.

Correct both issues.

Change-Id: Ia3300a8852825f7da830f7b1ed37b27625e267e9
Signed-off-by: Stephen Finucane <stephenfin@redhat.com>
2023-08-28 15:56:03 +01:00

410 lines
7.4 KiB
ReStructuredText
Raw Blame History

.. -*- rst -*-
Generic volume groups (groups)
==============================
Generic volume groups enable you to create a group of volumes and
manage them together.
How is generic volume groups different from consistency groups?
Currently consistency groups in cinder only support consistent group
snapshot. It cannot be extended easily to serve other purposes. A project
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. By decoupling the tight relationship
between the group construct and the consistency concept, generic volume
groups can be extended to support other features in the future.
List groups
~~~~~~~~~~~
.. rest_method:: GET /v3/{project_id}/groups
Lists groups. Since v3.31 if non-admin users specify
invalid filters in the url, API will return bad request.
Response codes
--------------
.. rest_status_code:: success ../status.yaml
- 200
.. rest_status_code:: error ../status.yaml
- 400
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- all_tenants: all-tenants
- sort: sort
- sort_key: sort_key
- sort_dir: sort_dir
- limit: limit
- offset: offset
- marker: marker
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- groups: groups
- id: id
- name: group_name
Response Example
----------------
.. literalinclude:: ./samples/groups-list-response.json
:language: javascript
Create group
~~~~~~~~~~~~
.. rest_method:: POST /v3/{project_id}/groups
Creates a group.
Response codes
--------------
.. rest_status_code:: success ../status.yaml
- 202
.. rest_status_code:: error ../status.yaml
- 400
- 404
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- group: group
- description: description_group_false
- availability_zone: availability_zone
- group_type: group_type_id
- volume_types: volume_types
- name: group_name
Request Example
---------------
.. literalinclude:: ./samples/group-create-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- id: group_id_path
- name: group_name
Response Example
----------------
.. literalinclude:: ./samples/group-create-response.json
:language: javascript
Show group details
~~~~~~~~~~~~~~~~~~
.. rest_method:: GET /v3/{project_id}/groups/{group_id}
Shows details for a group.
Response codes
--------------
.. rest_status_code:: success ../status.yaml
- 200
.. rest_status_code:: error ../status.yaml
- 404
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- group_id: group_id_path
- list_volume: list_volume
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- group: group
- status: status_group
- description: description_group_true
- availability_zone: availability_zone
- created_at: created_at
- group_type: group_type_id
- group_snapshot_id: group_snapshot_id
- source_group_id: source_group_id
- volume_types: volume_types
- id: id
- name: group_name
- volumes: volume_ids
- replication_status: group_replication_status
- project_id: project_id_group
Response Example
----------------
.. literalinclude:: ./samples/group-show-response.json
:language: javascript
Create group from source
~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: POST /v3/{project_id}/groups/action
Creates a group from source.
Response codes
--------------
.. rest_status_code:: success ../status.yaml
- 202
.. rest_status_code:: error ../status.yaml
- 400
- 404
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- create-from-src: create-from-src
- description: description_group_false
- group_snapshot_id: group_snapshot_id_req
- source_group_id: source_group_id_req
- name: group_name
Request Example
---------------
.. literalinclude:: ./samples/group-create-from-src-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- id: group_id_path
- name: group_name
Response Example
----------------
.. literalinclude:: ./samples/group-create-from-src-response.json
:language: javascript
Delete group
~~~~~~~~~~~~
.. rest_method:: POST /v3/{project_id}/groups/{group_id}/action
Deletes a group.
Response codes
--------------
.. rest_status_code:: success ../status.yaml
- 202
.. rest_status_code:: error ../status.yaml
- 400
- 404
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- group_id: group_id_path
- delete: delete
- delete-volumes: delete-volumes
Request Example
---------------
.. literalinclude:: ./samples/group-delete-request.json
:language: javascript
List groups with details
~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: GET /v3/{project_id}/groups/detail
Lists groups with details, since v3.31 if non-admin
users specify invalid filters in the url, API will return bad request.
Response codes
--------------
.. rest_status_code:: success ../status.yaml
- 200
.. rest_status_code:: error ../status.yaml
- 400
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- all_tenants: all-tenants
- sort: sort
- sort_key: sort_key
- sort_dir: sort_dir
- limit: limit
- offset: offset
- marker: marker
- list_volume: list_volume
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- groups: groups
- status: status_group
- description: description_group_true
- availability_zone: availability_zone
- created_at: created_at
- group_type: group_type_id
- group_snapshot_id: group_snapshot_id
- source_group_id: source_group_id
- volume_types: volume_types
- id: group_id_path
- name: name
- volumes: volume_ids
- replication_status: group_replication_status
- project_id: project_id_group
Response Example
----------------
.. literalinclude:: ./samples/groups-list-detailed-response.json
:language: javascript
Update group
~~~~~~~~~~~~
.. rest_method:: PUT /v3/{project_id}/groups/{group_id}
Updates a group.
Response codes
--------------
.. rest_status_code:: success ../status.yaml
- 202
.. rest_status_code:: error ../status.yaml
- 400
- 404
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- group_id: group_id_path
- group: group
- remove_volumes: remove_volumes
- description: description_group_false
- add_volumes: add_volumes
- name: group_name
Request Example
---------------
.. literalinclude:: ./samples/group-update-request.json
:language: javascript
Reset group status
~~~~~~~~~~~~~~~~~~
.. rest_method:: POST /v3/{project_id}/groups/{group_id}/action
Resets the status for a group. Specify the ``reset_status`` action in the
request body.
Response codes
--------------
.. rest_status_code:: success ../status.yaml
- 202
.. rest_status_code:: error ../status.yaml
- 400
- 404
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- group_id: group_id_path
- reset_status: reset_status
- status: status
Request Example
---------------
.. literalinclude:: ./samples/group-reset-status-request.json
:language: javascript
View Git Blame Copy Permalink