Add attachment API doc

Add attachment API related Docs, please note we
use 'instance_uuid' in the request and 'instance' in
the response to represent the same thing 'server_id'.

DocImpact

Change-Id: I8bd5a9061af2b47fd227e8cf2f48f80f271bde14

api-ref/source/v3/attachments.inc

@@ -0,0 +1,251 @@
+.. -*- rst -*-
+
+Attachments
+===========
+
+Lists all, lists all with details, shows details for, creates, and
+deletes attachment.
+
+
+Delete attachment
+~~~~~~~~~~~~~~~~~
+
+.. rest_method::  DELETE /v3/{project_id}/attachments/{attachment_id}
+
+Deletes an attachment.
+
+Normal response codes: 202
+Error response codes: badRequest(400), itemNotFound(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.
+
+
+Normal response codes: 200
+Error response codes: badRequest(400), itemNotFound(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
+   - 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.
+
+
+Normal response codes: 200
+Error response codes:
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - project_id: project_id_path
+   - sort_key: sort_key
+   - sort_dir: sort_dir
+   - 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
+   - 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.
+
+
+Normal response codes: 200
+Error response codes:
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - project_id: project_id_path
+   - sort_key: sort_key
+   - sort_dir: sort_dir
+   - limit: limit
+   - offset: offset
+   - marker: marker
+
+
+Response Parameters
+-------------------
+
+.. rest_parameters:: parameters.yaml
+
+   - status: status_9
+   - instance: instance_uuid
+   - 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.
+
+Normal response codes: 202
+Error response codes: badRequest(400), itemNotFound(404)
+
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - project_id: project_id_path
+   - instance_uuid: instance_uuid_1
+   - connector: connector
+   - volume_uuid: volume_id_7
+
+Request Example
+---------------
+
+.. literalinclude:: ./samples/attachment-create-request.json
+   :language: javascript
+
+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
+   - 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.
+
+Normal response codes: 202
+Error response codes: badRequest(400), itemNotFound(404)
+
+Request
+-------
+
+.. rest_parameters:: parameters.yaml
+
+   - project_id: project_id_path
+   - attachment_id: attachment_id_1
+   - connector: connector
+
+Request Example
+---------------
+
+.. literalinclude:: ./samples/attachment-update-request.json
+   :language: javascript
+
+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
+   - volume_id: volume_id_7
+   - id: attachment_id_2
+
+Response Example
+----------------
+
+.. literalinclude:: ./samples/attachment-update-response.json
+   :language: javascript

api-ref/source/v3/index.rst

@@ -7,6 +7,7 @@ Block Storage API V3 (CURRENT)
 .. rest_expand_all::
 
 .. include:: api-versions.inc
+.. include:: attachments.inc
 .. include:: ext-backups.inc
 .. include:: ext-backups-actions-v3.inc
 .. include:: capabilities-v3.inc

api-ref/source/v3/parameters.yaml

@@ -19,6 +19,12 @@ all_tenants:
   in: path
   required: false
   type: string
+attachment_id_1:
+  description: |
+    The ID of the attachment.
+  in: path
+  required: true
+  type: string
 backup_id:
   description: |
     The UUID for a backup.
@@ -296,18 +302,37 @@ alias:
   in: body
   required: true
   type: string
+attach_mode:
+  description: |
+    The attach mode of attachment, read-only ('ro') or
+    read-and-write ('rw'), default is 'ro'.
+  in: body
+  required: false
+  type: string
 attach_status:
   description: |
     The volume attach status.
   in: body
   required: false
   type: string
+attached_at:
+  description: |
+    The time when attachment is attached.
+  in: body
+  required: false
+  type: string
 attachment_id:
   description: |
     The interface ID.
   in: body
   required: false
   type: string
+attachment_id_2:
+  description: |
+    The ID of attachment.
+  in: body
+  required: true
+  type: string
 attachments:
   description: |
     Instance attachment information.  If this volume
@@ -402,6 +427,12 @@ cluster_mutex:
   in: body
   required: false
   type: string
+connection_info:
+  description: |
+    The connection info used for server to connect the volume.
+  in: body
+  required: true
+  type: object
 connector:
   description: |
     The ``connector`` object.
@@ -601,6 +632,12 @@ description_9:
   in: body
   required: true
   type: string
+detached_at:
+  description: |
+    The time when attachment is detached.
+  in: body
+  required: false
+  type: string
 display_name:
   description: |
     The name of volume backend capabilities.
@@ -873,6 +910,12 @@ instance_uuid:
   in: body
   required: false
   type: string
+instance_uuid_1:
+  description: |
+    The UUID of the attaching instance.
+  in: body
+  required: true
+  type: string
 instances:
   description: |
     The number of instances that are allowed for each
@@ -1698,6 +1741,12 @@ status_8:
   in: body
   required: true
   type: string
+status_9:
+  description: |
+    The status of the attachment.
+  in: body
+  required: true
+  type: string
 storage_protocol:
   description: |
     The storage back end for the back-end volume. For
@@ -1885,6 +1934,13 @@ volume_id_6:
   in: body
   required: false
   type: string
+volume_id_7:
+  description: |
+    The UUID of the volume which the attachment belongs
+    to.
+  in: body
+  required: true
+  type: string
 volume_type_1:
   description: |
     A ``volume_type`` object.

api-ref/source/v3/samples/attachment-create-request.json

@@ -0,0 +1,16 @@
+{
+    "attachment": {
+        "instance_uuid": "462dcc2d-130d-4654-8db1-da0df2da6a0d",
+        "connector": {
+            "initiator": "iqn.1993-08.org.debian: 01: cad181614cec",
+            "ip": "192.168.1.20",
+            "platform": "x86_64",
+            "host": "tempest-1",
+            "os_type": "linux2",
+            "multipath": false,
+            "mountpoint": "/dev/vdb",
+            "mode": "ro"
+        },
+        "volume_uuid": "462dcc2d-130d-4654-8db1-da0df2da6a0d"
+    }
+}

api-ref/source/v3/samples/attachment-create-response.json

@@ -0,0 +1,12 @@
+{
+    "attachment": {
+        "status": "attaching",
+        "detached_at": "2015-09-16T09:28:52.000000",
+        "connection_info": {},
+        "attached_at": "2015-09-16T09:28:52.000000",
+        "attach_mode": "ro",
+        "instance": "3b8b6631-1cf7-4fd7-9afb-c01e541as345",
+        "volume_id": "462dcc2d-130d-4654-8db1-da0df2da6a0d",
+        "id": "3b8b6631-1cf7-4fd7-9afb-c01e541a073c"
+    }
+}

api-ref/source/v3/samples/attachment-list-detailed-response.json

@@ -0,0 +1,14 @@
+{
+    "attachments": [
+        {
+            "status": "attaching",
+            "detached_at": "2015-09-16T09:28:52.000000",
+            "connection_info": {},
+            "attached_at": "2015-09-16T09:28:52.000000",
+            "attach_mode": "ro",
+            "instance": "31c79baf-b59e-469c-979f-1df4ecb6eea7",
+            "volume_id": "462dcc2d-130d-4654-8db1-da0df2da6a0d",
+            "id": "3b8b6631-1cf7-4fd7-9afb-c01e541a073c"
+        }
+    ]
+}

api-ref/source/v3/samples/attachment-list-response.json

@@ -0,0 +1,10 @@
+{
+  "attachments": [
+    {
+      "status": "attaching",
+      "instance": "31c79baf-b59e-469c-979f-1df4ecb6eea7",
+      "id": "3b8b6631-1cf7-4fd7-9afb-c01e541a073c",
+      "volume_id": "462dcc2d-130d-4654-8db1-da0df2da6a0d"
+    }
+  ]
+}

api-ref/source/v3/samples/attachment-show-response.json

@@ -0,0 +1,12 @@
+{
+    "attachment": {
+        "status": "attaching",
+        "detached_at": "2015-09-16T09:28:52.000000",
+        "connection_info": {},
+        "attached_at": "2015-09-16T09:28:52.000000",
+        "attach_mode": "ro",
+        "instance": "3b8b6631-1cf7-4fd7-9afb-c01e541as345",
+        "volume_id": "462dcc2d-130d-4654-8db1-da0df2da6a0d",
+        "id": "3b8b6631-1cf7-4fd7-9afb-c01e541a073c"
+    }
+}

api-ref/source/v3/samples/attachment-update-request.json

@@ -0,0 +1,14 @@
+{
+    "attachment": {
+        "connector": {
+            "initiator": "iqn.1993-08.org.debian: 01: cad181614cec",
+            "ip": "192.168.1.20",
+            "platform": "x86_64",
+            "host": "tempest-1",
+            "os_type": "linux2",
+            "multipath": false,
+            "mountpoint": "/dev/vdb",
+            "mode": "ro"
+        }
+    }
+}

api-ref/source/v3/samples/attachment-update-response.json

@@ -0,0 +1,12 @@
+{
+    "attachment": {
+        "status": "attaching",
+        "detached_at": "2015-09-16T09:28:52.000000",
+        "connection_info": {},
+        "attached_at": "2015-09-16T09:28:52.000000",
+        "attach_mode": "ro",
+        "instance": "3b8b6631-1cf7-4fd7-9afb-c01e541as345",
+        "volume_id": "462dcc2d-130d-4654-8db1-da0df2da6a0d",
+        "id": "3b8b6631-1cf7-4fd7-9afb-c01e541a073c"
+    }
+}