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.

注釈

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.

注釈

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.
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
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.

POST

/v2/images

Create an image

detail

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

• With correct permissions, you can see the image status as queued through 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. Example formats are: ami, ari, aki, bare, ovf, ova, or docker. The value might be null (JSON null data type).
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. Example formats are: ami, ari, aki, vhd, vhdx, vmdk, raw, qcow2, vdi, ploop or iso. The value might be null (JSON null data type). Newton changes: The vhdx disk format is a supported value. Ocata changes: The ploop 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 409 response code.
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.

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
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. 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. Example formats are: 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, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC.
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. Example formats are: ami, ari, aki, vhd, vhdx, vmdk, raw, qcow2, vdi, ploop or iso. The value might be null (JSON null data type). Newton changes: The vhdx disk format is a supported value. Ocata changes: The ploop 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, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00. If the updated_at date and time stamp is not set, its value is null.
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.

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,
    "owner": "bab7d5c60cd041a0a36f7c4b6e1dd978",
    "virtual_size": null,
    "min_ram": 0,
    "schema": "/v2/schemas/image"
}

GET

/v2/images/{image_id}

Show image details

detail

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	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. 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. Example formats are: 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, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC.
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. Example formats are: ami, ari, aki, vhd, vhdx, vmdk, raw, qcow2, vdi, ploop or iso. The value might be null (JSON null data type). Newton changes: The vhdx disk format is a supported value. Ocata changes: The ploop 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, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00. If the updated_at date and time stamp is not set, its value is null.
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.
hw_firmware_type (Optional)	body	string	If uefi, image enable UEFI BOOT.

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",
    "owner": "5ef70662f8b34079a6eddb8da9d75fe8",
    "size": 13167616,
    "min_ram": 0,
    "schema": "/v2/schemas/image",
    "virtual_size": null
}

GET

/v2/images

Show images

detail

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
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

注釈

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 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.
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 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 ±hh:mm value, if included, is the time zone as an offset from UTC. For example, 2015-08-27T09:49:58-05:00. 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 ±hh:mm value, if included, is the time zone as an offset from UTC. For example, 2015-08-27T09:49:58-05:00. 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 desc. Use the comma (,) character to separate multiple values. For example: 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",
            "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"
}

PATCH

/v2/images/{image_id}

Update an image

detail

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.

注釈

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).

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 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).

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	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. 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. Example formats are: 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, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC.
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. Example formats are: ami, ari, aki, vhd, vhdx, vmdk, raw, qcow2, vdi, ploop or iso. The value might be null (JSON null data type). Newton changes: The vhdx disk format is a supported value. Ocata changes: The ploop 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, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00. If the updated_at date and time stamp is not set, its value is null.
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.

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",
    "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"
}

DELETE

/v2/images/{image_id}

Delete an image

detail

(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 protected attribute of the image cannot be true.
• You have permission to perform image deletion under the configured image deletion policy.

Synchronous Postconditions

• The response is empty and returns the HTTP 204 response 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.

Sharing

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.

注釈

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.

• Some deployments may choose instead to have the identifier of the user who created the image as the value of the 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.
• Note that you, as an image owner, do not have a choice about what value to use for the 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).
• Please consult your cloud's local documentation for details.

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.

注釈

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.

• In some clouds, the ability to "communitize" an image may be prohibited or restricted to trusted users. Please consult your cloud's local documentation for details.

POST

/v2/images/{image_id}/members

Create image member

detail

Adds a tenant ID as an image member. (Since Image API v2.1)

Preconditions

• The image must exist.
• The image must have a visibility value of shared.
• You must be the owner of the image.

Synchronous Postconditions

• With correct permissions, you can see the member status of the image member as pending through API calls.

Troubleshooting

• Even if you have correct permissions, if the 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.
• If the member is already a member for the image, the service returns the 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

Request

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.

Request Example

{
    "member": "8989447062e04a818baf9e073fd04fa7"
}

Response Parameters

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, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC.
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, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00. If the updated_at date and time stamp is not set, its value is null.

Response Example

{
    "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"
}

GET

/v2/images/{image_id}/members/{member_id}

Show image member details

detail

Shows image member details. (Since Image API v2.1)

Response body is a single image member entity.

Preconditions

• The image must exist.
• The image must have a visibility value of shared.
• You must be the owner or the member of the image who's referenced in the call.

Normal response codes: 200

Error response codes: 400, 401, 404

Request

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.

Response Parameters

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, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC.
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, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00. If the updated_at date and time stamp is not set, its value is null.

Response Example

{
    "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"
}

GET

/v2/images/{image_id}/members

List image members

detail

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

• The image must exist.
• The image must have a visibility value of shared.
• You must be the owner or a member of the image.

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
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.

Response Example

{
    "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"
}

PUT

/v2/images/{image_id}/members/{member_id}

Update image member

detail

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.

• When an image is shared with you, your member_status is 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.
• If you want to see a particular shared image in your image list, then you must use this call to change your member status on the image to accepted.
• The image owner can see what your member status is on an image, but the owner cannot change the status. Only you (or an administrator) can do that.
• There are three member status values: 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

