Glance-tasks-api
Contents
Overview
This proposal unifies the new upload workflow [1], new download workflow [2], and image cloning [3] blueprints in an extensible, consistent, and easy-to-learn way.
General Workflow
- User posts a request to /v2/tasks
- Glance returns a 201 with Location: /v2/tasks/{task-uuid}
- The resource at /v2/tasks/{task-uuid} will be an expirable entity
- User polls /v2/tasks/{task-uuid} for status information on the requested task
- Eventually, when the task is completed, the resource will contain
- task result information, e.g.,
- if the task was successful, the location of the result of the task
- for import or clone tasks, this will be an /images resource
- for export, it will be a location where the exported item may be retrieved
- if the task was not successful, an informative message
- if the task was successful, the location of the result of the task
- the expiration datetime of the tasks resource itself
- task result information, e.g.,
Task Entities
An task entity is represented by a JSON-encoded data structure.
An 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.
An task is always guaranteed to have the following attributes: id, type, status, and self. The other attributes defined in the task schema below are guaranteed to be defined, but will only be returned with a task entity if they have been explicitly set.
Task Properties
(no ordering, just using the numerals to keep count)
- id
- type
- status
- owner : this is whatever is being used as the image owner in this glance installation
- input : task "parameters"
- result
- created_at
- updated_at
- expires_at
- message
Task Schema
A json-schema for the task entity will be available at the URI /v2/schemas/tasks
And it goes a little something like this:
{ "name": "task", "properties": { "id": { "description": "An identifier for the task", "pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$", "type": "string", "required": true }, "owner": { "description": "An identifier for the owner of this task", "type": "string", "required": true }, "type" : { "description": "The type of task represented by this content", "enum": [ "import", "export", "clone" ], "type": "string", "required": true }, "status" : { "description": "The current status of this task.", "enum": [ "pending", "processing", "success", "failure" ], "type": "string", "required": true }, "created_at": { "description": "Datetime when this resource was created", "type": "string", "required": true }, "updated_at": { "description": "Datetime when this resource was most recently updated", "type": "string", "required": true }, "expires_at": { "description": "Datetime when this resource is subject to removal", "type": "string" }, "message": { "description": "Human-readable informative message only included when appropriate (usually on failure)", "type": "string", }, "input": { "description": "The input parameters for this task", "type": "object", "required": true }, "result": { "description": "Informatic results of this task", "type": "object", }, }, "links": [ { "href": "{self}", "rel": "self" }, { "href": "{file}", "rel": "enclosure" }, { "href": "{schema}", "rel": "describedby" } ], }
Task Response Body
The basic tasks response will be Content-type: application/json and will adhere to the task json schema described above.
Task Request Schema
The basic tasks request is defined by the following JSON schema.
{ "name": "task_request", "properties": { "type": { "description": "The type of task requested", "enum": [ "import", "export", "clone" ], "type": "string", "required": true }, "input": { "description": "The input parameters for this task. Valid content depends on the task type, see the documentation for details.", "type": "object", "required": true } } }
Task Request Body =
The basic task request will be Content-type: application/json and will adhere to the task_request json schema described above.
Task States
Tasks will have the following states:
-
pending
: a task has been created, but Glance (via async worker or whatever) hasn't begun to execute the task yet -
processing
: the task is underway -
success
: the task has complete successfully -
failure
: something went wrong, the task was not able to complete
In the case of failure, it's expected that the task resource will contain a message explaining what went wrong.
Requests
Create a Task
POST /v2/tasks
Request body must be appropriate for the task_type.
Display Task Detail
GET /v2/tasks/{task_id}
Returns a task response as defined above.
List Tasks
GET /v2/tasks
Returns a list of tasks owned by the user making the request.
Query Parameters
We'll want to allow filtering on the task type, e.g.,
GET /v2/tasks?type=import
would return all non-expired import tasks owned by the user making the request. The allowed values are 'import', 'export', 'clone'.
Open Questions
- What do we return when a user makes a GET for a task UUID that exists, but they don't own?
- 401 or 404?
- The task request will return a 200 even when the task_status is 'failure' (since the task response itself is being returned OK). Some of these failures will be for things like not-found, format-not-supported, conflict ... this will be mentioned in the 'message' field, but do we want to have a separate failure code or something to make it easier for an API user to extract this info?
Proposed Tasks
Related Documents
- Havana summit discussion etherpad (see bottom of pad) [7]
- original blueprint proposal [8]
- mailing list discussion of original proposal [9]
- mailing list discussion of this proposal [10]
- etherpad of further discussion refining this proposal [11]
References
- ↑ https://wiki.openstack.org/wiki/Glance-tasks-import
- ↑ https://wiki.openstack.org/wiki/Glance-tasks-export
- ↑ https://wiki.openstack.org/wiki/Glance-tasks-clone
- ↑ https://wiki.openstack.org/wiki/Glance-tasks-import
- ↑ https://wiki.openstack.org/wiki/Glance-tasks-export
- ↑ https://wiki.openstack.org/wiki/Glance-tasks-clone
- ↑ https://etherpad.openstack.org/havana-getting-glance-ready-for-public-clouds
- ↑ https://blueprints.launchpad.net/glance/+spec/upload-download-workflow
- ↑ http://lists.openstack.org/pipermail/openstack-dev/2013-May/009385.html
- ↑ http://lists.openstack.org/pipermail/openstack-dev/2013-August/012866.html
- ↑ https://etherpad.openstack.org/LG39UnQA7z