From 3da1c7d4fbaae01a325854262a9ccc3789bbbc8f Mon Sep 17 00:00:00 2001 From: zhongjun Date: Tue, 31 Oct 2017 19:57:42 +0800 Subject: [PATCH] Add API document for share group [2/3] This patch adds a new API document for share group Partial-Bug: 1724716 Change-Id: I852d264eb120027aad32997dc64a6ca128ee55a3 --- api-ref/source/index.rst | 1 + api-ref/source/parameters.yaml | 16 +- .../samples/share-group-create-request.json | 11 + .../samples/share-group-create-response.json | 28 ++ .../share-group-reset-state-request.json | 5 + .../samples/share-group-show-response.json | 27 ++ .../samples/share-group-update-request.json | 6 + .../samples/share-group-update-response.json | 28 ++ .../samples/share-groups-list-response.json | 32 ++ api-ref/source/share-groups.inc | 285 ++++++++++++++++++ 10 files changed, 437 insertions(+), 2 deletions(-) create mode 100644 api-ref/source/samples/share-group-create-request.json create mode 100644 api-ref/source/samples/share-group-create-response.json create mode 100644 api-ref/source/samples/share-group-reset-state-request.json create mode 100644 api-ref/source/samples/share-group-show-response.json create mode 100644 api-ref/source/samples/share-group-update-request.json create mode 100644 api-ref/source/samples/share-group-update-response.json create mode 100644 api-ref/source/samples/share-groups-list-response.json create mode 100644 api-ref/source/share-groups.inc diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst index 2d99711544..8cd753f09e 100644 --- a/api-ref/source/index.rst +++ b/api-ref/source/index.rst @@ -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 diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index ceca13433a..7bb47d385d 100644 --- a/api-ref/source/parameters.yaml +++ b/api-ref/source/parameters.yaml @@ -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. diff --git a/api-ref/source/samples/share-group-create-request.json b/api-ref/source/samples/share-group-create-request.json new file mode 100644 index 0000000000..de9f2b5ac3 --- /dev/null +++ b/api-ref/source/samples/share-group-create-request.json @@ -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", + } +} diff --git a/api-ref/source/samples/share-group-create-response.json b/api-ref/source/samples/share-group-create-response.json new file mode 100644 index 0000000000..fb5de7c7d9 --- /dev/null +++ b/api-ref/source/samples/share-group-create-response.json @@ -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"] + } +} diff --git a/api-ref/source/samples/share-group-reset-state-request.json b/api-ref/source/samples/share-group-reset-state-request.json new file mode 100644 index 0000000000..e5f70b3722 --- /dev/null +++ b/api-ref/source/samples/share-group-reset-state-request.json @@ -0,0 +1,5 @@ +{ + "reset_status": { + "status": "error" + } +} diff --git a/api-ref/source/samples/share-group-show-response.json b/api-ref/source/samples/share-group-show-response.json new file mode 100644 index 0000000000..71eb1b2e86 --- /dev/null +++ b/api-ref/source/samples/share-group-show-response.json @@ -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", + } +} diff --git a/api-ref/source/samples/share-group-update-request.json b/api-ref/source/samples/share-group-update-request.json new file mode 100644 index 0000000000..880d72c35c --- /dev/null +++ b/api-ref/source/samples/share-group-update-request.json @@ -0,0 +1,6 @@ +{ + "share_group": { + "name": "new name", + "description": "Changing the share group description." + } +} diff --git a/api-ref/source/samples/share-group-update-response.json b/api-ref/source/samples/share-group-update-response.json new file mode 100644 index 0000000000..f80b8b7add --- /dev/null +++ b/api-ref/source/samples/share-group-update-response.json @@ -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"] + } +} diff --git a/api-ref/source/samples/share-groups-list-response.json b/api-ref/source/samples/share-groups-list-response.json new file mode 100644 index 0000000000..e0f462c00b --- /dev/null +++ b/api-ref/source/samples/share-groups-list-response.json @@ -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" + } + ] +} diff --git a/api-ref/source/share-groups.inc b/api-ref/source/share-groups.inc new file mode 100644 index 0000000000..a57181c194 --- /dev/null +++ b/api-ref/source/share-groups.inc @@ -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 + `_. + 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