New Image API /v2/images/{id}/tasks for task information¶
https://blueprints.launchpad.net/glance/+spec/messages-api
The image service now supports importing images or copying existing images in multiple glance stores using glance tasks, but there is restriction that only one import operation or copy operation is permitted simultaneously on an image to avoid race condition.
Problem description¶
Task APIs are not available to normal users. In Victoria we have fixed race condition while copying existing images in multiple stores which uses “task-id” to obtain lock on the image to prevent other import operations on the same image. The additional image property “os_glance_import_task” will be used to store “task id”. We are updating ‘message’ property of the task which helps calculate time based on last updated time of task to burst the lock as well as show how much data has been copied of that image. Copying operation may take a long time and normal user can be clueless about when lock will be busted or why his (other) requests are rejected without contacting to the administrator.
Proposed chage¶
Add new fields image_id, request_id and user fields to tasks database and new API /v2/images/{id}/tasks which will fetch the tasks associated with image_id of that image and returns it to the user. This new API will return all tasks associated with image which are not expired. This expiration time is calculated when task reaches a final state of success or failure using task_time_to_live configuration parameter defined in glance-api.conf file. If active task is not present for given image then it will return empty list to user.
The request-id will effectively help user to find out what happened with his request, why his request has been denied and which task is currently being performed on the image.
The user field is an alternate to request_id field. In general client tools can access/generate request-ids but possibility normal users don’t have access to the request-ids, in this case the user field will help them to identify their particular task and its status. So from now on the tasks will have either request-id or user or both associated with it.
More details on this API can be found in the REST API section of this spec.
Alternatives¶
Add new API endpoint /v2/messages/{task_id} which will return related task information to the user. In this case user have to know task_id in advance. To know the task_id in advance he needs to call GET API of image to figure out whether os_glance_import_task property is set on the image or not.
Another alternative is to expose task show API to all the users. At the moment task API’s are managed with two different policies; “tasks_api_access” and then crud level policies such as “add_task”, “get_tasks” etc. So in this case we first need to expose tasks_api_access to all users (than admin) and then need to expose individual level policies to end user. This might be confusing and need to document carefully otherwise default access might be provided to all task API’s by mistake.
Data model impact¶
This spec proposes to add image_id, request-id and user fields to tasks database table. Those will be null and does not require any migration script to add this information to existing records.
REST API impact¶
New API
Show tasks associated with the given image, for example, information about all active (not expired) tasks associated with the image.
Common Response Codes
Not Found: 404 Not Found with details.
API Version
All URLS will be under the v2 Glance API. If it is not explicitly specified assume /v2/<url>
[New API] Get tasks associated with image
Show tasks associated with given image:
GET /v2/images/{image_id}/tasks
This API takes no query parameters and when authorized returns tasks associated with given image. If it does not found any active task associated with the image then it will return empty list to the user. Example of the valid response:
{
"tasks": [
{
"task": {
"id": "ee22890e-8948-4ea6-9668-831f973c84f5",
"image_id": "dddddddd-dddd-dddd-dddd-dddddddddddd",
"request-id": "rrrrrrr-rrrr-rrrr-rrrr-rrrrrrrrrrrr",
"user": "uuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuuu",
"type": "api_image_import",
"status": "processing",
"owner": "64f0efc9955145aeb06f297a8a6fe402",
"expires_at": null,
"created_at": "2020-12-18T05:20:38.000000",
"updated_at": "2020-12-18T05:25:39.000000",
"deleted_at": null,
"deleted": false,
"input": {
"image_id": "829c729b-ebc4-4cc7-a164-6f43f1149b17",
"import_req": {
"method": {"name": "copy-image"},
"all_stores": true,
"all_stores_must_succeed": false
}
"backend": [
"fast",
"cheap",
"slow",
"reliable",
"common"
]
},
"result": null,
"message": "Copied 15 MiB"
},
}
]
}
Response codes:
200 – Upon authorization and successful request. The response body contains the JSON payload with the known stores.
Example curl usage:
curl -g -i -X GET -H "X-Auth-Token: $token"
-H "Content-Type: application/octet-stream"
$image_url/v2/images/{image_id}/tasks
Security impact¶
None
Notifications impact¶
None
Other end user impact¶
This proposal introduces a few other user impacts worth noting.
Glance client Ideally the glance client (CLI + REST client) should be updated in accordance with this spec. Notably:
CLI / API support for get task information from image.
Performance Impact¶
None
Other deployer impact¶
None
Developer impact¶
None
Implementation¶
Assignee(s)¶
- Primary assignee:
abhishek-kekane
- Other contributors:
None
Work Items¶
Implementation tasks may consist of:
Add expand script for adding new fields to tasks database
Modify tasks data layer to use newly added fields
Modify tasks CRUD operations to use newly added fields
Add support for new API.
Add python-glanceclient support
Add API documentation for new API
Dependencies¶
None
Testing¶
Need to add new unit tests for coverage
Documentation Impact¶
As mentioned in the ‘work items’ section, we’ll need to ensure the glance docs are updated for:
The new get tasks from image REST API.
Overall glance multi-store documentation to educate deployers on the feature and how/when it’s used.
