Glance-tasks-api-product

This is a "product package" for:

• Glance blueprints
  • "New Upload Workflow ("Import")"
  • "New Download Workflow ("Export")"
  • "Model for cloning image from one region to another"
• Full specifications
  • "Glance Tasks API"
  • "Import Task"
  • "Export Task"
  • "Clone Task"

Press Release

OpenStack Announces Images Tasks API

Available now with the Icehouse OpenStack release, the Images v2 Tasks API provides cloud users with a unified interface for performing image-related tasks. Three tasks are currently available: import, export, and clone. You simply make a post to /v2/tasks with specifics about the task in the request body, and receive a Location header with the URI of a task resource. By polling the task resource, you'll be kept informed about the status of your task until it reaches its conclusion. At that point, the task resource will contain information concerning the product of your task (e.g., the UUID of the image that was imported). It will also have an expiration timestamp to indicate when the task resource itself will be deleted. (We don't want these things clogging up your tasks list!)

Create some tasks in a Glance located near you today!

The Import Task

The import task allows you to specify the location of the image you want to import into the cloud. You make the request, Glance will retrieve the image, and pull it into the cloud, where you can use it to boot instances. As part of this process, your image may undergo some transformation and validation before it becomes an active image.

The Export Task

The export task enables you to export an image you've created in some provider's cloud in the quasi-official qcow2 format.

The Clone Task

The clone task allows you to copy an image from region to region within a cloud.

Tasks API FAQ

General FAQ

What are Tasks?

A glance task is a request to perform an asynchronous image-related operation. The request results in the creation of a task resource that can be polled for information about the status of the operation.

What happens when a task expires?

The task resource itself will be deleted. The result of the task, e.g., an imported image, will still exist.

Can I cancel a task?

Not sure about this yet. It may depend upon the status of the task.

Can I use my images while they are being processed by a task?

Probably as long as you don't do something like delete an image you are trying to clone or export.

How can I tell if an image is currently being used by a task?

You can't. Export and clone tasks are non-invasive, so your image can still be used. If you delete the image before the export or clone task is complete, the task will fail.

Import Task FAQ

Why do I need to import an image?

Different clouds use different underlying technologies. Importing an image allows your cloud provider to process the image to make it suitable for booting in their cloud.

How do I import an image?

First, you put the image into a cloud storage account in an OpenStack cloud. Next, you issue a POST to /v2/tasks with an import task request content. Glance will fetch the image from your cloud storage, do whatever processing the cloud provider deems necessary to prepare your image for booting in their cloud, and create a new image for you.

What are the supported formats?

The standard OpenStack image interchange format is qcow2. Your cloud provider may allow imports from other formats.

Can I just send glance the image bits directly?

No. (We don't want to tie up the glance nodes with slow uploads. Instead, the workflow is to get users to upload to cloud storage, which is specifically designed to handle large uploads of data from connections of varying bandwidth.)

Export Task FAQ

Why do I need to export an image?

Different clouds use different underlying technologies. Exporting an image allows your cloud provider to process the image and convert it to a standard interchange format so that you can use your image in other clouds.

If you just want to use your image in another region of the same cloud, you might want to use the clone task instead.

How do I export an image?

First, you determine the UUID of the image you want to export. Next, you issue a POST to /v2/tasks with an export task request content. Glance will do whatever processing is necessary to remove provider-specific information from the image and convert it to a standard interchange format. Finally, it will transfer the exported image to your cloud storage account.

What are the supported formats?

The standard OpenStack image interchange format is qcow2. Your cloud provider may allow exports to other formats.

Can I just get the image bits directly from glance?

No. (For the same reason we don't allow direct import of image bits.)

Are there images that I cannot export?

Check the policies of your cloud provider.

Clone Task FAQ

What is the clone task?

Many providers have clouds divided into various "regions". An image can only be used to boot instances in the same region as the image is located. The clone task allows you to copy your image to another region so it can be used there.

How are cloned images related to each other?

They aren't. Each will have a different UUID (though their checksums are equal), and you may update the metadata of each image independently. There is no ongoing synchronization of metadata. Hence, there is no concept of a "master" image.

How do I clone an image?

The image clone task is designed on a "pull" model, i.e., you request the task in the region where you want the copy to show up. You make a POST to /v2/tasks with a clone task request body. Glance will contact the glance in the other region and work out the details of the transfer. The task resource will contain the UUID of the cloned image when the task is complete.

I wasn't paying attention and don't know the UUID of my cloned image. How can I find it?

Hopefully, you still remember what image you wanted to clone from another region. Go to that region and find its checksum value. Then do an image list in the region where the clone is, using that value for the 'checksum' filter.