Add API Reference for groups

This patch adds API reference for group types,
groups, and group snapshots.

Change-Id: Ia42b4a036fc6396cca37c03092c089cc5df1170a
This commit is contained in:
xing-yang 2016-07-22 22:17:43 -04:00
parent 6aceda61b7
commit 0e8ebbdf82
26 changed files with 1057 additions and 4 deletions

View File

@ -8,10 +8,10 @@ List All Api Versions
Lists information for all Block Storage API versions.
Normal response codes: 200,300
Normal response codes: 200,202,300
Error response codes: computeFault(400, 500), serviceUnavailable(503), badRequest(400),
unauthorized(401), forbidden(403), badMethod(405), itemNotFound(404)
unauthorized(401), forbidden(403), badMethod(405), itemNotFound(404), conflict(409)
Request
-------

View File

@ -0,0 +1,181 @@
.. -*- rst -*-
===============
Group snapshots
===============
Lists all, lists all with details, shows details for, creates, and
deletes group snapshots.
Delete group snapshot
=====================
.. rest_method:: DELETE /v3/{tenant_id}/group_snapshots/{group_snapshot_id}
Deletes a group snapshot.
Normal response codes: 202
Error response codes: badRequest(400), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- group_snapshot_id: group_snapshot_id
Show group snapshot details
===========================
.. rest_method:: GET /v3/{tenant_id}/group_snapshots/{group_snapshot_id}
Shows details for a group snapshot.
Normal response codes: 200
Error response codes: badRequest(400), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- group_snapshot_id: group_snapshot_id
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- status: status
- description: description
- created_at: created_at
- group_id: group_id
- id: id
- name: name
Response Example
----------------
.. literalinclude:: ./samples/group-snapshots-show-response.json
:language: javascript
List group snapshots with details
=================================
.. rest_method:: GET /v3/{tenant_id}/group_snapshots/detail
Lists all group snapshots with details.
Normal response codes: 200
Error response codes:
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- status: status
- description: description
- created_at: created_at
- group_id: group_id
- id: id
- name: name
Response Example
----------------
.. literalinclude:: ./samples/group-snapshots-list-detailed-response.json
:language: javascript
List group snapshots
====================
.. rest_method:: GET /v3/{tenant_id}/group_snapshots
Lists all group snapshots.
Normal response codes: 200
Error response codes:
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- id: id
- name: name
Response Example
----------------
.. literalinclude:: ./samples/group-snapshots-list-response.json
:language: javascript
Create group snapshot
=====================
.. rest_method:: POST /v3/{tenant_id}/group_snapshots
Creates a group snapshot.
Normal response codes: 202
Error response codes: badRequest(400), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- name: name
- description: description
- group_id: group_id
- tenant_id: tenant_id
Request Example
---------------
.. literalinclude:: ./samples/group-snapshots-create-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- status: status
- description: description
- created_at: created_at
- group_id: group_id
- id: id
- name: name

View File

