glance/doc/source/tasks.rst

Tasks

Conceptual Overview

Image files can be quite large, and processing images (converting an image from one format to another, for example) can be extremely resource intensive. Additionally, a one-size-fits-all approach to processing images is not desirable. A public cloud will have quite different security concerns than, for example, a small private cloud run by an academic department in which all users know and trust each other. Thus a public cloud deployer may wish to run various validation checks on an image that a user wants to bring in to the cloud, whereas the departmental cloud deployer may view such processing as a waste of resources.

To address this situation, Glance contains tasks. Tasks are intended to offer end users a front end to long running asynchronous operations -- the type of operation you kick off and don't expect to finish until you've gone to the coffee shop, had a pleasant chat with your barista, had a coffee, had a pleasant walk home, etc. The asynchronous nature of tasks is emphasized up front in order to set end user expectations with respect to how long the task may take (hint: longer than other Glance operations). Having a set of operations performed by tasks allows a deployer flexibility with respect to how many operations will be processed simultaneously, which in turn allows flexibility with respect to what kind of resources need to be set aside for task processing. Thus, although large cloud deployers are certainly interested in tasks for the alternative custom image processing workflow they enable, smaller deployers find them useful as a means of controlling resource utilization.

An additional reason tasks have been introduced into Glance is to support Glance's role in the OpenStack ecosystem. Glance provides cataloging, storage, and delivery of virtual machine images. As such, it needs to be responsive to other OpenStack components. Nova, for instance, requests images from Glance in order to boot instances; it uploads images to Glance as part of its workflow for the Nova image-create action; and it uses Glance to provide the data for the image-related API calls that are defined in the Compute API that Nova instantiates. It is necessary to the proper functioning of an OpenStack cloud that these synchronous operations not be compromised by excess load caused by non-essential functionality such as image import.

By separating the tasks resource from the images resource in the Images API, it's easier for deployers to allocate resources and route requests for tasks separately from the resources required to support Glance's service role. At the same time this separation avoids confusion for users of an OpenStack cloud. Responses to requests to /v2/images should return fairly quickly, while requests to /v2/tasks may take a while.

In short, tasks provide a common API across OpenStack installations for users of an OpenStack cloud to request image-related operations, yet at the same time tasks are customizable for individual cloud providers.

Conceptual Details

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.

A specific type of resource distinct from the traditional Glance image resource is appropriate here for several reasons:

• A dedicated task resource can be developed independently of the traditional Glance image resource, both with respect to structure and workflow.
• There may be multiple tasks (for example, image export or image conversion) operating on an image simultaneously.
• A dedicated task resource allows for the delivery to the end user of clear, detailed error messages specific to the particular operation.
• A dedicated task resource respects the principle of least surprise. For example, an import task does not create an image in Glance until it's clear that the bits submitted pass the deployer's tests for an allowable image.

Upon reaching a final state (success or error) a task resource is assigned an expiration datetime that's displayed in the expires_at field. (The time between final state and expiration is configurable.) After that datetime, the task resource is subject to being deleted. The result of the task (for example, an imported image) will still exist.

For details about the defined task statuses, please see task-statuses.

Tasks expire eventually because there's no reason to keep them around, as the user will have the result of the task, which was the point of creating the task in the first place. The reason tasks aren't instantly deleted is that there may be information contained in the task resource that's not easily available elsewhere. (For example, a successful import task will eventually result in the creation of an image in Glance, and it would be useful to know the UUID of this image. Similarly, if the import task fails, we want to give the end user time to read the task resource to analyze the error message.)

Task Entities

A task entity is represented by a JSON-encoded data structure defined by the JSON schema available at /v2/schemas/task.

A task entity has an identifier (id) that is guaranteed to be unique within the endpoint to which it belongs. The id is used as a token in request URIs to interact with that specific task.

In addition to the usual properties you'd expect (for example, created_at, self, type, status, updated_at, etc.), tasks have these properties of interest:

• input: this is defined to be a JSON blob, the exact content of which will depend upon the requirements set by the specific cloud deployer. The intent is that each deployer will document these requirements for end users.
• result: this is also defined to be a JSON blob, the content of which will be documented by each cloud deployer. The result element will be null until the task has reached a final state, and if the final status is failure, the result element remains null.
• message: this string field is expected to be null unless the task has entered failure status. At that point, it contains an informative human-readable message concerning the reason(s) for the task failure.