Add tasks info to glance documentation
Adds conceptual overview of tasks and documents the tasks API calls. This is a partial fix (parts 1 & 2) for bug #1484566. Change-Id: If295c35d3cfa2f39d9f6bac8f02947bce3552d0a Partial-bug: #1484566
This commit is contained in:
bria4010
Darja Shakhray
parent
262d0245a5
commit
c2f2dab939
@ -674,6 +674,88 @@ New API Calls
|
||||
where <STATUS_VALUE> is ``pending``, ``accepted``, or ``rejected``.
|
||||
The {memberId} is the tenant ID of the image member.
|
||||
|
||||
Images v2 Tasks API
|
||||
-------------------
|
||||
|
||||
Version 2 of the OpenStack Images API introduces a Task resource that is used
|
||||
to create and monitor long-running asynchronous image-related processes. See
|
||||
the :doc:`Tasks <tasks>` section of the Glance documentation for more
|
||||
information.
|
||||
|
||||
The following Task calls are available:
|
||||
|
||||
Create a Task
|
||||
*************
|
||||
|
||||
A user wants to initiate a task. The user issues a ``POST`` request to
|
||||
``/v2/tasks``. The request body is of Content-type ``application/json`` and
|
||||
must contain the following fields:
|
||||
|
||||
* ``type``: a string specified by the enumeration defined in the Task schema
|
||||
|
||||
* ``input``: a JSON object. The content is defined by the cloud provider who
|
||||
has exposed the endpoint being contacted
|
||||
|
||||
The response is a Task entity as defined by the Task schema. It includes an
|
||||
``id`` field that can be used in a subsequent call to poll the task for status
|
||||
changes.
|
||||
|
||||
A task is created in ``pending`` status.
|
||||
|
||||
Show a Task
|
||||
***********
|
||||
|
||||
A user wants to see detailed information about a task the user owns. The user
|
||||
issues a ``GET`` request to ``/v2/tasks/{taskId}``.
|
||||
|
||||
The response is in ``application/json`` format. The exact structure is given
|
||||
by the task schema located at ``/v2/schemas/task``.
|
||||
|
||||
List Tasks
|
||||
**********
|
||||
|
||||
A user wants to see what tasks have been created in his or her project. The
|
||||
user issues a ``GET`` request to ``/v2/tasks``.
|
||||
|
||||
The response is in ``application/json`` format. The exact structure is given
|
||||
by the task schema located at ``/v2/schemas/tasks``.
|
||||
|
||||
Note that, as indicated by the schema, the list of tasks is provided in a
|
||||
sparse format. To see more information about a particular task in the list,
|
||||
the user would use the show task call described above.
|
||||
|
||||
Filtering and Sorting the Tasks List
|
||||
************************************
|
||||
|
||||
The ``GET /v2/tasks`` request takes query parameters that server to filter the
|
||||
returned list of tasks. The following list details these query parameters.
|
||||
|
||||
* ``status={status}``
|
||||
|
||||
Filters the list to display only those tasks in the specified status. See
|
||||
the task schema or the :doc:`Task Statuses <statuses>` section of this
|
||||
documentation for the legal values to use for ``{status}``.
|
||||
|
||||
For example, a request to ``GET /v2/tasks?status=pending`` would return only
|
||||
those tasks whose current status is ``pending``.
|
||||
|
||||
* ``type={type}``
|
||||
|
||||
Filters the list to display only those tasks of the specified type. See the
|
||||
enumeration defined in the task schema for the legal values to use for
|
||||
``{type}``.
|
||||
|
||||
For example, a request to ``GET /v2/tasks?type=import`` would return only
|
||||
import tasks.
|
||||
|
||||
* ``sort_dir={direction}``
|
||||
|
||||
Sorts the list of tasks according to ``updated_at`` datetime. Legal values
|
||||
are ``asc`` (ascending) and ``desc`` (descending). By default, the task list
|
||||
is sorted by ``created_at`` time in descending chronological order.
|
||||
|
||||
|
||||
|
||||
|
||||
API Message Localization
|
||||
------------------------
|
||||
|
||||
@ -55,6 +55,7 @@ Glance Background Concepts
|
||||
domain_model
|
||||
identifiers
|
||||
statuses
|
||||
tasks
|
||||
formats
|
||||
common-image-properties
|
||||
metadefs-concepts
|
||||
|
||||
138
doc/source/tasks.rst
Normal file
138
doc/source/tasks.rst
Normal file
@ -0,0 +1,138 @@
|
||||
..
|
||||
Copyright 2015 OpenStack Foundation
|
||||
All Rights Reserved.
|
||||
|
||||
Licensed under the Apache License, Version 2.0 (the "License"); you may
|
||||
not use this file except in compliance with the License. You may obtain
|
||||
a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
||||
WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
|
||||
License for the specific language governing permissions and limitations
|
||||
under the License.
|
||||
|
||||
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 :doc:`Task
|
||||
Statuses <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.
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user