diff --git a/specs/newton/list-manage-existing.rst b/specs/newton/list-manage-existing.rst new file mode 100644 index 00000000..0a774614 --- /dev/null +++ b/specs/newton/list-manage-existing.rst @@ -0,0 +1,178 @@ +.. + This work is licensed under a Creative Commons Attribution 3.0 Unported + License. + + http://creativecommons.org/licenses/by/3.0/legalcode + +======================================================== +List volumes and snapshots available for manage-existing +======================================================== + +https://blueprints.launchpad.net/cinder/+spec/list-manage-existing + +Cinder currently has the ability to take over the management of existing +volumes and snapshots ("manage existing") and to relinquish management of +volumes and snapshots ("unmanage"). The API to manage an existing volume takes +a reference, which is a driver-specific string that is used to identify the +volume on the storage backend. This process is currently confusing and error +prone. This spec's purpose is to detail APIs for listing volumes and snapshots +available for management to make this flow more user-friendly. Allowing the +listing of available volumes/snapshots will allow for the creation of an +easy-to-use GUI to migrate existing volumes to a new OpenStack environment, or +to recover in the case the Cinder database is lost. + +Problem description +=================== + +There is no Cinder API to list the volumes and snapshots available for +managing, nor to know what reference string to use without referring to +driver-specific documentation. This means that an admin must query the storage +backend, get the appropriate references, and put them into the appropriate +Cinder API. Without the proposed APIs this flow is confusing and error-prone. + +Use Cases +========= + +Having Cinder manage an existing block storage volume or snapshot, using only +Cinder APIs and without referring to external driver documentation. + +Proposed change +=============== + +Add new APIs to: +1) list volumes available for management in a given pool. +2) list snapshots available for management in a given pool. + +The APIs would return information regarding the volumes/snapshots, provided by +the driver. In addition, for each resource, an indication will be provided if +it is safe to manage it. The cinder-volume manager will call the appropriate +driver to get a list of resources. For each, the driver will return a safety +indication, which includes if a volume is attached, or a Cinder ID if it +suspects the resource is already managed by Cinder. The manager will look up +any resources suspected already in use in the DB and mark them as not safe +(this avoids the driver accessing the DB). + +A list of items will be returned to the user, consisting of: + +- *ref* (string): a backend-specific reference to the volume that will be + specified when the user wants to manage that volume. +- *size* (integer): the size of the volume, rounded up to Gigabytes, as an + OpenStack user would see it if the volume is managed. +- *actual_size* (integer): the size of the volume in bytes, which may not be a + precise Gigabyte multiple, as the volume was not created by OpenStack. +- *safe_to_manage* (boolean): True if a call to manage the volume specified by + host_ref is expected to be safe, False if it is known that it will not be + (for example, if the driver detects that the volume is attached, or + cinder-volume detects that it already manages the resource). +- *reason_not_safe* (string): If "safe_to_manage" is False, specifies why. +- *driver-specific key-value pairs* (list of string:string): Any additional + information that a driver may wish to return to help the admin identify the + volumes/snapshots, for example a description, timestamps, etc. + +For listing snapshots, return these additional fields: + +- *source_volume_ref* (string): The backend-specific reference of the volume + that is the source of the snapshot. +- *source_volume_id* (string): The Cinder volume ID of the volume that owns the + snapshot if the volume is already managed by Cinder. + +Alternatives +------------ + +Leave as is. + +Data model impact +----------------- + +None + +REST API impact +--------------- + +Add two additional API extensions. + +Security impact +--------------- + +Cinder currently has the ability to create objects in the storage pool, and +view or modify those objects. This allows the admin to view volumes not created +by Cinder. On the other hand, the admin can take the storage credentials that +Cinder has and perform the action on the storage backend itself, so there is no +real impact. + + +Notifications impact +-------------------- + +None + +Other end user impact +--------------------- + +None + +Performance Impact +------------------ + +None + +Other deployer impact +--------------------- + +None + +Developer impact +---------------- + +Driver maintainers can add the two new calls to bring this functionality to +their drivers. + + +Implementation +============== + +I propose that list_manageable be added as a new GET action on the +os-volume-manage Cinder extension.  It would be separately specifiable in +Cinder's policy.json file to restrict access appropriately (default being +admin_api). + +There would be new RPC calls to cinder-volume which would call two new driver +APIs (list_manageable_volumes and list_manageable_snapshots). I will implement +the LVM driver code as well, as a reference implementation. + +Assignee(s) +----------- + +Primary assignee: + avishay + +Work Items +---------- + +- Create APIs +- Create RPC calls +- Create driver interface +- Implement LVM reference +- Implement tempest test + +Dependencies +============ + +None + +Testing +======= + +Standard unit tests and manual testing, as well as tempest test for these +proposed APIs, as well as manage and unmanage. + +Documentation Impact +==================== + +The new APIs will be documented. + + +References +========== + +None