From 9f2f05ffc4757b144efa21a1b1b72ae0d822d991 Mon Sep 17 00:00:00 2001 From: zhongjun Date: Fri, 4 Aug 2017 10:47:27 +0800 Subject: [PATCH] Add API document for share group [1/3] This patch adds a new API document for share group type. Partial-Bug: 1724716 Change-Id: I852d264eb120027aad32997dc64a6ca428ee55a4 --- api-ref/source/index.rst | 1 + api-ref/source/parameters.yaml | 329 +++++++++++++++- .../share-group-type-create-request.json | 10 + .../share-group-type-create-response.json | 9 + ...share-group-type-grant-access-request.json | 5 + ...hare-group-type-revoke-access-request.json | 5 + .../samples/share-group-type-set-request.json | 5 + .../share-group-type-set-response.json | 5 + ...are-group-types-default-list-response.json | 9 + ...group-types-group-specs-list-response.json | 5 + ...hare-group-types-list-access-response.json | 12 + .../share-group-types-list-response.json | 11 + api-ref/source/share-group-types.inc | 358 ++++++++++++++++++ 13 files changed, 757 insertions(+), 7 deletions(-) create mode 100644 api-ref/source/samples/share-group-type-create-request.json create mode 100644 api-ref/source/samples/share-group-type-create-response.json create mode 100644 api-ref/source/samples/share-group-type-grant-access-request.json create mode 100644 api-ref/source/samples/share-group-type-revoke-access-request.json create mode 100644 api-ref/source/samples/share-group-type-set-request.json create mode 100644 api-ref/source/samples/share-group-type-set-response.json create mode 100644 api-ref/source/samples/share-group-types-default-list-response.json create mode 100644 api-ref/source/samples/share-group-types-group-specs-list-response.json create mode 100644 api-ref/source/samples/share-group-types-list-access-response.json create mode 100644 api-ref/source/samples/share-group-types-list-response.json create mode 100644 api-ref/source/share-group-types.inc diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst index bcd5a38305..2d99711544 100644 --- a/api-ref/source/index.rst +++ b/api-ref/source/index.rst @@ -37,3 +37,4 @@ Shared File Systems API (EXPERIMENTAL) .. include:: experimental.inc .. include:: share-migration.inc .. include:: share-replicas.inc +.. include:: share-group-types.inc diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index ef11a20725..ceca13433a 100644 --- a/api-ref/source/parameters.yaml +++ b/api-ref/source/parameters.yaml @@ -14,6 +14,12 @@ export_location_id_path: in: path required: false type: string +group_snapshot_id_path: + description: | + The group snapshot ID. + in: path + required: true + type: string message_id: description: | The UUID of the message. @@ -26,6 +32,12 @@ security_service_id_path: in: path required: false type: string +share_group_type_id_path: + description: | + The UUID of the share group type. + in: path + required: true + type: string share_id: description: | The UUID of the share. @@ -114,9 +126,9 @@ action_id: The ID of the action during which the message was created. all_tenants: description: | - (Admin only). Defines whether to list shares for - all tenants. Set to ``1`` to list shares for all tenants. Set to - ``0`` to list shares only for the current tenant. + (Admin only). Defines whether to list shares or share groups for + all tenants. Set to ``1`` to list shares or sharegroups for all tenants. + Set to ``0`` to list shares or share groups only for the current tenant. in: query required: false type: boolean @@ -159,6 +171,13 @@ description_inexact_query: required: false type: string min_version: 2.36 +description_query: + description: | + The share group description that can be used to filter + share groups. + in: query + required: false + type: string detail_id: in: query required: false @@ -190,6 +209,28 @@ extra_specs_1: in: query required: false type: string +group_snapshot_description_query: + description: | + The share group snapshot description that can be used to filter + share group snapshots. + in: query + required: false + type: string +group_snapshot_name_query: + description: | + The share group snapshot name that can be used to filter + share group snapshots. + in: query + required: false + type: string +group_snapshot_status_query: + description: | + Filters by a share group snapshot status. A valid value is + ``creating``, ``error``, ``available``, ``deleting``, + ``error_deleting``. + in: query + required: false + type: string host_11: description: | The host name for the back end. @@ -214,6 +255,12 @@ limit: in: query required: false type: integer +limit_query: + description: | + The maximum number of share groups members to return. + in: query + required: false + type: integer media_types: description: | Media types supported by the API. @@ -247,9 +294,15 @@ name_inexact_query: required: false type: string min_version: 2.36 +name_query: + description: | + The share group name that can be used to filter share groups. + in: query + required: false + type: string offset: description: | - The offset to define start point of share + The offset to define start point of share or share group listing. in: query required: false @@ -325,13 +378,33 @@ share_group_id_query: required: false type: string min_version: 2.31 +share_group_status_query: + description: | + Filters by a share group status. A valid value is + ``creating``, ``error``, ``available``, ``deleting``, + ``error_deleting``. + in: query + required: false + type: string +share_group_type_id_query: + description: | + The share group type ID to filter share groups. + in: query + required: false + type: string share_network_id_5: description: | The UUID of the share network. in: query required: false type: string -share_server_id_2: +share_network_id_query: + description: | + The UUID of the share network. + in: query + required: false + type: string +share_server_id_query: description: | The UUID of the share server. in: query @@ -350,6 +423,12 @@ share_type_query: in: query required: false type: string +share_types_query: + description: | + A list of one or more share type IDs. Allows filtering share groups. + in: query + required: false + type: array snapshot_id_query: description: | The UUID of the share's base snapshot to filter the request based on. @@ -390,6 +469,14 @@ sort_key_messages: in: query required: false type: string +source_share_group_snapshot_id_query: + description: | + The source share group snapshot ID to list the + share group. + in: query + required: false + type: string + min_version: 2.31 state_2: description: | The current state of the service. A valid value @@ -624,6 +711,13 @@ availability_zone_id: in: body required: true type: string +availability_zone_id_2: + description: | + The availability zone ID for create share group. + in: body + required: false + type: string + min_version: 2.34 availability_zone_name: description: | The name of the availability zone. @@ -833,6 +927,13 @@ cidr_1: in: body required: true type: string +consistent_snapshot_support: + description: | + The consistency snapshot support. + in: body + required: false + type: string + min_version: 2.34 created_at_11: description: | The date and time stamp when the share server was created. @@ -1285,6 +1386,92 @@ free_capacity_gb: in: body required: true type: string +group_snapshot_created_at: + description: | + The date and time stamp when the share group snapshot was created. + + The date and time stamp format is `ISO 8601 + `_: + + :: + + CCYY-MM-DDThh:mm:ss±hh:mm + + The ``±hh:mm`` value, if included, returns the time zone as an + offset from UTC. + + For example, ``2015-08-27T09:49:58-05:00``. + in: body + required: true + type: string +group_snapshot_description: + description: | + The share group snapshot description. + in: body + required: true + type: string +group_snapshot_description_option: + description: | + The share group snapshot description. + in: body + required: false + type: string +group_snapshot_id: + description: | + The share group snapshot ID. + in: body + required: true + type: object +group_snapshot_links: + description: | + The share group snapshot links. + in: body + required: true + type: string +group_snapshot_members: + description: | + The share group snapshot members. + in: body + required: true + type: string +group_snapshot_name: + description: | + The share group snapshot name. + in: body + required: true + type: string +group_snapshot_name_option: + description: | + The share group snapshot name. + in: body + required: false + type: string +group_snapshot_status_required: + description: | + Filters by a share group snapshot status. A valid value is + ``creating``, ``error``, ``available``, ``deleting``, + ``error_deleting``. + in: body + required: true + type: string +group_spec_key: + description: | + The extra specification key for the share group type. + in: body + required: true + type: string +group_specs: + description: | + The extra specifications for the share group type. + in: body + required: false + type: object +group_specs_required: + description: | + The extra specifications for the share group type. + in: body + required: true + type: object has_replicas: description: | (Since API v2.11) Indicates whether a share has @@ -2393,9 +2580,40 @@ share_backend_name: type: string share_force_delete: description: | - To force-delete a share, set this value to + To force-delete a share or share group, set this value to ``null``. The force-delete action, unlike the delete action, - ignores the share status. + ignores the share or share group status. + in: body + required: true + type: string +share_group_created_at: + description: | + The date and time stamp when the share group was + created. + + The date and time stamp format is `ISO 8601 + `_: + + :: + + CCYY-MM-DDThh:mm:ss±hh:mm + + The ``±hh:mm`` value, if included, returns the time zone as an + offset from UTC. + + For example, ``2016-12-31T13:14:15-05:00``. + in: body + required: true + type: string +share_group_description: + description: | + The share group description. + in: body + required: false + type: string +share_group_description_response: + description: | + The share group description. in: body required: true type: string @@ -2413,6 +2631,65 @@ share_group_id_request: required: False type: string min_version: 2.31 +share_group_links: + description: | + The share group links. + in: body + required: true + type: string +share_group_name: + description: | + The share group name. + in: body + required: false + type: string +share_group_name_response: + description: | + The share group name. + in: body + required: true + type: string +share_group_status: + description: | + The share group status, which is ``available``, + ``error``, ``creating``, or ``deleting``. + in: body + required: true + type: string +share_group_type_id: + description: | + The share group type ID to create a share group. + in: body + required: false + type: string +share_group_type_id_required: + description: | + The share group type ID. + in: body + required: true + type: string +share_group_type_is_public: + description: | + The level of visibility for the share group type. Set to + ``true`` to make share group type public. Set to ``false`` to + make it private. Default value is ``false``. + in: body + required: true + type: boolean +share_group_type_is_public_request: + description: | + The level of visibility for the share group type. Set to + ``true`` to make share group type public. Set to ``false`` to + make it private. Default value is ``false``. + in: body + required: false + type: boolean +share_group_type_name: + description: | + The share group type name. + in: body + required: true + type: string share_id_2: description: | The UUID of the share from which the share @@ -2992,6 +3269,20 @@ snapshot_unmanage: in: body required: true type: string +source_share_group_snapshot_id: + description: | + The source share group snapshot ID to create the + share group. + in: body + required: false + type: string +source_share_group_snapshot_id_response: + description: | + The source share group snapshot ID to create the + share group. + in: body + required: true + type: string state: description: | Prior to versions 2.28, the state of all access rules of a given share @@ -3011,6 +3302,30 @@ state_1: in: body required: true type: string +status: + description: | + The consistency group snapshot status, which is + ``available``, ``creating``, ``error``, ``deleting``, or + ``error_deleting``. + in: body + required: true + type: string +status_1: + description: | + The consistency group status. A valid value is + ``creating``, ``available``, ``error``, ``deleting``, or + ``error_deleting``. + in: body + required: true + type: string +status_10: + description: | + The consistency group status. A valid value is + ``creating``, ``error``, ``available``, ``deleting``, or + ``error_deleting``. + in: body + required: true + type: string status_15: description: | The share server status, which is ``active``, diff --git a/api-ref/source/samples/share-group-type-create-request.json b/api-ref/source/samples/share-group-type-create-request.json new file mode 100644 index 0000000000..450118ecc4 --- /dev/null +++ b/api-ref/source/samples/share-group-type-create-request.json @@ -0,0 +1,10 @@ +{ + "share_group_type": { + "is_public": true, + "group_specs": { + "snapshot_support": true + }, + "share_types": ["ecd11f4c-d811-4471-b656-c755c77e02ba"], + "name": "my_new_group_type" + } +} diff --git a/api-ref/source/samples/share-group-type-create-response.json b/api-ref/source/samples/share-group-type-create-response.json new file mode 100644 index 0000000000..a4b8464aaf --- /dev/null +++ b/api-ref/source/samples/share-group-type-create-response.json @@ -0,0 +1,9 @@ +{ + "share_group_type": { + "is_public": true, + "group_specs": {}, + "share_types": ["ecd11f4c-d811-4471-b656-c755c77e02ba"], + "id": "89861c2a-10bf-4013-bdd4-3d020466aee4", + "name": "test_group_type" + } +} diff --git a/api-ref/source/samples/share-group-type-grant-access-request.json b/api-ref/source/samples/share-group-type-grant-access-request.json new file mode 100644 index 0000000000..952cf49632 --- /dev/null +++ b/api-ref/source/samples/share-group-type-grant-access-request.json @@ -0,0 +1,5 @@ +{ + "addProjectAccess": { + "project": "e1284adea3ee4d2482af5ed214f3ad90" + } +} diff --git a/api-ref/source/samples/share-group-type-revoke-access-request.json b/api-ref/source/samples/share-group-type-revoke-access-request.json new file mode 100644 index 0000000000..bdc492dd4f --- /dev/null +++ b/api-ref/source/samples/share-group-type-revoke-access-request.json @@ -0,0 +1,5 @@ +{ + "removeProjectAccess": { + "project": "818a3f48dcd644909b3fa2e45a399a27" + } +} diff --git a/api-ref/source/samples/share-group-type-set-request.json b/api-ref/source/samples/share-group-type-set-request.json new file mode 100644 index 0000000000..8c5820c7cd --- /dev/null +++ b/api-ref/source/samples/share-group-type-set-request.json @@ -0,0 +1,5 @@ +{ + "group_specs": { + "my_group_key": "my_group_value" + } +} diff --git a/api-ref/source/samples/share-group-type-set-response.json b/api-ref/source/samples/share-group-type-set-response.json new file mode 100644 index 0000000000..8c5820c7cd --- /dev/null +++ b/api-ref/source/samples/share-group-type-set-response.json @@ -0,0 +1,5 @@ +{ + "group_specs": { + "my_group_key": "my_group_value" + } +} diff --git a/api-ref/source/samples/share-group-types-default-list-response.json b/api-ref/source/samples/share-group-types-default-list-response.json new file mode 100644 index 0000000000..a4b8464aaf --- /dev/null +++ b/api-ref/source/samples/share-group-types-default-list-response.json @@ -0,0 +1,9 @@ +{ + "share_group_type": { + "is_public": true, + "group_specs": {}, + "share_types": ["ecd11f4c-d811-4471-b656-c755c77e02ba"], + "id": "89861c2a-10bf-4013-bdd4-3d020466aee4", + "name": "test_group_type" + } +} diff --git a/api-ref/source/samples/share-group-types-group-specs-list-response.json b/api-ref/source/samples/share-group-types-group-specs-list-response.json new file mode 100644 index 0000000000..fe575c6499 --- /dev/null +++ b/api-ref/source/samples/share-group-types-group-specs-list-response.json @@ -0,0 +1,5 @@ +{ + "group_specs": { + "snapshot_support": "True", + } +} diff --git a/api-ref/source/samples/share-group-types-list-access-response.json b/api-ref/source/samples/share-group-types-list-access-response.json new file mode 100644 index 0000000000..1ea8a168e0 --- /dev/null +++ b/api-ref/source/samples/share-group-types-list-access-response.json @@ -0,0 +1,12 @@ +{ + "share_group_type_access": [ + { + "share_group_type_id": "1732f284-401d-41d9-a494-425451e8b4b8", + "project_id": "818a3f48dcd644909b3fa2e45a399a27" + }, + { + "share_group_type_id": "1732f284-401d-41d9-a494-425451e8b4b8", + "project_id": "e1284adea3ee4d2482af5ed214f3ad90" + } + ] +} diff --git a/api-ref/source/samples/share-group-types-list-response.json b/api-ref/source/samples/share-group-types-list-response.json new file mode 100644 index 0000000000..7a6d489536 --- /dev/null +++ b/api-ref/source/samples/share-group-types-list-response.json @@ -0,0 +1,11 @@ +{ + "share_group_types": [ + { + "is_public": true, + "group_specs": {}, + "share_types": ["ecd11f4c-d811-4471-b656-c755c77e02ba"], + "id": "89861c2a-10bf-4013-bdd4-3d020466aee4", + "name": "test_group_type" + } + ] +} diff --git a/api-ref/source/share-group-types.inc b/api-ref/source/share-group-types.inc new file mode 100644 index 0000000000..bb20120150 --- /dev/null +++ b/api-ref/source/share-group-types.inc @@ -0,0 +1,358 @@ +.. -*- rst -*- + +=================================== +Share group types (since API v2.31) +=================================== + +A share group type enables you to filter or choose back ends before you +create a share group. + +You can set share group types as either public or private. By default a +share group type is created as publicly accessible. Set +``share_group_type_access:is_public`` to ``False`` to make the share group +type private. + +You can manage the access to the private share group types for the +different projects. You can add access, remove access, and get +information about access for a private share group type. + +Administrators can specifies which `share type(s) +`_ +a given group type may contain. If Administrators does not specify it, then +manila will use ``default`` share type. The scheduler then creates the group on +one of the back ends that match the specified share type(s) and share group type. + +Administrators can also set additional group extra specifications for a +share group type for the following purposes: + +- Filter back ends by group scheduler. Specify these group extras specifications + in this format: ``group_specs=value``. For example, + ``consistent_snapshot_support=true``. + +.. note:: + + Share Group Types APIs are part of the `experimental APIs + `_. + +List share group types +====================== + +.. rest_method:: GET /v2/{tenant_id}/share-group-types + +Lists all share group types. + +Normal response codes: 200 + +Request +------- + +.. rest_parameters:: parameters.yaml + + - tenant_id: tenant_id_path + +Response parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - id: share_group_type_id_required + - is_public: share_group_type_is_public + - share_types: share_types_1 + - name: share_group_type_name + - group_specs: group_specs_required + +Response example +---------------- + +.. literalinclude:: samples/share-group-types-list-response.json + :language: javascript + + +List default share group types +============================== + +.. rest_method:: GET /v2/{tenant_id}/share-group-types/default + +Lists default share group types. + +Normal response codes: 200 +Error response codes: badRequest(400), unauthorized(401), forbidden(403), +itemNotFound(404) + +Request +------- + +.. rest_parameters:: parameters.yaml + + - tenant_id: tenant_id_path + +Response parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - id: share_group_type_id_required + - is_public: share_group_type_is_public + - share_types: share_types_1 + - name: share_group_type_name + - group_specs: group_specs_required + +Response example +---------------- + +.. literalinclude:: samples/share-group-types-default-list-response.json + :language: javascript + + +List share group types extra specs +================================== + +.. rest_method:: GET /v2/{tenant_id}/share-group-types/{share_group_type_id}/group_specs + +Lists the extra specifications for a share group type. + +Normal response codes: 200 +Error response codes: badRequest(400), unauthorized(401), forbidden(403), +itemNotFound(404) + +Request +------- + +.. rest_parameters:: parameters.yaml + + - tenant_id: tenant_id_path + - share_group_type_id: share_group_type_id_required + +Response parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - group_specs: group_specs_required + +Response example +---------------- + +.. literalinclude:: samples/share-group-types-group-specs-list-response.json + :language: javascript + + +Create share group type +======================= + +.. rest_method:: POST /v2/{tenant_id}/share-group-types + +Creates a share group type. + +Normal response codes: 200 +Error response codes: badRequest(400), unauthorized(401), forbidden(403), +itemNotFound(404), conflict(409) + +Request +------- + +.. rest_parameters:: parameters.yaml + + - tenant_id: tenant_id_path + - share_types: share_types_1 + - name: share_group_type_name + - group_specs: group_specs + - is_public: share_group_type_is_public_request + +Request example +--------------- + +.. literalinclude:: samples/share-group-type-create-request.json + :language: javascript + +Response parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - id: share_group_type_id_required + - group_specs: group_specs_required + - name: share_group_type_name + - share_types: share_types_1 + - is_public: share_group_type_is_public + +Response example +---------------- + +.. literalinclude:: samples/share-group-type-create-response.json + :language: javascript + + +Show share group type access details +==================================== + +.. rest_method:: GET /v2/{tenant_id}/share-group-types/{share_group_type_id}/share_type_access + +Shows access details for a share group type. + +You can view access details for private share group types only. + +Normal response codes: 200 +Error response codes: badRequest(400), unauthorized(401), forbidden(403), +itemNotFound(404) + +Request +------- + +.. rest_parameters:: parameters.yaml + + - tenant_id: tenant_id_path + - share_group_type_id: share_group_type_id_required + +Response parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - share_group_type_id: share_group_type_id_required + - project_id: project_id_9 + +Response example +---------------- + +.. literalinclude:: samples/share-group-types-list-access-response.json + :language: javascript + + +Set extra spec for share group type +=================================== + +.. rest_method:: POST /v2/{tenant_id}/share-group-types/{share_group_type_id}/group_specs + +Sets an extra specification for the share group type. + +Normal response codes: 200 +Error response codes: badRequest(400), unauthorized(401), forbidden(403), +itemNotFound(404), conflict(409) + +Request +------- + +.. rest_parameters:: parameters.yaml + + - tenant_id: tenant_id_path + - share_group_type_id: share_group_type_id_required + - group_specs: group_specs_required + +Request example +--------------- + +.. literalinclude:: samples/share-group-type-set-request.json + :language: javascript + +Response parameters +------------------- + +.. rest_parameters:: parameters.yaml + + - group_specs: group_specs_required + +Response example +---------------- + +.. literalinclude:: samples/share-group-type-set-response.json + :language: javascript + + +Unset an group spec +=================== + +.. rest_method:: DELETE /v2/{tenant_id}/share-group-types/{share_group_type_id}/group-specs/{group_spec_key} + +Unsets an extra specification for the share type. + +Normal response codes: 202 +Error response codes: badRequest(400), unauthorized(401), forbidden(403), +itemNotFound(404) + +Request +------- + +.. rest_parameters:: parameters.yaml + + - tenant_id: tenant_id_path + - share_group_type_id: share_group_type_id_required + - group_spec_key: group_spec_key + + +Add share group type access +=========================== + +.. rest_method:: POST /v2/{tenant_id}/share-group-types/{share_group_type_id}/action + +Adds share group type access for a project. + +You can add access to private share group types only. + +Normal response codes: 202 +Error response codes: badRequest(400), unauthorized(401), forbidden(403), +itemNotFound(404), conflict(409) + +Request +------- + +.. rest_parameters:: parameters.yaml + + - tenant_id: tenant_id_path + - share_group_type_id: share_group_type_id_path + - project: project + +Request example +--------------- + +.. literalinclude:: samples/share-group-type-grant-access-request.json + :language: javascript + + +Remove share group type access +============================== + +.. rest_method:: POST /v2/{tenant_id}/share-group-types/{share_group_type_id}/action + +Removes share group type access from a project. + +You can remove access from private share group types only. + +Normal response codes: 202 +Error response codes: badRequest(400), unauthorized(401), forbidden(403), +itemNotFound(404) + +Request +------- + +.. rest_parameters:: parameters.yaml + + - tenant_id: tenant_id_path + - share_group_type_id: share_group_type_id_path + - project: project + +Request example +--------------- + +.. literalinclude:: samples/share-group-type-revoke-access-request.json + :language: javascript + + +Delete share group type +======================= + +.. rest_method:: DELETE /v2/{tenant_id}/share-group-types/{share_group_type_id} + +Deletes a share group type. + +Normal response codes: 202 +Error response codes: badRequest(400), unauthorized(401), forbidden(403), +itemNotFound(404) + +Request +------- + +.. rest_parameters:: parameters.yaml + + - tenant_id: tenant_id_path + - share_group_type_id: share_group_type_id_path