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

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

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
+    <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:
   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
+    <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
   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``,

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

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

api-ref/source/samples/share-group-type-grant-access-request.json

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

api-ref/source/samples/share-group-type-revoke-access-request.json

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

api-ref/source/samples/share-group-type-set-request.json

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

api-ref/source/samples/share-group-type-set-response.json

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

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

api-ref/source/samples/share-group-types-group-specs-list-response.json

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

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

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

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)
+<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