openstack/cinder
Code Issues Proposed changes
e55043ff00
cinder/api-ref/source/v3/ext-backups.inc
Alan Bishop f91aec5869 Add encryption_key_id to volume and backup details 
Add microversion 3.64 for including the encryption_key_id in the
volume and backup details when the associated volume is encrypted.
This facilitates associating encryption keys (typically stored in
Barbican) with the volume or backup that uses it.

The encryption_key_id is included in the details only when the
associated volume is encrypted, and it isn't using the all-zeros
key ID used by the legacy fixed-key ConfKeyMgr.

APIImpact
DocImpact

Implements: blueprint include-encryption-key-id-in-details
Change-Id: I16f54e6722cdbcbad4af1eb0d30264b0039412fd
2021-02-04 07:23:08 -08:00

530 lines
11 KiB
ReStructuredText
Raw Blame History

.. -*- rst -*-
Backups (backups)
=================
A backup is a full copy of a volume stored in an external service.
The service can be configured. The only supported service is Object
Storage. A backup can subsequently be restored from the external
service to either the same volume that the backup was originally
taken from or to a new volume.
When you create, list, or delete backups, these status values are
possible:
**Backup statuses**
+-----------------+---------------------------------------------+
| Status | Description |
+-----------------+---------------------------------------------+
| creating | The backup is being created. |
+-----------------+---------------------------------------------+
| available | The backup is ready to restore to a volume. |
+-----------------+---------------------------------------------+
| deleting | The backup is being deleted. |
+-----------------+---------------------------------------------+
| error | A backup error occurred. |
+-----------------+---------------------------------------------+
| restoring | The backup is being restored to a volume. |
+-----------------+---------------------------------------------+
| error_deleting | An error occurred while deleting the backup.|
+-----------------+---------------------------------------------+
If an error occurs, you can find more information about the error
in the ``fail_reason`` field for the backup.
List backups with detail
~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: GET /v3/{project_id}/backups/detail
Lists Block Storage backups, with details, to which the project has access,
since v3.31 if non-admin users specify invalid filters in the url,
API will return bad request.
Response codes
--------------
.. rest_status_code:: success ../status.yaml
- 200
.. rest_status_code:: error ../status.yaml
- 400
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- all_tenants: all-tenants
- sort: sort
- limit: limit
- offset: offset
- marker: marker
- with_count: with_count
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- backups: backups
- status: status_backup
- object_count: object_count
- fail_reason: fail_reason
- description: description
- links: links_backup
- availability_zone: availability_zone
- created_at: created_at
- updated_at: updated_at
- name: name_backup
- has_dependent_backups: has_dependent_backups
- volume_id: volume_id
- container: container
- size: size
- id: id_backup
- is_incremental: is_incremental
- data_timestamp: data_timestamp
- snapshot_id: snapshot_id_source_vol
- os-backup-project-attr:project_id: os-backup-project-attr:project_id
- count: count
- metadata: metadata_backup
- user_id: user_id_backup
- encryption_key_id: encryption_key_id
Response Example
----------------
.. literalinclude:: ./samples/backups-list-detailed-response.json
:language: javascript
Show backup detail
~~~~~~~~~~~~~~~~~~
.. rest_method:: GET /v3/{project_id}/backups/{backup_id}
Shows details for a backup.
Response codes
--------------
.. rest_status_code:: success ../status.yaml
- 200
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- backup_id: backup_id_required
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- backup: backup
- status: status_backup
- object_count: object_count
- container: container
- description: description
- links: links_backup
- availability_zone: availability_zone
- created_at: created_at
- updated_at: updated_at
- name: name_backup
- has_dependent_backups: has_dependent_backups
- volume_id: volume_id
- fail_reason: fail_reason
- size: size
- backup: backup
- id: id_backup
- is_incremental: is_incremental
- data_timestamp: data_timestamp
- snapshot_id: snapshot_id_source_vol
- os-backup-project-attr:project_id: os-backup-project-attr:project_id
- metadata: metadata_backup
- user_id: user_id_backup
- encryption_key_id: encryption_key_id
Response Example
----------------
.. literalinclude:: ./samples/backup-show-response.json
:language: javascript
Delete a backup
~~~~~~~~~~~~~~~
.. rest_method:: DELETE /v3/{project_id}/backups/{backup_id}
Deletes a backup.
Response codes
--------------
.. rest_status_code:: success ../status.yaml
- 202
.. rest_status_code:: error ../status.yaml
- 400
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- backup_id: backup_id_required
Restore a backup
~~~~~~~~~~~~~~~~
.. rest_method:: POST /v3/{project_id}/backups/{backup_id}/restore
Restores a Block Storage backup to an existing or new Block Storage volume.
The name parameter will work only if a new volume is created.
If UUID is specified, the backup will be restored to the specified volume.
The specified volume has the following requirements:
* the specified volume status is ``available``.
* the size of specified volume must be equal to or greater than the size of
backup.
If no existing volume UUID is provided, the backup will be restored to a
new volume matching the size and name of the originally backed up volume.
In this case, if the name parameter is provided, it will be used as the
name of the new volume.
Response codes
--------------
.. rest_status_code:: success ../status.yaml
- 202
.. rest_status_code:: error ../status.yaml
- 400
- 413
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- backup_id: backup_id_required
- restore: restore
- name: volume_name_optional
- volume_id: volume_id_restore
Request Example
---------------
.. literalinclude:: ./samples/backup-restore-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- restore: restore
- backup_id: backup_id_required
- volume_id: volume_id
- volume_name: volume_name
Response Example
----------------
.. literalinclude:: ./samples/backup-restore-response.json
:language: javascript
Create a backup
~~~~~~~~~~~~~~~
.. rest_method:: POST /v3/{project_id}/backups
Creates a Block Storage backup from a volume or snapshot.
The status of the volume must be ``available`` or if the ``force`` flag is
used, backups of ``in-use`` volumes may also be created.
Response codes
--------------
.. rest_status_code:: success ../status.yaml
- 202
.. rest_status_code:: error ../status.yaml
- 400
- 500
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- backup: backup
- volume_id: volume_id_backup
- container: container
- description: description
- incremental: incremental
- force: force
- name: name_optional
- snapshot_id: snapshot_id_backup
- metadata: metadata_backup
- availability_zone: availability_zone_backup
Request Example
---------------
.. literalinclude:: ./samples/backup-create-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- backup: backup
- id: id_backup
- links: links_backup
- name: name_backup
- metadata: metadata_backup
Response Example
----------------
.. literalinclude:: ./samples/backup-create-response.json
:language: javascript
Update a backup
~~~~~~~~~~~~~~~
.. rest_method:: PUT /v3/{project_id}/backups/{backup_id}
Update a Block Storage backup. This API is available since v3.9.
Response codes
--------------
.. rest_status_code:: success ../status.yaml
- 200
.. rest_status_code:: error ../status.yaml
- 400
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- backup_id: backup_id_required
- backup: backup
- description: description
- name: name_optional
- metadata: metadata_backup
Request Example
---------------
.. literalinclude:: ./samples/backup-update-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- backup: backup
- id: id_backup
- links: links_backup
- name: name_backup
- metadata: metadata_backup
Response Example
----------------
.. literalinclude:: ./samples/backup-update-response.json
:language: javascript
List backups for project
~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: GET /v3/{project_id}/backups
Lists Block Storage backups to which the project has access,
since v3.31 if non-admin users specify invalid filters in the
url, API will return bad request.
Response codes
--------------
.. rest_status_code:: success ../status.yaml
- 200
.. rest_status_code:: error ../status.yaml
- 400
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- all_tenants: all-tenants
- sort: sort
- limit: limit
- marker: marker
- with_count: with_count
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- backups: backups
- id: id_backup
- links: links_backup
- name: name_backup
- count: count
Response Example
----------------
.. literalinclude:: ./samples/backups-list-response.json
:language: javascript
Export a backup
~~~~~~~~~~~~~~~
.. rest_method:: GET /v3/{project_id}/backups/{backup_id}/export_record
Export information about a backup.
Response codes
--------------
.. rest_status_code:: success ../status.yaml
- 200
.. rest_status_code:: error ../status.yaml
- 400
- 404
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- backup_id: backup_id_required
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- backup-record: backup_record
- backup_service: backup_service
- backup_url: backup_url
Response Example
----------------
.. literalinclude:: ./samples/backup-record-export-response.json
:language: javascript
Import a backup
~~~~~~~~~~~~~~~
.. rest_method:: POST /v3/{project_id}/backups/{backup_id}/import_record
Import information about a backup.
Response codes
--------------
.. rest_status_code:: success ../status.yaml
- 201
.. rest_status_code:: error ../status.yaml
- 400
- 503
Request
-------
.. rest_parameters:: parameters.yaml
- project_id: project_id_path
- backup_id: backup_id_required
- backup-record: backup_record
- backup_service: backup_service
- backup_url: backup_url
Request Example
---------------
.. literalinclude:: ./samples/backup-record-import-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- id: id_backup
- links: links_backup
- name: name_backup
Response Example
----------------
.. literalinclude:: ./samples/backup-record-import-response.json
View Git Blame Copy Permalink