Add API document for share replica

This patch adds a new API document for share replica.

Change-Id: Ia0cc534e0bfb2ca4e485e575e27e9911c746691b

api-ref/source/index.rst

@@ -36,3 +36,4 @@ Shared File Systems API (EXPERIMENTAL)
 .. include:: share-migration.inc
 .. include:: consistency-groups.inc
 .. include:: consistency-group-snapshots.inc
+.. include:: share-replicas.inc

api-ref/source/parameters.yaml

@@ -86,6 +86,12 @@ share_network_id_path:
   in: path
   required: true
   type: string
+share_replica_id_path:
+  description: |
+    The UUID of the share replica.
+  in: path
+  required: true
+  type: string
 share_server_id_1:
   description: |
     The UUID of the share server.
@@ -2881,12 +2887,6 @@ share_network_id_6:
   in: body
   required: true
   type: string
-share_network_id_7:
-  description: |
-    The UUID of the share network.
-  in: body
-  required: false
-  type: string
 share_network_name:
   description: |
     The name of a share network.
@@ -2945,6 +2945,109 @@ share_protocol:
   in: body
   required: true
   type: string
+share_replica_az:
+  description: |
+    The availability zone.
+  in: body
+  required: false
+  type: string
+share_replica_cast_rules_to_readonly:
+  description: |
+    Since the share instance has its ``cast_rules_to_readonly`` attribute
+    set to True, existing rules will be cast to read/only.
+  in: body
+  required: true
+  type: string
+share_replica_created_at:
+  description: |
+    The date and time stamp when the share replica 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
+share_replica_force_delete:
+  description: |
+    To force-delete a share replica, set this value to
+    ``null``. The force-delete action, unlike the delete action,
+    ignores the share replica status.
+  in: body
+  required: true
+  type: string
+share_replica_host:
+  description: |
+    The host name of the share replica.
+  in: body
+  required: true
+  type: string
+share_replica_id:
+  description: |
+    The UUID of the share replica.
+  in: body
+  required: true
+  type: string
+share_replica_replica_state:
+  description: |
+    The replica state of a share replica. List of possible values:
+    ``active``, ``in_sync``, ``out_of_sync``, and ``error``.
+  in: body
+  required: true
+  type: string
+share_replica_reset_replica_state:
+  description: |
+    The ``reset_replica_state`` object.
+  in: body
+  required: true
+  type: object
+share_replica_share_id:
+  description: |
+    The UUID of the share from which to create a
+    share replica.
+  in: body
+  required: true
+  type: string
+share_replica_share_network_id:
+  description: |
+    The UUID of the share network.
+  in: body
+  required: false
+  type: string
+share_replica_status:
+  description: |
+    The status of a share replica. List of possible values:
+    ``available``, ``error``, ``creating``, ``deleting``,
+    or ``error_deleting``.
+  in: body
+  required: true
+  type: string
+share_replica_updated_at:
+  description: |
+    The date and time stamp when the share replica was updated.
+
+    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
 share_server_id:
   description: |
     The UUID of the share server.

api-ref/source/samples/share-replica-create-request.json

@@ -0,0 +1,7 @@
+{
+    "share_replica": {
+        "share_id": "50a6a566-6bac-475c-ad69-5035c86696c0",
+        "availability_zone": "nova",
+        "share_network_id": "f5a55875-e33a-4888-be52-7cd75b72294b"
+    }
+}

api-ref/source/samples/share-replica-create-response.json

@@ -0,0 +1,15 @@
+{
+    "share_replica": {
+        "status": "creating",
+        "share_id": "5043dffd-f033-4248-a315-319ca2bd70c8",
+        "availability_zone": null,
+        "cast_rules_to_readonly": true,
+        "updated_at": null,
+        "share_network_id": null,
+        "share_server_id": null,
+        "host": "",
+        "id": "c9f52e33-d780-41d8-89ba-fc06869f465f",
+        "replica_state": null,
+        "created_at": "2017-08-15T20:21:43.493731"
+    }
+}

api-ref/source/samples/share-replicas-force-delete-request.json

@@ -0,0 +1,3 @@
+{
+    "force_delete": null
+}

api-ref/source/samples/share-replicas-list-detail-response.json

@@ -0,0 +1,30 @@
+{
+    "share_replicas": [
+        {
+            "status": "available",
+            "share_id": "5043dffd-f033-4248-a315-319ca2bd70c8",
+            "availability_zone": "nova",
+            "cast_rules_to_readonly": false,
+            "updated_at": "2017-08-15T20:20:50.000000",
+            "share_network_id": null,
+            "share_server_id": null,
+            "host": "ubuntu@generic3#fake_pool_for_DummyDriver",
+            "id": "57f5c47a-0216-4ee0-a517-0460d63301a6",
+            "replica_state": "active",
+            "created_at": "2017-08-15T20:20:45.000000"
+        },
+        {
+            "status": "available",
+            "share_id": "5043dffd-f033-4248-a315-319ca2bd70c8",
+            "availability_zone": "nova",
+            "cast_rules_to_readonly": true,
+            "updated_at": "2017-08-15T20:21:49.000000",
+            "share_network_id": null,
+            "share_server_id": null,
+            "host": "ubuntu@generic2#fake_pool_for_DummyDriver",
+            "id": "c9f52e33-d780-41d8-89ba-fc06869f465f",
+            "replica_state": "in_sync",
+            "created_at": "2017-08-15T20:21:43.000000"
+        }
+    ]
+}

