Image Service API v2 (CURRENT)¶
Images¶
Creates, lists, shows, updates, deletes, and performs other operations on images.
General information¶
Images
An image is represented by a JSON Object, that is, as a set of key:value pairs. Some of these keys are base properties that are managed by the Image service. The remainder are properties put on the image by the operator or the image owner.
Note
Another common term for “image properties” is “image metadata” because what we’re talking about here are properties that describe the image data that can be consumed by various OpenStack services (for example, by the Compute service to boot a server, or by the Volume service to create a bootable volume).
Here’s some important information about image properties:
The base properties are always included in the image representation. A base property that doesn’t have a value is displayed with its value set to
null(that is, the JSON null data type).Additional properties, whose value is always a string data type, are only included in the response if they have a value.
Since version 2.2, the Images API allows an operator to configure property protections, by which the create, read, update, and delete operations on specific image properties may be restricted to particular user roles. Consult the documentation of your cloud operator for details.
Arguably the most important properties of an image are its id, which uniquely identifies the image, its status, which indicates the current situation of the image (which, in turn, indicates what you can do with the image), and its visibility, which indicates who has access to the image.
Some properties are used internally by glance and API users are not allowed to set or modify them. Examples of these are id, status, and anything prefixed with the os_glance namespace.
Note
In addition to image properties, there’s usually a data payload that is
accessible via the image. In order to give image consumers some guarantees
about the data payload (for example, that the data associated with image
06b73bc7-9d62-4d37-ad95-d4708f37734f is the same today as it was when
you used it to boot a server yesterday) the Image service controls
particular image properties (for example, checksum) that cannot be
modified. A shorthand way to refer to the way the image data payload is
related to its representation as an image in the Images API is to say that
“images are immutable”. (This obviously applies to the image data payload,
not its representation in the Image service.) See the Image Data section of this document for more information.
Image status
The possible status values for images are presented in the following table.
Status |
Description |
|---|---|
queued |
The Image service reserved an image ID for the image in the catalog but did not yet upload any image data. |
saving |
The Image service is in the process of saving the raw data for the image into the backing store. |
active |
The image is active and ready for consumption in the Image service. |
killed |
An image data upload error occurred. |
deleted |
The Image service retains information about the image but the image is no longer available for use. |
pending_delete |
Similar to the |
deactivated |
The image data is not available for use. |
uploading |
Data has been staged as part of the interoperable image import process. It is not yet available for use. (Since Image API 2.6) |
importing |
The image data is being processed as part of the interoperable image import process, but is not yet available for use. (Since Image API 2.6) |
Image visibility
The possible values for image visibility are presented in the following table.
Visibility |
Description |
|---|---|
|
Any user may read the image and its data payload. Additionally, the image appears in the default image list of all users. |
|
Any user may read the image and its data payload, but the image does not appear in the default image list of any user other than the owner. (This visibility value was added in the Image API v2.5) |
|
An image must have this visibility in order for image members to be added to it. Only the owner and the specific image members who have been added to the image may read the image or its data payload. The image appears in the default image list of the owner. It also appears in the default image list of members who have accepted the image. See the Image Sharing section of this document for more information. If you do not specify a visibility value when you create an image, it is assigned this visibility by default. Non-owners, however, will not have access to the image until they are added as image members. (This visibility value was added in the Image API v2.5) |
|
Only the owner image may read the image or its data payload. Additionally, the image appears in the owner’s default image list. Since Image API v2.5, an image with private visibility cannot have members added to it. |
Note that the descriptions above discuss read access to images. Only the image owner (or an administrator) has write access to image properties and the image data payload. Further, in order to promise image immutability, the Image service will allow even the owner (or an administrator) only write-once permissions to specific image properties and the image data payload.
Creates a catalog record for an operating system disk image. (Since Image API v2.0)
The Location response header contains the URI for the image.
A multiple store backend support is introduced in the Rocky release
as a part of the EXPERIMENTAL Image API v2.8. Since Image API v2.8 a
new header OpenStack-image-store-ids which contains the list of
available stores will be included in response. This header is only
included if multiple backend stores are supported.
The response body contains the new image entity.
Synchronous Postconditions
With correct permissions, you can see the image status as
queuedthrough API calls.
Normal response codes: 201
Error response codes: 400, 401, 403, 409, 413, 415
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
container_format (Optional) |
body |
enum |
Format of the image container. Values may vary based on the configuration available in a particular OpenStack cloud. See the Image Schema response from the cloud itself for the valid values available. See Container Format in the Glance documentation for more information. Example formats are: The value might be Train changes: The |
disk_format (Optional) |
body |
enum |
The format of the disk. Values may vary based on the configuration available in a particular OpenStack cloud. See the Image Schema response from the cloud itself for the valid values available. See Disk Format in the Glance documentation for more information. Example formats are: The value might be Newton changes: The |
id (Optional) |
body |
string |
A unique, user-defined image UUID, in the format: nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn
Where n is a hexadecimal digit from 0 to f, or F. For example: b2173dd3-7ad6-4362-baa6-a68bce3565cb
If you omit this value, the API generates a UUID for the image. If you
specify a value that has already been assigned, the request fails with
a |
min_disk (Optional) |
body |
integer |
Amount of disk space in GB that is required to boot the image. |
min_ram (Optional) |
body |
integer |
Amount of RAM in MB that is required to boot the image. |
name (Optional) |
body |
string |
The name of the image. |
protected (Optional) |
body |
boolean |
Image protection for deletion. Valid value is |
tags (Optional) |
body |
array |
List of tags for this image. Each tag is a string of at most 255 chars. The maximum number of tags allowed on an image is set by the operator. |
visibility (Optional) |
body |
string |
Visibility for this image. Valid value is one of: |
Additionally, you may include additional properties specified as key:value pairs, where the value must be a string data type. Keys are limited to 255 chars in length. Available key names may be limited by the cloud’s property protection configuration and reserved namespaces like os_glance.
Request Example¶
{
"container_format": "bare",
"disk_format": "raw",
"name": "Ubuntu",
"id": "b2173dd3-7ad6-4362-baa6-a68bce3565cb"
}
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
Location |
header |
string |
The URL to access the image file from the external store. |
OpenStack-image-import-methods (Optional) |
header |
string |
A comma separated list of import method identifiers. Included only if image import is enabled in your cloud. Since Image API v2.6 |
OpenStack-image-store-ids (Optional) |
header |
string |
A comma separated list of available store identifiers. If this header is missing the cloud does not support multiple backend stores. |
checksum |
body |
string |
An MD5 hash over the image data. The value might be |
container_format |
body |
enum |
Format of the image container. Values may vary based on the configuration available in a particular OpenStack cloud. See the Image Schema response from the cloud itself for the valid values available. See Container Format in the Glance documentation for more information. Example formats are: The value might be Train changes: The |
created_at |
body |
string |
The date and time when the resource was created. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm
For example, The |
disk_format |
body |
enum |
The format of the disk. Values may vary based on the configuration available in a particular OpenStack cloud. See the Image Schema response from the cloud itself for the valid values available. See Disk Format in the Glance documentation for more information. Example formats are: The value might be Newton changes: The |
file |
body |
string |
The URL for the virtual machine image file. |
id |
body |
string |
A unique, user-defined image UUID, in the format: nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn
Where n is a hexadecimal digit from 0 to f, or F. For example: b2173dd3-7ad6-4362-baa6-a68bce3565cb
If you omit this value, the API generates a UUID for the image. |
min_disk |
body |
integer |
Amount of disk space in GB that is required to boot the image.
The value might be |
min_ram |
body |
integer |
Amount of RAM in MB that is required to boot the image.
The value might be |
name |
body |
string |
The name of the image. Value might be |
os_hash_algo |
body |
string |
The algorithm used to compute a secure hash of the image data for this
image. The result of the computation is displayed as the value of the
|
os_hash_value |
body |
string |
The hexdigest of the secure hash of the image data computed using the
algorithm whose name is the value of the |
os_hidden |
body |
boolean |
This field controls whether an image is displayed in the default image-list response. A “hidden” image is out of date somehow (for example, it may not have the latest updates applied) and hence should not be a user’s first choice, but it’s not deleted because it may be needed for server rebuilds. By hiding it from the default image list, it’s easier for end users to find and use a more up-to-date version of this image. (Since Image API v2.7) |
owner |
body |
string |
An identifier for the owner of the image, usually the project (also
called the “tenant”) ID.
The value might be |
protected |
body |
boolean |
A boolean value that must be |
schema |
body |
string |
The URL for the schema describing a virtual machine image. |
self |
body |
string |
The URL for the virtual machine image. |
size |
body |
integer |
The size of the image data, in bytes. The value
might be |
status |
body |
string |
The image status. |
tags |
body |
array |
List of tags for this image, possibly an empty list. |
updated_at |
body |
string |
The date and time when the resource was updated. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm
For example, The If the |
virtual_size |
body |
integer |
The virtual size of the image. The value might
be |
visibility |
body |
string |
Image visibility, that is, the access permission for the image. |
direct_url (Optional) |
body |
string |
The URL to access the image file kept in external store. It is present
only if the |
locations (Optional) |
body |
array |
A list of objects, each of which describes an image location. Each object
contains a |
The response may also include additional properties specified as key:value pairs if additional properties were specified in the request.
Response Example¶
{
"status": "queued",
"name": "Ubuntu",
"tags": [],
"container_format": "bare",
"created_at": "2015-11-29T22:21:42Z",
"size": null,
"disk_format": "raw",
"updated_at": "2015-11-29T22:21:42Z",
"visibility": "private",
"locations": [],
"self": "/v2/images/b2173dd3-7ad6-4362-baa6-a68bce3565cb",
"min_disk": 0,
"protected": false,
"id": "b2173dd3-7ad6-4362-baa6-a68bce3565cb",
"file": "/v2/images/b2173dd3-7ad6-4362-baa6-a68bce3565cb/file",
"checksum": null,
"os_hash_algo": null,
"os_hash_value": null,
"os_hidden": false,
"owner": "bab7d5c60cd041a0a36f7c4b6e1dd978",
"virtual_size": null,
"min_ram": 0,
"schema": "/v2/schemas/image"
}
Shows details for an image. (Since Image API v2.0)
The response body contains a single image entity.
Preconditions
The image must exist.
Normal response codes: 200
Error response codes: 400, 401, 403, 404
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
image_id |
path |
string |
The UUID of the image. |
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
checksum |
body |
string |
An MD5 hash over the image data. The value might be |
container_format |
body |
enum |
Format of the image container. Values may vary based on the configuration available in a particular OpenStack cloud. See the Image Schema response from the cloud itself for the valid values available. See Container Format in the Glance documentation for more information. Example formats are: The value might be Train changes: The |
created_at |
body |
string |
The date and time when the resource was created. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm
For example, The |
disk_format |
body |
enum |
The format of the disk. Values may vary based on the configuration available in a particular OpenStack cloud. See the Image Schema response from the cloud itself for the valid values available. See Disk Format in the Glance documentation for more information. Example formats are: The value might be Newton changes: The |
file |
body |
string |
The URL for the virtual machine image file. |
id |
body |
string |
A unique, user-defined image UUID, in the format: nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn
Where n is a hexadecimal digit from 0 to f, or F. For example: b2173dd3-7ad6-4362-baa6-a68bce3565cb
If you omit this value, the API generates a UUID for the image. |
min_disk |
body |
integer |
Amount of disk space in GB that is required to boot the image.
The value might be |
min_ram |
body |
integer |
Amount of RAM in MB that is required to boot the image.
The value might be |
name |
body |
string |
The name of the image. Value might be |
os_hash_algo |
body |
string |
The algorithm used to compute a secure hash of the image data for this
image. The result of the computation is displayed as the value of the
|
os_hash_value |
body |
string |
The hexdigest of the secure hash of the image data computed using the
algorithm whose name is the value of the |
os_hidden |
body |
boolean |
This field controls whether an image is displayed in the default image-list response. A “hidden” image is out of date somehow (for example, it may not have the latest updates applied) and hence should not be a user’s first choice, but it’s not deleted because it may be needed for server rebuilds. By hiding it from the default image list, it’s easier for end users to find and use a more up-to-date version of this image. (Since Image API v2.7) |
owner |
body |
string |
An identifier for the owner of the image, usually the project (also
called the “tenant”) ID.
The value might be |
protected |
body |
boolean |
A boolean value that must be |
schema |
body |
string |
The URL for the schema describing a virtual machine image. |
self |
body |
string |
The URL for the virtual machine image. |
size |
body |
integer |
The size of the image data, in bytes. The value
might be |
status |
body |
string |
The image status. |
tags |
body |
array |
List of tags for this image, possibly an empty list. |
updated_at |
body |
string |
The date and time when the resource was updated. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm
For example, The If the |
virtual_size |
body |
integer |
The virtual size of the image. The value might
be |
visibility |
body |
string |
Image visibility, that is, the access permission for the image. |
direct_url (Optional) |
body |
string |
The URL to access the image file kept in external store. It is present
only if the |
locations (Optional) |
body |
array |
A list of objects, each of which describes an image location. Each object
contains a |
The response may also include additional properties specified as key:value pairs if such properties have been added to the image by the owner or an administrator.
Response Example¶
{
"status": "active",
"name": "cirros-0.3.2-x86_64-disk",
"tags": [],
"container_format": "bare",
"created_at": "2014-05-05T17:15:10Z",
"disk_format": "qcow2",
"updated_at": "2014-05-05T17:15:11Z",
"visibility": "public",
"self": "/v2/images/1bea47ed-f6a9-463b-b423-14b9cca9ad27",
"min_disk": 0,
"protected": false,
"id": "1bea47ed-f6a9-463b-b423-14b9cca9ad27",
"file": "/v2/images/1bea47ed-f6a9-463b-b423-14b9cca9ad27/file",
"checksum": "64d7c1cd2b6f60c92c14662941cb7913",
"os_hash_algo": "sha512",
"os_hash_value": "073b4523583784fbe01daff81eba092a262ec37ba6d04dd3f52e4cd5c93eb8258af44881345ecda0e49f3d8cc6d2df6b050ff3e72681d723234aff9d17d0cf09",
"os_hidden": false,
"owner": "5ef70662f8b34079a6eddb8da9d75fe8",
"size": 13167616,
"min_ram": 0,
"schema": "/v2/schemas/image",
"virtual_size": null
}
Shows tasks associated with an image. (Since Image API v2.12)
The response body contains list of tasks, possibly empty, associated with the specified image.
Preconditions
The image must exist.
Normal response codes: 200
Error response codes: 404
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
image_id |
path |
string |
The UUID of the image. |
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
tasks |
body |
array |
A list of task objects, associated with the given image. |
Response Example¶
{
"tasks": [
{
"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"
}
]
}
Lists public virtual machine (VM) images. (Since Image API v2.0)
Pagination
Returns a subset of the larger collection of images and a link that you can use
to get the next set of images. You should always check for the presence of a
next link and use it as the URI in a subsequent HTTP GET request. You
should follow this pattern until a next link is no longer provided.
The next link preserves any query parameters that you send in your initial
request. You can use the first link to jump back to the first page of the
collection. If you prefer to paginate through images manually, use the
limit and marker parameters.
Query Filters
The list operation accepts query parameters to filter the response.
A client can provide direct comparison filters by using most image attributes,
such as name=Ubuntu, visibility=public, and so on.
To filter using image tags, use the filter tag (note the singular). To
filter on multiple tags, include each tag separately in the query. For
example, to find images with the tag ready, include tag=ready in your
query string. To find images tagged with ready and approved, include
tag=ready&tag=approved in your query string. (Note that only images
containing both tags will be included in the response.)
A client cannot use any link in the json-schema, such as self, file, or
schema, to filter the response.
You can list VM images that have a status of active, queued, or
saving.
The in Operator
As a convenience, you may specify several values for any of the following
fields by using the in operator:
container_format
disk_format
id
name
status
For most of these, usage is straight forward. For example, to list images in queued or saving status, use:
GET /v2/images?status=in:saving,queued
To find images in a particular list of image IDs, use:
GET /v2/images?id=in:3afb79c1-131a-4c38-a87c-bc4b801d14e6,2e011209-660f-44b5-baf2-2eb4babae53d
Using the in operator with the name property of images can be a bit
trickier, depending upon how creatively you have named your images. The
general rule is that if an image name contains a comma (,), you must
enclose the entire name in quotation marks ("). As usual, you must URL
encode any characters that require it.
For example, to find images named glass, darkly or share me, you would
use the following filter specification:
GET v2/images?name=in:"glass,%20darkly",share%20me
As with regular filtering by name, you must specify the complete name you are
looking for. Thus, for example, the query string name=in:glass,share will
only match images with the exact name glass or the exact name share.
It will not find an image named glass, darkly or an image named share
me.
Size Comparison Filters
You can use the size_min and size_max query parameters to filter images
that are greater than or less than the image size. The size, in bytes, is the
size of an image on disk.
For example, to filter the container to include only images that are from 1 to
4 MB, set the size_min query parameter to 1048576 and the size_max
query parameter to 4194304.
Time Comparison Filters
You can use a comparison operator along with the created_at or
updated_at fields to filter your results. Specify the operator first, a
colon (:) as a separator, and then the time in ISO 8601 Format. Available comparison operators
are:
Operator |
Description |
|---|---|
|
Return results more recent than the specified time. |
|
Return any results matching the specified time and also any more recent results. |
|
Return any results matching the specified time exactly. |
|
Return any results that do not match the specified time. |
|
Return results older than the specified time. |
|
Return any results matching the specified time and also any older results. |
For example:
GET v2/images?created_at=gt:2016-04-18T21:38:54Z
Sorting
You can use query parameters to sort the results of this operation.
sort_key. Sorts by an image attribute. Sorts in the natural sorting direction of the image attribute.sort_dir. Sorts in a sort direction.sort. Sorts by one or more sets of attribute and sort direction combinations. If you omit the sort direction in a set, the default isdesc.
To sort the response, use the sort_key and sort_dir query
parameters:
GET /v2/images?sort_key=name&sort_dir=asc&sort_key=status&sort_dir=desc
Alternatively, specify the sort query parameter:
GET /v2/images?sort=name:asc,status:desc
Note
Although this call has been available since version 2.0 of this API, it has been enhanced from release to release. The filtering and sorting functionality and syntax described above apply to the most recent release (Newton). Not everything described above will be available in prior releases.
Normal response codes: 200
Error response codes: 400, 401, 403
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
limit (Optional) |
query |
integer |
Requests a page size of items. Returns a number of items up to a limit
value. Use the |
marker (Optional) |
query |
string |
The ID of the last-seen item. Use the |
name (Optional) |
query |
string |
Filters the response by a name, as a string. A valid value is the name of an image. |
owner (Optional) |
query |
string |
Filters the response by a project (also called a “tenant”) ID. Shows only images that are shared with you by the specified owner. |
protected (Optional) |
query |
boolean |
Filters the response by the ‘protected’ image property. A valid value is one of ‘true’, ‘false’ (must be all lowercase). Any other value will result in a 400 response. |
status (Optional) |
query |
integer |
Filters the response by an image status. |
tag (Optional) |
query |
string |
Filters the response by the specified tag value. May be repeated, but keep in mind that you’re making a conjunctive query, so only images containing all the tags specified will appear in the response. |
visibility (Optional) |
query |
string |
Filters the response by an image visibility value. A valid value is
|
os_hidden (Optional) |
query |
boolean |
When |
member_status (Optional) |
query |
string |
Filters the response by a member status. A valid value is |
size_max (Optional) |
query |
string |
Filters the response by a maximum image size, in bytes. |
size_min (Optional) |
query |
string |
Filters the response by a minimum image size, in bytes. |
created_at (Optional) |
query |
string |
Specify a comparison filter based on the date and time when the resource was created. (See Time Comparison Filters). The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm
The For example, If you omit the time zone, the UTC time zone is assumed. |
updated_at (Optional) |
query |
string |
Specify a comparison filter based on the date and time when the resource was most recently modified. (See Time Comparison Filters). The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm
The For example, If you omit the time zone, the UTC time zone is assumed. |
sort_dir (Optional) |
query |
string |
Sorts the response by a set of one or more sort
direction and attribute ( |
sort_key (Optional) |
query |
string |
Sorts the response by an attribute, such as
|
sort (Optional) |
query |
string |
Sorts the response by one or more attribute and sort direction
combinations. You can also set multiple sort keys and directions.
Default direction is Use the comma ( GET /v2/images?sort=name:asc,status:desc
|
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
images |
body |
array |
A list of image objects, as described by the Images Schema. |
first |
body |
string |
The URI for the first page of response. |
next |
body |
string |
The URI for the next page of response. Will not be present on the last page of the response. |
schema |
body |
string |
The URL for the schema describing a list of images. |
Response Example¶
{
"images": [
{
"status": "active",
"name": "cirros-0.3.2-x86_64-disk",
"tags": [],
"container_format": "bare",
"created_at": "2014-11-07T17:07:06Z",
"disk_format": "qcow2",
"updated_at": "2014-11-07T17:19:09Z",
"visibility": "public",
"self": "/v2/images/1bea47ed-f6a9-463b-b423-14b9cca9ad27",
"min_disk": 0,
"protected": false,
"id": "1bea47ed-f6a9-463b-b423-14b9cca9ad27",
"file": "/v2/images/1bea47ed-f6a9-463b-b423-14b9cca9ad27/file",
"checksum": "64d7c1cd2b6f60c92c14662941cb7913",
"os_hash_algo": "sha512",
"os_hash_value": "073b4523583784fbe01daff81eba092a262ec37ba6d04dd3f52e4cd5c93eb8258af44881345ecda0e49f3d8cc6d2df6b050ff3e72681d723234aff9d17d0cf09",
"os_hidden": false,
"owner": "5ef70662f8b34079a6eddb8da9d75fe8",
"size": 13167616,
"min_ram": 0,
"schema": "/v2/schemas/image",
"virtual_size": null
},
{
"status": "active",
"name": "F17-x86_64-cfntools",
"tags": [],
"container_format": "bare",
"created_at": "2014-10-30T08:23:39Z",
"disk_format": "qcow2",
"updated_at": "2014-11-03T16:40:10Z",
"visibility": "public",
"self": "/v2/images/781b3762-9469-4cec-b58d-3349e5de4e9c",
"min_disk": 0,
"protected": false,
"id": "781b3762-9469-4cec-b58d-3349e5de4e9c",
"file": "/v2/images/781b3762-9469-4cec-b58d-3349e5de4e9c/file",
"checksum": "afab0f79bac770d61d24b4d0560b5f70",
"os_hash_algo": "sha512",
"os_hash_value": "ea3e20140df1cc65f53d4c5b9ee3b38d0d6868f61bbe2230417b0f98cef0e0c7c37f0ebc5c6456fa47f013de48b452617d56c15fdba25e100379bd0e81ee15ec",
"os_hidden": false,
"owner": "5ef70662f8b34079a6eddb8da9d75fe8",
"size": 476704768,
"min_ram": 0,
"schema": "/v2/schemas/image",
"virtual_size": null
}
],
"schema": "/v2/schemas/images",
"first": "/v2/images"
}
Updates an image. (Since Image API v2.0)
Conceptually, you update an image record by patching the JSON representation of the image, passing a request body conforming to one of the following media types:
application/openstack-images-v2.0-json-patch(deprecated)application/openstack-images-v2.1-json-patch(since Image API v2.1)
Attempting to make a PATCH call using some other media type will provoke a response code of 415 (Unsupported media type).
The application/openstack-images-v2.1-json-patch media type provides a
useful and compatible subset of the functionality defined in JavaScript Object
Notation (JSON) Patch RFC6902, which
defines the application/json-patch+json media type.
Note
The application/openstack-images-v2.0-json-patch media type is based on
draft 4 of the standard. Its use is deprecated.
For information about the PATCH method and the available media types, see Image API v2 HTTP PATCH media types.
Attempting to modify some image properties will cause the entire request to fail with a 403 (Forbidden) response code:
An attempt to modify any of the “base” image properties that are managed by the Image Service. These are the properties specified as read only in the Image Schema.
An attempt to create or modify image properties for which you do not have permission to do so (since Image API v2.2). This depends upon how property protections are configured in the OpenStack cloud in which you are making the call. Consult your cloud’s documentation for details.
An attempt to delete the only image location, or to replace the image locations with an empty list (since Image API v2.4).
An attempt to set or modify a property with a reserved name, such as anything prefixed with the os_glance namespace.
Attempting to add a location path to an image that is not in queued or
active state will result in a 409 (Conflict) response code
(since Image API v2.4).
Normal response codes: 200
Error response codes: 400, 401, 403, 404, 409, 413, 415
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
Content-Type |
header |
string |
The media type descriptor for the request body. Use
|
image_id |
path |
string |
The UUID of the image. |
The request body must conform to the
application/openstack-images-v2.1-json-patch media type definition (see
above).
Request Example¶
[
{
"op": "replace",
"path": "/name",
"value": "Fedora 17"
},
{
"op": "replace",
"path": "/tags",
"value": [
"fedora",
"beefy"
]
}
]
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
checksum |
body |
string |
An MD5 hash over the image data. The value might be |
container_format |
body |
enum |
Format of the image container. Values may vary based on the configuration available in a particular OpenStack cloud. See the Image Schema response from the cloud itself for the valid values available. See Container Format in the Glance documentation for more information. Example formats are: The value might be Train changes: The |
created_at |
body |
string |
The date and time when the resource was created. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm
For example, The |
disk_format |
body |
enum |
The format of the disk. Values may vary based on the configuration available in a particular OpenStack cloud. See the Image Schema response from the cloud itself for the valid values available. See Disk Format in the Glance documentation for more information. Example formats are: The value might be Newton changes: The |
file |
body |
string |
The URL for the virtual machine image file. |
id |
body |
string |
A unique, user-defined image UUID, in the format: nnnnnnnn-nnnn-nnnn-nnnn-nnnnnnnnnnnn
Where n is a hexadecimal digit from 0 to f, or F. For example: b2173dd3-7ad6-4362-baa6-a68bce3565cb
If you omit this value, the API generates a UUID for the image. |
min_disk |
body |
integer |
Amount of disk space in GB that is required to boot the image.
The value might be |
min_ram |
body |
integer |
Amount of RAM in MB that is required to boot the image.
The value might be |
name |
body |
string |
The name of the image. Value might be |
owner |
body |
string |
An identifier for the owner of the image, usually the project (also
called the “tenant”) ID.
The value might be |
os_hash_algo |
body |
string |
The algorithm used to compute a secure hash of the image data for this
image. The result of the computation is displayed as the value of the
|
os_hash_value |
body |
string |
The hexdigest of the secure hash of the image data computed using the
algorithm whose name is the value of the |
os_hidden |
body |
boolean |
This field controls whether an image is displayed in the default image-list response. A “hidden” image is out of date somehow (for example, it may not have the latest updates applied) and hence should not be a user’s first choice, but it’s not deleted because it may be needed for server rebuilds. By hiding it from the default image list, it’s easier for end users to find and use a more up-to-date version of this image. (Since Image API v2.7) |
protected |
body |
boolean |
A boolean value that must be |
schema |
body |
string |
The URL for the schema describing a virtual machine image. |
self |
body |
string |
The URL for the virtual machine image. |
size |
body |
integer |
The size of the image data, in bytes. The value
might be |
status |
body |
string |
The image status. |
tags |
body |
array |
List of tags for this image, possibly an empty list. |
updated_at |
body |
string |
The date and time when the resource was updated. The date and time stamp format is ISO 8601: CCYY-MM-DDThh:mm:ss±hh:mm
For example, The If the |
visibility |
body |
string |
Image visibility, that is, the access permission for the image. |
direct_url (Optional) |
body |
string |
The URL to access the image file kept in external store. It is present
only if the |
locations (Optional) |
body |
array |
A list of objects, each of which describes an image location. Each object
contains a |
Response Example¶
{
"checksum": "710544e7f0c828b42f51207342622d33",
"container_format": "ovf",
"created_at": "2016-06-29T16:13:07Z",
"disk_format": "vhd",
"file": "/v2/images/2b61ed2b-f800-4da0-99ff-396b742b8646/file",
"id": "2b61ed2b-f800-4da0-99ff-396b742b8646",
"min_disk": 20,
"min_ram": 512,
"name": "Fedora 17",
"owner": "02a7fb2dd4ef434c8a628c511dcbbeb6",
"os_hash_algo": "sha512",
"os_hash_value": "ef7d1ed957ffafefb324d50ebc6685ed03d0e64549762ba94a1c44e92270cdbb69d7437dd1e101d00dd41684aaecccad1edc5c2e295e66d4733025b052497844",
"os_hidden": false,
"protected": false,
"schema": "/v2/schemas/image",
"self": "/v2/images/2b61ed2b-f800-4da0-99ff-396b742b8646",
"size": 21909,
"status": "active",
"tags": [
"beefy",
"fedora"
],
"updated_at": "2016-07-25T14:48:18Z",
"virtual_size": null,
"visibility": "private"
}
(Since Image API v2.0) Deletes an image.
You cannot delete images with the protected attribute set to
true (boolean).
Preconditions
You can delete an image in any status except
deleted.The
protectedattribute of the image cannot betrue.You have permission to perform image deletion under the configured image deletion policy.
Synchronous Postconditions
The response is empty and returns the HTTP
204response code.The API deletes the image from the images index.
If the image has associated binary image data in the storage backend, the OpenStack Image service deletes the data.
Normal response codes: 204
Error response codes: 400, 401, 403, 404, 409
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
image_id |
path |
string |
The UUID of the image. |
Deactivates an image. (Since Image API v2.3)
By default, this operation is restricted to administrators only.
If you try to download a deactivated image, you will receive a 403 (Forbidden) response code. Additionally, only administrative users can view image locations for deactivated images.
The deactivate operation returns an error if the image status is
not active or deactivated.
Preconditions
The image must exist.
Normal response codes: 204
Error response codes: 400, 403, 404
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
image_id |
path |
string |
The UUID of the image. |
Reactivates an image. (Since Image API v2.3)
By default, this operation is restricted to administrators only.
The reactivate operation returns an error if the image status is
not active or deactivated.
Preconditions
The image must exist.
Normal response codes: 204
Error response codes: 400, 403, 404
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
image_id |
path |
string |
The UUID of the image. |
Add location to an image which is in queued state. Accepts
location url, validation_data in JSON body.
Adding a location to an image is only allowed for the owner or a user with the service role. If these conditions are not met, a 403 (Forbidden) will be returned.
Attempting to add a location path to an image that is not in queued
state will result in a 409 (Conflict) response code
Attempting to provide incorrect hash value in validation data(in the case of http store) to the image will result in a 400 (Bad Request) response code.
Normal response codes: 200
Error response codes: 400, 403, 404, 409
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
image_id |
path |
string |
The UUID of the image. |
url |
body |
string |
The URL of the new location to be added in the image. |
validation_data (Optional) |
body |
object |
An image metadata in key:value pairs containing values of
|
Request Example¶
{
"url": "cinder://lvmdriver-1/39e6ffab-7502-4199-9609-416601615ca3",
"validation_data": {
"os_hash_algo": "sha512",
"os_hash_value": "c5041ae163cf0f65600acfe7f6a63f212101687d41a57a4e18ffd2a07a452cd8175b8f5a4868dd2330bfe5ae123f18216bdbc9e0f80d131e64b94913a7b40bb5"
}
}
Lists all locations associated to an image with location url and store-id, accesssible to only service user, for non service users API will return forbidden.
Normal response codes: 200
Error response codes: 403, 404
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
image_id |
path |
string |
The UUID of the image. |
This call does not allow a request body.
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
locations (Optional) |
body |
array |
A list of objects, each of which describes an image location. Each object
contains a |
Response Example¶
[
{
"url": "cinder://lvmdriver-1/39e6ffab-7502-4199-9609-416601615ca3",
"metadata": {
"store": "lvmdriver-1"
}
}
]
Image Schemas¶
Gets a JSON-schema document that represents the various entities talked about by the Images v2 API.
(Since Images v2.0)
Shows a JSON schema document that represents an images entity.
An images entity is a container of image entities.
The following schema is solely an example. Consider only the response to the API call as authoritative.
Normal response codes: 200
Error response codes: 400, 401
Request¶
This operation has no request parameters and does not accept a request body.
Response Example¶
{
"links": [
{
"href": "{first}",
"rel": "first"
},
{
"href": "{next}",
"rel": "next"
},
{
"href": "{schema}",
"rel": "describedby"
}
],
"name": "images",
"properties": {
"first": {
"type": "string"
},
"images": {
"items": {
"additionalProperties": {
"type": "string"
},
"links": [
{
"href": "{self}",
"rel": "self"
},
{
"href": "{file}",
"rel": "enclosure"
},
{
"href": "{schema}",
"rel": "describedby"
}
],
"name": "image",
"properties": {
"architecture": {
"description": "Operating system architecture as specified in https://docs.openstack.org/python-glanceclient/latest/cli/property-keys.html",
"is_base": false,
"type": "string"
},
"checksum": {
"description": "md5 hash of image contents.",
"maxLength": 32,
"readOnly": true,
"type": [
"null",
"string"
]
},
"container_format": {
"description": "Format of the container",
"enum": [
null,
"ami",
"ari",
"aki",
"bare",
"ovf",
"ova",
"docker",
"compressed"
],
"type": [
"null",
"string"
]
},
"created_at": {
"description": "Date and time of image registration",
"readOnly": true,
"type": "string"
},
"direct_url": {
"description": "URL to access the image file kept in external store",
"readOnly": true,
"type": "string"
},
"disk_format": {
"description": "Format of the disk",
"enum": [
null,
"ami",
"ari",
"aki",
"vhd",
"vhdx",
"vmdk",
"raw",
"qcow2",
"vdi",
"iso",
"ploop"
],
"type": [
"null",
"string"
]
},
"file": {
"description": "An image file url",
"readOnly": true,
"type": "string"
},
"id": {
"description": "An identifier for the image",
"pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$",
"type": "string"
},
"instance_uuid": {
"description": "Metadata which can be used to record which instance this image is associated with. (Informational only, does not create an instance snapshot.)",
"is_base": false,
"type": "string"
},
"kernel_id": {
"description": "ID of image stored in Glance that should be used as the kernel when booting an AMI-style image.",
"is_base": false,
"pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$",
"type": [
"null",
"string"
]
},
"locations": {
"description": "A set of URLs to access the image file kept in external store",
"items": {
"properties": {
"metadata": {
"type": "object"
},
"url": {
"maxLength": 255,
"type": "string"
}
},
"required": [
"url",
"metadata"
],
"type": "object"
},
"type": "array"
},
"min_disk": {
"description": "Amount of disk space (in GB) required to boot image.",
"type": "integer"
},
"min_ram": {
"description": "Amount of ram (in MB) required to boot image.",
"type": "integer"
},
"name": {
"description": "Descriptive name for the image",
"maxLength": 255,
"type": [
"null",
"string"
]
},
"os_distro": {
"description": "Common name of operating system distribution as specified in https://docs.openstack.org/python-glanceclient/latest/cli/property-keys.html",
"is_base": false,
"type": "string"
},
"os_hash_algo": {
"description": "Algorithm to calculate the os_hash_value",
"maxLength": 64,
"readOnly": true,
"type": [
"null",
"string"
]
},
"os_hash_value": {
"description": "Hexdigest of the image contents using the algorithm specified by the os_hash_algo",
"maxLength": 128,
"readOnly": true,
"type": [
"null",
"string"
]
},
"os_hidden": {
"description": "If true, image will not appear in default image list response.",
"type": "boolean"
},
"os_version": {
"description": "Operating system version as specified by the distributor",
"is_base": false,
"type": "string"
},
"owner": {
"description": "Owner of the image",
"maxLength": 255,
"type": [
"null",
"string"
]
},
"protected": {
"description": "If true, image will not be deletable.",
"type": "boolean"
},
"ramdisk_id": {
"description": "ID of image stored in Glance that should be used as the ramdisk when booting an AMI-style image.",
"is_base": false,
"pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$",
"type": [
"null",
"string"
]
},
"schema": {
"description": "An image schema url",
"readOnly": true,
"type": "string"
},
"self": {
"description": "An image self url",
"readOnly": true,
"type": "string"
},
"size": {
"description": "Size of image file in bytes",
"readOnly": true,
"type": [
"null",
"integer"
]
},
"status": {
"description": "Status of the image",
"enum": [
"queued",
"saving",
"active",
"killed",
"deleted",
"pending_delete",
"deactivated",
"uploading",
"importing"
],
"readOnly": true,
"type": "string"
},
"tags": {
"description": "List of strings related to the image",
"items": {
"maxLength": 255,
"type": "string"
},
"type": "array"
},
"updated_at": {
"description": "Date and time of the last image modification",
"readOnly": true,
"type": "string"
},
"virtual_size": {
"description": "Virtual size of image in bytes",
"readOnly": true,
"type": [
"null",
"integer"
]
},
"visibility": {
"description": "Scope of image accessibility",
"enum": [
"public",
"private"
],
"type": "string"
}
}
},
"type": "array"
},
"next": {
"type": "string"
},
"schema": {
"type": "string"
}
}
}
(Since Images v2.0)
Shows a JSON schema document that represents an image entity.
The following schema is solely an example. Consider only the response to the API call as authoritative.
Normal response codes: 200
Error response codes: 400, 401
Request¶
This operation has no request parameters and does not accept a request body.
Response Example¶
{
"additionalProperties": {
"type": "string"
},
"links": [
{
"href": "{self}",
"rel": "self"
},
{
"href": "{file}",
"rel": "enclosure"
},
{
"href": "{schema}",
"rel": "describedby"
}
],
"name": "image",
"properties": {
"architecture": {
"description": "Operating system architecture as specified in https://docs.openstack.org/python-glanceclient/latest/cli/property-keys.html",
"is_base": false,
"type": "string"
},
"checksum": {
"description": "md5 hash of image contents.",
"maxLength": 32,
"readOnly": true,
"type": [
"null",
"string"
]
},
"container_format": {
"description": "Format of the container",
"enum": [
null,
"ami",
"ari",
"aki",
"bare",
"ovf",
"ova",
"docker",
"compressed"
],
"type": [
"null",
"string"
]
},
"created_at": {
"description": "Date and time of image registration",
"readOnly": true,
"type": "string"
},
"direct_url": {
"description": "URL to access the image file kept in external store",
"readOnly": true,
"type": "string"
},
"disk_format": {
"description": "Format of the disk",
"enum": [
null,
"ami",
"ari",
"aki",
"vhd",
"vhdx",
"vmdk",
"raw",
"qcow2",
"vdi",
"iso",
"ploop"
],
"type": [
"null",
"string"
]
},
"file": {
"description": "An image file url",
"readOnly": true,
"type": "string"
},
"id": {
"description": "An identifier for the image",
"pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$",
"type": "string"
},
"instance_uuid": {
"description": "Metadata which can be used to record which instance this image is associated with. (Informational only, does not create an instance snapshot.)",
"is_base": false,
"type": "string"
},
"kernel_id": {
"description": "ID of image stored in Glance that should be used as the kernel when booting an AMI-style image.",
"is_base": false,
"pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$",
"type": [
"null",
"string"
]
},
"locations": {
"description": "A set of URLs to access the image file kept in external store",
"items": {
"properties": {
"metadata": {
"type": "object"
},
"url": {
"maxLength": 255,
"type": "string"
}
},
"required": [
"url",
"metadata"
],
"type": "object"
},
"type": "array"
},
"min_disk": {
"description": "Amount of disk space (in GB) required to boot image.",
"type": "integer"
},
"min_ram": {
"description": "Amount of ram (in MB) required to boot image.",
"type": "integer"
},
"name": {
"description": "Descriptive name for the image",
"maxLength": 255,
"type": [
"null",
"string"
]
},
"os_distro": {
"description": "Common name of operating system distribution as specified in https://docs.openstack.org/python-glanceclient/latest/cli/property-keys.html",
"is_base": false,
"type": "string"
},
"os_hash_algo": {
"description": "Algorithm to calculate the os_hash_value",
"maxLength": 64,
"readOnly": true,
"type": [
"null",
"string"
]
},
"os_hash_value": {
"description": "Hexdigest of the image contents using the algorithm specified by the os_hash_algo",
"maxLength": 128,
"readOnly": true,
"type": [
"null",
"string"
]
},
"os_hidden": {
"description": "If true, image will not appear in default image list response.",
"type": "boolean"
},
"os_version": {
"description": "Operating system version as specified by the distributor",
"is_base": false,
"type": "string"
},
"owner": {
"description": "Owner of the image",
"maxLength": 255,
"type": [
"null",
"string"
]
},
"protected": {
"description": "If true, image will not be deletable.",
"type": "boolean"
},
"ramdisk_id": {
"description": "ID of image stored in Glance that should be used as the ramdisk when booting an AMI-style image.",
"is_base": false,
"pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$",
"type": [
"null",
"string"
]
},
"schema": {
"description": "An image schema url",
"readOnly": true,
"type": "string"
},
"self": {
"description": "An image self url",
"readOnly": true,
"type": "string"
},
"size": {
"description": "Size of image file in bytes",
"readOnly": true,
"type": [
"null",
"integer"
]
},
"status": {
"description": "Status of the image",
"enum": [
"queued",
"saving",
"active",
"killed",
"deleted",
"pending_delete",
"deactivated",
"uploading",
"importing"
],
"readOnly": true,
"type": "string"
},
"tags": {
"description": "List of strings related to the image",
"items": {
"maxLength": 255,
"type": "string"
},
"type": "array"
},
"updated_at": {
"description": "Date and time of the last image modification",
"readOnly": true,
"type": "string"
},
"virtual_size": {
"description": "Virtual size of image in bytes",
"readOnly": true,
"type": [
"null",
"integer"
]
},
"visibility": {
"description": "Scope of image accessibility",
"enum": [
"public",
"private"
],
"type": "string"
}
}
}
(Since Images v2.1)
Shows a JSON schema document that represents an image members entity.
An image members entity is a container of image member entities.
The following schema is solely an example. Consider only the response to the API call as authoritative.
Normal response codes: 200
Error response codes: 400, 401
Request¶
This operation has no request parameters and does not accept a request body.
Response Example¶
{
"links": [
{
"href": "{schema}",
"rel": "describedby"
}
],
"name": "members",
"properties": {
"members": {
"items": {
"name": "member",
"properties": {
"created_at": {
"description": "Date and time of image member creation",
"type": "string"
},
"image_id": {
"description": "An identifier for the image",
"pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$",
"type": "string"
},
"member_id": {
"description": "An identifier for the image member (tenantId)",
"type": "string"
},
"schema": {
"readOnly": true,
"type": "string"
},
"status": {
"description": "The status of this image member",
"enum": [
"pending",
"accepted",
"rejected"
],
"type": "string"
},
"updated_at": {
"description": "Date and time of last modification of image member",
"type": "string"
}
}
},
"type": "array"
},
"schema": {
"type": "string"
}
}
}
(Since Images v2.1)
Shows a JSON schema document that represents an image member entity.
The following schema is solely an example. Consider only the response to the API call as authoritative.
Normal response codes: 200
Error response codes: 400, 401
Request¶
This operation has no request parameters and does not accept a request body.
Response Example¶
{
"name": "member",
"properties": {
"created_at": {
"description": "Date and time of image member creation",
"type": "string"
},
"image_id": {
"description": "An identifier for the image",
"pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$",
"type": "string"
},
"member_id": {
"description": "An identifier for the image member (tenantId)",
"type": "string"
},
"schema": {
"readOnly": true,
"type": "string"
},
"status": {
"description": "The status of this image member",
"enum": [
"pending",
"accepted",
"rejected"
],
"type": "string"
},
"updated_at": {
"description": "Date and time of last modification of image member",
"type": "string"
}
}
}
Image data¶
Uploads and downloads raw image data.
These operations may be restricted to administrators. Consult your cloud operator’s documentation for details.
Uploads binary image data. (Since Image API v2.0)
Set the Content-Type request header to application/octet-stream.
A multiple store backend support is introduced in the Rocky release as a part of the EXPERIMENTAL Image API v2.8.
Beginning with API version 2.8, an optional X-Image-Meta-Store
header may be added to the request. When present, the image data will be
placed into the backing store whose identifier is the value of this
header. If the store identifier specified is not recognized, a 400 (Bad
Request) response is returned. When the header is not present, the image
data is placed into the default backing store.
Store identifiers are site-specific. Use the Store Discovery call to determine what stores are available in a particular cloud.
The default store may be determined from the Store Discovery response.
A default store is always defined, so if you do not have a need to use a particular store, simply omit this header and the default store will be used.
For API versions before version 2.8, this header is silently ignored.
Example call:
curl -i -X PUT -H "X-Auth-Token: $token" \
-H "X-Image-Meta-Store: {store_identifier}" \
-H "Content-Type: application/octet-stream" \
-d @/home/glance/ubuntu-12.10.qcow2 \
$image_url/v2/images/{image_id}/file
Preconditions
Before you can store binary image data, you must meet the following preconditions:
The image must exist.
You must set the disk and container formats in the image.
The image status must be
queued.Your image storage quota must be sufficient.
The size of the data that you want to store must not exceed the size that the OpenStack Image service allows.
Synchronous Postconditions
With correct permissions, you can see the image status as
activethrough API calls.With correct access, you can see the stored data in the storage system that the OpenStack Image Service manages.
Troubleshooting
If you cannot store the data, either your request lacks required information or you exceeded your allotted quota. Ensure that you meet the preconditions and run the request again. If the request fails again, review your API request.
The storage back ends for storing the data must have enough free storage space to accommodate the size of the data.
Normal response codes: 204
Error response codes: 400, 401, 403, 404, 409, 410, 413, 415, 503
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
Content-type |
header |
string |
The media type descriptor for the request body. Use
|
X-Image-Meta-Store (Optional) |
header |
string |
A store identifier to upload or import image data. Should only be included when making a request to a cloud that supports multiple backing stores. Use the Store Discovery call to determine an appropriate store identifier. Simply omit this header to use the default store. (Since Image API v2.8) |
image_id |
path |
string |
The UUID of the image. |
Downloads binary image data. (Since Image API v2.0)
Example call: curl -i -X GET -H "X-Auth-Token: $token"
$image_url/v2/images/{image_id}/file
The response body contains the raw binary data that represents the
actual virtual disk. The Content-Type header contains the
application/octet-stream value. The Content-MD5 header
contains an MD5 checksum of the image data. Use this checksum to
verify the integrity of the image data.
Preconditions
The image must exist.
Synchronous Postconditions
You can download the binary image data in your machine if the image has image data.
If image data exists, the call returns the HTTP
200response code for a full image download request.If image data exists, the call returns the HTTP
206response code for a partial download request.If no image data exists, the call returns the HTTP
204(No Content) response code.If no image record exists, the call returns the HTTP
404response code for an attempted full image download request.For an unsatisfiable partial download request, the call returns the HTTP
416response code.
Normal response codes: 200, 204, 206
Error response codes: 400, 403, 404, 416
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
image_id |
path |
string |
The UUID of the image. |
Range (Optional) |
header |
string |
The range of image data requested. Note that multi range requests are not supported. For details, see Hypertext Transfer Protocol (HTTP/1.1): Range Requests. |
Response¶
Name |
In |
Type |
Description |
|---|---|---|---|
Content-Type |
header |
string |
The media type descriptor of the response body, namely
|
Content-Md5 |
header |
string |
The MD5 checksum of the body. |
Content-Length |
header |
string |
The length of the body in octets (8-bit bytes) |
Content-Range (Optional) |
header |
string |
The content range of image data. For details, see Hypertext Transfer Protocol (HTTP/1.1): Range Requests. |
Interoperable image import¶
An interoperable image import process is introduced in the Image API v2.6.
Use the API versions call to determine what API versions are available in your cloud.
General information¶
The exact workflow you use for interoperable image import depends upon the import methods available in the cloud in which you want to import an image. Each of these methods is well defined (which is what makes this process interoperable among different OpenStack clouds).
Four import methods are defined:
glance-directweb-downloadcopy-imageglance-download
Note
Use the Import Method Discovery call to determine what import methods are available in the cloud to which you wish to import an image.
The first step in each interoperable image import method is the same: you must create an image record. This will give you an image id to work with. This image id is how the OpenStack Image service will understand that the other calls you make are referring to this particular image.
Thus, the first step is:
Create an image record using the Image Create API call. You must do this first so that you have an image id to work with for the other calls.
In a cloud in which interoperable image import is enabled, the Image Create response will include a
OpenStack-image-import-methodsheader listing the types of import methods available in that cloud. Alternatively, these methods may be determined independently of creating an image by making the Import Method Discovery call.In a cloud in which multiple storage backends are available, the Image Create response will include a
OpenStack-image-store-idsheader listing the stores available in that cloud. Alternatively, these stores may be determined independently of creating an image by making the Stores Discovery call.
The glance-direct import method¶
The glance-direct workflow has three parts:
Create an image record as described above.
Upload the image data to a staging area using the Image Stage API call. Note that this image data is not accessible until after the third step has successfully completed.
Issue the Image Import call to complete the import process. You will specify that you are using the
glance-directimport method in the body of the import call.
The web-download import method¶
The web-download workflow has two parts:
Create an image record as described above.
Issue the Image Import call to complete the import process. You will specify that you are using the
web-downloadimport method in the body of the import call.
The copy-image import method¶
The copy-image workflow has two parts:
Identify the existing image whose data you want to copy to other stores.
Issue the Image Import call to complete the import process. You will specify that you are using the
copy-imageimport method in the body of the import call.
The glance-download import method¶
The glance-download workflow has two parts:
Create an image record as described above.
Issue the Image Import call to complete the import process. You will specify that you are using the
glance-downloadimport method in the body of the import call.
Places the binary image data in a staging area. It is not stored in the storage backend and is not accessible for download until after the Image Import call is made. (Since Image API v2.6)
Set the Content-Type request header to application/octet-stream.
Example call:
curl -i -X PUT -H "X-Auth-Token: $token" \
-H "Content-Type: application/octet-stream" \
-d @/home/glance/my.to-import.qcow2 \
$image_url/v2/images/{image_id}/stage
Preconditions
Before you can stage binary image data, you must meet the following preconditions:
The image record must exist.
The image status must be
queued.Your image storage quota must be sufficient.
The size of the data that you want to store must not exceed the size that the OpenStack Image service allows.
Synchronous Postconditions
With correct permissions, you can see the image status as
uploadingthrough API calls.
Troubleshooting
If you cannot store the data, either your request lacks required information or you exceeded your allotted quota. Ensure that you meet the preconditions and run the request again. If the request fails again, review your API request.
The storage back ends for storing the data must have enough free storage space to accommodate the size of the data.
Normal response codes: 204
Error response codes: 400, 401, 403, 404, 405, 409, 410, 413, 415, 503
If the image import process is not enabled in your cloud, this request will result in a 404 response code with an appropriate message.
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
Content-type |
header |
string |
The media type descriptor for the request body. Use
|
image_id |
path |
string |
The UUID of the image. |
Signals the Image Service to complete the image import workflow by processing data that has been made available to the OpenStack image service. (Since Image API v2.6)
In the glance-direct workflow, the data has been made available to the
Image service via the Stage binary image data API
call.
In the web-download workflow, the data is made available to the Image
service by being posted to an accessible location with a URL that you know.
In the copy-image workflow, the data is made available to the Image
service by copying existing image data to the staging area.
In the glance-download workflow, the data is made available to the Image
service by fetching an image accessible from another glance service specified
by a region name and an image id that you know.
Beginning with API version 2.8, an optional stores parameter may be added
to the body request. When present, it contains the list of backing store
identifiers to import the image binary data to. If at least one store
identifier specified is not recognized, a 409 (Conflict) response is returned.
When the parameter is not present, the image data is placed into the default
backing store.
Store identifiers are site-specific. Use the Store Discovery call to determine what stores are available in a particular cloud.
The default store may be determined from the Store Discovery response.
A default store is always defined, so if you do not have a need to use particular stores, simply omit this parameter and the default store will be used.
For API versions before version 2.8, this parameter is silently ignored.
For backwards compatibility, if the stores parameter is not specified, the
header ‘X-Image-Meta-Store’ is evaluated.
To import the data into the entire set of stores you may consume from this
particular deployment of Glance without specifying each one of them, you can
use the optional boolean body parameter all_stores.
Note that this can’t be used simultaneously with the stores parameter.
To set the behavior of the import workflow in case of error, you can use the
optional boolean body parameter all_stores_must_succeed.
When set to True (default), if an error occurs during the upload in at least one store,
the worfklow fails, the data is deleted from stores where copying is done and
the state of the image remains unchanged.
When set to False, the workflow will fail only if the upload fails
on all stores specified. In case of a partial success, the locations added to
the image will be the stores where the data has been correctly uploaded.
The JSON request body specifies what import method you wish to use for this image request.
Preconditions
Before you can complete the interoperable image import workflow, you must meet the following preconditions:
The image record must exist.
You must set the disk and container formats in the image record. (This can be done at the time of image creation, or you can make the Image Update API call.
Your image storage quota must be sufficient.
The size of the data that you want to store must not exceed the size that the OpenStack Image service allows.
Additional Preconditions
If you are using the glance-direct import method:
The image status must be
uploading. (This indicates that the image data has been uploaded to the stage.)The body of your request must indicate that you are using the
glance-directimport method.
If you are using the web-download import method:
The image status must be
queued. (This indicates that no image data has yet been associated with the image.)The body of your request must indicate that you are using the
web-downloadimport method, and it must contain the URL at which the data is to be found.Note
The acceptable set of URLs for the
web-downloadimport method may be restricted in a particular cloud. Consult the cloud’s local documentation for details.
If you are using the copy-image import method:
The image status must be
active. (This indicates that image data is associated with the image.)The body of your request must indicate that you are using the
copy-imageimport method, and it must contain either the list of stores where you want to copy your image or all_stores which will copy the image in all available stores set in glance_api.conf usingenabled_backendsconfiguration option.If body of your request contains
all_stores_must_succeed(default to True) and an error occurs during the copying in at least one store, the request will be rejected, the data will be deleted from the new stores where copying is done (not staging), and the state of the image remains the same.If body of your request contains
all_stores_must_succeedset to False and an error occurs, then the request will fail (data deleted from stores, …) only if the copying fails on all stores specified by the user. In case of a partial success, the locations added to the image will be the stores where the data has been correctly uploaded.By default, you may perform the copy-image operation only on images that you own. This action is governed by policy, so some users may be granted permission to copy unowned images. Consult your cloud’s local documentation for details.
If you are using the glance-download import method:
The image status must be
queued. (This indicates that no image data has yet been associated with the image.)The body of your request must indicate that you are using the
glance-downloadimport method, and it must contain the region name of the remote openstack region and the image id to fetch. You might optionaly set the service interface name (public by default) to request.
Synchronous Postconditions
With correct permissions, you can see the image status as
importing(only for glance-direct, web-download and glance-download import methods) through API calls. (Be aware, however, that if the import process completes before you make the API call, the image may already show asactive.)
Normal response codes: 202
Error response codes: 400, 401, 403, 404, 405, 409, 410, 413, 415, 503
If the image import process is not enabled in your cloud, this request will result in a 404 response code with an appropriate message.
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
Content-type |
header |
string |
The media type descriptor for the request body. Use
|
X-Image-Meta-Store (Optional) |
header |
string |
A store identifier to upload or import image data. Should only be included when making a request to a cloud that supports multiple backing stores. Use the Store Discovery call to determine an appropriate store identifier. Simply omit this header to use the default store. (Since Image API v2.8) |
image_id |
path |
string |
The UUID of the image. |
method |
body |
object |
A JSON object indicating what import method you wish to use to import
your image. The content of this JSON object is another JSON object
with a |
all_stores (Optional) |
body |
boolean |
When set to True the data will be imported to the set of stores you may
consume from this particular deployment of Glance (ie: the same set of
stores returned to a call to /v2/info/stores on the glance-api the request
hits).
This can’t be used simultaneously with the |
all_stores_must_succeed (Optional) |
body |
boolean |
A boolean parameter indicating the behavior of the import workflow when an error occurs. When set to True (default), if an error occurs during the upload in at least one store, the worfklow fails, the data is deleted from stores where copying is done (not staging), and the state of the image is unchanged. When set to False, the workflow will fail (data deleted from stores, …) only if the import fails on all stores specified by the user. In case of a partial success, the locations added to the image will be the stores where the data has been correctly uploaded. Default is True. |
stores (Optional) |
body |
array |
If present contains the list of store id to import the image binary data to. |
Request Example - glance-direct import method¶
{
"method": {
"name": "glance-direct"
},
"stores": ["common", "cheap", "fast", "reliable"],
"all_stores_must_succeed": false
}
Request Example - web-download import method¶
{
"method": {
"name": "web-download",
"uri": "https://download.cirros-cloud.net/0.4.0/cirros-0.4.0-ppc64le-disk.img"
},
"all_stores": true,
"all_stores_must_succeed": true
}
Request Example - copy-image import method¶
{
"method": {
"name": "copy-image"
},
"stores": ["common", "cheap", "fast", "reliable"],
"all_stores_must_succeed": false,
"all_stores": false
}
Request Example - glance-download import method¶
{
"method": {
"name": "glance-download",
"glance_image_id": "c4705b36-b281-40f6-a01d-bf98883ead8e",
"glance_region": "REGION2",
"glance_service_interface": "public"
}
}
Stores¶
Multi-store backend support allows for storing copies of an image in multiple places.
This API allows you to delete a copy of the image from a specific store. (Since Image API v2.10)
Note
This API will not allow deletion of the last location for an image.
Normal response codes: 204
Error response codes: 400, 401, 403, 404, 409
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
store_id |
path |
string |
The ID of the store from which image is to be deleted. |
image_id |
path |
string |
The UUID of the image. |
Image Service Info (Discovery)¶
General information¶
These calls allow you to discover useful information about what services you may consume from a particular deployment of the OpenStack Image Service.
Returns information concerning the constraints around image import in
the cloud in which the call is made, for example, supported container
formats, supported disk formats, maximum image size, etc. This call
contains a import-methods field consisting of an array of string
identifiers indicating what import methods are supported in the cloud
in which the call is made.
(Since Image API v2.6)
Note
In the Image API v2.6-2.8, this discovery call contains
only the import-methods field.
Normal response codes: 200
Error response codes: 400, 401, 403
Request¶
There are no request parameters.
This call does not allow a request body.
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
import-methods |
body |
object |
A JSON object containing a |
Response Example¶
{
"import-methods": {
"description": "Import methods available.",
"type": "array",
"value": [
"glance-direct",
"web-download"
]
}
}
A multiple store backend support is introduced in the Rocky release as a part of the EXPERIMENTAL Image API v2.8.
In version 2.7 of the API, this call will return a 404 (Not Found). Use the API versions call to determine what API versions are available in your cloud.
Normal response codes: 200
Error response codes: 404
Request¶
There are no request parameters.
This call does not allow a request body.
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
stores |
body |
array |
A list of store objects, where each store object may contain the following fields:
|
Response Example¶
{
"stores": [
{
"id":"reliable",
"description": "More expensive store with data redundancy"
},
{
"id":"fast",
"description": "Provides quick access to your image data",
"default": true
},
{
"id":"cheap",
"description": "Less expensive store for seldom-used images"
},
{
"id":"special",
"description": "Need a plausible description here that doesn't expose the store type",
"read-only": true
}
]
}
The user’s quota and current usage are displayed, if enabled by server-side configuration.
Normal response codes: 200
Request¶
There are no request parameters.
This call does not allow a request body.
Response Example¶
{
"usage": {
"image_size_total": {
"limit": 1024,
"usage": 256
},
"image_count_total": {
"limit": 10,
"usage": 2
},
"image_stage_total": {
"limit": 512,
"usage": 0
},
"image_count_uploading": {
"limit": 2,
"usage": 0
}
}
}
Lists all the backend stores, with detail, accessible to admins, for non-admin user API will return bad request.
Normal response codes: 200
Error response codes: 403, 404
Request¶
There are no request parameters.
This call does not allow a request body.
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
stores |
body |
array |
A list of store objects, where each store object may contain the following fields:
|
Response Example¶
{
"stores": [
{
"id":"reliable",
"type": "rbd",
"description": "More expensive store with data redundancy",
"default": true,
"weight": 100,
"properties": {
"pool": "pool1",
"chunk_size": 65536,
"thin_provisioning": false
}
},
{
"id":"cheap",
"type": "file",
"description": "Less expensive store for seldom-used images",
"weight": 200,
"properties": {
"datadir": "fdir",
"chunk_size": 65536,
"thin_provisioning": false
}
},
{
"id":"fast",
"type": "cinder",
"description": "Reasonably-priced fast store",
"weight": 300,
"properties": {
"volume_type": "volume1",
"use_multipath": false
}
},
{
"id":"slow",
"type": "swift",
"description": "Entry-level store balancing price and speed",
"weight": 400,
"properties": {
"container": "container1",
"large_object_size": 52428,
"large_object_chunk_size": 204800
}
}
]
}
Tasks¶
Creates, lists, and shows details for tasks.
(Since API v2.2)
General Information¶
API Status
This API was made admin-only by default in the OpenStack Mitaka release. Thus the following calls may not be available to end users in your cloud. Please consult your cloud provider’s documentation for more information.
Conceptual Overview
Please see the Tasks section of the Glance Developers Documentation for a conceptual overview of tasks.
Task Status
The possible status values for tasks are presented in the following table.
Status |
Description |
|---|---|
pending |
The task is waiting for execution. |
processing |
Execution of the task is underway. |
success |
The task completed successfully. The |
failure |
The task failed to complete. The |
Creates a task.
Normal response codes: 201
Error response codes: 401, 413, 415
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
type |
body |
string |
The type of task represented by this content. |
input |
body |
object |
A JSON object specifying the input parameters to the task. Consult your cloud provider’s documentation for details. |
Request Example¶
{
"type": "import",
"input": {
"import_from": "http://app-catalog.openstack.example.org/groovy-image",
"import_from_format": "qcow2",
"image_properties": {
"disk_format": "vhd",
"container_format": "ovf"
}
}
}
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
created_at |
body |
string |
The date and time when the task was created. The date and time stamp format is ISO 8601. |
id |
body |
string |
The UUID of the task. |
input |
body |
object |
A JSON object specifying the input parameters to the task. Consult your cloud provider’s documentation for details. |
message |
body |
string |
Human-readable text, possibly an empty string, usually displayed in an error situation to provide more information about what has occurred. |
owner |
body |
string |
An identifier for the owner of the task, usually the tenant ID. |
result |
body |
object |
A JSON object specifying information about the ultimate outcome of the task. Consult your cloud provider’s documentation for details. |
schema |
body |
string |
The URI for the schema describing an image task. |
self |
body |
string |
A URI for this task. |
status |
body |
string |
The current status of this task. The value can be |
type |
body |
string |
The type of task represented by this content. |
updated_at |
body |
string |
The date and time when the task was updated. The date and time stamp format is ISO 8601. If the |
Response Example¶
{
"created_at": "2016-06-24T14:57:19Z",
"id": "bb480de2-7077-4ea9-bbe9-be1891290d3e",
"input": {
"image_properties": {
"container_format": "ovf",
"disk_format": "vhd"
},
"import_from": "http://app-catalog.openstack.example.org/groovy-image",
"import_from_format": "qcow2"
},
"message": "",
"owner": "fa6c8c1600f4444281658a23ee6da8e8",
"result": null,
"schema": "/v2/schemas/task",
"self": "/v2/tasks/bb480de2-7077-4ea9-bbe9-be1891290d3e",
"status": "pending",
"type": "import",
"updated_at": "2016-06-24T14:57:19Z"
}
Lists tasks.
Normal response codes: 200
Error response codes: 403, 404, 413
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
limit (Optional) |
query |
integer |
Requests a page size of items. Returns a number of items up to a limit
value. Use the |
marker (Optional) |
query |
string |
The ID of the last-seen item. Use the |
sort_dir (Optional) |
query |
string |
Sorts the response by a set of one or more sort direction and attribute
( |
sort_key (Optional) |
query |
string |
Sorts the response by one of the following attributes: |
status (Optional) |
query |
string |
Filters the response by a task status. A valid value is |
type (Optional) |
query |
string |
Filters the response by a task type. A valid value is |
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
first |
body |
string |
The URI for the first page of response. |
next |
body |
string |
The URI for the next page of response. Will not be present on the last page of the response. |
schema |
body |
string |
The URI for the schema describing an image task list. |
tasks |
body |
array |
A list of sparse task objects. Each object contains the following fields:
|
Response Example¶
{
"first": "/v2/tasks",
"schema": "/v2/schemas/tasks",
"tasks": [
{
"created_at": "2016-06-24T14:44:19Z",
"id": "08b7e1c8-3821-4f54-b3b8-d6655d178cdf",
"owner": "fa6c8c1600f4444281658a23ee6da8e8",
"schema": "/v2/schemas/task",
"self": "/v2/tasks/08b7e1c8-3821-4f54-b3b8-d6655d178cdf",
"status": "processing",
"type": "import",
"updated_at": "2016-06-24T14:44:19Z"
},
{
"created_at": "2016-06-24T14:40:19Z",
"id": "231c311d-3557-4e23-afc4-6d98af1419e7",
"owner": "fa6c8c1600f4444281658a23ee6da8e8",
"schema": "/v2/schemas/task",
"self": "/v2/tasks/231c311d-3557-4e23-afc4-6d98af1419e7",
"status": "processing",
"type": "import",
"updated_at": "2016-06-24T14:40:20Z"
}
]
}
Shows details for a task.
Normal response codes: 200
Error response codes: 404
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
task_id |
path |
string |
The identifier for the task, a UUID. |
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
created_at |
body |
string |
The date and time when the task was created. The date and time stamp format is ISO 8601. |
expires_at |
body |
string |
The date and time when the task is subject to removal. While the task object, that is, the record describing the task is subject to deletion, the result of the task (for example, an imported image) still exists. The date and time stamp format is ISO 8601. This value is only set when the task reaches status |
id |
body |
string |
The UUID of the task. |
input |
body |
object |
A JSON object specifying the input parameters to the task. Consult your cloud provider’s documentation for details. |
message |
body |
string |
Human-readable text, possibly an empty string, usually displayed in an error situation to provide more information about what has occurred. |
owner |
body |
string |
An identifier for the owner of the task, usually the tenant ID. |
result |
body |
object |
A JSON object specifying information about the ultimate outcome of the task. Consult your cloud provider’s documentation for details. |
schema |
body |
string |
The URI for the schema describing an image task. |
self |
body |
string |
A URI for this task. |
status |
body |
string |
The current status of this task. The value can be |
type |
body |
string |
The type of task represented by this content. |
updated_at |
body |
string |
The date and time when the task was updated. The date and time stamp format is ISO 8601. If the |
Response Example (task status: processing)¶
{
"created_at": "2016-06-24T14:40:19Z",
"id": "231c311d-3557-4e23-afc4-6d98af1419e7",
"input": {
"image_properties": {
"container_format": "ovf",
"disk_format": "vhd"
},
"import_from": "http://example.com",
"import_from_format": "qcow2"
},
"message": "",
"owner": "fa6c8c1600f4444281658a23ee6da8e8",
"result": null,
"schema": "/v2/schemas/task",
"self": "/v2/tasks/231c311d-3557-4e23-afc4-6d98af1419e7",
"status": "processing",
"type": "import",
"updated_at": "2016-06-24T14:40:20Z"
}
Response Example (task status: success)¶
{
"created_at": "2016-06-29T16:13:07Z",
"expires_at": "2016-07-01T16:13:07Z",
"id": "805f47d2-8814-4cd7-bef3-37037389a998",
"input": {
"image_properties": {
"container_format": "ovf",
"disk_format": "vhd"
},
"import_from": "https://apps.openstack.org/excellent-image",
"import_from_format": "qcow2"
},
"message": "",
"owner": "02a7fb2dd4ef434c8a628c511dcbbeb6",
"result": {
"image_id": "2b61ed2b-f800-4da0-99ff-396b742b8646"
},
"schema": "/v2/schemas/task",
"self": "/v2/tasks/805f47d2-8814-4cd7-bef3-37037389a998",
"status": "success",
"type": "import",
"updated_at": "2016-06-29T16:13:07Z"
}
Response Example (task status: failure)¶
{
"created_at": "2016-06-24T14:57:20Z",
"expires_at": "2016-06-26T14:57:20Z",
"id": "bb480de2-7077-4ea9-bbe9-be1891290d3e",
"input": {
"image_properties": {
"container_format": "ovf",
"disk_format": "vhd"
},
"import_from": "http://app-catalog.openstack.example.org/groovy-image",
"import_from_format": "qcow2"
},
"message": "Task failed due to Internal Error",
"owner": "fa6c8c1600f4444281658a23ee6da8e8",
"result": null,
"schema": "/v2/schemas/task",
"self": "/v2/tasks/bb480de2-7077-4ea9-bbe9-be1891290d3e",
"status": "failure",
"type": "import",
"updated_at": "2016-06-24T14:57:20Z"
}
Task Schemas¶
Gets a JSON-schema document that represents an individual task and a list of tasks.
(Since Images v2.2)
Shows a JSON schema document that represents a list of tasks.
An tasks list entity is a container of entities containing abbreviated information about individual tasks.
The following schema is solely an example. Consider only the response to the API call as authoritative.
Normal response codes: 200
Error response codes: 401
Request¶
This operation has no request parameters and does not accept a request body.
Response Example¶
{
"links": [
{
"href": "{schema}",
"rel": "describedby"
}
],
"name": "tasks",
"properties": {
"schema": {
"type": "string"
},
"tasks": {
"items": {
"name": "task",
"properties": {
"created_at": {
"description": "Datetime when this resource was created",
"type": "string"
},
"expires_at": {
"description": "Datetime when this resource would be subject to removal",
"type": [
"null",
"string"
]
},
"id": {
"description": "An identifier for the task",
"pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$",
"type": "string"
},
"owner": {
"description": "An identifier for the owner of this task",
"type": "string"
},
"schema": {
"readOnly": true,
"type": "string"
},
"self": {
"readOnly": true,
"type": "string"
},
"status": {
"description": "The current status of this task",
"enum": [
"pending",
"processing",
"success",
"failure"
],
"type": "string"
},
"type": {
"description": "The type of task represented by this content",
"enum": [
"import"
],
"type": "string"
},
"updated_at": {
"description": "Datetime when this resource was updated",
"type": "string"
}
}
},
"type": "array"
}
}
}
(Since Images v2.2)
Shows a JSON schema document that represents an task entity.
The following schema is solely an example. Consider only the response to the API call as authoritative.
Normal response codes: 200
Error response codes: 401
Request¶
This operation has no request parameters and does not accept a request body.
Response Example¶
{
"name": "task",
"properties": {
"created_at": {
"description": "Datetime when this resource was created",
"type": "string"
},
"expires_at": {
"description": "Datetime when this resource would be subject to removal",
"type": [
"null",
"string"
]
},
"id": {
"description": "An identifier for the task",
"pattern": "^([0-9a-fA-F]){8}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){4}-([0-9a-fA-F]){12}$",
"type": "string"
},
"input": {
"description": "The parameters required by task, JSON blob",
"type": [
"null",
"object"
]
},
"message": {
"description": "Human-readable informative message only included when appropriate (usually on failure)",
"type": "string"
},
"owner": {
"description": "An identifier for the owner of this task",
"type": "string"
},
"result": {
"description": "The result of current task, JSON blob",
"type": [
"null",
"object"
]
},
"schema": {
"readOnly": true,
"type": "string"
},
"self": {
"readOnly": true,
"type": "string"
},
"status": {
"description": "The current status of this task",
"enum": [
"pending",
"processing",
"success",
"failure"
],
"type": "string"
},
"type": {
"description": "The type of task represented by this content",
"enum": [
"import"
],
"type": "string"
},
"updated_at": {
"description": "Datetime when this resource was updated",
"type": "string"
}
}
}
Cache Manage¶
List and manage the cache.
Lists all images in cache or queue. (Since Image API v2.14)
Normal response codes: 200
Error response codes: 400, 401, 403
Request¶
No request parameters.
Response Parameters¶
Name |
In |
Type |
Description |
|---|---|---|---|
cached_images |
body |
array |
A list of cached image JSON objects, possibly empty, where each object contains the following fields:
|
queued_images |
body |
array |
A list of image ids, possibly empty, of images queued to be cached, listed in the order in which they will be processed. |
Response Example¶
{
"cached_images": [
{
"image_id": "fe05d6c9-ef02-4161-9056-81ed046f3024",
"hits": 0,
"last_accessed": 1651504844.0860524,
"last_modified": 1651504844.0860524,
"size": 987654
}
],
"queued_images": [
"e34e6e2f-fe16-420d-ad36-cebf69506106",
"6b9fbf2b-3031-429a-80b1-b509e4c44046"
]
}
Queues image for caching. (Since Image API v2.14)
Normal response codes: 202
Error response codes: 400, 401, 403, 404
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
image_id |
path |
string |
The UUID of the image. |
Deletes a image from cache. (Since Image API v2.14)
Normal response codes: 204
Error response codes: 400, 401, 403, 404
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
image_id |
path |
string |
The UUID of the image. |
Clears the cache and its queue. (Since Image API v2.14)
Normal response codes: 204
Error response codes: 400, 401, 403
Request¶
Name |
In |
Type |
Description |
|---|---|---|---|
x-image-cache-clear-target (Optional) |
header |
string |
A keyword indicating ‘cache’, ‘queue’ or empty string to indicate the delete API to delete images from cache or queue or delete from both. If this header is missing then all cached and queued images for caching will be deleted. |