• The image must exist.
• The image must have a visibility value of shared.
• You must be the member of the image referenced in the call.

Synchronous Postconditions

• If you update the member status to accepted and have the correct permissions, you see the image in list images responses.
• With correct permissions, you can make API calls to see the updated member status of the image.

Normal response codes: 200

Error response codes: 400, 401, 404, 403

Request

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.

Request Example

{
    "status": "accepted"
}

Response Parameters

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, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC.
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, 2015-08-27T09:49:58-05:00. The ±hh:mm value, if included, is the time zone as an offset from UTC. In the previous example, the offset value is -05:00. If the updated_at date and time stamp is not set, its value is null.

Response Example

{
    "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"
}

DELETE

/v2/images/{image_id}/members/{member_id}

Delete image member

detail

Deletes a tenant ID from the member list of an image. (Since Image API v2.1)

Preconditions

• The image must exist.
• The image must have a visibility value of shared.
• You must be the owner of the image.

Synchronous Postconditions

• The API removes the member from the image members.

Troubleshooting

• Even if you have correct permissions, if you are not the owner of the image or you specify an incorrect image ID or member ID, the call returns the HTTP 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

Request

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.

Image tags

Adds and deletes image tags.

Image tags may also be modfied by the Update an image call.

PUT

/v2/images/{image_id}/tags/{tag}

Add image tag

detail

Adds a tag to an image. (Since Image API v2.0)

Normal response codes: 204

Error response codes: 400, 401, 403, 404, 413

Request

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.

DELETE

/v2/images/{image_id}/tags/{tag}

Delete image tag

detail

Deletes a tag from an image. (Since Image API v2.0)

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.
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.

Image Schemas

Gets a JSON-schema document that represents the various entities talked about by the Images v2 API.

GET

/v2/schemas/images

Show images schema

detail

(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"
                        ],
                        "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_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"
        }
    }
}

GET

/v2/schemas/image

Show image schema

detail

(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"
            ],
            "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_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"
        }
    }
}

GET

/v2/schemas/members

Show image members schema

detail

(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"
        }
    }
}

GET

/v2/schemas/member

Show image member schema

detail

(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.

PUT

/v2/images/{image_id}/file

Upload binary image data

detail

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:

• 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 active through 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 application/octet-stream
image_id	path	string	The UUID of the image.

GET

/v2/images/{image_id}/file

Download binary image data

detail

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 200 response code for a full image download request.
• If image data exists, the call returns the HTTP 206 response 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 404 response code for an attempted full image download request.
• For an unsatisfiable partial download request, the call returns the HTTP 416 response 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 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.

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).

Two import methods are defined, glance-direct and web-download.

注釈

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:

1. 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-methods header 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.

The glance-direct import method

The glance-direct workflow has three parts:

1. Create an image record as described above.
2. 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.
3. Issue the Image Import call to complete the import process. You will specify that you are using the glance-direct import method in the body of the import call.

The web-download import method

The web-download workflow has two parts:

1. Create an image record as described above.
2. Issue the Image Import call to complete the import process. You will specify that you are using the web-download import method in the body of the import call.

PUT

/v2/images/{image_id}/stage

Stage binary image data

detail

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 uploading through 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 application/octet-stream
image_id	path	string	The UUID of the image.

POST

/v2/images/{image_id}/import

Import an image

detail

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.

Example call: curl -i -X POST -H "X-Auth-Token: $token" $image_url/v2/images/{image_id}/import

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-direct import 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-download import method, and it must contain the URL at which the data is to be found.

  注釈

  The acceptable set of URLs for the web-download import method may be restricted in a particular cloud. Consult the cloud's local documentation for details.

Synchronous Postconditions

• With correct permissions, you can see the image status as importing through API calls. (Be aware, however, that if the import process completes before you make the API call, the image may already show as active.)

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 application/json.
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 name field whose value is the identifier for the import method.

Request Example - glance-direct import method

{
    "method": {
        "name": "glance-direct"
    }
}

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"
    }
}

GET

/v2/info/import

Import methods and values discovery

detail

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)

注釈

In the Image API v2.6, 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 value element, which is an array of string identifiers indicating what import methods are available in the cloud in which the call is made. This list may be empty.

Response Example

{
    "import-methods": {
        "description": "Import methods available.",
        "type": "array",
        "value": [
            "glance-direct",
            "web-download"
        ]
    }
}

Task Schemas

Gets a JSON-schema document that represents an individual task and a list of tasks.

GET

/v2/schemas/tasks

Show tasks schema

detail

(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"
        }
    }
}

GET

/v2/schemas/task

Show task schema

detail

(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"
        }
    }
}

目次

• 1. Smart Data Platform Image Data Storage API List (JP1/JP2/JP3/JP4/JP5/JP6)
  • 1.1. Image Data Storage (Glance)
• 2. Smart Data Platform Image Data Storage DataType List
  • 2.1. Resource
• 3. Smart Data Platform Image Data Storage API List (JP7)
  • 3.1. Smart Data Platform Image Data Storage API List (JP7)
• 4. Revision History

---

Image Service Versions

Metadata Definitions Service API v2 (CURRENT)