api-ref/source/samples/share-replicas-list-response.json

@@ -0,0 +1,16 @@
+{
+    "share_replicas": [
+        {
+            "status": "available",
+            "share_id": "5043dffd-f033-4248-a315-319ca2bd70c8",
+            "id": "57f5c47a-0216-4ee0-a517-0460d63301a6",
+            "replica_state": "active",
+        },
+        {
+            "status": "available",
+            "share_id": "5043dffd-f033-4248-a315-319ca2bd70c8",
+            "id": "c9f52e33-d780-41d8-89ba-fc06869f465f",
+            "replica_state": "in_sync",
+        }
+    ]
+}

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

@@ -0,0 +1,5 @@
+{
+    "reset_replica_state": {
+        "replica_state": "out_of_sync"
+    }
+}

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

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

api-ref/source/samples/share-replicas-show-response.json

@@ -0,0 +1,15 @@
+{
+    "share_replica": {
+         "status": "available",
+         "share_id": "5043dffd-f033-4248-a315-319ca2bd70c8",
+         "availability_zone": "nova",
+         "cast_rules_to_readonly": false,
+         "updated_at": "2017-08-15T20:20:50.000000",
+         "share_network_id": null,
+         "share_server_id": null,
+         "host": "ubuntu@generic3#fake_pool_for_DummyDriver",
+         "id": "57f5c47a-0216-4ee0-a517-0460d63301a6",
+         "replica_state": "active",
+         "created_at": "2017-08-15T20:20:45.000000"
+    }
+}

api-ref/source/share-replicas.inc

