Add a tasks resource for tracking long running actions

Registered by Andrew Laski

Start of discussion: https://etherpad.openstack.org/p/IcehouseTaskAPI

I'm proposing that in the v3 API we create a task for POST requests on instances, including the create request. One of the challenges in the API up to this point has been signalling a failure of an action without affecting the instance itself. For example, if a reboot fails that may leave the instance untouched and usable so it's not appropriate to set the vm_state to ERROR, but without doing so there's no way to indicate that the reboot failed. The state and success/failure of a task should be treated separately from the state of the instance. By separating the concept of a task out into it's own resource we can provide much more information about what is happening and has happened on an instance without complicating the state transitions of an instance or adding new fields that only have relevance when an instance is "in motion."

Another benefit is that we can start to think of tasks as driving changes on instances. By modeling the concept of work to be done we can later add support for queuing/stopping/pausing/resuming that work. This should allow the upgrade story to become easier if work can be resumed after a service restart.

The initial design I'm proposing is as follows:

A POST to /v3/servers or /v3/servers/<uuid> would return a 202 resp that includes a Location header referencing a task at /v3/servers/<server_uuid>/tasks/<task_uuid> and would have the task itself in the response. A task looks like
{ 'name': 'create/reboot/rebuild/etc...',
  'state': 'In Progress/Finished/Errored/Queued/etc...',
  'uuid': 'c8578700-9827-482e-9b78-f3765b47f14c',
  'instance_uuid': 'b2d9a768-027e-4812-82a5-bd9640d750d5',
  'user_id': 'pulled from context',
  'project_id': 'pulled from context',
  'start_time': timeutils.utcnow(), # at time of task creation
  'finish_time': '',
}

In order to keep v2 from changing the current task_state on an instance will not be removed, though it may not be shown in v3, and all task_state management will remain in place for now. Any new state management will be deferred for now, and possibly until v2 has been removed.

Blueprint information

Status:
Started
Approver:
Joe Gordon
Priority:
Undefined
Drafter:
Andrew Laski
Direction:
Needs approval
Assignee:
Andrew Laski
Definition:
Review
Series goal:
None
Implementation:
Good progress
Milestone target:
milestone icon next
Started by
Andrew Laski

Related branches

Sprints

Whiteboard

The tag portion of this, and anything related to the idempotent requests use case is being separated into a new blueprint. --alaski Feb 24, 2014.

This blueprint has been deferred from the icehouse-3 milestone to Juno because it missed the "feature proposal freeze" deadline. https://wiki.openstack.org/wiki/Icehouse_Release_Schedule. However, this is important, so leaving as high priority --johngarbutt

Moved this to high, while we chat through, need this before we fix API v3 in stone --johnthetubaguy

Deferred to icehouse-3 as the blueprint was not approved by the icehouse-2 blueprint approval deadline. --russellb

If any specification or use cases have been thought, I would appreciate your additional writing.

------ This is from OpenStack Dev Mailing List ------

I'm working on the implementation of instance-tasks-api[0] in Nova and this is what I've been moving towards so far.
The API will accept a string to be a part of the task but it will have meaning only to the client, not to Nova.
Then if tasks can be searched or filtered by that field I think that would meet the requirements you layed out above, or is something missing?
-- Andrew Laski[2013/11/22]

>I'm working on the implementation of instance-tasks-api[0] in Nova and this is what I've been moving towards so far.
Yes, I know. I think that is good idea.
>The API will accept a string to be a part of the task but it will have meaning only to the client, not to Nova. Then if
>tasks can be searched or filtered by that field I think that would meet the requirements you layed out above, or is
>something missing?
Hmmm, as far as I understand, keystone(keystone work plan blueprint) generate request_id to each request.
(I think that is a good idea.)
And task_id is generated by instance-tasks-api.
Is my understanding of this correct?
Or if I miss something, thanks for telling me anything.
-- Haruka Tanizawa[2013/11/22]

You're correct on request_id and task_id.
What I'm planning is a string field that a user can pass in with the request and it will be part of the task representation.
That field will have no meaning to Nova, but a client like Heat could use it to ensure that they don't send requests twice by checking if there's a task with that field set.
-- Andrew Laski[2013/11/28]

>You're correct on request_id and task_id.
>What I'm planning is a string field that a user can pass in with the request and it will be part of the task representation.
>That field will have no meaning to Nova, but a client like Heat could use it to ensure that they don't send requests twice
>by checking if there's a task with that field set.
I see.
Especially, this point is so good.
'Heat could use it to ensure that they don't send requests twice by checking if there's a task with that field set.'
Moreover, I want to ask some questions about instance-tasks-api.
(I'm sorry it's a little bit long...)
* Is instance-tasks-api process outside of Nova? Is it standalone?
* About 'user can pass in with the request'
  When user specifies task_id, task_id would be which user specified.
  And if user doesn't specify task_id, does task_id generate automatically by Nova?
  (like correlation_id is generated by oslo auto when specified from noonne.)
