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

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

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.

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

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

api-ref/source/samples/share-group-reset-state-request.json

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

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

api-ref/source/samples/share-group-update-request.json

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

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

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

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