478 lines
8.7 KiB
ReStructuredText
478 lines
8.7 KiB
ReStructuredText
.. -*- rst -*-
|
|
|
|
Share backups (since API v2.80)
|
|
===============================
|
|
|
|
Use the Shared File Systems service to make backups of shares. A share
|
|
backup is a point-in-time, read-only copy of the data that is
|
|
contained in a share. The APIs below allow controlling share backups. They
|
|
are represented by a "backup" resource in the Shared File Systems service,
|
|
and they can have user-defined metadata such as a name and description.
|
|
|
|
You can create, restore, update, list and delete share backups. After you
|
|
create a share backup, you can access backup and use it. You can also restore
|
|
a backup into a share as long as certain criteria are met e.g. size.
|
|
|
|
You can update a share backup to change its name or description. As
|
|
administrator, you can also reset the state of a backup. Backup can be in
|
|
one of the following states:
|
|
|
|
- ``available``
|
|
|
|
- ``error``
|
|
|
|
- ``creating``
|
|
|
|
- ``deleting``
|
|
|
|
- ``restoring``
|
|
|
|
|
|
During a backup or restore operation, share can be in one of the following
|
|
states:
|
|
|
|
- ``available``
|
|
|
|
- ``backup_creating``
|
|
|
|
- ``backup_restoring``
|
|
|
|
- ``backup_restoring_error``
|
|
|
|
|
|
List share backups
|
|
~~~~~~~~~~~~~~~~~~
|
|
|
|
.. rest_method:: GET /v2/share-backups
|
|
|
|
.. versionadded:: 2.80
|
|
|
|
Lists all share backups.
|
|
|
|
Response codes
|
|
--------------
|
|
|
|
.. rest_status_code:: success status.yaml
|
|
|
|
- 200
|
|
|
|
.. rest_status_code:: error status.yaml
|
|
|
|
- 400
|
|
- 401
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- share_id: backup_share_id_query
|
|
- name~: name_inexact_query_versionless
|
|
- description~: description_inexact_query_versionless
|
|
- limit: limit
|
|
- offset: offset
|
|
- sort_key: sort_key_backup
|
|
- sort_dir: sort_dir
|
|
- status: backup_status_query
|
|
- host: backup_host_query
|
|
- topic: backup_topic_query
|
|
|
|
Response parameters
|
|
-------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- id: backup_id_response
|
|
- share_id: backup_share_id
|
|
- status: backup_status
|
|
|
|
Response example
|
|
----------------
|
|
|
|
.. literalinclude:: samples/share-backups-list-response.json
|
|
:language: javascript
|
|
|
|
|
|
List share backups with details
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. rest_method:: GET /v2/share-backups/detail
|
|
|
|
.. versionadded:: 2.80
|
|
|
|
Lists all share backups with details.
|
|
|
|
Response codes
|
|
--------------
|
|
|
|
.. rest_status_code:: success status.yaml
|
|
|
|
- 200
|
|
|
|
.. rest_status_code:: error status.yaml
|
|
|
|
- 400
|
|
- 401
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- share_id: backup_share_id_query
|
|
- name~: name_inexact_query_versionless
|
|
- description~: description_inexact_query_versionless
|
|
- limit: limit
|
|
- offset: offset
|
|
- sort_key: sort_key_backup
|
|
- sort_dir: sort_dir
|
|
- status: backup_status_query
|
|
- host: backup_host_query
|
|
- topic: backup_topic_query
|
|
|
|
Response parameters
|
|
-------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- id: backup_id_response
|
|
- share_id: backup_share_id
|
|
- status: backup_status
|
|
- size: backup_size
|
|
- availability_zone: backup_az
|
|
- name: name
|
|
- description: description
|
|
- created_at: created_at
|
|
- updated_at: updated_at
|
|
- progress: backup_progress
|
|
- restore_progress: backup_restore_progress
|
|
|
|
Response example
|
|
----------------
|
|
|
|
.. literalinclude:: samples/share-backups-list-detailed-response.json
|
|
:language: javascript
|
|
|
|
|
|
Show share backup details
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. rest_method:: GET /v2/share-backups/{backup_id}
|
|
|
|
.. versionadded:: 2.80
|
|
|
|
Shows details for a share backup.
|
|
|
|
Response codes
|
|
--------------
|
|
|
|
.. rest_status_code:: success status.yaml
|
|
|
|
- 200
|
|
|
|
.. rest_status_code:: error status.yaml
|
|
|
|
- 400
|
|
- 401
|
|
- 404
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- backup_id: backup_id_request_path
|
|
|
|
Response parameters
|
|
-------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- id: backup_id_response
|
|
- share_id: backup_share_id
|
|
- status: backup_status
|
|
- size: backup_size
|
|
- availability_zone: backup_az
|
|
- name: name
|
|
- description: description
|
|
- created_at: created_at
|
|
- updated_at: updated_at
|
|
- progress: backup_progress
|
|
- restore_progress: backup_restore_progress
|
|
|
|
Response example
|
|
----------------
|
|
|
|
.. literalinclude:: samples/share-backup-show-response.json
|
|
:language: javascript
|
|
|
|
|
|
Create share backup
|
|
~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. rest_method:: POST /v2/share-backups
|
|
|
|
.. versionadded:: 2.80
|
|
|
|
Creates a backup from a share.
|
|
|
|
|
|
Response codes
|
|
--------------
|
|
|
|
.. rest_status_code:: success status.yaml
|
|
|
|
- 202
|
|
|
|
.. rest_status_code:: error status.yaml
|
|
|
|
- 400
|
|
- 401
|
|
- 403
|
|
- 404
|
|
- 409
|
|
- 422
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- share_id: backup_share_id
|
|
- name: name_request
|
|
- description: description_request
|
|
- backup_options: backup_options_request
|
|
|
|
Request example
|
|
---------------
|
|
|
|
.. literalinclude:: samples/share-backup-create-request.json
|
|
:language: javascript
|
|
|
|
Response parameters
|
|
-------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- id: backup_id_response
|
|
- share_id: backup_share_id
|
|
- status: backup_status
|
|
- size: backup_size
|
|
- availability_zone: backup_az
|
|
- name: name
|
|
- description: description
|
|
- created_at: created_at
|
|
- updated_at: updated_at
|
|
- progress: backup_progress
|
|
- restore_progress: backup_restore_progress
|
|
|
|
Response example
|
|
----------------
|
|
|
|
.. literalinclude:: samples/share-backup-create-response.json
|
|
:language: javascript
|
|
|
|
|
|
Update share backup
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. rest_method:: PUT /v2/share-backups/{backup_id}
|
|
|
|
.. versionadded:: 2.80
|
|
|
|
Updates a share backup.
|
|
|
|
You can update these attributes:
|
|
|
|
- ``display_name``, which changes the ``name`` of the share backup.
|
|
|
|
- ``display_description``, which changes the ``description`` of
|
|
the share backup.
|
|
|
|
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
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- backup_id: backup_id_request_path
|
|
- display_name: display_name_request
|
|
- display_description: display_description_request
|
|
|
|
Request example
|
|
---------------
|
|
|
|
.. literalinclude:: samples/share-backup-update-request.json
|
|
:language: javascript
|
|
|
|
Response parameters
|
|
-------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- id: backup_id_response
|
|
- share_id: backup_share_id
|
|
- status: backup_status
|
|
- size: backup_size
|
|
- availability_zone: backup_az
|
|
- name: name
|
|
- description: description
|
|
- created_at: created_at
|
|
- updated_at: updated_at
|
|
- progress: backup_progress
|
|
- restore_progress: backup_restore_progress
|
|
|
|
Response example
|
|
----------------
|
|
|
|
.. literalinclude:: samples/share-backup-update-response.json
|
|
:language: javascript
|
|
|
|
|
|
Delete share backup
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. rest_method:: DELETE /v2/share-backups/{backup_id}
|
|
|
|
.. versionadded:: 2.80
|
|
|
|
Deletes a share backup.
|
|
|
|
Preconditions
|
|
|
|
- Share backup 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
|
|
|
|
- backup_id: backup_id_request_path
|
|
|
|
|
|
Restore a share backup
|
|
~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. rest_method:: POST /v2/share-backups/{backup_id}/action
|
|
|
|
.. versionadded:: 2.80
|
|
|
|
Restores a share backup into original share.
|
|
|
|
Preconditions
|
|
|
|
- Share backup status must be ``available``.
|
|
|
|
Response codes
|
|
--------------
|
|
|
|
.. rest_status_code:: success status.yaml
|
|
|
|
- 202
|
|
|
|
.. rest_status_code:: error status.yaml
|
|
|
|
- 400
|
|
- 401
|
|
- 403
|
|
- 404
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- backup_id: backup_id_request_path
|
|
|
|
Request example
|
|
---------------
|
|
|
|
.. literalinclude:: samples/share-backup-restore-request.json
|
|
:language: javascript
|
|
|
|
Response parameters
|
|
-------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- backup_id: backup_id_response
|
|
- share_id: backup_share_id
|
|
|
|
Response example
|
|
----------------
|
|
|
|
.. literalinclude:: samples/share-backup-restore-response.json
|
|
:language: javascript
|
|
|
|
|
|
Reset share backup status
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. rest_method:: POST /v2/share-backups/{backup_id}/action
|
|
|
|
.. versionadded:: 2.80
|
|
|
|
Administrator only. Explicitly updates the state of a share backup.
|
|
|
|
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
|
|
- backup_id: backup_id_request_path
|
|
- status: backup_status_request
|
|
|
|
Request example
|
|
---------------
|
|
|
|
.. literalinclude:: samples/share-backup-reset-status-request.json
|
|
:language: javascript
|