openstack/cinder-specs
Code Issues Proposed changes

Add volume reimage spec

Browse Source 
This patch adds the spec for reimage feature which enables the
functionality to rebuild a volume backed instance.

Implements: blueprint add-volume-re-image-api

Change-Id: I067d113cacaf9a4d9e6a7f4d7ed1e0dfcc3ae509
This commit is contained in:
Rajat Dhasmana 2021-09-17 05:48:07 -04:00 committed by whoami-rajat
parent 7464b781cf
commit a5e710f8ba
1 changed files with 90 additions and 65 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

155
specs/train/add-volume-re-image-api.rst → specs/yoga/add-volume-re-image-api.rst
View File

@ -24,13 +24,13 @@ 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]_,
In addition, as mentioned in nova spec '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.
As the discussion result during Yoga PTG [2]_, the idea still makes sense and
we would propose to implement a new API to support this.
.. _not supported: https://review.openstack.org/#/c/520660/
@ -48,33 +48,44 @@ 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.
* The request will be rejected if cinder microversion is not new enough to
support 'os-reimage' action.
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:
As mentioned above, the main purpose of this spec is for Nova's rebuild use
case. When Nova calls cinder for re-image then cinder will perform these 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.
#. See nova side operations in the nova spec here
'volume-backend-server-rebuild' [1]_
#. Receive the re-image request from nova and check if the volume is in
``reserved`` state.
#. Perform the re-image operation. During this, the volume will transition
into ``downloading`` state which is similar to the state when creating a
bootable volume from image (more detailed information is captured later in
this section).
#. Add a new 'volume-reimaged' external event and use it notify nova when the
re-image operation is complete, like we use for volume-extend.
See `perform_resize_volume_online`_ for details.
#. After successful completion of the re-image operation, nova will call cinder
to update the attachment with connector info.
#. Cinder will update the attachment and return connection info to Nova.
#. After Nova completes the connection with brick, Nova will make the attachment
complete call marking the volume ``in-use``.
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.
.. _perform_resize_volume_online: https://review.opendev.org/c/openstack/nova/+/454322
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``.
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 ``reimage_reserved`` parameter is ``True``. The volume
state will be changed to ``downloading`` first.
If the image status is not ``active``, image size or image min_disk size is
larger than volume size, will raise InvalidInput (400) error.
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 ``SYSTEM_ADMIN_OR_PROJECT_MEMBER``.
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.
@ -83,20 +94,22 @@ This spec proposes to add a new 'os-reimage' action to volume actions API.
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.
* Add an external event ``volume-reimaged`` and call it to notify nova API
about completion of reimage operation.
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.
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.
the volume status will changed to ``error``.
There are also some other optimized mechanisms that should be considered to
support in future, but will not be implemented in this spec:
@ -142,31 +155,31 @@ The rest API look like this in v3:
POST /v3/{project_id}/volumes/{volume_id}/action
.. code-block:: python
.. code-block:: json
{
'os-reimage': {
'image_id': "71543ced-a8af-45b6-a5c4-a46282108a90",
'ignore_reserved': false
}
}
{
"os-reimage": {
"image_id": "71543ced-a8af-45b6-a5c4-a46282108a90",
"reimage_reserved": true
}
}
* The <string> 'image_id' refers to the id of image.
No default value since this is a required parameter.
* The <boolean> '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 <string> 'image_id' refers to the id of image.
No default value since this is a required parameter.
* The <boolean> 'reimage_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
.. code-block:: json
{
{
"volume": {
"migration_status": null,
"attachments": [ ],
"attachments": [],
"links": [
{
"href": "http://10.79.144.144/volume/v3/ffc60994a7274553905e5e5a8f890ab3/volumes/d90bfc0e-babf-4478-a591-23ca883ba2be",
@ -209,17 +222,17 @@ The response body of it is like:
"bootable": "true",
"created_at": "2018-09-26T01:55:38.735749",
"volume_type": "lvmdriver-1"
}
}
}
}
* The <string> 'status' will be 'downloading'.
* The <dict> '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.
* The <string> 'status' will be 'downloading'.
* The <dict> '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
- Normal response codes: 202
- Error response codes: 400, 403, 404, 409
- Error response codes: 400, 403, 404, 409
Data model impact
-----------------
@ -246,6 +259,13 @@ 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.
The only exception here is Nova which will be notified via external events
API and doesn't need to poll for the re-image to be completed.
Since this is a data path change, it will only modify the contents of volume and
dependent resources like snapshots or backups won't be affected by it. Just
to keep in mind that restoring to an earlier backup/snapshot will also revert
the volume to the old image.
Performance Impact
------------------
@ -269,9 +289,7 @@ Assignee(s)
-----------
Primary assignee:
Yikun Jiang <yikunkero@gmail.com>
Other assignee:
TommyLike <tommylikehu@gmail.com>
Rajat Dhasmana <rajatdhasmana@gmail.com>
Work Items
----------
@ -287,6 +305,8 @@ By supporting re-image volumes, we need to do the following changes:
* Set a user message in the event when the re-image fails.
* Add a call to nova external events API with 'volume-reimaged' event
Dependencies
============
@ -303,11 +323,16 @@ Documentation Impact
Need to document the new behavior of the volume re-image, as well
as related client examples, etc.
We also need to mention in the documentation that when the volume
is re-imaged, all current content on the volume will be *destroyed*.
This is important as cinder volumes are considered to be persistent,
which is not the case with this operation.
References
==========
.. [1] http://review.openstack.org/#/c/532407
.. [1] https://review.opendev.org/c/openstack/nova-specs/+/809621
.. [2] https://wiki.openstack.org/wiki/CinderSteinPTGSummary#Nova_Cross_Project_Time
.. [2] https://wiki.openstack.org/wiki/CinderYogaPTGSummary#Volume_re-image
.. [3] http://lists.openstack.org/pipermail/openstack-operators/2018-March/014952.html