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