.. -*- rst -*- Volume snapshots (snapshots) ============================ A snapshot is a point-in-time copy of the data that a volume contains. When you create, list, or delete snapshots, these status values are possible: **Snapshot statuses** +----------------+---------------------------------------------+ | Status | Description | +----------------+---------------------------------------------+ | creating | The snapshot is being created. | +----------------+---------------------------------------------+ | available | The snapshot is ready to use. | +----------------+---------------------------------------------+ | backing-up | The snapshot is being backed up. | +----------------+---------------------------------------------+ | deleting | The snapshot is being deleted. | +----------------+---------------------------------------------+ | error | A snapshot creation error occurred. | +----------------+---------------------------------------------+ | deleted | The snapshot has been deleted. | +----------------+---------------------------------------------+ | unmanaging | The snapshot is being unmanaged. | +----------------+---------------------------------------------+ | restoring | The snapshot is being restored to a volume. | +----------------+---------------------------------------------+ | error_deleting | A snapshot deletion error occurred. | +----------------+---------------------------------------------+ List snapshots and details ~~~~~~~~~~~~~~~~~~~~~~~~~~ .. rest_method:: GET /v3/{project_id}/snapshots/detail Lists all Block Storage snapshots, with details, that the project can 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 - sort_key: sort_key - sort_dir: sort_dir - limit: limit - offset: offset - marker: marker - with_count: with_count - consumes_quota: filter_consumes_quota Response Parameters ------------------- .. rest_parameters:: parameters.yaml - status: status_snap - os-extended-snapshot-attributes:progress: os-ext-snap-attr:progress - description: description_snap_req - created_at: created_at - name: name - user_id: user_id_min - volume_id: volume_id_snap - os-extended-snapshot-attributes:project_id: os-ext-snap-attr:project_id - size: size - id: id_snap - metadata: metadata - count: count - updated_at: updated_at - snapshots_links: links_snap - group_snapshot_id: group_snapshot_id_3_14 - consumes_quota: consumes_quota Response Example (v3.65) ------------------------ .. literalinclude:: ./samples/snapshots/v3.65/snapshots-list-detailed-response.json :language: javascript Create a snapshot ~~~~~~~~~~~~~~~~~ .. rest_method:: POST /v3/{project_id}/snapshots Creates a volume snapshot, which is a point-in-time, complete copy of a volume. You can create a volume from a snapshot. Prior to API version 3.66, a 'force' flag was required to create a snapshot of an in-use volume, but this is no longer the case. From API version 3.66, the 'force' flag is invalid when passed in a volume snapshot request. (For backward compatibility, however, a 'force' flag with a value evaluating to True is silently ignored.) Response codes -------------- .. rest_status_code:: success ../status.yaml - 202 Request ------- .. rest_parameters:: parameters.yaml - project_id: project_id_path - snapshot: snapshot_obj - volume_id: volume_id - name: name_snap_req - description: description_snap - force: force_snapshot - metadata: metadata_snap Request Example --------------- .. literalinclude:: ./samples/snapshots/snapshot-create-request.json :language: javascript Response Parameters ------------------- .. rest_parameters:: parameters.yaml - status: status_snap - description: description_snap_req - created_at: created_at - name: name_snap_req - snapshot: snapshot_obj - user_id: user_id_min - volume_id: volume_id_snap - metadata: metadata - id: id_snap - size: size - updated_at: updated_at - group_snapshot_id: group_snapshot_id_3_14 - consumes_quota: consumes_quota Response Example (v3.65) ------------------------ .. literalinclude:: ./samples/snapshots/v3.65/snapshot-create-response.json :language: javascript List accessible snapshots ~~~~~~~~~~~~~~~~~~~~~~~~~ .. rest_method:: GET /v3/{project_id}/snapshots Lists all Block Storage snapshots, with summary information, that the project can 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 - sort_key: sort_key - sort_dir: sort_dir - limit: limit - offset: offset - marker: marker - consumes_quota: filter_consumes_quota - with_count: with_count Response Parameters ------------------- .. rest_parameters:: parameters.yaml - status: status_snap - description: description_snap_req - created_at: created_at - name: name - volume_id: volume_id_snap - metadata: metadata - id: id_snap - size: size - count: count - updated_at: updated_at - snapshots_links: links_snap Response Example ---------------- .. literalinclude:: ./samples/snapshots/snapshots-list-response.json :language: javascript Show a snapshot's metadata ~~~~~~~~~~~~~~~~~~~~~~~~~~ .. rest_method:: GET /v3/{project_id}/snapshots/{snapshot_id}/metadata Shows metadata for a snapshot. Response codes -------------- .. rest_status_code:: success ../status.yaml - 200 Request ------- .. rest_parameters:: parameters.yaml - project_id: project_id_path - snapshot_id: snapshot_id_path Response Parameters ------------------- .. rest_parameters:: parameters.yaml - metadata: metadata Response Example ---------------- .. literalinclude:: ./samples/snapshots/snapshot-metadata-show-response.json :language: javascript Create a snapshot's metadata ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. rest_method:: POST /v3/{project_id}/snapshots/{snapshot_id}/metadata Updates metadata for a snapshot. Creates or replaces metadata items that match keys. Does not modify items that are not in the request. Response codes -------------- .. rest_status_code:: success ../status.yaml - 200 Request ------- .. rest_parameters:: parameters.yaml - project_id: project_id_path - snapshot_id: snapshot_id_path - metadata: metadata Request Example --------------- .. literalinclude:: ./samples/snapshots/snapshot-metadata-create-request.json :language: javascript Response Parameters ------------------- .. rest_parameters:: parameters.yaml - metadata: metadata Response Example ---------------- .. literalinclude:: ./samples/snapshots/snapshot-metadata-create-response.json :language: javascript Update a snapshot's metadata ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. rest_method:: PUT /v3/{project_id}/snapshots/{snapshot_id}/metadata Replaces all the snapshot's metadata with the key-value pairs in the request. Response codes -------------- .. rest_status_code:: success ../status.yaml - 200 Request ------- .. rest_parameters:: parameters.yaml - project_id: project_id_path - snapshot_id: snapshot_id_path - metadata: metadata Request Example --------------- .. literalinclude:: ./samples/snapshots/snapshot-metadata-update-request.json :language: javascript Response Parameters ------------------- .. rest_parameters:: parameters.yaml - metadata: metadata Response Example ---------------- .. literalinclude:: ./samples/snapshots/snapshot-metadata-update-response.json :language: javascript Show a snapshot's details ~~~~~~~~~~~~~~~~~~~~~~~~~ .. rest_method:: GET /v3/{project_id}/snapshots/{snapshot_id} Shows details for a snapshot. Response codes -------------- .. rest_status_code:: success ../status.yaml - 200 Request ------- .. rest_parameters:: parameters.yaml - project_id: project_id_path - snapshot_id: snapshot_id_path Response Parameters ------------------- .. rest_parameters:: parameters.yaml - status: status_snap - os-extended-snapshot-attributes:progress: os-ext-snap-attr:progress - description: description_snap_req - created_at: created_at - name: name - snapshot: snapshot_obj - user_id: user_id_min - volume_id: volume_id_snap - os-extended-snapshot-attributes:project_id: os-ext-snap-attr:project_id - size: size - id: id_snap - metadata: metadata - updated_at: updated_at - group_snapshot_id: group_snapshot_id_3_14 - consumes_quota: consumes_quota Response Example (v3.65) ------------------------ .. literalinclude:: ./samples/snapshots/v3.65/snapshot-show-response.json :language: javascript Update a snapshot ~~~~~~~~~~~~~~~~~ .. rest_method:: PUT /v3/{project_id}/snapshots/{snapshot_id} Updates a snapshot. Response codes -------------- .. rest_status_code:: success ../status.yaml - 200 Request ------- .. rest_parameters:: parameters.yaml - project_id: project_id_path - snapshot_id: snapshot_id_path - snapshot: snapshot_obj - description: description_snap - name: snapshot_name Request Example --------------- .. literalinclude:: ./samples/snapshots/snapshot-update-request.json :language: javascript Response Parameters ------------------- .. rest_parameters:: parameters.yaml - status: status_snap - description: description_snap_req - created_at: created_at - name: name - snapshot: snapshot_obj - id: id_snap - size: size - volume_id: volume_id_snap - user_id: user_id_min - metadata: metadata - group_snapshot_id: group_snapshot_id_3_14 - consumes_quota: consumes_quota Response Example (v3.65) ------------------------ .. literalinclude:: ./samples/snapshots/v3.65/snapshot-update-response.json :language: javascript Delete a snapshot ~~~~~~~~~~~~~~~~~ .. rest_method:: DELETE /v3/{project_id}/snapshots/{snapshot_id} Deletes a snapshot. Preconditions: - Snapshot status must be ``available`` or ``error`` Response codes -------------- .. rest_status_code:: success ../status.yaml - 202 .. rest_status_code:: error ../status.yaml - 400 - 403 - 404 Request ------- .. rest_parameters:: parameters.yaml - project_id: project_id_path - snapshot_id: snapshot_id_path Show a snapshot's metadata for a specific key ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. rest_method:: GET /v3/{project_id}/snapshot/{snapshot_id}/metadata/{key} Shows metadata for a snapshot for a specific key. Response codes -------------- .. rest_status_code:: success ../status.yaml - 200 Request ------- .. rest_parameters:: parameters.yaml - project_id: project_id_path - snapshot_id: snapshot_id_path - key: key_view Response Parameters ------------------- .. rest_parameters:: parameters.yaml - meta: meta_snap Response Example ---------------- .. literalinclude:: ./samples/snapshots/snapshot-metadata-show-key-response.json :language: javascript Delete a snapshot's metadata ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. rest_method:: DELETE /v3/{project_id}/snapshots/{snapshot_id}/metadata/{key} Deletes metadata for a snapshot. Response codes -------------- .. rest_status_code:: success ../status.yaml - 200 Request ------- .. rest_parameters:: parameters.yaml - project_id: project_id_path - snapshot_id: snapshot_id_path - key: key_path Update a snapshot's metadata for a specific key ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. rest_method:: PUT /v3/{project_id}/snapshots/{snapshot_id}/metadata/{key} Update metadata for a snapshot for a specific key. Response codes -------------- .. rest_status_code:: success ../status.yaml - 200 Request ------- .. rest_parameters:: parameters.yaml - project_id: project_id_path - snapshot_id: snapshot_id_path - key: key_update - meta: meta_snap Request Example --------------- .. literalinclude:: ./samples/snapshots/snapshot-metadata-update-key-request.json :language: javascript Response Parameters ------------------- .. rest_parameters:: parameters.yaml - meta: meta_snap Response Example ---------------- .. literalinclude:: ./samples/snapshots/snapshot-metadata-update-key-response.json :language: javascript