@ -0,0 +1,251 @@
.. -*- rst -*-
===========
Group types
===========
Update group type
=================
.. rest_method:: PUT /v3/{tenant_id}/group_types/{group_type_id}
Updates a group type.
To create a generic volume group, you must specify a group type.
Normal response codes: 200
Error response codes: badRequest(400), forbidden(403), itemNotFound(404),
conflict(409), computeFault(500)
Request
-------
.. rest_parameters:: parameters.yaml
- group_type: group_type
- group_type_id: group_type_id
- tenant_id: tenant_id
Request Example
---------------
.. literalinclude:: ./samples/group-type-update-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- is_public: is_public
- group_specs: group_specs
- description: description
- group_type: group_type
- name: name
Response Example
----------------
.. literalinclude:: ./samples/group-type-show-response.json
:language: javascript
Create group specs for a group type
===================================
.. rest_method:: POST /v3/{tenant_id}/group_types/{group_type_id}/group_specs
Create group specs for a group type.
Normal response codes: 202
Error response codes: badRequest(400), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- group_specs: group_specs
- group_type: group_type
- group_type_id: group_type_id
- tenant_id: tenant_id
Request Example
---------------
.. literalinclude:: ./samples/group-type-specs-create-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- is_public: is_public
- group_specs: group_specs
- description: description
- group_type: group_type
- name: name
Response Example
----------------
.. literalinclude:: ./samples/group-type-show-response.json
:language: javascript
Show group type details
=======================
.. rest_method:: GET /v3/{tenant_id}/group_types/{group_type_id}
Shows details for a group type.
Normal response codes: 200
Error response codes: itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- group_type_id: group_type_id
- tenant_id: tenant_id
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- is_public: is_public
- group_specs: group_specs
- description: description
- group_type: group_type
- name: name
Response Example
----------------
.. literalinclude:: ./samples/group-type-show-response.json
:language: javascript
Delete group type
=================
.. rest_method:: DELETE /v3/{tenant_id}/group_types/{group_type_id}
Deletes a group type.
Normal response codes: 202
Error response codes: badRequest(400), forbidden(403), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- group_type_id: group_type_id
- tenant_id: tenant_id
List group types
================
.. rest_method:: GET /v3/{tenant_id}/group_types
Lists group types.
Normal response codes: 200
Error response codes:
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- sort_key: sort_key
- sort_dir: sort_dir
- limit: limit
- marker: marker
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- group_types: group_types
- group_specs: group_specs
- name: name
- group_type: group_type
Response Example
----------------
.. literalinclude:: ./samples/group-types-list-response.json
:language: javascript
Create group type
=================
.. rest_method:: POST /v2/{tenant_id}/group_types
Creates a group type.
To create a generic volume group, you must specify a group type.
Normal response codes: 202
Error response codes: badRequest(400), forbidden(403), itemNotFound(404),
conflict(409)
Request
-------
.. rest_parameters:: parameters.yaml
- group_type: group_type
- tenant_id: tenant_id
Request Example
---------------
.. literalinclude:: ./samples/group-type-create-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- is_public: is_public
- group_specs: group_specs
- description: description
- group_type: group_type
- name: name
Response Example
----------------
.. literalinclude:: ./samples/group-type-show-response.json
:language: javascript

View File

@ -0,0 +1,257 @@
.. -*- rst -*-
=====================
Generic volume 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 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. 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/{tenant_id}/groups
Lists groups.
Normal response codes: 200
Error response codes:
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- sort_key: sort_key
- sort_dir: sort_dir
- limit: limit
- marker: marker
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- id: id
- name: name
Response Example
----------------
.. literalinclude:: ./samples/groups-list-response.json
:language: javascript
Create group
============
.. rest_method:: POST /v3/{tenant_id}/groups
Creates a group.
Normal response codes: 202
Error response codes: badRequest(400), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- description: description
- availability_zone: availability_zone
- group_type: group_type
- volume_types: volume_types
- name: name
- tenant_id: tenant_id
Request Example
---------------
.. literalinclude:: ./samples/group-create-request.json
:language: javascript
Show group details
==================
.. rest_method:: GET /v3/{tenant_id}/groups/{group_id}
Shows details for a group.
Normal response codes: 200
Error response codes: itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- group_id: group_id
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- status: status
- description: description
- availability_zone: availability_zone
- created_at: created_at
- group_type: group_type
- volume_types: volume_types
- id: id
- name: name
Response Example
----------------
.. literalinclude:: ./samples/group-show-response.json
:language: javascript
Create group from source
========================
.. rest_method:: POST /v3/{tenant_id}/groups/action
Creates a group from source.
Normal response codes: 202
Error response codes: badRequest(400), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- description: description
- group_snapshot_id: group_snapshot_id
- source_group_id: source_group_id
- name: name
- tenant_id: tenant_id
Request Example
---------------
.. literalinclude:: ./samples/group-create-from-src-request.json
:language: javascript
Delete group
============
.. rest_method:: POST /v3/{tenant_id}/groups/{group_id}/action
Deletes a group.
Normal response codes: 202
Error response codes: badRequest(400), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- delete-volumes: delete-volumes
- tenant_id: tenant_id
- group_id: group_id
Request Example
---------------
.. literalinclude:: ./samples/group-delete-request.json
:language: javascript
List groups with details
========================
.. rest_method:: GET /v3/{tenant_id}/groups/detail
Lists groups with details.
Normal response codes: 200
Error response codes:
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- sort_key: sort_key
- sort_dir: sort_dir
- limit: limit
- marker: marker
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- status: status
- description: description
- availability_zone: availability_zone
- created_at: created_at
- group_type: group_type
- volume_types: volume_types
- id: id
- name: name
Response Example
----------------
.. literalinclude:: ./samples/groups-list-detailed-response.json
:language: javascript
Update group
============
.. rest_method:: PUT /v3/{tenant_id}/groups/{group_id}
Updates a group.
Normal response codes: 202
Error response codes: badRequest(400), itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- remove_volumes: remove_volumes
- description: description
- add_volumes: add_volumes
- name: name
- tenant_id: tenant_id
- group_id: group_id
Request Example
---------------
.. literalinclude:: ./samples/group-update-request.json
:language: javascript

