Add API document for share replica

This patch adds a new API document for share replica.

Change-Id: Ia0cc534e0bfb2ca4e485e575e27e9911c746691b
This commit is contained in:
zhongjun 2017-08-16 17:25:22 +08:00 committed by zhongjun
parent 6f2c8d45eb
commit 514c1a05a1
11 changed files with 600 additions and 6 deletions

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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

View File

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