openstack/manila
Code Issues Proposed changes

Add API document for share group [2/3]

Browse Source 
This patch adds a new API document for share group

Partial-Bug: 1724716
Change-Id: I852d264eb120027aad32997dc64a6ca128ee55a3
This commit is contained in:
zhongjun 2017-10-31 19:57:42 +08:00 committed by zhongjun
parent 84d284b1e3
commit 3da1c7d4fb
10 changed files with 437 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
api-ref/source/index.rst
View File

@ -37,4 +37,5 @@ Shared File Systems API (EXPERIMENTAL)
.. include:: experimental.inc
.. include:: share-migration.inc
.. include:: share-replicas.inc
.. include:: share-groups.inc
.. include:: share-group-types.inc

16
api-ref/source/parameters.yaml
View File

@ -32,6 +32,12 @@ security_service_id_path:
in: path
required: false
type: string
share_group_id_path:
description: |
The UUID of the share group.
in: path
required: true
type: string
share_group_type_id_path:
description: |
The UUID of the share group type.
@ -715,7 +721,7 @@ availability_zone_id_2:
description: |
The availability zone ID for create share group.
in: body
required: false
required: true
type: string
min_version: 2.34
availability_zone_name:
@ -931,7 +937,7 @@ consistent_snapshot_support:
description: |
The consistency snapshot support.
in: body
required: false
required: true
type: string
min_version: 2.34
created_at_11:
@ -2617,6 +2623,12 @@ share_group_description_response:
in: body
required: true
type: string
share_group_host:
description: |
The share group host name.
in: body
required: false
type: string
share_group_id:
description: |
The UUID of the share group.

11
api-ref/source/samples/share-group-create-request.json Normal file
View File

@ -0,0 +1,11 @@
{
"share_group": {
"share_types": ["ecd11f4c-d811-4471-b656-c755c77e02ba"],
"name": "my_group",
"description": "for_test",
"share_group_type_id": "89861c2a-10bf-4013-bdd4-3d020466aee4",
"availability_zone": "nova",
"share_network_id": "82168c2a-10bf-4013-bcc4-3d984136aee3",,
"source_share_group_snapshot_id": "69861c2a-10bf-4013-bcc4-3d020466aee3",
}
}

28
api-ref/source/samples/share-group-create-response.json Normal file
View File

@ -0,0 +1,28 @@
{
"share_groups": {
"status": "creating",
"description": null,
"links": [
{
"href": "http://192.168.98.191:8786/v2/e23850eeb91d4fa3866af634223e454c/share_groups/f9c1f80c-2392-4e34-bd90-fc89cdc5bf93",
"rel": "self"
},
{
"href": "http://192.168.98.191:8786/e23850eeb91d4fa3866af634223e454c/share_groups/f9c1f80c-2392-4e34-bd90-fc89cdc5bf93",
"rel": "bookmark"
}
],
"availability_zone": null,
"source_share_group_snapshot_id": null,
"share_network_id": null,
"share_server_id": null,
"host": null,
"share_group_type_id": "89861c2a-10bf-4013-bdd4-3d020466aee4",
"consistent_snapshot_support": null,
"id": "f9c1f80c-2392-4e34-bd90-fc89cdc5bf93",
"name": null,
"created_at": "2017-08-03T19:20:33.974421",
"project_id": "e23850eeb91d4fa3866af634223e454c",
"share_types": ["ecd11f4c-d811-4471-b656-c755c77e02ba"]
}
}

5
api-ref/source/samples/share-group-reset-state-request.json Normal file
View File

@ -0,0 +1,5 @@
{
"reset_status": {
"status": "error"
}
}

27
api-ref/source/samples/share-group-show-response.json Normal file
View File

@ -0,0 +1,27 @@
{
"share_groups": {
"links": [
{
"href": "http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/share_groups/011d21e2-fbc3-4e4a-9993-9ea223f73264",
"rel": "self"
},
{
"href": "http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/share_groups/011d21e2-fbc3-4e4a-9993-9ea223f73264",
"rel": "bookmark"
}
],
"availability_zone": "nova",
"consistent_snapshot_support": true,
"share_group_type_id": "313df749-aac0-1a54-af52-10f6c991e80c"
"share_network_id": "713df749-aac0-4a54-af52-10f6c991e80c",
"id": "011d21e2-fbc3-4e4a-9993-9ea223f73264",
"share_types": ["25747776-08e5-494f-ab40-a64b9d20d8f7", ],
"project_id": "16e1ab15c35a457e9c2b2aa189f544e1",
"status": "available",
"description": "My custom share London",
"host": "manila2@generic1#GENERIC1",
"source_share_group_snapshot_id": null
"name": "share_London",
"created_at": "2015-09-18T10:25:24.000000",
}
}

