From 8f56a9a01c4c9f71aa3ea7c20fcf72e7c6e4536c Mon Sep 17 00:00:00 2001 From: Masahito Muroi Date: Tue, 6 Jan 2015 09:18:11 +0000 Subject: [PATCH] Add conditions and troubleshoot in Images and Image data section Adding preconditions, postconditions and troubleshooting information in Image and Image data section. Partial-bug: #1390523 Partial-bug: #1390528 Change-Id: I3bb83ddd5fee06f0be7bb74d20a21a8aa0a8360d --- api-ref/src/docbkx/ch_images-v2.xml | 3 +- .../wadls/image-api/src/v2/os-image-v2.wadl | 131 ++++++++++++++++-- 2 files changed, 122 insertions(+), 12 deletions(-) diff --git a/api-ref/src/docbkx/ch_images-v2.xml b/api-ref/src/docbkx/ch_images-v2.xml index db96bb6be..77278f158 100644 --- a/api-ref/src/docbkx/ch_images-v2.xml +++ b/api-ref/src/docbkx/ch_images-v2.xml @@ -27,8 +27,7 @@
Images Create, update, and delete image metadata records. - Enable users to share images with each other. Also, upload - and download raw image data. + Enable users to share images with each other. diff --git a/api-ref/src/wadls/image-api/src/v2/os-image-v2.wadl b/api-ref/src/wadls/image-api/src/v2/os-image-v2.wadl index 1ea17d2ce..e83c688ff 100644 --- a/api-ref/src/wadls/image-api/src/v2/os-image-v2.wadl +++ b/api-ref/src/wadls/image-api/src/v2/os-image-v2.wadl @@ -133,6 +133,9 @@ parameters. The API uses the natural sorting of whatever image attribute is provided as the sort_key. + You can see a list of VM images which status is in + active, queued, or + saving. @@ -162,6 +165,16 @@ Created with a Location header that contains the newly-created URI for the image. Response body represents the created image entity. + Synchronous Postconditions + + With correct permissions, you can see + the image status as queued through API + calls. + With correct permissions, you can see + the image status as active through API + calls if you created the image with + Location header. + Appendix B: HTTP PATCH media types in the OpenStack Image Service API v2 Reference. + Preconditions + + When adding or replacing a new location + to the specified image, you need to set disk_format + and container_format in the image. + When locations of the specified image + is replaced by replacing operation, the old location + needs to be set in the image on ahead. + + Synchronous Postconditions + + With correct permissions, you can see + the updated values of the image's attributes. + + With correct permissions, you can see + the image status as active through API calls + after adding a location to the image which had no + location. + With correct permissions, you can see + the image status as queued through API calls + after removing all locations from the image + + + Troubleshooting + + If you can not update locations you might + lack some infomation in your requests. Ensure you meet + the preconditions then investigate the your API + requests. + @@ -289,6 +332,10 @@ Gets details for a specified image. (Since Image API v2.0.) Response body is a single image entity. + Preconditions + + The specified image must exist. + @@ -310,12 +357,33 @@ Deletes a specified image. (Since Image API v2.0.) You cannot delete images with the 'protected' - attribute set to true (boolean); the response returns - the HTTP 403 status code. - You must first set the 'protected' attribute to - false (boolean) and then perform the delete. The - response is empty and returns the HTTP 204 status - code. + attribute set to true (boolean); + Preconditions + + You can delete an image in all status + except deleted. + You must first set the 'protected' attribute + to false (boolean) and then perform + the delete. + + Synchronous Postconditions + + The response is empty and returns the + HTTP 204 status code. + The image is deleted in images index. + + The binary image data managed by OpenStack + Image Service is deleted from the storage node if the + deleted image stores image data in the node. + + TroubleShooting + + The response returns the HTTP 403 status + code when the 'protected' attribute is set to + true even if you have a correct permissions. + Ensure you meet the preconditions then investigate + the attribute. + @@ -330,8 +398,6 @@ title="Upload binary image data"> Uploads binary image data. (Since Image API v2.0.) - An image record must exist before a client can store - binary image data with it. Set the Content-Type request header to application/octet-stream. Example call: curl -i -X PUT -H "X-Auth-Token: @@ -339,6 +405,38 @@ application/octet-stream" -d @/home/glance/ubuntu-12.10.qcow2 $image_url/v2/images/{image_id}/file + Preconditions + + The specified image must exist before you + store binary image data. + You need to set disk_format and container_format + in the image before you store the data. + You can only store the data into a image which + status is queued. + The user must have enough image strage quota + remaining to store the data. + Size of the data must be less than OpenStack + Image Service restricts. + + Synchronous Postconditions + + With correct permissions, you can see the + image status as active via API calls. + + With correct access, you can see the stored + data in the storage system that OpenStack Image Service + manages. + + Troubleshooting + + If you can not store the data you might lack + some infomation in your requests or exceed the quota + you are allowed to use. Ensure you meet the preconditions + then investigate the your API requests. + The storage backends for storing the data need + enough free storage space to match the size of the data. + + @@ -362,8 +460,21 @@ checksum of the image data. Clients are encouraged to verify the integrity of the image data they receive by using this checksum. - If no image data exists, returns the HTTP 204 status - code. + + Preconditions + + The specified images must exist. + + Synchronous Postconditions + + You can download the binary image data + in your machine if the specified image has image + data. + If image data exists, you receive the + HTTP 200 status code. + If no image data exists, you receive + the HTTP 204 status code. +