NovaImageCreationAPI

Nova API Extensions for Image Building

Introduction:

This document looks at the API necessary to enable image creation within OpenStack, without the use of external tools, such as Oz or ImageFactory. The focus is on what additions would be made to the Nova REST API for Images and not on the implementation details of a Nova extension.

Create Image:

To support creating a new image from OS installation sources, POST should be added to the /images URI.The request body should be an 'image' with the following attributes:

• name - The name for the new image [required]
• metadata - Key/value pairs [optional]

It should be noted that, so far, the format of 'image' is the same as 'createImage' sent as the request body for POST to /servers/:id/action.

The 'image' should have an additional attribute, 'imageSpec', with the following key/value pairs:

• osName - The name of the OS to install in the image. [required]
• osVersion - The version of the OS to install in the image. If not specified, installSource will be used to try and determine the version. [optional]
• osArch - The architecture of the OS to install in the image. If not specified, installSource will be used to try and determine the architecture. [optional]
• installScript - The OS installation script (ie kickstart, preseed file). If not specified, libosinfo will be used to provide a sensible default. [optional]
• installSource - A set of (potentially OS-specific) key/value pairs specifying where the install media is located. [optional]

Note: Consideration was given to using a metadata key 'ImageSpec' with key/value pairs as its value to specify what is needed to create an image. However, the size limitation of metadata keys and values to 255 bytes each, may be too small in some cases.

Once complete, a new image will be available that can be used to rebuild or create servers. The full URL to the newly created image is returned via the Location header, additional attributes for the image including creation status may be retrieved by performing a subsequent GET on that URL.

Response Codes:

• Normal Response Code(s): 202
• Error Response Code(s): computeFault (400, 500, …), serviceUnavailable (503), unauthorized (401), forbidden (403), badRequest (400), badMethod (405), overLimit (413), badMediaType (415), serverCapacityUnavailable (503)

Image Status Transition:

• BUILDING -> ACTIVE
• BUILDING -> ERROR (on error)

Currently, 'BUILDING' is not a status for images and would need to be added.

Error conditions:

In the case that an error is encountered while building the base image, a key/value pair with the key 'buildError' and a value of a string providing some detail or context for the error should be added to the image metadata.

Get Image Details:

Details for an image created in Nova via native OS installation procedure requires little change from what is currently described by Get Image Details.

The only additions needed are:

• Add 'BUILDING' as an image status value
• Add the 'imageSpec' attribute to the image as described above in 'Create Image'
• Add the 'buildImage' attribute, the URI to the image launched to run the OS installer
• Add the 'buildServer' attribute, the URI to the server where the OS installer is being run

List Images:

There are few additions to be made for listing images as described by List Images.

The only additions needed are:

• Add 'BUILDING' as an image status for filtering
• Add the following optional URI parameters for filtering:

• osname=osName& (Filters the list of images by OS name)
• osversion=osVersion& (Filters the list of images by OS version)
• osarch=osArch& (Filters the list of images by OS architecture)

Delete Images:

There is only one addition to be made for deleting images as described by Delete Image.

Deleting an image that with a status of 'BUILDING' will require an additional status transition (BUILDING -> DELETED)