View File

@ -12,6 +12,9 @@ Block Storage API V3 (CURRENT)
.. include:: capabilities-v3.inc
.. include:: os-cgsnapshots-v3.inc
.. include:: consistencygroups-v3.inc
.. include:: groups.inc
.. include:: group-snapshots.inc
.. include:: group-types.inc
.. include:: limits.inc
.. include:: os-vol-image-meta-v3.inc
.. include:: os-vol-pool-v3.inc

View File

@ -38,6 +38,24 @@ force_3:
in: path
required: false
type: boolean
group_id:
description: |
The ID of the group.
in: path
required: false
type: string
group_snapshot_id:
description: |
The ID of the group snapshot.
in: path
required: false
type: string
group_type_id:
description: |
The UUID for an existing group type.
in: path
required: false
type: string
hostname:
description: |
The name of the host that hosts the storage back
@ -227,7 +245,7 @@ absolute:
add_volumes:
description: |
One or more volume UUIDs, separated by commas, to
add to the volume consistency group.
add to the volume group or consistency group.
in: body
required: false
type: string
@ -398,6 +416,13 @@ created_at_1:
in: body
required: true
type: string
delete-volumes:
description: |
If set to ``true``, allows deletion of a
group as well as all volumes in the group.
in: body
required: false
type: boolean
description:
description: |
The backup description or null.
@ -422,6 +447,24 @@ description_11:
in: body
required: false
type: string
description_12:
description: |
The group type description.
in: body
required: false
type: string
description_13:
description: |
The group description.
in: body
required: false
type: string
description_14:
description: |
The group snapshot description.
in: body
required: false
type: string
description_2:
description: |
The description of the consistency group.
@ -550,6 +593,37 @@ free_capacity:
in: body
required: true
type: string
group_id_1:
description: |
The ID of the group.
in: body
required: false
type: string
group_snapshot_id_1:
description: |
The ID of the group snapshot.
in: body
required: false
type: string
group_specs:
description: |
A set of key and value pairs that contains the
specifications for a group type.
in: body
required: false
type: object
group_type:
description: |
A ``group_type`` object.
in: body
required: true
type: object
group_types:
description: |
The list of group types.
in: body
required: true
type: array
has_dependent_backups:
description: |
If this value is ``true``, the backup depends on
@ -688,6 +762,12 @@ is_public:
in: body
required: false
type: boolean
is_public_1:
description:
Group type which is accessible to the public.
in: body
required: false
type: boolean
key:
description: |
The metadata key name for the metadata that you
@ -928,6 +1008,24 @@ name_15:
in: body
required: false
type: string
name_16:
description: |
The group type name.
in: body
required: false
type: string
name_17:
description: |
The group name.
in: body
required: false
type: string
name_18:
description: |
The group snapshot name.
in: body
required: false
type: string
name_2:
description: |
The consistency group snapshot name.
@ -1200,7 +1298,7 @@ ref_1:
remove_volumes:
description: |
One or more volume UUIDs, separated by commas, to
remove from the volume consistency group.
remove from the volume group or consistency group.
in: body
required: false
type: string
@ -1297,6 +1395,12 @@ source_cgid:
in: body
required: false
type: string
source_group_id:
description: |
The UUID of the source group.
in: body
required: false
type: string
source_replica:
description: |
The UUID of the primary volume to clone.

