Posted by: John Bresnahan | August 7, 2013

Download Modules In Nova

A patch has recently been accepted into Nova that allows for images to be downloaded in user defined ways.  In the past images could only be fetched via the Glance REST API but now it is possible to fetch images via customized protocols (think bittorrent and direct access to swift).

Loading Modules

In nova.conf there is the option allowed_direct_url_schemes. This is a list of strings that tell nova what download modules should be imported at load time.

Download modules are loaded via stevedore.  Each download module must be registered with Python as an entry point.  The name space must be and the name must match the strings in the allowed_direct_url_schemes list.

When Nova-compute starts it will walk the list of values in allowed_direct_url_schemes and for each one it will ask stevedore to return the module associated with that name under the name space.  Nova will them make a call into that module (<module>.get_schemes()) to get a list of URL schemes for which the module can be used.  The module will then be associated with each of the strings returned by get_schemes() in a look-up table.

Later, when Nova attempts to download an image it will ask Glance for a list of direct URLs where that image can be found.  It will then walk that list to see if any of the URL schemes can be found in the download module look-up table.  If so it will be used for that download.

A File Example.

For example, here is the setup.cfg for the file download module:

[entry_points] =
file =

This sets up the module as an entry point.

When allowed_direct_url_schemes = file Nova will ask stevedore for the entry point.  Stevedore will return the module  Nova will then call  This call will return the list of strings file and filesystem.  Two entries will then be added to the download module look-up table:

download_modules['file'] =
download_modules['filesystem'] =

When booting, if Glance returns a direct URL of file:///var/lib/glance/images/fedora19.qcow2 Nova will look up file in the download_modules table and thereby get the module for use in the download (I feel like I have said download too many times.  download).

The Interface

Download modules are python modules that must have the following interface functions:

def get_download_hander(**kwargs):
    returns a
def get_schemes():
    returns a list of strings representing schemes

The meat of the work is done by an implementation of  This object only needs to have a single method:

download(self, url_parts, dst_path, metadata, **kwargs):

It is called with the URL to download (already parsed with urlparse), the path to the local destination file, and metadata describing the transfer (this last one will be described in a later post).  When it returns Nova will assume that the data has been downloaded to dst_path.  If anything goes wrong one of the following errors should be raised:



  1. […] Download plug-ins […]

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s


%d bloggers like this: