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

Method: GET
Path: /pulp/api/v2/tasks/<task_id>/
Permission: read
Response Codes:
  • 200 - if the task is found
  • 404 - if the task is not found
Return: a Task Report representing the task queried

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.

Method: DELETE
Path: /pulp/api/v2/tasks/<task_id>/
Permission: delete
Response Codes:
  • 200 - if the task cancellation request was successfully received
  • 404 - if the task is not found
Return: null

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.

Method: GET
Path: /pulp/api/v2/tasks/
Permission: read
Query Parameters:
  • tag (string) - (optional) only return tasks tagged with all tag parameters
Response Codes:
  • 200 - containing an array of tasks
Return: array of Task Report

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.

Method: DELETE
Path: /pulp/api/v2/tasks/
Permission: delete
  • state (string) - (optional) only delete tasks currently in this state

For example:

/pulp/api/v2/tasks/?state=finished&state=skipped
Response Codes:
  • 204 - if the tasks were successfully deleted
  • 403 - if there was a forbidden request
Return: httpResponse or pulp Exception

Searching for Tasks

API callers may also search for tasks. This uses a search criteria document.

Method: POST
Path: /pulp/api/v2/tasks/search/
Permission: read
Request Body Contents: include the key “criteria” whose value is a mapping structure as defined in Search Criteria
Response Codes:
  • 200 - containing the list of tasks
Return: the same format as retrieving a single task, except the base of the return value is a list. If no results are found, an empty list is returned.
Method: GET
Path: /pulp/api/v2/tasks/search/
Permission: read
Query Parameters: query params should match the attributes of a Criteria object as defined in Search Criteria. The exception is that field names should be specified in singular form with as many ‘field=foo’ pairs as needed.

For example:

/pulp/api/v2/tasks/search/?field=id&field=task_type&limit=20
Response Codes:
  • 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.

Method: DELETE
Path: /pulp/api/v2/task_groups/<group_id>/
Permission: delete
Response Codes:
  • 200 - if the task group cancellation request was successfully received
  • 404 - if the task group is not found
Return: null

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

Method: GET
Path: /pulp/api/v2/task_groups/<task_group_id>/state_summary/
Permission: read
Response Codes:
  • 200 - if the task group is found
  • 404 - if the task group id is not found
Return: a Cancelling Tasks in a Task Group summarizing the state of all tasks belonging to queried task group id