View File

@ -0,0 +1,11 @@
{
"create-from-src": {
"name": "first_group",
"description": "first group",
"group_snapshot_id": "6f519a48-3183-46cf-a32f-41815f813986",
"source_group_id": None,
"user_id": "6f519a48-3183-46cf-a32f-41815f815555",
"project_id": "6f519a48-3183-46cf-a32f-41815f814444",
"status": "creating"
}
}

View File

@ -0,0 +1,12 @@
{
"group": {
"name": "first_group",
"description": "first group",
"group_type": "29514915-5208-46ab-9ece-1cc4688ad0c1",
"volume_types": [
"4e9e6d23-eed0-426d-b90a-28f87a94b6fe",
"c4daaf47-c530-4901-b28e-f5f0a359c4e6"
],
"availability_zone": "az0",
}
}

View File

@ -0,0 +1,6 @@
{
"group": {
"id": "6f519a48-3183-46cf-a32f-41815f816666",
"name": "first_group"
}
}

View File

@ -0,0 +1,5 @@
{
"delete": {
"delete-volumes": False
}
}

View File

@ -0,0 +1,16 @@
{
"group": {
"id": "6f519a48-3183-46cf-a32f-41815f813986",
"status": "available",
"availability_zone": "az1",
"created_at": "2015-09-16T09:28:52.000000",
"name": "first_group",
"description": "my first group",
"group_type": "29514915-5208-46ab-9ece-1cc4688ad0c1",
"volume_types": [
"c4daaf47-c530-4901-b28e-f5f0a359c4e6"
],
"group_snapshot_id": None,
"source_group_id": None
}
}

View File

@ -0,0 +1,7 @@
{
"group_snapshot": {
"group_id": "6f519a48-3183-46cf-a32f-41815f814546",
"name": "first_group_snapshot",
"description": "first group snapshot",
}
}

View File

@ -0,0 +1,6 @@
{
"group_snapshot": {
"id": "6f519a48-3183-46cf-a32f-41815f816666",
"name": "first_group_snapshot"
}
}

View File

@ -0,0 +1,20 @@
{
"group_snapshots": [
{
"id": "6f519a48-3183-46cf-a32f-41815f813986",
"group_id": "6f519a48-3183-46cf-a32f-41815f814444",
"status": "available",
"created_at": "2015-09-16T09:28:52.000000",
"name": "my_group_snapshot1",
"description": "my first group snapshot"
},
{
"id": "aed36625-a6d7-4681-ba59-c7ba3d18c148",
"group_id": "aed36625-a6d7-4681-ba59-c7ba3d18dddd",
"status": "error",
"created_at": "2015-09-16T09:31:15.000000",
"name": "my_group_snapshot2",
"description": "Edited description"
}
]
}

View File

@ -0,0 +1,12 @@
{
"group_snapshots": [
{
"id": "6f519a48-3183-46cf-a32f-41815f813986",
"name": "my_group_snapshot1"
},
{
"id": "aed36625-a6d7-4681-ba59-c7ba3d18c148",
"name": "my_group_snapshot2"
}
]
}

View File

@ -0,0 +1,10 @@
{
"group_snapshot": {
"id": "6f519a48-3183-46cf-a32f-41815f813986",
"group_id": "6f519a48-3183-46cf-a32f-41815f814444",
"status": "available",
"created_at": "2015-09-16T09:28:52.000000",
"name": "my_group_snapshot1",
"description": "my first group snapshot"
}
}

