The nova.image.api Module

Main abstraction layer for retrieving and storing information about disk images used by the compute layer.

class API

Bases: object

Responsible for exposing a relatively stable internal API for other modules in Nova to retrieve information about disk images. This API attempts to match the nova.volume.api and nova.network.api calling interface.

create(context, image_info, data=None)

Creates a new image record, optionally passing the image bits to backend storage.

Parameters:

• context – The nova.context.Context object for the request
• image_info – A dict of information about the image that is passed to the image registry.
• data – Optional file handle or bytestream iterator that is passed to backend storage.

delete(context, id_or_uri)

Delete the information about an image and mark the image bits for deletion.

Parameters:

• context – The nova.context.Context object for the request
• id_or_uri – A UUID identifier or an image URI to look up image information for.

download(context, id_or_uri, data=None, dest_path=None)

Transfer image bits from Glance or a known source location to the supplied destination filepath.

Parameters:

• context – The nova.context.RequestContext object for the request
• id_or_uri – A UUID identifier or an image URI to look up image information for.
• data – A file object to use in downloading image data.
• dest_path – Filepath to transfer image bits to.

Note that because of the poor design of the glance.ImageService.download method, the function returns different things depending on what arguments are passed to it. If a data argument is supplied but no dest_path is specified (only done in the XenAPI virt driver’s image.utils module) then None is returned from the method. If the data argument is not specified but a destination path is specified, then a writeable file handle to the destination path is constructed in the method and the image bits written to that file, and again, None is returned from the method. If no data argument is supplied and no dest_path argument is supplied (VMWare and XenAPI virt drivers), then the method returns an iterator to the image bits that the caller uses to write to wherever location it wants. Finally, if the allow_direct_url_schemes CONF option is set to something, then the nova.image.download modules are used to attempt to do an SCP copy of the image bits from a file location to the dest_path and None is returned after retrying one or more download locations (libvirt and Hyper-V virt drivers through nova.virt.images.fetch).

I think the above points to just how hacky/wacky all of this code is, and the reason it needs to be cleaned up and standardized across the virt driver callers.

get(context, id_or_uri, include_locations=False, show_deleted=True)

Retrieves the information record for a single disk image. If the supplied identifier parameter is a UUID, the default driver will be used to return information about the image. If the supplied identifier is a URI, then the driver that matches that URI endpoint will be used to query for image information.

Parameters:

• context – The nova.context.Context object for the request
• id_or_uri – A UUID identifier or an image URI to look up image information for.
• include_locations – (Optional) include locations in the returned dict of information if the image service API supports it. If the image service API does not support the locations attribute, it will still be included in the returned dict, as an empty list.
• show_deleted – (Optional) show the image even the status of image is deleted.

get_all(context, **kwargs)

Retrieves all information records about all disk images available to show to the requesting user. If the requesting user is an admin, all images in an ACTIVE status are returned. If the requesting user is not an admin, the all public images and all private images that are owned by the requesting user in the ACTIVE status are returned.

Parameters:

• context – The nova.context.Context object for the request
• kwargs – A dictionary of filter and pagination values that may be passed to the underlying image info driver.

update(context, id_or_uri, image_info, data=None, purge_props=False)

Update the information about an image, optionally along with a file handle or bytestream iterator for image bits. If the optional file handle for updated image bits is supplied, the image may not have already uploaded bits for the image.

Parameters:

• context – The nova.context.Context object for the request
• id_or_uri – A UUID identifier or an image URI to look up image information for.
• image_info – A dict of information about the image that is passed to the image registry.
• data – Optional file handle or bytestream iterator that is passed to backend storage.
• purge_props – Optional, defaults to False. If set, the backend image registry will clear all image properties and replace them the image properties supplied in the image_info dictionary’s ‘properties’ collection.