Difference between revisions of "Glance-tasks-export"

Revision as of 01:34, 22 July 2013

This is the full specification for blueprint:https://blueprints.launchpad.net/glance/+spec/new-download-workflow

Motivation

Here's why we want an alternative to the "normal" Glance download workflow:

• want to allow a cloud provider the opportunity to "scrub" or otherwise process an image that's going to be pulled out of that provider's cloud
  • they don't have to, but want to make the option available
• want to push all efforts associated with getting images out of the cloud to the cloud periphery so the bandwidth/compute required doesn't affect normal cloud functionality

"Export"

We propose to introduce as a Glance task an end-user download-type operation called export.

The arguments in favor of an "import" operation also apply to "export", so they're not repeated here. See the Import specification ^[1] for more information.

Example Workflow (API View)

Initial Export Request

The initial request would be directed to the tasks path and will return the location of task resource that can be subsequently polled to determine the status of the export.

Request 1: POST /v2/tasks
{ "task_type": "export",
  "image_uuid": "deadbeef-dead-dead-dead-beefbeefbeef",
  "export_to": "swift://cloud.foo/myaccount/mycontainer/path",
}

Alternative: could make a POST to /v2/images/deadbeef-dead-dead-dead-beefbeefbeef/export

Response 1: 201 created
Location: "http://glance-server/v2/tasks/43215678-4321-4321-4321-432156789abc"

(Note: probably return the task resource in the body)

Polling for Export Status

Request 2 - N: GET /v2/tasks/43215678-4321-4321-4321-432156789abc

Response 2 - N-1: 200 OK
{ "task_type": "export",
  "task_status" : "waiting",
  "image_uuid" : "deadbeef-dead-dead-dead-beefbeefbeef",
  "export_to": "swift://cloud.foo/myaccount/mycontainer/path",
  "id": "43215678-4321-4321-4321-432156789abc",
   ..., 
}

Final Result of Export

Response N: 200 OK
{ "task_status" : "success",
  "image_uuid" : "deadbeef-dead-dead-dead-beefbeefbeef",
  "export_location": "swift://cloud.foo/myaccount/mycontainer/path/12345678-abcd-abcd-abcd-987654321abc",
  "expires_at" : "2013-05-21T15:19:56+0000" }
or
{ "task_status" : "failure", 
  "image_uuid" : "deadbeef-dead-dead-dead-beefbeefbeef",
  "message" : "Some really informative message",
  "expires_at" : "2013-05-21T15:19:56+0000" }

In this example, the "export_to" field indicated a location where the user had write privileges (how do we handle credentials?). Alternatively, it could be a temp url where the data could be retrieved before the "expires_at" time; the user would do a GET on the temp url and receive application/octet-stream. The "expires_at" would also specify the expiration of the task resource containing the field.

To Do

• define JSON schema for export tasks request
• define JSON schema for export tasks response
  • enumerate 'task_status' values for export

Open Questions

1. When an task resource is created for {imageId}, we have to make it the case that the image cannot be deleted until the export task reaches either success or failure status.
   • Do we need an image task_state like instances have?
2. Need to decide how credentials will be supplied for the "export_to" location, or we could just go with the temp url in the success response for the first implementation
3. What's the best URI to use for the POST operation? Here are a few choices:
   • /v2/tasks
     • Pro: symmetry with import, clone; Con: doesn't make use of the fact that we have an existing image to export
   • /v2/images/UUID/export
     • Pro: makes use of existing image resource; Con: we're not really creating an "export" resource at this URI.
   • /v2/images/UUID/tasks
     • Pro: makes use of existing image resource; Con: we are creating a "task", but not at this URI. Guess you could create a task object at this URI, e.g., /v2/images/IMAGE-UUID/tasks/TASK-UUID, but then you lose the ability to do a GET /v2/tasks to list all your current tasks.
4. What would be appropriate export statuses?
   • queued : an export task has been created, but Glance (via async worker or whatever) hasn't begun to act upon the request yet
   • processing : Glance is doing some work (scrubbing or whatever)
   • transferring : data is being moved (or should we just let this be part of "processing"?)
   • success : data has been transferred to the location specified in the response
   • failure : something went wrong, an exported image will not be created from this export request
   • anything else?

Revison History

This is a revised version of ^[2]. The revision is mostly to make this part of the tasks API ^[3].

References

1. ↑ https://wiki.openstack.org/wiki/Glance-tasks-import
2. ↑ https://wiki.openstack.org/wiki/Glance-new-download-workflow
3. ↑ https://wiki.openstack.org/wiki/Glance-tasks-api