Creates, lists, shows, updates, deletes, and performs other operations on images.
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:
null
(that is, the JSON null data type).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 deleted status. An image in this state is not
recoverable. |
deactivated | The image data is not available for use. |
Image visibility
The possible values for image visibility are presented in the following table.
Visibility | Description |
---|---|
public |
Any user may read the image and its data payload. Additionally, the image appears in the default image list of all users. |
community |
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) |
shared |
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) |
private |
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.
The response body contains the new image entity.
Synchronous Postconditions
queued
through API calls.Normal response codes: 201
Error response codes: 400, 401, 403, 409, 413, 415
Name | In | Type | Description |
---|---|---|---|
container_format (Optional) | body | enum | Format of the image container. A valid value is one of
ami , ari , aki , bare , ovf , ova , or
docker . |
disk_format (Optional) | body | enum | The format of the disk. Responses 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. Example formats are: The value might be vhdx disk format is a supported value. |
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 true or false .
Default is false . |
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: public , private ,
shared , or community .
At most sites, only an administrator can make an image public .
Some sites may restrict what users can make an image community .
Some sites may restrict what users can perform member operations on
a shared image.
Since the Image API v2.5, the default value is “shared“. |
Additionally, you may include additional properties specified as key:value pairs, where the value must be a string data type. Keys and values are limited to 255 chars in length. Available key names may be limited by the cloud’s property protection configuration.
{
"container_format": "bare",
"disk_format": "raw",
"name": "Ubuntu",
"id": "b2173dd3-7ad6-4362-baa6-a68bce3565cb"
}
Name | In | Type | Description |
---|---|---|---|
Location | header | string | The URL to access the image file from the external store. |
checksum | body | string | Hash that is used over the image data. The Image
service uses this value for verification. The value might be
null (JSON null data type). |
container_format | body | enum | Format of the image container. A valid value is one of
ami , ari , aki , bare , ovf , ova , or
docker . The value might be null (JSON null data type). |
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. Responses 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. Example formats are: The value might be vhdx disk format is a supported value. |
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 null (JSON null data type). |
min_ram | body | integer | Amount of RAM in MB that is required to boot the image.
The value might be null (JSON null data type). |
name | body | string | The name of the image. Value might be null (JSON null data type). |
owner | body | string | An identifier for the owner of the image, usually the project (also
called the “tenant”) ID.
The value might be null (JSON null data type). |
protected | body | boolean | A boolean value that must be false or the image cannot be deleted. |
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 null (JSON null data type). |
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 null (JSON null data type). |
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 show_image_direct_url option is true in the Image
service’s configuration file. Because it presents a security risk, this
option is disabled by default. |
locations (Optional) | body | array | A list of objects, each of which describes an image location. Each object
contains a url key, whose value is a URL specifying a location, and a
metadata key, whose value is a dict of key:value pairs containing
information appropriate to the use of whatever external store is indicated
by the URL. This list appears only if the show_multiple_locations
option is set to true in the Image service’s configuration file.
Because it presents a security risk, this option is disabled by
default. |
The response may also include additional properties specified as key:value pairs if additional properties were specified in the request.
{
"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,
"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
Normal response codes: 200
Error response codes: 400, 401, 403, 404
Name | In | Type | Description |
---|---|---|---|
image_id | path | string | The UUID of the image. |
Name | In | Type | Description |
---|---|---|---|
checksum | body | string | Hash that is used over the image data. The Image
service uses this value for verification. The value might be
null (JSON null data type). |
container_format | body | enum | Format of the image container. A valid value is one of
ami , ari , aki , bare , ovf , ova , or
docker . The value might be null (JSON null data type). |
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. Responses 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. Example formats are: The value might be vhdx disk format is a supported value. |
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 null (JSON null data type). |
min_ram | body | integer | Amount of RAM in MB that is required to boot the image.
The value might be null (JSON null data type). |
name | body | string | The name of the image. Value might be null (JSON null data type). |
owner | body | string | An identifier for the owner of the image, usually the project (also
called the “tenant”) ID.
The value might be null (JSON null data type). |
protected | body | boolean | A boolean value that must be false or the image cannot be deleted. |
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 null (JSON null data type). |
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 null (JSON null data type). |
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 show_image_direct_url option is true in the Image
service’s configuration file. Because it presents a security risk, this
option is disabled by default. |
locations (Optional) | body | array | A list of objects, each of which describes an image location. Each object
contains a url key, whose value is a URL specifying a location, and a
metadata key, whose value is a dict of key:value pairs containing
information appropriate to the use of whatever external store is indicated
by the URL. This list appears only if the show_multiple_locations
option is set to true in the Image service’s configuration file.
Because it presents a security risk, this option is disabled by
default. |
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.
{
"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",
"owner": "5ef70662f8b34079a6eddb8da9d75fe8",
"size": 13167616,
"min_ram": 0,
"schema": "/v2/schemas/image",
"virtual_size": null
}
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:
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 |
---|---|
gt |
Return results more recent than the specified time. |
gte |
Return any results matching the specified time and also any more recent results. |
eq |
Return any results matching the specified time exactly. |
neq |
Return any results that do not match the specified time. |
lt |
Return results older than the specified time. |
lte |
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 is desc
.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
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 limit parameter to make an initial limited request and
use the ID of the last-seen item from the response as the marker
parameter value in a subsequent limited request. |
marker (Optional) | query | string | The ID of the last-seen item. Use the limit parameter to make an
initial limited request and use the ID of the last-seen item from the
response as the marker parameter value in a subsequent limited request. |
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. |
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
public , private , community , or shared . (Note that if you
filter on shared , the images included in the response will only be
those where your member status is accepted unless you explicitly
include a member_status filter in the request.) If you omit this
parameter, the response shows public , private , and those shared
images with a member status of accepted . |
member_status (Optional) | query | string | Filters the response by a member status. A valid value is accepted ,
pending , rejected , or all . Default is accepted . |
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 ) combinations. A valid value
for the sort direction is asc (ascending) or desc
(descending). If you omit the sort direction in a set, the default
is desc . |
sort_key (Optional) | query | string | Sorts the response by an attribute, such as
name , id , or updated_at . Default is created_at .
The API uses the natural sorting direction of the sort_key
image attribute. |
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
|
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. |
{
"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",
"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",
"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:
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
Name | In | Type | Description |
---|---|---|---|
Content-Type | header | string | The media type descriptor for the request body. Use
application/openstack-images-v2.1-json-patch . (You can also use
application/openstack-images-v2.0-json-patch , but keep in mind that
it’s deprecated.) |
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).
[
{
"op": "replace",
"path": "/name",
"value": "Fedora 17"
},
{
"op": "replace",
"path": "/tags",
"value": [
"fedora",
"beefy"
]
}
]
Name | In | Type | Description |
---|---|---|---|
checksum | body | string | Hash that is used over the image data. The Image
service uses this value for verification. The value might be
null (JSON null data type). |
container_format | body | enum | Format of the image container. A valid value is one of
ami , ari , aki , bare , ovf , ova , or
docker . The value might be null (JSON null data type). |
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. Responses 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. Example formats are: The value might be vhdx disk format is a supported value. |
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 null (JSON null data type). |
min_ram | body | integer | Amount of RAM in MB that is required to boot the image.
The value might be null (JSON null data type). |
owner | body | string | An identifier for the owner of the image, usually the project (also
called the “tenant”) ID.
The value might be null (JSON null data type). |
name | body | string | The name of the image. Value might be null (JSON null data type). |
protected | body | boolean | A boolean value that must be false or the image cannot be deleted. |
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 null (JSON null data type). |
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 show_image_direct_url option is true in the Image
service’s configuration file. Because it presents a security risk, this
option is disabled by default. |
locations (Optional) | body | array | A list of objects, each of which describes an image location. Each object
contains a url key, whose value is a URL specifying a location, and a
metadata key, whose value is a dict of key:value pairs containing
information appropriate to the use of whatever external store is indicated
by the URL. This list appears only if the show_multiple_locations
option is set to true in the Image service’s configuration file.
Because it presents a security risk, this option is disabled by
default. |
{
"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",
"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
deleted
.protected
attribute of the image cannot be true
.Synchronous Postconditions
204
response code.Normal response codes: 204
Error response codes: 400, 401, 403, 404, 409
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
Normal response codes: 204
Error response codes: 400, 403, 404
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
Normal response codes: 204
Error response codes: 400, 403, 404
Name | In | Type | Description |
---|---|---|---|
image_id | path | string | The UUID of the image. |
Images may be shared among projects by creating members on the image. Image members have read-only privileges on the image. The following calls allow you to create, list, update, and delete image members.
Note
An image member is an identifier for a consumer with whom the image is
shared. In most OpenStack clouds, where the value of the owner
property
of an image is a project ID, the appropriate identifier to use for the
member_id
is the consumer’s project ID (also known as the “tenant ID”).
In these clouds, image sharing is project-to-project, and all the individual
users in the consuming project have access to the image.
owner
property. In such clouds,
the appropriate identifier to use for the member_id
is the user ID of
the person with whom you want to share the image. In these clouds, image
sharing is user-to-user.member_id
. If, like most OpenStack clouds, your cloud
uses the tenant ID for the image owner
, sharing will not work if you
use a user ID as the member_id
of an image (and vice-versa).When an image is shared, the member is given immediate access to the image. In order to prevent spamming other users’ image lists, a shared image does not appear in a member’s image list until the member “accepts” the image.
Only the image owner may create members. Only an image member may modify his or her member status.
For a conceptual overview of image sharing, including a suggested workflow, please consult Image API v2 Sharing.
Note
If you don’t want to maintain a sharing relationship with particular
image consumers, but instead want to make an image available to all
users, you may update your image’s visibility
property to
community
.
Adds a tenant ID as an image member. (Since Image API v2.1)
Preconditions
visibility
value of shared
.Synchronous Postconditions
pending
through API calls.Troubleshooting
visibility
attribute is not set to shared
, the request returns the HTTP
403
response code. Ensure that you meet the preconditions and
run the request again. If the request fails again, review your
API request.Conflict (409)
response code. If you meant to
specify a different member, run the request again.Normal response codes: 200
Error response codes: 400, 401, 403, 404, 409, 413
Name | In | Type | Description |
---|---|---|---|
image_id | path | string | The UUID of the image. |
member | body | string | The ID of the image member. An image member is usually a project (also called the “tenant”) with whom the image is shared. |
{
"member": "8989447062e04a818baf9e073fd04fa7"
}
Name | In | Type | Description |
---|---|---|---|
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 |
image_id | body | string | The UUID of the image. |
member_id | body | string | The ID of the image member. An image member is usually a project (also called the “tenant”) with whom the image is shared. |
schema | body | string | The URL for the schema describing an image member. |
status | body | string | The status of this image member. Value is one of pending ,
accepted , rejected . |
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 |
{
"created_at": "2013-09-20T19:22:19Z",
"image_id": "a96be11e-8536-4910-92cb-de50aa19dfe6",
"member_id": "8989447062e04a818baf9e073fd04fa7",
"schema": "/v2/schemas/member",
"status": "pending",
"updated_at": "2013-09-20T19:25:31Z"
}
Shows image member details. (Since Image API v2.1)
Response body is a single image member entity.
Preconditions
visibility
value of shared
.Normal response codes: 200
Error response codes: 400, 401, 404
Name | In | Type | Description |
---|---|---|---|
image_id | path | string | The UUID of the image. |
member_id | path | string | The ID of the image member. An image member is usually the project (also called the “tenant”) with whom the image is shared. |
Name | In | Type | Description |
---|---|---|---|
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 |
image_id | body | string | The UUID of the image. |
member_id | body | string | The ID of the image member. An image member is usually a project (also called the “tenant”) with whom the image is shared. |
schema | body | string | The URL for the schema describing an image member. |
status | body | string | The status of this image member. Value is one of pending ,
accepted , rejected . |
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 |
{
"status": "pending",
"created_at": "2013-11-26T07:21:21Z",
"updated_at": "2013-11-26T07:21:21Z",
"image_id": "0ae74cc5-5147-4239-9ce2-b0c580f7067e",
"member_id": "8989447062e04a818baf9e073fd04fa7",
"schema": "/v2/schemas/member"
}
Lists the tenants that share this image. (Since Image API v2.1)
If the image owner makes this call, the complete member list is returned.
If a user who is an image member makes this call, the member list contains only information for that user.
If a user who is not an image member makes this call, the call
returns the HTTP 404
response code.
Preconditions
visibility
value of shared
.Normal response codes: 200
Error response codes: 400, 401, 403, 404
Name | In | Type | Description |
---|---|---|---|
image_id | path | string | The UUID of the image. |
Name | In | Type | Description |
---|---|---|---|
members | body | array | A list of member objects, as described by the Image Members Schema. Each member object describes a member with whom this image is being shared. |
schema | body | string | The URL for the schema describing an image member list. |
{
"members": [
{
"created_at": "2013-10-07T17:58:03Z",
"image_id": "dbc999e3-c52f-4200-bedd-3b18fe7f87fe",
"member_id": "123456789",
"schema": "/v2/schemas/member",
"status": "pending",
"updated_at": "2013-10-07T17:58:03Z"
},
{
"created_at": "2013-10-07T17:58:55Z",
"image_id": "dbc999e3-c52f-4200-bedd-3b18fe7f87fe",
"member_id": "987654321",
"schema": "/v2/schemas/member",
"status": "accepted",
"updated_at": "2013-10-08T12:08:55Z"
}
],
"schema": "/v2/schemas/members"
}
Sets the status for an image member. (Since Image API v2.1)
This call allows an image member to change his or her member status.
When an image is shared with you, you have immediate access to the image. What updating your member status on the image does for you is that it affects whether the image will appear in your image list response.
pending
. You
won’t see the image unless you go looking for it, either by making a show
image detail request using the image’s ID, or by making an image list call
specifically looking for a shared image in member status pending
. This
way, other users cannot “spam” your image list with images you may not want
to see.accepted
.pending
, accepted
, and
rejected
. The pending
and rejected
statuses are functionally
identical. The difference is that pending
indicates to the owner that
you haven’t updated the image, so perhaps you aren’t aware that it’s been
shared with you. The rejected
status indicates that you are aware that
the image exists and you specifically decided that you don’t want to see it
in your image list response.For a more detailed discussion of image sharing, please consult Image API v2 Sharing.
Preconditions
visibility
value of shared
.Synchronous Postconditions
accepted
and have the
correct permissions, you see the image in list images responses.Normal response codes: 200
Error response codes: 400, 401, 404, 403
Name | In | Type | Description |
---|---|---|---|
image_id | path | string | The UUID of the image. |
member_id | path | string | The ID of the image member. An image member is usually the project (also called the “tenant”) with whom the image is shared. |
status | body | string | The status of this image member. Value is one of pending ,
accepted , rejected . |
{
"status": "accepted"
}
Name | In | Type | Description |
---|---|---|---|
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 |
image_id | body | string | The UUID of the image. |
member_id | body | string | The ID of the image member. An image member is usually a project (also called the “tenant”) with whom the image is shared. |
schema | body | string | The URL for the schema describing an image member. |
status | body | string | The status of this image member. Value is one of pending ,
accepted , rejected . |
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 |
{
"created_at": "2013-09-20T19:22:19Z",
"image_id": "a96be11e-8536-4910-92cb-de50aa19dfe6",
"member_id": "8989447062e04a818baf9e073fd04fa7",
"schema": "/v2/schemas/member",
"status": "accepted",
"updated_at": "2013-09-20T20:15:31Z"
}
Deletes a tenant ID from the member list of an image. (Since Image API v2.1)
Preconditions
visibility
value of shared
.Synchronous Postconditions
Troubleshooting
403
or 404
response code. Ensure
that you meet the preconditions and run the request again. If the
request fails again, review your API request URI.Normal response codes: 204
Error response codes: 400, 401, 403, 404
Name | In | Type | Description |
---|---|---|---|
image_id | path | string | The UUID of the image. |
member_id | path | string | The ID of the image member. An image member is usually the project (also called the “tenant”) with whom the image is shared. |
Adds and deletes image tags.
Image tags may also be modfied by the Update an image call.
Adds a tag to an image. (Since Image API v2.0)
Normal response codes: 204
Error response codes: 400, 401, 403, 404, 413
Name | In | Type | Description |
---|---|---|---|
image_id | path | string | The UUID of the image. |
tag | path | string | The image tag. A tag is limited to 255 chars in length. You may wish to use characters that can easily be written in a URL. |
Deletes a tag from an image. (Since Image API v2.0)
Normal response codes: 204
Error response codes: 400, 401, 403, 404
Name | In | Type | Description |
---|---|---|---|
image_id | path | string | The UUID of the image. |
tag | path | string | The image tag. A tag is limited to 255 chars in length. You may wish to use characters that can easily be written in a URL. |
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
This operation has no request parameters and does not accept a request body.
{
"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 http://docs.openstack.org/trunk/openstack-compute/admin/content/adding-images.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"
],
"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 http://docs.openstack.org/trunk/openstack-compute/admin/content/adding-images.html",
"is_base": false,
"type": "string"
},
"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"
],
"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
This operation has no request parameters and does not accept a request body.
{
"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 http://docs.openstack.org/trunk/openstack-compute/admin/content/adding-images.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"
],
"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 http://docs.openstack.org/trunk/openstack-compute/admin/content/adding-images.html",
"is_base": false,
"type": "string"
},
"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"
],
"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
This operation has no request parameters and does not accept a request body.
{
"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
This operation has no request parameters and does not accept a request body.
{
"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"
}
}
}
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
.
Example call:
curl -i -X PUT -H "X-Auth-Token: $token" \
-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:
queued
.Synchronous Postconditions
active
through API calls.Troubleshooting
Normal response codes: 204
Error response codes: 400, 401, 403, 404, 409, 410, 413, 415, 503
Name | In | Type | Description |
---|---|---|---|
Content-type | header | string | The media type descriptor for the request body. Use
application/octet-stream |
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
Synchronous Postconditions
200
response code for a
full image download request.206
response code for a
partial download request.204
(No Content)
response code.404
response code
for an attempted full image download request.416
response code.Normal response codes: 200, 204, 206
Error response codes: 400, 403, 404, 416
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. |
Name | In | Type | Description |
---|---|---|---|
Content-Type | header | string | The media type descriptor of the response body, namely
application/octet-stream |
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. |
Creates, lists, and shows details for tasks.
(Since API v2.2)
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 result element should be
populated. |
failure | The task failed to complete. The message element should be a
non-empty string. |
Creates a task.
Normal response codes: 201
Error response codes: 401, 413, 415
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. |
{
"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"
}
}
}
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 pending ,
processing , success or failure . |
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 |
{
"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
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 limit parameter to make an initial limited request and
use the ID of the last-seen item from the response as the marker
parameter value in a subsequent limited request. |
marker (Optional) | query | string | The ID of the last-seen item. Use the limit parameter to make an
initial limited request and use the ID of the last-seen item from the
response as the marker parameter value in a subsequent limited request. |
sort_dir (Optional) | query | string | Sorts the response by a set of one or more sort direction and attribute
(sort_key ) combinations. A valid value for the sort direction is
asc (ascending) or desc (descending). If you omit the sort
direction in a set, the default is desc . |
sort_key (Optional) | query | string | Sorts the response by one of the following attributes: created_at ,
expires_at , status , type , updated_at . Default is
created_at . |
status (Optional) | query | string | Filters the response by a task status. A valid value is pending ,
processing , success , or failure . |
type (Optional) | query | string | Filters the response by a task type. A valid value is import . |
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:
|
{
"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
Name | In | Type | Description |
---|---|---|---|
task_id | path | string | The identifier for the task, a UUID. |
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 pending ,
processing , success or failure . |
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 |
{
"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"
}
{
"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"
}
{
"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"
}
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
This operation has no request parameters and does not accept a request body.
{
"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
This operation has no request parameters and does not accept a request body.
{
"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"
}
}
}
Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.