6
api-ref/source/samples/share-group-update-request.json Normal file
View File

@ -0,0 +1,6 @@
{
"share_group": {
"name": "new name",
"description": "Changing the share group description."
}
}

28
api-ref/source/samples/share-group-update-response.json Normal file
View File

@ -0,0 +1,28 @@
{
"share_groups": {
"status": "creating",
"description": "Changing the share group description.",
"links": [
{
"href": "http://192.168.98.191:8786/v2/e23850eeb91d4fa3866af634223e454c/share_groups/f9c1f80c-2392-4e34-bd90-fc89cdc5bf93",
"rel": "self"
},
{
"href": "http://192.168.98.191:8786/e23850eeb91d4fa3866af634223e454c/share_groups/f9c1f80c-2392-4e34-bd90-fc89cdc5bf93",
"rel": "bookmark"
}
],
"availability_zone": null,
"source_share_group_snapshot_id": null,
"share_network_id": null,
"share_server_id": null,
"host": null,
"share_group_type_id": "89861c2a-10bf-4013-bdd4-3d020466aee4",
"consistent_snapshot_support": null,
"id": "f9c1f80c-2392-4e34-bd90-fc89cdc5bf93",
"name": "new name",
"created_at": "2017-08-03T19:20:33.974421",
"project_id": "e23850eeb91d4fa3866af634223e454c",
"share_types": ["ecd11f4c-d811-4471-b656-c755c77e02ba"]
}
}

32
api-ref/source/samples/share-groups-list-response.json Normal file
View File

@ -0,0 +1,32 @@
{
"share_groups": [
{
"id": "b94a8548-2079-4be0-b21c-0a887acd31ca",
"links": [
{
"href": "http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/share_groups/b94a8548-2079-4be0-b21c-0a887acd31ca",
"rel": "self"
},
{
"href": "http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/share_groups/b94a8548-2079-4be0-b21c-0a887acd31ca",
"rel": "bookmark"
}
],
"name": "My_share_group"
},
{
"id": "306ea93c-32e9-4907-a117-148b3945749f",
"links": [
{
"href": "http://172.18.198.54:8786/v2/16e1ab15c35a457e9c2b2aa189f544e1/share_groups/306ea93c-32e9-4907-a117-148b3945749f",
"rel": "self"
},
{
"href": "http://172.18.198.54:8786/16e1ab15c35a457e9c2b2aa189f544e1/share_groups/306ea93c-32e9-4907-a117-148b3945749f",
"rel": "bookmark"
}
],
"name": "Test_Share_group"
}
]
}

285
api-ref/source/share-groups.inc Normal file
View File

