.. This work is licensed under a Creative Commons Attribution 3.0 Unported License. http://creativecommons.org/licenses/by/3.0/legalcode ======================= Add volume re-image API ======================= https://blueprints.launchpad.net/cinder/+spec/add-volume-re-image-api This blueprint proposes to add volume re-image API to enable the ability to re-image a specific volume. Problem description =================== Currently, users can create a volume with a specific image, but once this volume is created, the image of this volume can't be changed anymore. If users want to re-image a specific volume, they can only create a new volume with new image, and then delete the old volume, which is not very convenient. However, if the image-backed volume is already used as a boot volume which is already attached to a server, it makes the case more complicated, because changing the image in an attached root volume is `not supported`_. In addition, as mentioned in nova bp 'volume-backend-server-rebuild' [1]_, if users want to rebuild a volume-backed server, they can complete it by using re-image API, this way there is no new volume with new volume id, we don't have to worry about types, quota problem, etc. As the discussion result during Stein PTG [2]_, we would propose to implement a new API to support this. .. _not supported: https://review.openstack.org/#/c/520660/ Use Cases ========= * The user wants to re-image a volume without re-creating a new volume with new volume id. * Nova wants a new API to re-image an attached root volume when the server is rebuilt. Proposed change =============== This spec proposes to add a new 'os-reimage' action to volume actions API. * Add a new 'os-reimage' action to volume actions API. As mentioned above, the main purpose of this spec is for Nova's rebuild use case. In this case, nova will perform the following steps: #. Create an empty (no connector) volume attachment for the volume and server. This ensures the volume remains ``reserved`` through the next step. #. Delete the existing volume attachment (the old one). #. Call the new ``os-reimage`` API. #. Poll the volume status for completion (either success or failure). #. Upon successful completion of the re-image operation, update the empty volume attchment in Cinder, and then do the attachment on the Nova host when spawning the (rebuilt) guest VM and "complete" the attachment which will make the volume ``in-use`` again. So, we propose to add a new microversion to support users to re-image a specific volume with new image id. Only ``reserved``, ``available`` and ``error`` volume can be re-imaged. The ``reserved`` volume can only be re-imaged when the ``ignore_reserved`` parameter is ``True``. The volume state will be changed to ``downloading`` first. Two separate policies will be introduced, one for re-imaging an ``available`` or ``error`` volume and another for re-imaging an ``reserved`` volume, the default policies for these new actions are ``RULE_ADMIN_OR_OWNER``. If the image status is not ``active``, image size or image min_disk size is larger than volume size, will raise InvalidInput (400) error. * Add a new ``reimage`` cast rpc. This rpc is used to cast an async message from cinder API to the cinder-volume service or cluster. * Add a new method for volume manager. There will be a new method for volume manager which will be called 'reimage', this method will first download the image from glance and then perform the re-image operation. We propose to only support the basic implementation in this spec, the re-image method will call driver's 'copy_image_to_volume' to re-write the specific volume with new image. If the specific image is encrypted, then it will call driver's 'copy_image_to_encrypted_volume'. It's similar to what we have done when we create volume from image. After the re-image operation is complete, the volume will set back to original state, and all previously existing volume_glance_metadata of this volume will be replaced with the metadata from new image. * If the re-image operation fails, we will set a user message to give hints to the user how they can recover from a potentially now corrupt boot volume and the volume status will changed to ``error``. The latter part is important for the caller to know when to stop polling for the operation to complete. There are also some other optimized mechanisms that should be considered to support in future, but will not be implemented in this spec: * Re-image an ``in-use`` volume. If we want to support it, we should make sure this volume can be multi-attached, so that we can attach this volume to a host to support copy image to volume. And also re-image an ``in-use`` volume is a very dangerous operation, we must make sure there is no IO, onging or cached on VMs before we complete re-imaging, otherwise will damage the volume data. We will not support this operation in this spec. * Re-image a volume from image cache. Currently, Cinder supports creating a volume from image cache, which can improve the performance of creating a volume from an image, we can also consider to add this improvement in the advanced implementation. * Add image signature verification support when re-imaging a volume. There is also a signature when we create volume from image, we will also support it in the advanced implementation. This will be called out in the API reference documentation as a limitation until it is implemented. Alternatives ------------ If the users want to re-image a volume to same image, the users could revert the volume to a snapshot created after image. But for different image, the users could first delete the volume and then re-create a volume with a specific new image. And nova could orchestrate creating a new root volume with the new image, then replace it during the server rebuild operation, but there are several issue with that as mentioned above like quota and the questions about what nova should do about the old volume, you can see more detail information in ML [3]_. REST API impact --------------- * A new microversion will be created to support volume 'os-reimage' action API The rest API look like this in v3: .. code-block:: console POST /v3/{project_id}/volumes/{volume_id}/action .. code-block:: python { 'os-reimage': { 'image_id': "71543ced-a8af-45b6-a5c4-a46282108a90", 'ignore_reserved': false } } * The 'image_id' refers to the id of image. No default value since this is a required parameter. * The 'ignore_reserved' refers to re-image a volume and ignore its 'reserved' status. The 'available' and 'error' volume can be re-imaged directly, but the 'reserved' volume can only be re-imaged when this parameter is 'true'. Defaults to 'false', this is an optional parameter. The response body of it is like: .. code-block:: python { "volume": { "migration_status": null, "attachments": [ ], "links": [ { "href": "http://10.79.144.144/volume/v3/ffc60994a7274553905e5e5a8f890ab3/volumes/d90bfc0e-babf-4478-a591-23ca883ba2be", "rel": "self" }, { "href": "http://10.79.144.144/volume/ffc60994a7274553905e5e5a8f890ab3/volumes/d90bfc0e-babf-4478-a591-23ca883ba2be", "rel": "bookmark" } ], "availability_zone": "nova", "os-vol-host-attr:host": "ubuntubase@lvmdriver-1#lvmdriver-1", "encrypted": false, "updated_at": "2018-09-26T01:55:41.084080", "replication_status": null, "snapshot_id": null, "id": "d90bfc0e-babf-4478-a591-23ca883ba2be", "size": 2, "user_id": "f33299af48b44050b96bc51104f2290a", "os-vol-tenant-attr:tenant_id": "ffc60994a7274553905e5e5a8f890ab3", "os-vol-mig-status-attr:migstat": null, "metadata": { }, "status": "downloading", "volume_image_metadata": { "container_format": "bare", "min_ram": "0", "disk_format": "qcow2", "image_name": "cirros-0.3.5-x86_64-disk", "image_id": "24d0c0c3-9e03-498c-926f-ac964cbe2e08", "checksum": "f8ab98ff5e73ebab884d80c9dc9c7290", "min_disk": "0", "size": "13267968" }, "description": null, "multiattach": false, "source_volid": null, "consistencygroup_id": null, "os-vol-mig-status-attr:name_id": null, "name": null, "bootable": "true", "created_at": "2018-09-26T01:55:38.735749", "volume_type": "lvmdriver-1" } } * The 'status' will be 'downloading'. * The 'volume_image_metadata' refers to the image metadata of the volume. It will include the original image until the re-image operation is complete in cinder-volume. - Normal response codes: 202 - Error response codes: 400, 403, 404, 409 Data model impact ----------------- None Security impact --------------- Two new policy rules will be introduced as noted in the `Proposed change`_ section. Notifications impact -------------------- Notifications will be added for re-image volume. Other end user impact --------------------- A new command, ``cinder reimage [--ignore-reserved]``, will be added to python-cinderclient. This command mirrors the underlying API function. Callers of the new API will need to poll the status of the volume until it goes back to its original status or ``error`` in case the operation failed. Performance Impact ------------------ None Other deployer impact --------------------- None Developer impact ---------------- None Implementation ============== Assignee(s) ----------- Primary assignee: Yikun Jiang Other assignee: TommyLike Work Items ---------- By supporting re-image volumes, we need to do the following changes: * Add a new 'os-reimage' action to volume actions API. * Add a new 'reimage' cast rpc. * Add a new 'reimage' method in volume manager. * Adopt the new microversion in python-cinderclient. * Set a user message in the event when the re-image fails. Dependencies ============ None Testing ======= Unit-tests, tempest and other related tests will be implemented. Documentation Impact ==================== Need to document the new behavior of the volume re-image, as well as related client examples, etc. References ========== .. [1] http://review.openstack.org/#/c/532407 .. [2] https://wiki.openstack.org/wiki/CinderSteinPTGSummary#Nova_Cross_Project_Time .. [3] http://lists.openstack.org/pipermail/openstack-operators/2018-March/014952.html