deb-manila/api-ref/source/consistency-groups.inc
Ha Van Tu 8eaf23982c [api-ref] Refactor consistency group API
This patch refactors consistency group API to make it clear to
understand and maintain.

Change-Id: I5b48f354cb32d2606e6eaf2c01c49a333921ff4f
2016-09-15 11:00:49 +07:00

356 lines
8.5 KiB
ReStructuredText

.. -*- rst -*-
===================================
Consistency groups (since API v2.4)
===================================
Consistency groups enable you to create snapshots at the exact same
point in time from multiple file system shares. For example, a
database might place its tables, logs, and configuration on
separate shares. To restore this database from a previous point in
time, it makes sense to restore the logs, tables, and configuration
together from the exact same point in time.
As an administrator, you can also reset the state of a consistency
group and force-delete a consistency group in any state. Use the
``policy.json`` file to grant permissions for these actions to
other roles.
.. note::
Consistency groups APIs are part of an ``experimental`` feature introduced
in version 2.4. The APIs may change or be removed in further versions
of the Shared File Systems API. All experimental APIs require the
``X-OpenStack-Manila-API-Experimental: True`` header to be sent in the
requests.
List consistency groups
=======================
.. rest_method:: GET /v2/{tenant_id}/consistency-groups
Lists all consistency groups.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id_path
- all_tenants: cg_all_tenants_query
- limit: cg_limit_query
- offset: cg_offset_query
Response parameters
-------------------
.. rest_parameters:: parameters.yaml
- consistency_groups: consistency_groups
- consistency_group: consistency_group
- id: cg_id_response
- name: cg_name_response
- link: cg_links
Response example
----------------
.. literalinclude:: samples/consistency-group-list-response.json
:language: javascript
List consistency groups with details
====================================
.. rest_method:: GET /v2/{tenant_id}/consistency-groups/detail
Lists all consistency groups with details.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403)
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id_path
- all_tenants: cg_all_tenants_query
- limit: cg_limit_query
- offset: cg_offset_query
Response parameters
-------------------
.. rest_parameters:: parameters.yaml
- consistency_groups: consistency_groups
- consistency_group: consistency_group
- id: cg_id_response
- status: cg_status
- links: cg_links
- name: cg_name_response
- description: cg_description_response
- source_cgsnapshot_id: cg_snapshot_id
- created_at: cg_created_at
- share_network_id: cg_share_network_id
- host: cg_host
- project_id: cg_project_id
- share_server_id: cg_share_server_id
- share_types: cg_share_types_response
Response example
----------------
.. literalinclude:: samples/consistency-group-list-detail-response.json
:language: javascript
Show consistency group details
==============================
.. rest_method:: GET /v2/{tenant_id}/consistency-groups/{consistency_group_id}
Shows details for a consistency group.
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
- consistency_group_id: cg_id_path
Response parameters
-------------------
.. rest_parameters:: parameters.yaml
- consistency_group: consistency_group
- id: cg_id_response
- status: cg_status
- links: cg_links
- name: cg_name_response
- description: cg_description_response
- source_cgsnapshot_id: cg_snapshot_id
- created_at: cg_created_at
- share_network_id: cg_share_network_id
- host: cg_host
- project_id: cg_project_id
- share_server_id: cg_share_server_id
- share_types: cg_share_types_response
Response example
----------------
.. literalinclude:: samples/consistency-group-show-response.json
:language: javascript
Create consistency group
========================
.. rest_method:: POST /v2/{tenant_id}/consistency-groups
Creates a consistency group.
Normal response codes: 202
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
conflict(409)
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id_path
- share_types: cg_share_types_request
- name: cg_name_request
- description: cg_description_request
- share_network_id: cg_share_network_id
- source_cgsnapshot_id: cg_snapshot_id
Request example
---------------
.. literalinclude:: samples/consistency-group-create-request.json
:language: javascript
Response parameters
-------------------
.. rest_parameters:: parameters.yaml
- consistency_group: consistency_group
- id: cg_id_response
- status: cg_status
- links: cg_links
- name: cg_name_response
- description: cg_description_response
- source_cgsnapshot_id: cg_snapshot_id
- created_at: cg_created_at
- share_network_id: cg_share_network_id
- host: cg_host
- project_id: cg_project_id
- share_server_id: cg_share_server_id
- share_types: cg_share_types_response
Response example
----------------
.. literalinclude:: samples/consistency-group-create-response.json
:language: javascript
Update consistency group
========================
.. rest_method:: PUT /v2/{tenant_id}/consistency-groups/{consistency_group_id}
Updates a consistency group.
You can update only these attributes:
- ``name``, which changes the consistency group name.
- ``description``, which changes the consistency group description.
Normal response codes: 200
Error response codes: badRequest(400), unauthorized(401), forbidden(403),
itemNotFound(404)
Request
-------
.. rest_parameters:: parameters.yaml
- tenant_id: tenant_id
- consistency_group_id: cg_id_path
- name: cg_name_request
- description: cg_description_request
Request example
---------------
.. literalinclude:: samples/consistency-group-update-request.json
:language: javascript
Response parameters
-------------------
.. rest_parameters:: parameters.yaml
- consistency_group: consistency_group
- id: cg_id_response
- status: cg_status
- links: cg_links
- name: cg_name_response
- description: cg_description_response
- source_cgsnapshot_id: cg_snapshot_id
- created_at: cg_created_at
- share_network_id: share_network_id
- host: cg_host
- project_id: cg_project_id
- share_server_id: cg_share_server_id
- share_types: cg_share_types_response
Response example
----------------
.. literalinclude:: samples/consistency-group-update-response.json
:language: javascript
Reset consistency group state
=============================
.. rest_method:: POST /v2/{tenant_id}/consistency-groups/{consistency_group_id}/action
Administrator only. Explicitly updates the state of a consistency 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
- tenant_id: tenant_id_path
- consistency_group_id: cg_id_path
- reset_status: reset_status
- os-reset_status: os-reset_status
- status: status
Request example
---------------
.. literalinclude:: samples/consistency-group-reset_status-request.json
:language: javascript
Force-delete consistency group
==============================
.. rest_method:: POST /v2/{tenant_id}/consistency-groups/{consistency_group_id}/action
Administrator only. Force-deletes a consistency 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
- tenant_id: tenant_id_path
- consistency_group_id: cg_id_path
- os-force_delete: os-force_delete
- force_delete: force_delete
Request example
---------------
.. literalinclude:: samples/consistency-group-force_delete-request.json
:language: javascript
Delete consistency group
========================
.. rest_method:: DELETE /v2/{tenant_id}/consistency-groups/{consistency_group_id}
Deletes a consistency group.
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
- consistency_group_id: cg_id_path