From d2c5c5b8922fdc08f3e0a0e9642da49bbca3d22f Mon Sep 17 00:00:00 2001 From: Avishay Traeger Date: Sun, 21 Feb 2016 08:11:45 +0200 Subject: [PATCH] List volumes/snapshots for 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. blueprint: list-manage-existing Change-Id: Ie2a22deaac61ffe3ca69f62012d4cf894638c83c --- specs/newton/list-manage-existing.rst | 178 ++++++++++++++++++++++++++ 1 file changed, 178 insertions(+) create mode 100644 specs/newton/list-manage-existing.rst 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