@@ -0,0 +1,394 @@
+.. -*- rst -*-
+
+===================================
+Share replicas (Since version 2.11)
+===================================
+
+Share replicas are the replicated copies of the existing share. You can use
+Share Replicas to sync data so that each share replica has an identical copy
+of the same share. Share replication can be used as a disaster recovery
+solution or as a load sharing mirroring solution.
+
+Manila supports replication of shares between different storage pools.
+These pools may be on different back-end storage systems or within the same
+back end, depending upon the replication style chosen, the capability of
+the driver and the configuration of back ends. To ensure that a secondary
+copy is scheduled to a distinct back end, you must specify the
+``availability_zone`` attribute.
+
+.. note::
+
+  You can create a replicated share with the help of a share type
+  that has an extra-spec ``replication_type`` specified with a valid
+  replication style. Once a replicated share has been created,
+  it always starts out with an ``active`` replica. You may then create
+  secondary copies of the share. A secondary copy can be "promoted"
+  to fail-over to becoming the ``active`` replica.
+
+To create a share that supports replication, the share type must specify
+one of these supported replication types:
+
+- writable
+
+  Synchronously replicated shares where all replicas are writable.
+  Promotion is not supported and not needed because all copies are already
+  exported and can be accessed simultaneously.
+
+- readable
+
+  Mirror-style replication with a primary (writable) copy and one or more
+  secondary (read-only) copies which can become writable after a promotion.
+
+- dr (for Disaster Recovery)
+
+  Generalized replication with secondary copies that are inaccessible until
+  they are promoted to become the active replica.
+
+.. important::
+
+  The term active replica refers to the primary share. In writable style of
+  replication, all replicas are active, and there could be no distinction of
+  a primary share. In readable and dr styles of replication, a secondary
+  replica may be referred to as passive, non-active or simply replica.
+
+
+Create share replica
+====================
+
+.. rest_method::  POST /v2/{tenant_id}/share-replicas
+
+Create a share replica for the share.
+
+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_id: share_replica_share_id
+   - availability_zone: share_replica_az
+   - share_network_id: share_replica_share_network_id
+
+Request example
+---------------
+
+.. literalinclude:: samples/share-replica-create-request.json
+   :language: javascript
+
+Response parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - share_id: share_replica_share_id
+   - status: share_replica_status
+   - cast_rules_to_readonly: share_replica_cast_rules_to_readonly
+   - updated_at: share_replica_updated_at
+   - share_network_id: share_network_id
+   - share_server_id: share_server_id
+   - host: share_replica_host
+   - id: share_replica_id
+   - replica_state: share_replica_replica_state
+   - created_at: share_replica_created_at
+
+
+Response example
+----------------
+
+.. literalinclude:: samples/share-replica-create-response.json
+   :language: javascript
+
+
+Promote share replica
+=====================
+
+.. rest_method::  POST /v2/{tenant_id}/share-replicas/{share_replica_id}/action
+
+Promotes a replica to ``active`` replica state.
+
+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_replica_id: share_replica_id_path
+
+
+Resync share replica
+====================
+
+.. rest_method::  POST /v2/{tenant_id}/share-replicas/{share_replica_id}/action
+
+Resync a replica with its ``active`` mirror.
+
+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_replica_id: share_replica_id_path
+
+
+List share replicas
+===================
+
+.. rest_method::  GET /v2/{tenant_id}/share-replicas?share_id={share_id}
+
+Lists share replicas.
+
+Normal response codes: 200
+
+Error response codes: badRequest(400), unauthorized(401), forbidden(403),
+itemNotFound(404)
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - share_id: share_id
+   - tenant_id: tenant_id_path
+
+Response parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - share_id: share_replica_share_id
+   - status: share_replica_status
+   - id: share_replica_id
+   - replica_state: share_replica_replica_state
+
+Response example
+----------------
+
+.. literalinclude:: samples/share-replicas-list-response.json
+   :language: javascript
+
+
+List share replicas with details
+================================
+
+.. rest_method::  GET /v2/{tenant_id}/share-replicas/detail?share_id={share_id}
+
+Lists share replicas with details.
+
+Normal response codes: 200
+
+Error response codes: badRequest(400), unauthorized(401), forbidden(403),
+itemNotFound(404)
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - share_id: share_id
+   - tenant_id: tenant_id_path
+
+Response parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - share_id: share_replica_share_id
+   - status: share_replica_status
+   - cast_rules_to_readonly: share_replica_cast_rules_to_readonly
+   - updated_at: share_replica_updated_at
+   - share_network_id: share_network_id
+   - share_server_id: share_server_id
+   - host: share_replica_host
+   - id: share_replica_id
+   - replica_state: share_replica_replica_state
+   - created_at: share_replica_created_at
+
+Response example
+----------------
+
+.. literalinclude:: samples/share-replicas-list-detail-response.json
+   :language: javascript
+
+
+Show share replica
+==================
+
+.. rest_method::  GET /v2/{tenant_id}/share-replicas/{share_replica_id}
+
+Show a share replica.
+
+Normal response codes: 200
+
+Error response codes: badRequest(400), unauthorized(401), forbidden(403),
+itemNotFound(404)
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - share_replica_id: share_replica_id_path
+   - tenant_id: tenant_id_path
+
+
+Response parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - share_id: share_replica_share_id
+   - status: share_replica_status
+   - cast_rules_to_readonly: share_replica_cast_rules_to_readonly
+   - updated_at: share_replica_updated_at
+   - share_network_id: share_network_id
+   - share_server_id: share_server_id
+   - host: share_replica_host
+   - id: share_replica_id
+   - replica_state: share_replica_replica_state
+   - created_at: share_replica_created_at
+
+Response example
+----------------
+
+.. literalinclude:: samples/share-replicas-show-response.json
+   :language: javascript
+
+
+Reset status of the share replica
+=================================
+
+.. rest_method::  POST /v2/{tenant_id}/share-replicas/{share_replica_id}/action
+
+Administrator only. Explicitly updates the ``status`` of a share replica.
+
+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_replica_status
+   - share_replica_id: share_replica_id_path
+   - tenant_id: tenant_id_path
+
+Request example
+---------------
+
+.. literalinclude:: samples/share-replicas-reset-state-request.json
+   :language: javascript
+
+
+Reset replica_state of the share replica
+========================================
+
+.. rest_method::  POST /v2/{tenant_id}/share-replicas/{share_replica_id}/action
+
+Administrator only. Explicitly updates the ``replica state`` of a share replica.
+
+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_replica_state: share_replica_reset_replica_state
+   - replica_state: share_replica_replica_state
+   - share_replica_id: share_replica_id_path
+   - tenant_id: tenant_id_path
+
+Request example
+---------------
+
+.. literalinclude:: samples/share-replicas-reset-replica-state-request.json
+   :language: javascript
+
+
+Delete share replica
+====================
+
+.. rest_method::  DELETE /v2/{tenant_id}/share-replicas/{share_replica_id}
+
+Deletes a share replica.
+
+Normal response codes: 202
+
+Error response codes: badRequest(400), unauthorized(401), forbidden(403),
+itemNotFound(404), conflict(409)
+
+.. note::
+
+    The ``active`` replica cannot be deleted with this API.
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - share_replica_id: share_replica_id_path
+   - tenant_id: tenant_id_1
+
+
+Force-delete share replica
+==========================
+
+.. rest_method::  POST /v2/{tenant_id}/share-replicas/{share_replica_id}/action
+
+Administrator only. Force-deletes a share replica in any state.
+
+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)
+
+.. note::
+
+    The ``active`` replica cannot be deleted with this API.
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - force_delete: share_replica_force_delete
+   - share_replica_id: share_replica_id_path
+   - tenant_id: tenant_id_path
+
+Request example
+---------------
+
+.. literalinclude:: samples/share-replicas-force-delete-request.json
+   :language: javascript