Task Management¶
Pulp can execute almost any call asynchronously and some calls are always executed asynchronously. Pulp provides REST APIs to inspect and manage the tasks executing these calls.
Task Report¶
The task information object is used to report information about any asynchronously executed task.
- _href (string) - uri path to retrieve this task report object.
- state (string) - the current state of the task. The possible values include: ‘waiting’, ‘skipped’, ‘running’, ‘suspended’, ‘finished’, ‘error’ and ‘canceled’.
- task_id (string) - the unique id of the task that is executing the asynchronous call
- task_type (string) - deprecated the fully qualified (package/method) type of the task that is executing the asynchronous call. The field is empty for tasks performed by consumer agent.
- progress_report (object) - arbitrary progress information, usually in the form of an object
- result (any) - the return value of the call, if any
- exception (null or string) - deprecated the error exception value, if any
- traceback (null or array) - deprecated the resulting traceback if an exception was raised
- start_time (null or string) - the time the call started executing
- finish_time (null or string) - the time the call stopped executing
- tags (array) - arbitrary tags useful for looking up the call report
- spawned_tasks (array) - List of objects containing the uri and task id for any tasks that were spawned by this task.
- worker_name (string) - The worker associated with the task. This field is empty if a worker is not yet assigned.
- queue (string) - The queue associated with the task. This field is empty if a queue is not yet assigned.
- error (null or object) - Any, errors that occurred that did not cause the overall call to fail. See Error Details.
Note
The exception and traceback fields have been deprecated as of Pulp 2.4. The information about errors that have occurred will be contained in the error block. See Error Details for more information.
Example Task Report:
{
"_href": "/pulp/api/v2/tasks/0fe4fcab-a040-11e1-a71c-00508d977dff/",
"state": "running",
"worker_name": "reserved_resource_worker-0@your.domain.com",
"task_id": "0fe4fcab-a040-11e1-a71c-00508d977dff",
"task_type": "pulp.server.tasks.repository.sync_with_auto_publish",
"progress_report": {}, # contents depend on the operation
"result": null,
"start_time": "2012-05-17T16:48:00Z",
"finish_time": null,
"exception": null,
"traceback": null,
"tags": [
"pulp:repository:f16",
"pulp:action:sync"
],
"spawned_tasks": [{"href": "/pulp/api/v2/tasks/7744e2df-39b9-46f0-bb10-feffa2f7014b/",
"task_id": "7744e2df-39b9-46f0-bb10-feffa2f7014b" }],
"error": null
}
Polling Task Progress¶
Poll a task for progress and result information for the asynchronous call it is executing. Polling returns a Task Report
/pulp/api/v2/tasks/<task_id>/- 200 - if the task is found
- 404 - if the task is not found
Cancelling a Task¶
Some asynchronous tasks may be canceled by the user before they complete. A task must be in the waiting or running states in order to be canceled.
Note
It is possible for a task to complete or experience an error before the cancellation request is processed, so it is not guaranteed that a task’s final state will be ‘canceled’ as a result of this call. In these instances this method call will still return a response code of 200.
/pulp/api/v2/tasks/<task_id>/- 200 - if the task cancellation request was successfully received
- 404 - if the task is not found
Listing Tasks¶
All currently running and waiting tasks may be listed. This returns an array of Task Report instances. the array can be filtered by tags.
/pulp/api/v2/tasks/- tag (string) - (optional) only return tasks tagged with all tag parameters
- 200 - containing an array of tasks
Deleting Completed Tasks¶
All completed tasks with states finished, error, skipped may be deleted. This call returns response code 204 if successful or code 403 if the request is forbidden.
/pulp/api/v2/tasks/- state (string) - (optional) only delete tasks currently in this state
For example:
/pulp/api/v2/tasks/?state=finished&state=skipped
- 204 - if the tasks were successfully deleted
- 403 - if there was a forbidden request
Searching for Tasks¶
API callers may also search for tasks. This uses a search criteria document.
/pulp/api/v2/tasks/search/- 200 - containing the list of tasks
/pulp/api/v2/tasks/search/For example:
/pulp/api/v2/tasks/search/?field=id&field=task_type&limit=20
- 200 - containing the array of tasks.
Task Group Management¶
Cancelling Tasks in a Task Group¶
All asynchronous tasks in a particular task group may be canceled by the user before they complete. A task must be in the waiting or running state in order to be canceled.
Note
It is possible for a task to complete or experience an error before the cancellation request is processed, so it is not guaranteed that a task’s final state will be ‘canceled’ as a result of this call. In these instances this method call will still return a response code of 200.
/pulp/api/v2/task_groups/<group_id>/- 200 - if the task group cancellation request was successfully received
- 404 - if the task group is not found
Task Group Summary¶
Task Group Summary object summarizes the state of all the tasks belonging to a task group.
- accepted (int) - number of tasks in ‘accepted’ state
- finished (int) - number of tasks in ‘finished’ state
- running (int) - number of tasks in ‘running’ state
- canceled (int) - number of tasks in ‘canceled’ state
- waiting (int) - number of tasks in ‘waiting’ state
- skipped (int) - number of tasks in ‘skipped’ state
- suspended (int) - number of tasks in ‘suspended’ state
- error (int) - number of tasks in ‘error’ state
- total (int) - total number of tasks in the task group
Example task group summary:
{
"accepted": 0,
"finished": 100,
"running": 4,
"canceled": 0,
"waiting": 2,
"skipped": 0,
"suspended": 0,
"error": 0,
"total": 106
}
Polling Task Group Progress¶
Poll a group of tasks for progress summary. Polling returns a Cancelling Tasks in a Task Group
/pulp/api/v2/task_groups/<task_group_id>/state_summary/- 200 - if the task group is found
- 404 - if the task group id is not found