cinder/api-ref/source/v3/attachments.inc
TommyLike 6c9ec93a83 Update attachment create API document
Add 'mode' parameter to request body of
attachment create API.

Change-Id: I109e26837f107d2060f2c2f0ba9c94488e76b730
2018-07-19 01:21:43 +00:00

384 lines
7.8 KiB
ReStructuredText

.. -*- rst -*-
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.
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_1
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_1
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- status: status_9
- detached_at: detached_at
- connection_info: connection_info
- attached_at: attached_at
- attach_mode: attach_mode
- instance: instance_uuid_1
- volume_id: volume_id_7
- id: attachment_id_2
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
- limit: limit
- offset: offset
- marker: marker
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- status: status_9
- detached_at: detached_at
- connection_info: connection_info
- attached_at: attached_at
- attach_mode: attach_mode
- instance: instance_uuid_1
- volume_id: volume_id_7
- id: attachment_id_2
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
- limit: limit
- offset: offset
- marker: marker
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- status: status_9
- instance: instance_uuid_1
- volume_id: volume_id_7
- id: attachment_id_2
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_1
- connector: connector
- volume_uuid: volume_id_7
- mode: attach_mode_1
Request Example
---------------
.. literalinclude:: ./samples/attachment-create-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- attachment: attachment
- status: status_9
- detached_at: detached_at
- connection_info: connection_info
- attached_at: attached_at
- attach_mode: attach_mode
- instance: instance_uuid_1
- volume_id: volume_id_7
- id: attachment_id_2
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_1
- attachement: attachment
- connector: connector_1
Request Example
---------------
.. literalinclude:: ./samples/attachment-update-request.json
:language: javascript
Response Parameters
-------------------
.. rest_parameters:: parameters.yaml
- attachment: attachment
- status: status_9
- detached_at: detached_at
- connection_info: connection_info
- attached_at: attached_at
- attach_mode: attach_mode
- instance: instance_uuid_1
- volume_id: volume_id_7
- id: attachment_id_2
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_1
Request Example
---------------
.. literalinclude:: ./samples/attachment-complete.json
:language: javascript