openstack/manila
Code Issues Proposed changes
aebf40adda
manila/api-ref/source/snapshots.inc
Goutham Pacha Ravi 7705b74a75 [api-ref] add provider_location to snapshots 
This optional field was missing in the docs

Change-Id: I86a3161b098652788f8a982053a8efd06a73dbba
2023-08-10 15:00:33 -07:00

575 lines
11 KiB
ReStructuredText
Raw Blame History

.. -*- rst -*-
Share snapshots
===============
Use the Shared File Systems service to make snapshots of shares. A share
snapshot is a point-in-time, read-only copy of the data that is
contained in a share. The APIs below allow controlling share snapshots. They
are represented by a "snapshot" resource in the Shared File Systems service,
and they can have user-defined metadata such as a name and description.
You can create, manage, update, and delete
share snapshots. After you create or manage a share snapshot, you
can create a share from it. You can also revert a share to its most
recent snapshot.
You can update a share snapshot to rename it, change its
description, or update its state to one of these supported states:
- ``available``
- ``error``
- ``creating``
- ``deleting``
- ``error_deleting``
- ``manage_starting``
- ``manage_error``
- ``unmanage_starting``
- ``unmanage_error``
- ``restoring``
As administrator, you can also reset the state of a snapshot and
force-delete a share snapshot in any state. Use the ``policy.yaml``
file to grant permissions for these actions to other roles.
List share snapshots
~~~~~~~~~~~~~~~~~~~~
.. rest_method:: GET /v2/snapshots
Lists all share snapshots.
Response codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- all_tenants: all_tenants_query
- name~: name_inexact_query
- description~: description_inexact_query
- with_count: with_count_snapshot_query
Response parameters
-------------------
.. rest_parameters:: parameters.yaml
- id: snapshot_id
- name: name
Response example
----------------
.. literalinclude:: samples/snapshots-list-response.json
:language: javascript
List share snapshots with details
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: GET /v2/snapshots/detail
Lists all share snapshots with details.
Response codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- all_tenants: all_tenants_query
- name~: name_inexact_query
- description~: description_inexact_query
- with_count: with_count_snapshot_query
Response parameters
-------------------
.. rest_parameters:: parameters.yaml
- id: snapshot_id
- status: snapshot_status
- share_id: snapshot_share_id
- name: name
- description: description
- created_at: created_at
- share_proto: snapshot_share_protocol
- share_size: snapshot_share_size
- size: snapshot_size
- project_id: snapshot_project_id
- user_id: snapshot_user_id
- provider_location: snapshot_provider_location_optional
Response example
----------------
.. literalinclude:: samples/snapshots-list-detailed-response.json
:language: javascript
Show share snapshot details
~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: GET /v2/snapshots/{snapshot_id}
Shows details for a share snapshot.
Response codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
- 404
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- snapshot_id: snapshot_id_path
Response parameters
-------------------
.. rest_parameters:: parameters.yaml
- id: snapshot_id
- status: snapshot_status
- share_id: snapshot_share_id
- name: name
- description: description
- created_at: created_at
- share_proto: snapshot_share_protocol
- share_size: snapshot_share_size
- size: snapshot_size
- project_id: snapshot_project_id
- user_id: snapshot_user_id
- provider_location: snapshot_provider_location_optional
Response example
----------------
.. literalinclude:: samples/snapshot-show-response.json
:language: javascript
Create share snapshot
~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: POST /v2/snapshots
Creates a snapshot from a share.
Response codes
--------------
.. rest_status_code:: success status.yaml
- 202
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
- 404
- 422
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- share_id: snapshot_share_id_request
- force: force_snapshot_request
- name: name_request
- description: description_request
- display_name: display_name_request
- display_description: display_description_request
Request example
---------------
.. literalinclude:: samples/snapshot-create-request.json
:language: javascript
Response parameters
-------------------
.. rest_parameters:: parameters.yaml
- id: snapshot_id
- share_id: snapshot_share_id
- status: snapshot_status
- name: name
- description: description
- created_at: created_at
- share_proto: snapshot_share_protocol
- share_size: snapshot_share_size
- provider_location: snapshot_provider_location_optional
- size: snapshot_size
- project_id: snapshot_project_id
- user_id: snapshot_user_id
Response example
----------------
.. literalinclude:: samples/snapshot-create-response.json
:language: javascript
Manage share snapshot (since API v2.12)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: POST /v2/snapshots/manage
.. versionadded:: 2.12
Configures Shared File Systems to manage a share snapshot.
.. note::
Managing snapshots of shares that are created on top of share servers
(i.e. created with share networks) is not supported prior to API version
2.49.
Response codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
- 404
- 409
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- share_id: snapshot_manage_share_id
- provider_location: snapshot_provider_location_request
- name: name_request
- display_name: display_name_request
- description: description_request
- display_description: display_description_request
- driver_options: driver_options
Request example
---------------
.. literalinclude:: samples/snapshot-manage-request.json
:language: javascript
Response parameters
-------------------
.. rest_parameters:: parameters.yaml
- id: snapshot_id
- share_id: snapshot_share_id
- status: snapshot_manage_status
- name: name
- description: description
- created_at: created_at
- share_proto: snapshot_share_protocol
- share_size: snapshot_share_size
- provider_location: snapshot_provider_location
- size: snapshot_size
- project_id: snapshot_project_id
- user_id: snapshot_user_id
Response example
----------------
.. literalinclude:: samples/snapshot-manage-response.json
:language: javascript
Unmanage share snapshot (since API v2.12)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: POST /v2/snapshots/{snapshot_id}/action
.. versionadded:: 2.12
Configures Shared File Systems to stop managing a share snapshot.
.. note::
Unmanaging snapshots of shares that are created on top of share servers
(i.e. created with share networks) is not supported prior to API version
2.49.
Response codes
--------------
.. rest_status_code:: success status.yaml
- 202
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
- 404
- 409
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- snapshot_id: snapshot_id_path
- unmanage: snapshot_unmanage
Request example
---------------
.. literalinclude:: samples/snapshot-actions-unmanage-request.json
:language: javascript
Response parameters
-------------------
There is no body content for the response.
Reset share snapshot state
~~~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: POST /v2/snapshots/{snapshot_id}/action
Administrator only. Explicitly updates the state of a share snapshot.
Use the ``policy.yaml`` file to grant permissions for this action
to other roles.
Response codes
--------------
.. rest_status_code:: success status.yaml
- 202
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
- 404
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- snapshot_id: snapshot_id_path
- status: snapshot_status_request
Request example
---------------
.. literalinclude:: samples/snapshot-actions-reset-state-request.json
:language: javascript
Force-delete share snapshot
~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: POST /v2/snapshots/{snapshot_id}/action
Administrator only. Force-deletes a share snapshot in any state.
Use the ``policy.yaml`` file to grant permissions for this action
to other roles.
Response codes
--------------
.. rest_status_code:: success status.yaml
- 202
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
- 404
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- snapshot_id: snapshot_id_path
- force_delete: snapshot_force_delete
Request example
---------------
.. literalinclude:: samples/snapshot-actions-force-delete-request.json
:language: javascript
Update share snapshot
~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: PUT /v2/snapshots/{snapshot_id}
Updates a share snapshot.
You can update these attributes:
- ``display_name``, which also changes the ``name`` of the share
snapshot.
- ``display_description``, which also changes the ``description`` of
the share snapshot.
If you try to update other attributes, they retain their previous
values.
Response codes
--------------
.. rest_status_code:: success status.yaml
- 200
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
- 404
- 422
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- snapshot_id: snapshot_id_path
- display_name: display_name_request
- display_description: display_description_request
Request example
---------------
.. literalinclude:: samples/snapshot-update-request.json
:language: javascript
Response parameters
-------------------
.. rest_parameters:: parameters.yaml
- id: snapshot_id
- status: snapshot_status
- share_id: snapshot_share_id
- name: name
- description: description
- created_at: created_at
- share_proto: snapshot_share_protocol
- share_size: snapshot_share_size
- size: snapshot_size
- project_id: snapshot_project_id
- user_id: snapshot_user_id
Response example
----------------
.. literalinclude:: samples/snapshot-update-response.json
:language: javascript
Delete share snapshot
~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: DELETE /v2/snapshots/{snapshot_id}
Deletes a share snapshot.
Preconditions
- Share snapshot status must be ``available`` or ``error``.
Response codes
--------------
.. rest_status_code:: success status.yaml
- 202
.. rest_status_code:: error status.yaml
- 400
- 401
- 403
- 404
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- snapshot_id: snapshot_id_path
View Git Blame Copy Permalink