View File

@ -0,0 +1,10 @@
{
"group_type": {
"name": "grp-type-001",
"description": "group type 0001",
"is_public": True,
"group_specs": {
"consistent_group_snapshot_enabled": "<is> False"
}
}
}

View File

@ -0,0 +1,9 @@
{
"group_type": {
"id": "289da7f8-6440-407c-9fb4-7db01ec49164",
"name": "grp-type-001",
"group_specs": {
"consistent_group_snapshot_enabled": "<is> False"
}
}
}

View File

@ -0,0 +1,11 @@
{
"group_type": {
"id": "6685584b-1eac-4da6-b5c3-555430cf68ff",
"name": "grp-type-001",
"description": "group type 001",
"is_public": "true",
"group_specs": {
"consistent_group_snapshot_enabled": "<is> False"
}
}
}

View File

@ -0,0 +1,6 @@
{
"group_specs": {
"key1": "value1",
"key2": "value2",
}
}

View File

@ -0,0 +1,7 @@
{
"group_type": {
"name": "grp-type-001",
"description": "group type 0001",
"is_public": true,
}
}

View File

@ -0,0 +1,16 @@
{
"group_types": [
{
"group_specs": {
"consistent_group_snapshot_enabled": "<is> False"
},
"id": "6685584b-1eac-4da6-b5c3-555430cf68ff",
"name": "group_type1"
},
{
"group_specs": {},
"id": "8eb69a46-df97-4e41-9586-9a40a7533803",
"name": "group_type2"
}
]
}

View File

@ -0,0 +1,8 @@
{
"group": {
"name": "my_group",
"description": "My group",
"add_volumes": "volume-uuid-1,volume-uuid-2",
"remove_volumes": "volume-uuid-8,volume-uuid-9"
}
}

View File

@ -0,0 +1,29 @@
{
"groups": [
{
"id": "6f519a48-3183-46cf-a32f-41815f813986",
"status": "available",
"availability_zone": "az1",
"created_at": "2015-09-16T09:28:52.000000",
"name": "my_group1",
"description": "my first group",
"group_type": "29514915-5208-46ab-9ece-1cc4688ad0c1",
"volume_types": [
"4e9e6d23-eed0-426d-b90a-28f87a94b6fe",
"a3d55d15-eeb1-4816-ada9-bf82decc09b3"
]
},
{
"id": "aed36625-a6d7-4681-ba59-c7ba3d18c148",
"status": "error",
"availability_zone": "az2",
"created_at": "2015-09-16T09:31:15.000000",
"name": "my_group2",
"description": "Edited description",
"group_type": "f8645498-1323-47a2-9442-5c57724d2e3c",
"volume_types": [
"c4daaf47-c530-4901-b28e-f5f0a359c4e6"
]
}
]
}

View File

@ -0,0 +1,12 @@
{
"groups": [
{
"id": "6f519a48-3183-46cf-a32f-41815f813986",
"name": "my_group1"
},
{
"id": "aed36625-a6d7-4681-ba59-c7ba3d18c148",
"name": "my_group2"
}
]
}

View File

@ -0,0 +1,44 @@
{
"choices": [
{
"status": "SUPPORTED",
"media-types": [
{
"base": "application/xml",
"type": "application/vnd.openstack.volume+xml;version=1"
},
{
"base": "application/json",
"type": "application/vnd.openstack.volume+json;version=1"
}
],
"id": "v1.0",
"links": [
{
"href": "http://23.253.248.171:8776/v1/v2.json",
"rel": "self"
}
]
},
{
"status": "CURRENT",
"media-types": [
{
"base": "application/xml",
"type": "application/vnd.openstack.volume+xml;version=1"
},
{
"base": "application/json",
"type": "application/vnd.openstack.volume+json;version=1"
}
],
"id": "v2.0",
"links": [
{
"href": "http://23.253.248.171:8776/v2/v2.json",
"rel": "self"
}
]
}
]
}