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
This commit is contained in:
zhongjun 2017-08-04 10:47:27 +08:00 committed by zhongjun
parent c86e7658af
commit 9f2f05ffc4
13 changed files with 757 additions and 7 deletions

View File

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

View File

@ -14,6 +14,12 @@ export_location_id_path:
in: path in: path
required: false required: false
type: string type: string
group_snapshot_id_path:
description: |
The group snapshot ID.
in: path
required: true
type: string
message_id: message_id:
description: | description: |
The UUID of the message. The UUID of the message.
@ -26,6 +32,12 @@ security_service_id_path:
in: path in: path
required: false required: false
type: string type: string
share_group_type_id_path:
description: |
The UUID of the share group type.
in: path
required: true
type: string
share_id: share_id:
description: | description: |
The UUID of the share. The UUID of the share.
@ -114,9 +126,9 @@ action_id:
The ID of the action during which the message was created. The ID of the action during which the message was created.
all_tenants: all_tenants:
description: | description: |
(Admin only). Defines whether to list shares for (Admin only). Defines whether to list shares or share groups for
all tenants. Set to ``1`` to list shares for all tenants. Set to all tenants. Set to ``1`` to list shares or sharegroups for all tenants.
``0`` to list shares only for the current tenant. Set to ``0`` to list shares or share groups only for the current tenant.
in: query in: query
required: false required: false
type: boolean type: boolean
@ -159,6 +171,13 @@ description_inexact_query:
required: false required: false
type: string type: string
min_version: 2.36 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: detail_id:
in: query in: query
required: false required: false
@ -190,6 +209,28 @@ extra_specs_1:
in: query in: query
required: false required: false
type: string 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: host_11:
description: | description: |
The host name for the back end. The host name for the back end.
@ -214,6 +255,12 @@ limit:
in: query in: query
required: false required: false
type: integer type: integer
limit_query:
description: |
The maximum number of share groups members to return.
in: query
required: false
type: integer
media_types: media_types:
description: | description: |
Media types supported by the API. Media types supported by the API.
@ -247,9 +294,15 @@ name_inexact_query:
required: false required: false
type: string type: string
min_version: 2.36 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: offset:
description: | description: |
The offset to define start point of share The offset to define start point of share or share group
listing. listing.
in: query in: query
required: false required: false
@ -325,13 +378,33 @@ share_group_id_query:
required: false required: false
type: string type: string
min_version: 2.31 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: share_network_id_5:
description: | description: |
The UUID of the share network. The UUID of the share network.
in: query in: query
required: false required: false
type: string 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: | description: |
The UUID of the share server. The UUID of the share server.
in: query in: query
@ -350,6 +423,12 @@ share_type_query:
in: query in: query
required: false required: false
type: string 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: snapshot_id_query:
description: | description: |
The UUID of the share's base snapshot to filter the request based on. The UUID of the share's base snapshot to filter the request based on.
@ -390,6 +469,14 @@ sort_key_messages:
in: query in: query
required: false required: false
type: string 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: state_2:
description: | description: |
The current state of the service. A valid value The current state of the service. A valid value
@ -624,6 +711,13 @@ availability_zone_id:
in: body in: body
required: true required: true
type: string 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: availability_zone_name:
description: | description: |
The name of the availability zone. The name of the availability zone.
@ -833,6 +927,13 @@ cidr_1:
in: body in: body
required: true required: true
type: string type: string
consistent_snapshot_support:
description: |
The consistency snapshot support.
in: body
required: false
type: string
min_version: 2.34
created_at_11: created_at_11:
description: | description: |
The date and time stamp when the share server was created. The date and time stamp when the share server was created.
@ -1285,6 +1386,92 @@ free_capacity_gb:
in: body in: body
required: true required: true
type: string 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
<https://en.wikipedia.org/wiki/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: has_replicas:
description: | description: |
(Since API v2.11) Indicates whether a share has (Since API v2.11) Indicates whether a share has
@ -2393,9 +2580,40 @@ share_backend_name:
type: string type: string
share_force_delete: share_force_delete:
description: | 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, ``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
<https://en.wikipedia.org/wiki/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 in: body
required: true required: true
type: string type: string
@ -2413,6 +2631,65 @@ share_group_id_request:
required: False required: False
type: string type: string
min_version: 2.31 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: share_id_2:
description: | description: |
The UUID of the share from which the share The UUID of the share from which the share
@ -2992,6 +3269,20 @@ snapshot_unmanage:
in: body in: body
required: true required: true
type: string 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: state:
description: | description: |
Prior to versions 2.28, the state of all access rules of a given share Prior to versions 2.28, the state of all access rules of a given share
@ -3011,6 +3302,30 @@ state_1:
in: body in: body
required: true required: true
type: string 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: status_15:
description: | description: |
The share server status, which is ``active``, The share server status, which is ``active``,

View File

@ -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"
}
}

View File

@ -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"
}
}

View File

@ -0,0 +1,5 @@
{
"addProjectAccess": {
"project": "e1284adea3ee4d2482af5ed214f3ad90"
}
}

View File

@ -0,0 +1,5 @@
{
"removeProjectAccess": {
"project": "818a3f48dcd644909b3fa2e45a399a27"
}
}

View File

@ -0,0 +1,5 @@
{
"group_specs": {
"my_group_key": "my_group_value"
}
}

View File

@ -0,0 +1,5 @@
{
"group_specs": {
"my_group_key": "my_group_value"
}
}

View File

@ -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"
}
}

View File

@ -0,0 +1,5 @@
{
"group_specs": {
"snapshot_support": "True",
}
}

View File

@ -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"
}
]
}

View File

@ -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"
}
]
}

View File

@ -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)
<http://developer.openstack.org/api-ref/shared-file-systems/#experimental-apis>`_
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
<http://developer.openstack.org/api-ref/shared-file-systems/#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