diff --git a/api-ref/source/images.inc b/api-ref/source/images.inc index 527cff6104f5..3ad087810729 100644 --- a/api-ref/source/images.inc +++ b/api-ref/source/images.inc @@ -1,7 +1,4 @@ .. -*- rst -*- -.. needs:parameter_verification -.. needs:example_verification -.. needs:body_verification ==================== Images (DEPRECATED) @@ -15,12 +12,13 @@ See: `Relevant Image APIs `__. -Lists, shows details for, and deletes images. Also sets, lists, shows -details for, and deletes image metadata. +Lists, shows details, creates, updates, and deletes images. +Also sets, lists, shows details, create, update and deletes image metadata. An image is a collection of files that you use to create and rebuild a server. By default, operators provide pre-built operating system images. -You can also create custom images. See Compute server actions. +You can also create custom images. See: `Create Image Action +`__. By default, the ``policy.json`` file authorizes all users to view the image size in the ``OS-EXT-IMG-SIZE:size`` extended attribute. @@ -34,12 +32,33 @@ List images. Normal response codes: 200 -Error response codes: badRequest(400), unauthorized(401), forbidden(403), -itemNotFound(404) +Error response codes: badRequest(400), unauthorized(401), forbidden(403) + +Request +------- + +.. rest_parameters:: parameters.yaml + + - changes-since: changes-since + - server: image_server_query + - name: image_name_query + - status: image_status_query + - minDisk: minDisk + - minRam: minRam + - type : image_type_query + - limit : limit + - marker : marker Response -------- +.. rest_parameters:: parameters.yaml + + - images: images + - id: image_id_body + - name: image_name + - links: links + **Example List Images: JSON response** .. literalinclude:: ../../doc/api_samples/images/images-list-get-resp.json @@ -54,12 +73,43 @@ List images with details. Normal response codes: 200 -Error response codes: badRequest(400), unauthorized(401), forbidden(403), -itemNotFound(404) +Error response codes: badRequest(400), unauthorized(401), forbidden(403) + +Request +------- + +.. rest_parameters:: parameters.yaml + + - changes-since: changes-since + - server: image_server_query + - name: image_name_query + - status: image_status_query + - minDisk: minDisk + - minRam: minRam + - type : image_type_query + - limit : limit + - marker : marker Response -------- +.. rest_parameters:: parameters.yaml + + - images: images + - id: image_id_body + - name: image_name + - minRam: minRam_body + - minDisk: minDisk_body + - metadata: metadata_image + - created: created + - updated: updated + - status: image_status + - progress: image_progress + - links: links + - server: image_server + - OS-EXT-IMG-SIZE:size: image_size + - OS-DCF:diskConfig: OS-DCF:diskConfig + **Example List Images Details: JSON response** .. literalinclude:: ../../doc/api_samples/images/images-details-get-resp.json @@ -87,6 +137,23 @@ Request Response -------- +.. rest_parameters:: parameters.yaml + + - images: images + - id: image_id_body + - name: image_name + - minRam: minRam_body + - minDisk: minDisk_body + - metadata: metadata_image + - created: created + - updated: updated + - status: image_status + - progress: image_progress + - links: links + - server: image_server + - OS-EXT-IMG-SIZE:size: image_size + - OS-DCF:diskConfig: OS-DCF:diskConfig + **Example Show Image Details: JSON response** .. literalinclude:: ../../doc/api_samples/images/images-details-get-resp.json @@ -113,6 +180,8 @@ Request Response -------- +There is no body content for the response of a successful DELETE action. + List Image Metadata =================== @@ -134,7 +203,11 @@ Request Response -------- -**Example Show Image Metadata Details: JSON response** +.. rest_parameters:: parameters.yaml + + - metadata: metadata_image + +**Example List Image Metadata Details: JSON response** .. literalinclude:: ../../doc/api_samples/images/image-metadata-get-resp.json :language: javascript @@ -149,7 +222,7 @@ Create an image metadata. Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403), -itemNotFound(404), requestEntityTooLarge(413) +itemNotFound(404) Request ------- @@ -157,6 +230,7 @@ Request .. rest_parameters:: parameters.yaml - image_id: image_id + - metadata: metadata_image **Example Create Image Metadata: JSON request** @@ -166,6 +240,10 @@ Request Response -------- +.. rest_parameters:: parameters.yaml + + - metadata: metadata_image + **Example Create Image Metadata: JSON response** .. literalinclude:: ../../doc/api_samples/images/image-metadata-post-resp.json @@ -181,7 +259,7 @@ Update an image metadata Normal response codes: 200 Error response codes: badRequest(400), unauthorized(401), forbidden(403), -itemNotFound(404), requestEntityTooLarge(413) +itemNotFound(404) Request ------- @@ -189,6 +267,7 @@ Request .. rest_parameters:: parameters.yaml - image_id: image_id + - metadata: metadata_image **Example Update Image Metadata: JSON request** @@ -198,6 +277,10 @@ Request Response -------- +.. rest_parameters:: parameters.yaml + + - metadata: metadata_image + **Example Update Image Metadata: JSON response** .. literalinclude:: ../../doc/api_samples/images/image-metadata-put-resp.json @@ -225,6 +308,10 @@ Request Response -------- +.. rest_parameters:: parameters.yaml + + - meta: meta + **Example Show Image Metadata Item Details: JSON response** .. literalinclude:: ../../doc/api_samples/images/image-meta-key-get.json @@ -248,6 +335,7 @@ Request - image_id: image_id - key: key + - meta: meta **Example Create Or Update Image Metadata Item: JSON request** @@ -257,6 +345,10 @@ Request Response -------- +.. rest_parameters:: parameters.yaml + + - meta: meta + **Example Create Or Update Image Metadata Item: JSON response** .. literalinclude:: ../../doc/api_samples/images/image-meta-key-put-resp.json @@ -283,3 +375,5 @@ Request Response -------- + +There is no body content for the response of a successful DELETE action. diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index a49ab63774fd..9ff8f2e33069 100644 --- a/api-ref/source/parameters.yaml +++ b/api-ref/source/parameters.yaml @@ -320,7 +320,8 @@ changes-since: than re-downloading and re-parsing the full status at each polling interval. If data has changed, the call returns only the items changed since the ``changes-since`` time. If data has not changed since the ``changes-since`` time, the call returns an - empty list.\nTo enable you to keep track of changes, this filter also displays images + empty list. + To enable you to keep track of changes, this filter also displays images that were deleted if the ``changes-since`` value specifies a date in the last 30 days. Items deleted more than 30 days ago might be returned, but it is not guaranteed. The date and time stamp format is `ISO 8601 `_: @@ -407,12 +408,37 @@ hypervisor_query: in: query required: false type: string +image_name_query: + description: | + Filters the response by an image name, as a string. + in: query + required: false + type: string image_query: description: | Filters the response by an image, as a UUID. in: query required: false type: string +image_server_query: + description: | + Filters the response by a server, as a URL. + format: uri + in: query + required: false + type: string +image_status_query: + description: | + Filters the response by an image status, as a string. For example, ``ACTIVE``. + in: query + required: false + type: string +image_type_query: + description: | + Filters the response by an image type. For example, ``snapshot`` or ``backup``. + in: query + required: false + type: string include: description: | Specify ``include=uuid[,uuid...]`` to include the instances in the results. @@ -504,12 +530,6 @@ minRam: in: query required: false type: integer -name_7: - description: | - Filters the response by an image name, as a string. - in: query - required: false - type: string not_tags_any_query: in: query required: false @@ -534,13 +554,6 @@ reservation_id_query: type: string description: | A reservation id as returned by a servers multiple create call. -server_1: - description: | - Filters the response by a server, as a URL. - format: uri - in: query - required: false - type: string server_name_query: description: | Filters the response by a server name, as a string. You can use regular expressions @@ -576,12 +589,6 @@ sort_key: in: query required: false type: string -status_1: - description: | - Filters the response by an image status, as a string. For example, ``ACTIVE``. - in: query - required: false - type: string # TODO(sdague): when server-tags actually get documented, these should # be updated. tags_any_query: @@ -602,12 +609,6 @@ tags_query: all tags in this list will be returned. Boolean expression in this case is 't1 AND t2'. Tags in query must be separated by comma. min_version: 2.26 -type_1: - description: | - Filters the response by an image type. For example, ``snapshot`` or ``backup``. - in: query - required: false - type: string user_id_1: description: | Filters the response by a user, by ID. @@ -1983,6 +1984,51 @@ image: in: body required: true type: object +image_id_body: + description: | + The ID of the Image. + in: body + required: true + type: string +image_name: + description: | + The display name of an Image. + in: body + required: true + type: string +image_progress: + description: | + A percentage value of the image save progress. This can be one of: + + - ``ACTIVE``: 100 + - ``SAVING``: 25 or 50 + in: body + required: true + type: integer +image_server: + description: | + The server booted from image. + in: body + required: false + type: object +image_size: + description: | + The size of the image. + in: body + required: true + type: integer +image_status: + description: | + The status of image, as a string. This can be one of: + + - ``ACTIVE``: image is in active state + - ``SAVING``: image is in queued or in saving process + - ``DELETED``: image is deleted or in progress of deletion + - ``ERROR``: image is in error state + - ``UNKNOWN``: image is in unknown state + in: body + required: true + type: string imageRef: description: | The image reference, as a UUID or full URL, for the image to use for your server @@ -1999,10 +2045,10 @@ imageRef_1: type: string images: description: | - Image information. + An array of Image objects. in: body required: true - type: string + type: array in_use: description: | The in-use quota value. @@ -2396,6 +2442,12 @@ memory_mb_used: in: body required: true type: integer +meta: + description: | + The object of detailed key metadata items. + in: body + required: true + type: object metadata: description: | Metadata key and value pairs. The maximum size of the metadata key and value is @@ -2421,7 +2473,7 @@ metadata_image: Metadata key and value pairs. The maximum size for each metadata key and value pair is 255 bytes. in: body - required: false + required: true type: object metadata_items: description: | @@ -2470,6 +2522,18 @@ migrate: in: body required: true type: string +minDisk_body: + description: | + The minimum amount of disk space an image requires to boot, in GiB. For example, ``100``. + in: body + required: true + type: integer +minRam_body: + description: | + The minimum amount of RAM an image requires to function, in MB. For example, ``512``. + in: body + required: true + type: integer name: description: | The security group name. diff --git a/api-ref/source/servers-admin-action.inc b/api-ref/source/servers-admin-action.inc index 3b10b010f80a..84a86951ca46 100644 --- a/api-ref/source/servers-admin-action.inc +++ b/api-ref/source/servers-admin-action.inc @@ -42,7 +42,7 @@ Request - name: backup_name - backup_type: backup_type - rotation: backup_rotation - - metadata: metadata_image + - metadata: metadata **Example Create Server Back Up (Createbackup Action): JSON request**