1..
2      Licensed under the Apache License, Version 2.0 (the "License"); you may
3      not use this file except in compliance with the License. You may obtain
4      a copy of the License at
5
6          http://www.apache.org/licenses/LICENSE-2.0
7
8      Unless required by applicable law or agreed to in writing, software
9      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
10      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
11      License for the specific language governing permissions and limitations
12      under the License.
13
14==================================
15Volume Attach/Detach workflow - V2
16==================================
17
18Previously there were six API calls associated with attach/detach of volumes in
19Cinder (3 calls for each operation).  As the projects grew and the
20functionality of *simple* things like attach/detach evolved things have become
21a bit vague and we have a number of race issues during the calls that
22continually cause us some problems.
23
24Additionally, the existing code path makes things like multi-attach extremely
25difficult to implement due to no real good tracking mechanism of attachment
26info.
27
28To try and improve this we've proposed a new Attachments Object and API.  Now
29we keep an Attachment record for each attachment that we want to perform as
30opposed to trying to infer the information from the Volume Object.
31
32Attachment Object
33=================
34
35We actually already had a VolumeAttachment Table in the db, however we
36weren't really using it, or at least using it efficiently. For V2 of attach
37implementation (V3 API) flow we'll use the Attachment Table (object) as
38the primary handle for managing attachment(s) for a volume.
39
40In addition, we also introduce the AttachmentSpecs Table which will store the
41connector information for an Attachment so we no longer have the problem of
42lost connector info, or trying to reassemble it.
43
44New API and Flow
45================
46
47attachment-create
48-----------------
49
50```
51cinder --os-volume-api-version 3.27 attachment-create <volume-id> <instance-uuid>
52```
53
54The attachment_create call simply creates an empty Attachment record for the
55specified Volume with an Instance UUID field set.  This is particularly
56useful for cases like Nova Boot from Volume where Nova hasn't sent
57the job to the actual Compute host yet, but needs to make initial preparations
58to reserve the volume for use, so here we can reserve the volume and indicate
59that we will be attaching it to <Instance-UUID> in the future.
60
61Alternatively, the caller may provide a connector in which case the Cinder API
62will create the attachment and perform the update on the attachment to set the
63connector info and return the connection data needed to make a connection.
64
65The attachment_create call can be used in one of two ways:
66
671. Create an empty Attachment object (reserve). In this case the
68   attachment_create call requires an instance_uuid and a volume_uuid,
69   and just creates an empty Attachment object and returns the UUID of
70   Attachment to the caller.
71
722. Create and complete the Attachment process in one call.  The reserve process
73   is only needed in certain cases, in many cases Nova actually has enough
74   information to do everything in a single call.  Also, non-nova consumers
75   typically don't require the granularity of a separate reserve at all.
76
77   To perform the complete operation, include the connector data in the
78   attachment_create call and the Cinder API will perform the reserve and
79   initialize the connection in the single request.
80
81This full usage of attachment-create would be::
82
83  usage: cinder --os-volume-api-version 3.27 attachment-create
84         <volume>  <instance_uuid> ...
85
86  Positional arguments:
87  <volume>                  Name or ID of volume or volumes to attach.
88  <instance_uuid>           ID of instance attaching to.
89
90  Optional arguments:
91  --connect <connect>       Make an active connection using provided connector info (True or False).
92  --initiator <initiator>   iqn of the initiator attaching to. Default=None.
93  --ip <ip>                 ip of the system attaching to. Default=None.
94  --host <host>             Name of the host attaching to. Default=None.
95  --platform <platform>     Platform type. Default=x86_64.
96  --ostype <ostype>         OS type. Default=linux2.
97  --multipath <multipath>   Use multipath. Default=False.
98  --mountpoint <mountpoint> Mountpoint volume will be attached at. Default=None.
99
100Returns the connection information for the attachment::
101
102  +-------------------+-----------------------------------------------------------------------+
103  | Property          | Value                                                                 |
104  +-------------------+-----------------------------------------------------------------------+
105  | access_mode       | rw                                                                    |
106  | attachment_id     | 6ab061ad-5c45-48f3-ad9c-bbd3b6275bf2                                  |
107  | auth_method       | CHAP                                                                  |
108  | auth_password     | kystSioDKHSV2j9y                                                      |
109  | auth_username     | hxGUgiWvsS4GqAQcfA78                                                  |
110  | encrypted         | False                                                                 |
111  | qos_specs         | None                                                                  |
112  | target_discovered | False                                                                 |
113  | target_iqn        | iqn.2010-10.org.openstack:volume-23212c97-5ed7-42d7-b433-dbf8fc38ec35 |
114  | target_lun        | 0                                                                     |
115  | target_portal     | 192.168.0.9:3260                                                      |
116  | volume_id         | 23212c97-5ed7-42d7-b433-dbf8fc38ec35                                  |
117  +-------------------+-----------------------------------------------------------------------+
118
119attachment-update
120-----------------
121
122```
123cinder --os-volume-api-version 3.27 attachment-update <attachment-id>
124```
125
126Once we have a reserved volume, this CLI can be used to update an attachment for a cinder volume.
127This call is designed to be more of an attachment completion than anything else.
128It expects the value of a connector object to notify the driver that the volume is going to be
129connected and where it's being connected to. The usage is the following::
130
131  usage: cinder --os-volume-api-version 3.27 attachment-update
132         <attachment-id> ...
133
134  Positional arguments:
135    <attachment-id>           ID of attachment.
136
137  Optional arguments:
138    --initiator <initiator>   iqn of the initiator attaching to. Default=None.
139    --ip <ip>                 ip of the system attaching to. Default=None.
140    --host <host>             Name of the host attaching to. Default=None.
141    --platform <platform>     Platform type. Default=x86_64.
142    --ostype <ostype>         OS type. Default=linux2.
143    --multipath <multipath>   Use multipath. Default=False.
144    --mountpoint <mountpoint> Mountpoint volume will be attached at. Default=None.
145
146attachment-delete
147-----------------
148
149```
150cinder --os-volume-api-version 3.27 attachment-delete <attachment-id>
151```
152
153