* About management state of API
  Which is correct 'Queued, Active, Error, Complete' or ' pendig, in progress, and completed'?
  And for exmple 'live migration', there are 'pre migration', 'migration(migrateToURI)' and 'post migration'.
  Do you care about each detailed task? or care about 'live migrating ' ?
  Does 'in progress'(for example) say about in progress of 'pre migration' or in progress of 'live migration'?
* About relation with 'Taskflow'.
  Nova's taskflow-nize is not yet.
  However, taskflow's persistence of flow state is good helper for cancelling tasks, I think.
  (I think cancelling is not scope of i-2.)
  How do you think of this relation and the fiture?
-- Haruka Tanizawa[2013/11/29]

>* Is instance-tasks-api process outside of Nova? Is it standalone?
This is something that's entirely contained within Nova.
It's just adding a different representation of what is already occurring with task_states on an instance.
>* About 'user can pass in with the request'
>When user specifies task_id, task_id would be which user specified.
>And if user doesn't specify task_id, does task_id generate automatically by Nova?
>(like correlation_id is generated by oslo auto when specified from noonne.)
I think it's better to think of it as a 'tag' field, not task_id.
task_id is something that would be generated within Nova, but a tag field would allow a client to specify a small amount of data to attach to the task.
Like a token that could be used to identify requests that have been made.
So if nothing is specified the field will remain blank.
>* About management state of API
The implementation hasn't reached this point yet so it's up for discussion, but 'Queued, Active, Error, Complete' is the current plan.
>And for exmple 'live migration', there are 'pre migration', 'migration(migrateToURI)' and 'post migration'.
>Do you care about each detailed task? or care about 'live migrating ' ?
>Does 'in progress'(for example) say about in progress of 'pre migration' or in progress of 'live migration'?
I think it makes sense for live migration to be a task, and any associated steps would be sub resources under that task.
When we start to look at cancelling tasks it makes sense to cancel a live migration rather than cancelling a pre migration.
>* About relation with 'Taskflow'.
I think this is something to consider in the future.
For now I'm more focused on the user visibility into tasks than how they're implemented within Nova.
But there is a lot of implementation improvement that can happen later.
-- Andrew Laski[2013/12/04]

Is getting task information(e.g. list tasks) API separated by each user?
Or can anybody execute these APIs?
Without user separated thought, user may not set unique id,
because there is a case that other user has already used this id.
This id doesn't work as an unique key of a request.

Since task_id is auto generated, so I want to set unique string at 'tag' field by myself.
(Maybe putting task_id by user his/her self is hard to accept?)
I want to use this field as judgement materials of retry(duplicate) request or new request.
So, how about making this 'tag' field like flexible metadata field such as
other API(I don't know yet) can refer it.
-- Haruka Tanizawa[2013/12/04]

Reference:
http://openstack.10931.n7.nabble.com/nova-heat-keystone-RFC-introducing-quot-request-identification-quot-td24300.html

-----------------------------------------------------

Prerequisite:
    Not related to TaskAPI and request_id.

Points:
* task_id
-> client(user, heat, etc...) can't specify. TaskAPI generates it.
* value of 'tag' field
-> client(user, heat, etc...) can specify. If they don't specify, remain blank.

* Status which TaskAPI returns.
-> 'Queued, Active, Error, Complete'(just idea...)

If user can't get response, user can't know resource_id or task_id, so user can't judge next
action whether user shoud repost same request as previous or shoud not repost.
User doesn't want to create duplicate resource.
So, user need to 'tag' field which user can put their own value, not only task_id.
-- Haruka Tanizawa

Gerrit topic: https://review.openstack.org/#q,topic:bp/instance-tasks-api,n,z

Addressed by: https://review.openstack.org/70417
    WIP Instance tasks db model and NovaObject

Addressed by: https://review.openstack.org/70418
    WIP Instance tasks API

Addressed by: https://review.openstack.org/70421
    WIP Add instance task to the reboot action

Gerrit topic: https://review.openstack.org/#q,topic:bp/for,n,z

Addressed by: https://review.openstack.org/86938
    Proposed blueprint for instance tasks API

Gerrit topic: https://review.openstack.org/#q,topic:bp/covers,n,z

(?)

Work Items

Dependency tree

* Blueprints in grey have been implemented.