.. -*- rst -*- Attachments (attachments) ========================= Lists all, lists all with details, shows details for, creates, and deletes attachment. .. note:: Everything except for `Complete attachment` is new as of the 3.27 microversion. `Complete attachment` is new as of the 3.44 microversion. When you create, list, update, or delete attachment, the possible status values are: **VolumeAttachment statuses** +------------------+--------------------------------------------------------+ | Status | Description | +------------------+--------------------------------------------------------+ | attached | A volume is attached for the attachment. | +------------------+--------------------------------------------------------+ | attaching | A volume is attaching for the attachment. | +------------------+--------------------------------------------------------+ | detached | A volume is detached for the attachment. | +------------------+--------------------------------------------------------+ | reserved | A volume is reserved for the attachment. | +------------------+--------------------------------------------------------+ | error_attaching | A volume is error attaching for the attachment. | +------------------+--------------------------------------------------------+ | error_detaching | A volume is error detaching for the attachment. | +------------------+--------------------------------------------------------+ | deleted | The attachment is deleted. | +------------------+--------------------------------------------------------+ Delete attachment ~~~~~~~~~~~~~~~~~ .. rest_method:: DELETE /v3/{project_id}/attachments/{attachment_id} Deletes an attachment. For security reasons (see bug `#2004555 `_) the Block Storage API rejects REST API calls manually made from users with a 409 status code if there is a Nova instance currently using the attachment, which happens when all the following conditions are met: - Attachment has an instance uuid - VM exists in Nova - Instance has the volume attached - Attached volume in instance is using the attachment Calls coming from other OpenStack services (like the Compute Service) are always accepted. Available starting in the 3.27 microversion. Response codes -------------- .. rest_status_code:: success ../status.yaml - 200 .. rest_status_code:: error ../status.yaml - 400 - 404 - 409 Request ------- .. rest_parameters:: parameters.yaml - project_id: project_id_path - attachment_id: attachment_id_path Show attachment details ~~~~~~~~~~~~~~~~~~~~~~~ .. rest_method:: GET /v3/{project_id}/attachments/{attachment_id} Shows details for an attachment. Available starting in the 3.27 microversion. 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 - attachment_id: attachment_id_path Response Parameters ------------------- .. rest_parameters:: parameters.yaml - status: status_attachment - detached_at: detached_at - connection_info: connection_info - attached_at: attached_at - attach_mode: attach_mode_required - instance: instance_uuid_req - volume_id: volume_id_attachment - id: attachment_id_required Response Example ---------------- .. literalinclude:: ./samples/attachment-show-response.json :language: javascript List attachments with details ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. rest_method:: GET /v3/{project_id}/attachments/detail Lists all attachments with details. Since v3.31 if non-admin users specify invalid filters in the url, API will return bad request. Available starting in the 3.27 microversion. 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 Response Parameters ------------------- .. rest_parameters:: parameters.yaml - status: status_attachment - detached_at: detached_at - connection_info: connection_info - attached_at: attached_at - attach_mode: attach_mode_required - instance: instance_uuid_req - volume_id: volume_id_attachment - id: attachment_id_required Response Example ---------------- .. literalinclude:: ./samples/attachment-list-detailed-response.json :language: javascript List attachments ~~~~~~~~~~~~~~~~ .. rest_method:: GET /v3/{project_id}/attachments Lists all attachments, since v3.31 if non-admin users specify invalid filters in the url, API will return bad request. Available starting in the 3.27 microversion. 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 Response Parameters ------------------- .. rest_parameters:: parameters.yaml - status: status_attachment - instance: instance_uuid_req - volume_id: volume_id_attachment - id: attachment_id_required Response Example ---------------- .. literalinclude:: ./samples/attachment-list-response.json :language: javascript Create attachment ~~~~~~~~~~~~~~~~~ .. rest_method:: POST /v3/{project_id}/attachments Creates an attachment. Available starting in the 3.27 microversion. 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 - attachment: attachment - instance_uuid: instance_uuid - connector: connector - volume_uuid: volume_id_attachment - mode: attach_mode Request Example --------------- .. literalinclude:: ./samples/attachment-create-request.json :language: javascript Response Parameters ------------------- .. rest_parameters:: parameters.yaml - attachment: attachment - status: status_attachment - detached_at: detached_at - connection_info: connection_info - attached_at: attached_at - attach_mode: attach_mode_required - instance: instance_uuid_req - volume_id: volume_id_attachment - id: attachment_id_required Response Example ---------------- .. literalinclude:: ./samples/attachment-create-response.json :language: javascript Update an attachment ~~~~~~~~~~~~~~~~~~~~ .. rest_method:: PUT /v3/{project_id}/attachments/{attachment_id} Update a reserved attachment record with connector information and set up the appropriate connection_info from the driver. Available starting in the 3.27 microversion. 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 - attachment_id: attachment_id_path - attachement: attachment - connector: connector_required Request Example --------------- .. literalinclude:: ./samples/attachment-update-request.json :language: javascript Response Parameters ------------------- .. rest_parameters:: parameters.yaml - attachment: attachment - status: status_attachment - detached_at: detached_at - connection_info: connection_info - attached_at: attached_at - attach_mode: attach_mode_required - instance: instance_uuid_req - volume_id: volume_id_attachment - id: attachment_id_required Response Example ---------------- .. literalinclude:: ./samples/attachment-update-response.json :language: javascript Complete attachment ~~~~~~~~~~~~~~~~~~~ .. rest_method:: POST /v3/{project_id}/attachments/{attachment_id}/action Complete an attachment for a cinder volume. Available starting in the 3.44 microversion. Response codes -------------- .. rest_status_code:: success ../status.yaml - 204 .. rest_status_code:: error ../status.yaml - 400 - 404 Request ------- .. rest_parameters:: parameters.yaml - project_id: project_id_path - attachment_id: attachment_id_path Request Example --------------- .. literalinclude:: ./samples/attachment-complete.json :language: javascript