@ -0,0 +1,285 @@
.. -*- rst -*-
==============================
Share groups (since API v2.31)
==============================
The share groups enable you to create a group of volumes and manage them
together. A project can put shares be used in the same application together
in a share group, such as consistency group snapshot, clone, backup, migrate,
replicate, retype, etc.
Shares should be able to become a part of a share group only on share creation
step. If share was created without provided ``share_group_id`` then this share
won't be able to become a part of any share group.
You can create a share group and associate it with multiple shares, list
share groups, and show information for delete a share group.
.. note::
Share Group APIs are part of the `experimental APIs
<http://developer.openstack.org/api-ref/shared-file-systems/#experimental-apis>`_.
The ``availability_zone_id`` and ``consistent_snapshot_support`` fields were added
to ``share_group`` object introduced in version 2.34.
List share groups
=================
.. rest_method:: GET /v2/{tenant_id}/share_groups
Lists all share groups.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- project_id: project_id
- all_tenants: all_tenants
- name: name_query
- description: description_query
- status: share_group_status_query
- share_server_id: share_server_id_query
- snapshot_id: snapshot_id_query
- host: backend_host_query
- share_network_id: share_network_id_query
- share_group_type_id: share_group_type_id_query
- limit: limit_query
- offset: offset
- sort_key: sort_key
- sort_dir: sort_dir
- name~: name_inexact_query
- description~: description_inexact_query
Response parameters
-------------------
.. rest_parameters:: parameters.yaml
- id: share_group_id
- links: share_group_links
- name: share_group_name_response
- status: share_group_status
- description: share_group_description_response
Response example
----------------
.. literalinclude:: samples/share-groups-list-response.json
:language: javascript
Show share group details
========================
.. rest_method:: GET /v2/{tenant_id}/share_groups/{share_group_id}
Shows details for a share group.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- share_group_id: share_group_id_path
- tenant_id: tenant_id
Response parameters
-------------------
.. rest_parameters:: parameters.yaml
- id: share_group_id
- name: share_group_name_response
- created_at: share_group_created_at
- status: share_group_status
- description: share_group_description_response
- project_id: project_id
- host: backend_host
- share_group_type_id: share_group_type_id_required
- source_share_group_snapshot_id: source_share_group_snapshot_id_response
- share_network_id: share_network_id
- share_types: share_types_1
- links: share_group_links
- availability_zone: availability_zone_id_2
- consistent_snapshot_support: consistent_snapshot_support
Response example
----------------
.. literalinclude:: samples/share-group-show-response.json
:language: javascript
Create share group
==================
.. rest_method:: POST /v2/{tenant_id}/share_groups
Creates a share group.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404), conflict(409), unprocessableEntity(422)
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id_path
- name: share_group_name
- description: share_group_description
- share_types: share_types
- share_group_type: share_group_type_id
- share_network: share_network_id_1
- source_share_group_snapshot: source_share_group_snapshot_id
- availability_zone: availability_zone_id_2
Request example
---------------
.. literalinclude:: samples/share-group-create-request.json
:language: javascript
Response parameters
-------------------
.. rest_parameters:: parameters.yaml
- id: share_group_id
- name: share_group_name_response
- created_at: share_group_created_at
- status: share_group_status
- description: share_group_description_response
- project_id: project_id
- host: share_group_host
- share_group_type_id: share_group_type_id_required
- source_share_group_snapshot_id: source_share_group_snapshot_id_response
- share_network_id: share_network_id
- share_types: share_types_1
- links: share_group_links
- availability_zone: availability_zone_id_2
- consistent_snapshot_support: consistent_snapshot_support
Response example
----------------
.. literalinclude:: samples/share-group-create-response.json
:language: javascript
Reset share group state
=======================
.. rest_method:: POST /v2/{tenant_id}/share-groups/{share_group_id}/action
Administrator only. Explicitly updates the state of a share group.
Use the ``policy.json`` file to grant permissions for this action
to other roles.
Normal response codes: 202
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- reset_status: reset_status
- status: share_group_status
- share_group_id: share_group_id_path
- tenant_id: tenant_id_path
Request example
---------------
.. literalinclude:: samples/share-group-reset-state-request.json
:language: javascript
Update share group
==================
.. rest_method:: PUT /v2/{tenant_id}/share-groups/{share_group_id}
Updates a share group.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404), unprocessableEntity(422)
Request
-------
.. rest_parameters:: parameters.yaml
- display_name: share_group_name
- display_description: share_group_description
- share_group_id: share_group_id_path
- tenant_id: tenant_id_path
Request example
---------------
.. literalinclude:: samples/share-group-update-request.json
:language: javascript
Response parameters
-------------------
.. rest_parameters:: parameters.yaml
- id: share_group_id
- name: share_group_name_response
- created_at: share_group_created_at
- status: share_group_status
- description: share_group_description_response
- project_id: project_id
- host: share_group_host
- share_group_type_id: share_group_type_id_required
- source_share_group_snapshot_id: source_share_group_snapshot_id
- share_network_id: share_network_id
- share_types: share_types_1
- links: share_group_links
- availability_zone: availability_zone_id_2
- consistent_snapshot_support: consistent_snapshot_support
Response example
----------------
.. literalinclude:: samples/share-group-update-response.json
:language: javascript
Delete share group
==================
.. rest_method:: DELETE /v2/{tenant_id}/share-groups/{share_group_id}
Deletes a share group.
Normal response codes: 202
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404), conflict(409)
Request
-------
.. rest_parameters:: parameters.yaml
- share_group_id: share_group_id_path
- tenant_id: tenant_id_path
- force: share_force_delete