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