From 514c1a05a1b5f2e48cb111632300a5e6f26db7e6 Mon Sep 17 00:00:00 2001 From: zhongjun Date: Wed, 16 Aug 2017 17:25:22 +0800 Subject: [PATCH] Add API document for share replica This patch adds a new API document for share replica. Change-Id: Ia0cc534e0bfb2ca4e485e575e27e9911c746691b --- api-ref/source/index.rst | 1 + api-ref/source/parameters.yaml | 115 ++++- .../samples/share-replica-create-request.json | 7 + .../share-replica-create-response.json | 15 + .../share-replicas-force-delete-request.json | 3 + .../share-replicas-list-detail-response.json | 30 ++ .../samples/share-replicas-list-response.json | 16 + ...-replicas-reset-replica-state-request.json | 5 + .../share-replicas-reset-state-request.json | 5 + .../samples/share-replicas-show-response.json | 15 + api-ref/source/share-replicas.inc | 394 ++++++++++++++++++ 11 files changed, 600 insertions(+), 6 deletions(-) create mode 100644 api-ref/source/samples/share-replica-create-request.json create mode 100644 api-ref/source/samples/share-replica-create-response.json create mode 100644 api-ref/source/samples/share-replicas-force-delete-request.json create mode 100644 api-ref/source/samples/share-replicas-list-detail-response.json create mode 100644 api-ref/source/samples/share-replicas-list-response.json create mode 100644 api-ref/source/samples/share-replicas-reset-replica-state-request.json create mode 100644 api-ref/source/samples/share-replicas-reset-state-request.json create mode 100644 api-ref/source/samples/share-replicas-show-response.json create mode 100644 api-ref/source/share-replicas.inc diff --git a/api-ref/source/index.rst b/api-ref/source/index.rst index 290173eaa2..f853694ced 100644 --- a/api-ref/source/index.rst +++ b/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 diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index 82d14f5784..be75953f51 100644 --- a/api-ref/source/parameters.yaml +++ b/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 + `_: + + :: + + 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 + `_: + + :: + + 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. diff --git a/api-ref/source/samples/share-replica-create-request.json b/api-ref/source/samples/share-replica-create-request.json new file mode 100644 index 0000000000..1ca6cc337d --- /dev/null +++ b/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" + } +} diff --git a/api-ref/source/samples/share-replica-create-response.json b/api-ref/source/samples/share-replica-create-response.json new file mode 100644 index 0000000000..cc3f27e1f9 --- /dev/null +++ b/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" + } +} diff --git a/api-ref/source/samples/share-replicas-force-delete-request.json b/api-ref/source/samples/share-replicas-force-delete-request.json new file mode 100644 index 0000000000..efe8678808 --- /dev/null +++ b/api-ref/source/samples/share-replicas-force-delete-request.json @@ -0,0 +1,3 @@ +{ + "force_delete": null +} diff --git a/api-ref/source/samples/share-replicas-list-detail-response.json b/api-ref/source/samples/share-replicas-list-detail-response.json new file mode 100644 index 0000000000..fb3e971df3 --- /dev/null +++ b/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" + } + ] +} diff --git a/api-ref/source/samples/share-replicas-list-response.json b/api-ref/source/samples/share-replicas-list-response.json new file mode 100644 index 0000000000..280cf44128 --- /dev/null +++ b/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", + } + ] +} diff --git a/api-ref/source/samples/share-replicas-reset-replica-state-request.json b/api-ref/source/samples/share-replicas-reset-replica-state-request.json new file mode 100644 index 0000000000..37ecfff265 --- /dev/null +++ b/api-ref/source/samples/share-replicas-reset-replica-state-request.json @@ -0,0 +1,5 @@ +{ + "reset_replica_state": { + "replica_state": "out_of_sync" + } +} diff --git a/api-ref/source/samples/share-replicas-reset-state-request.json b/api-ref/source/samples/share-replicas-reset-state-request.json new file mode 100644 index 0000000000..f602ff8da0 --- /dev/null +++ b/api-ref/source/samples/share-replicas-reset-state-request.json @@ -0,0 +1,5 @@ +{ + "reset_status": { + "status": "available" + } +} diff --git a/api-ref/source/samples/share-replicas-show-response.json b/api-ref/source/samples/share-replicas-show-response.json new file mode 100644 index 0000000000..3313b648c5 --- /dev/null +++ b/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" + } +} \ No newline at end of file diff --git a/api-ref/source/share-replicas.inc b/api-ref/source/share-replicas.inc new file mode 100644 index 0000000000..692c20584c --- /dev/null +++ b/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