Docs: Document clone_image driver method
This patch improves and fixes the documentation of the clone_image driver method and updates the parameters in various places where the method is declared where they presented the wrong parameters. Since there is a valid default implementation for the method, a small text has been added to indicate that some of the core methods, like this one, are optional. To avoid getting docstrings from the driver and the interface (which is the one used for the documentation) out of sync we replace the description on cinder/volume/driver.py with a text referencing the interface docstring. Change-Id: I09a8357e15b9041790285ab1f9a3cdd7a18243b4
This commit is contained in:
Gorka Eguileor
parent
eb6ba62473
commit
e071ee2632
@ -17,7 +17,9 @@
|
||||
"""
|
||||
Core backend volume driver interface.
|
||||
|
||||
All backend drivers should support this interface as a bare minimum.
|
||||
All backend drivers should support this interface as a bare minimum, but some
|
||||
methods (marked as optional in their description) can rely on the default
|
||||
implementation.
|
||||
"""
|
||||
|
||||
from cinder.interface import base
|
||||
@ -222,16 +224,71 @@ class VolumeDriverCore(base.CinderInterface):
|
||||
force-detach and can be None.
|
||||
"""
|
||||
|
||||
def clone_image(self, volume, image_location, image_id, image_metadata,
|
||||
image_service):
|
||||
"""Clone an image to a volume.
|
||||
def clone_image(self, context, volume,
|
||||
image_location, image_meta, image_service):
|
||||
"""Create a volume efficiently from an existing image.
|
||||
|
||||
:param volume: The volume to create.
|
||||
:param image_location: Where to pull the image from.
|
||||
:param image_id: The image identifier.
|
||||
:param image_metadata: Information about the image.
|
||||
:param image_service: The image service to use.
|
||||
:returns: Model updates.
|
||||
Drivers that, always or under some circumstances, can efficiently
|
||||
create a volume from a Glance image can implement this method to be
|
||||
given a chance to try to do the volume creation as efficiently as
|
||||
possible.
|
||||
|
||||
If the driver cannot do it efficiently on a specific call it can
|
||||
return ``(None, False)`` to let Cinder try other mechanisms.
|
||||
|
||||
**This method is optional** and most drivers won't need to implement
|
||||
it and can leverage the default driver implementation that returns
|
||||
``(None, False)`` to indicate that this optimization is not possible on
|
||||
this driver.
|
||||
|
||||
Examples where drivers can do this optimization:
|
||||
|
||||
- When images are stored on the same storage system and the driver can
|
||||
locate them and efficiently create a volume. For example the RBD
|
||||
driver can efficiently create a volume if the image is stored on the
|
||||
same Ceph cluster and the image format is ``raw``. Another example
|
||||
is the GPFS driver.
|
||||
|
||||
- When volumes are locally accessible and accessing them that way is
|
||||
more efficient than going through the remote connection mechanism.
|
||||
For example in the GPFS driver if the cloning feature doesn't work it
|
||||
will copy the file without using os-brick to connect to the volume.
|
||||
|
||||
:param context: Security/policy info for the request.
|
||||
:param volume: The volume to create, as an OVO instance. Drivers should
|
||||
use attributes to access its values instead of using the
|
||||
dictionary compatibility interface it provides.
|
||||
:param image_location: Tuple with (``direct_url``, ``locations``) from
|
||||
the `image metadata fields.
|
||||
<https://docs.openstack.org/api-ref/image/v2/index.html?expanded=show-image-detail#show-image-detail>`_
|
||||
``direct_url``, when present, is a string whose
|
||||
format depends on the image service's external
|
||||
storage in use.
|
||||
Any, or both, tuple positions can be None,
|
||||
depending on the image service configuration.
|
||||
``locations``, when present, is a list of
|
||||
dictionaries where the value of the ``url`` key
|
||||
contains the direct urls (including the one from
|
||||
``direct_url``).
|
||||
:param image_meta: Dictionary containing `information about the image
|
||||
<https://docs.openstack.org/api-ref/image/v2/index.html?expanded=show-image-detail#show-image-detail>`_,
|
||||
including basic attributes and custom properties.
|
||||
Some transformations have been applied, such as
|
||||
converting timestamps (from ``created_at``,
|
||||
``updated_at``, and ``deleted_at``) to datetimes,
|
||||
and deserializing JSON values from
|
||||
``block_device_mapping`` and ``mappings`` keys if
|
||||
present.
|
||||
Base properties, as per the image's schema, will be
|
||||
stored on the base dictionary and the rest will be
|
||||
stored under the ``properties`` key.
|
||||
An important field to check in this method is the
|
||||
``disk_format`` (e.g. raw, qcow2).
|
||||
:param image_service: The image service to use (``GlanceImageService``
|
||||
instance). Can fetch image data directly using
|
||||
it.
|
||||
:returns: Tuple of (model_update, boolean) where the boolean specifies
|
||||
whether the clone occurred.
|
||||
"""
|
||||
|
||||
def copy_image_to_volume(self, context, volume, image_service, image_id):
|
||||
|
||||
@ -1158,8 +1158,13 @@ class BaseVD(object, metaclass=abc.ABCMeta):
|
||||
return attach_info
|
||||
|
||||
def clone_image(self, context, volume,
|
||||
image_location, image_meta,
|
||||
image_service):
|
||||
image_location, image_meta, image_service):
|
||||
"""Create a volume efficiently from an existing image.
|
||||
|
||||
Refer to
|
||||
:obj:`cinder.interface.volume_driver.VolumeDriverCore.clone_image`
|
||||
for additional information.
|
||||
"""
|
||||
return None, False
|
||||
|
||||
def backup_use_temp_snapshot(self):
|
||||
@ -1984,29 +1989,13 @@ class BaseVD(object, metaclass=abc.ABCMeta):
|
||||
|
||||
class CloneableImageVD(object, metaclass=abc.ABCMeta):
|
||||
@abc.abstractmethod
|
||||
def clone_image(self, volume, image_location,
|
||||
image_id, image_meta, image_service):
|
||||
def clone_image(self, context, volume,
|
||||
image_location, image_meta, image_service):
|
||||
"""Create a volume efficiently from an existing image.
|
||||
|
||||
image_location is a string whose format depends on the
|
||||
image service backend in use. The driver should use it
|
||||
to determine whether cloning is possible.
|
||||
|
||||
image_id is a string which represents id of the image.
|
||||
It can be used by the driver to introspect internal
|
||||
stores or registry to do an efficient image clone.
|
||||
|
||||
image_meta is a dictionary that includes 'disk_format' (e.g.
|
||||
raw, qcow2) and other image attributes that allow drivers to
|
||||
decide whether they can clone the image without first requiring
|
||||
conversion.
|
||||
|
||||
image_service is the reference of the image_service to use.
|
||||
Note that this is needed to be passed here for drivers that
|
||||
will want to fetch images from the image service directly.
|
||||
|
||||
Returns a dict of volume properties eg. provider_location,
|
||||
boolean indicating whether cloning occurred
|
||||
Refer to
|
||||
:obj:`cinder.interface.volume_driver.VolumeDriverCore.clone_image`
|
||||
for additional information.
|
||||
"""
|
||||
return None, False
|
||||
|
||||
@ -2553,8 +2542,14 @@ class VolumeDriver(ManageableVD, CloneableImageVD, ManageableSnapshotsVD,
|
||||
"""
|
||||
raise NotImplementedError()
|
||||
|
||||
def clone_image(self, volume, image_location, image_id, image_meta,
|
||||
image_service):
|
||||
def clone_image(self, context, volume,
|
||||
image_location, image_meta, image_service):
|
||||
"""Create a volume efficiently from an existing image.
|
||||
|
||||
Refer to
|
||||
:obj:`cinder.interface.volume_driver.VolumeDriverCore.clone_image`
|
||||
for additional information.
|
||||
"""
|
||||
return None, False
|
||||
|
||||
def get_pool(self, volume):
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user