736 lines
21 KiB
ReStructuredText
736 lines
21 KiB
ReStructuredText
.. -*- rst -*-
|
|
|
|
Images
|
|
******
|
|
|
|
Creates, lists, shows, updates, deletes, and performs other operations on
|
|
images.
|
|
|
|
General information
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
**Images**
|
|
|
|
An *image* is represented by a JSON Object, that is, as a set of key:value
|
|
pairs. Some of these keys are *base properties* that are managed by the
|
|
Image service. The remainder are properties put on the image by the operator
|
|
or the image owner.
|
|
|
|
.. note::
|
|
Another common term for "image properties" is "image metadata" because
|
|
what we're talking about here are properties that *describe* the image
|
|
data that can be consumed by various OpenStack services (for example,
|
|
by the Compute service to boot a server, or by the Volume service to
|
|
create a bootable volume).
|
|
|
|
Here's some important information about image properties:
|
|
|
|
* The base properties are always included in the image representation. A
|
|
base property that doesn't have a value is displayed with its value set
|
|
to ``null`` (that is, the JSON null data type).
|
|
|
|
* Additional properties, whose value is always a string data type, are
|
|
only included in the response if they have a value.
|
|
|
|
* Since version 2.2, the Images API allows an operator to configure
|
|
*property protections*, by which the create, read, update, and delete
|
|
operations on specific image properties may be restricted to particular
|
|
user roles. Consult the documentation of your cloud operator for details.
|
|
|
|
* Arguably the most important properties of an image are its *id*, which
|
|
uniquely identifies the image, its *status*, which indicates the current
|
|
situation of the image (which, in turn, indicates what you can do with the
|
|
image), and its *visibility*, which indicates who has access to the image.
|
|
|
|
.. 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 :ref:`Image Data
|
|
<image-data>` section of this document for more information.
|
|
|
|
**Image status**
|
|
|
|
The possible status values for images are presented in the following table.
|
|
|
|
.. list-table::
|
|
:header-rows: 1
|
|
|
|
* - 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.
|
|
|
|
.. list-table::
|
|
:header-rows: 1
|
|
|
|
* - 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 :ref:`Image Sharing <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.
|
|
|
|
.. _image-create:
|
|
|
|
Create image
|
|
~~~~~~~~~~~~
|
|
|
|
.. rest_method:: POST /v2/images
|
|
|
|
Creates a catalog record for an operating system disk image.
|
|
*(Since Image API v2.0)*
|
|
|
|
The ``Location`` response header contains the URI for the image.
|
|
|
|
A multiple store backend support is introduced in the Rocky release
|
|
as a part of the EXPERIMENTAL Image API v2.8. Since Image API v2.8 a
|
|
new header ``OpenStack-image-store-ids`` which contains the list of
|
|
available stores will be included in response. This header is only
|
|
included if multiple backend stores are supported.
|
|
|
|
.. note:: The Multi Store feature is introduced as EXPERIMENTAL in Rocky and
|
|
its use in production systems is currently **not supported**.
|
|
However we encourage people to use this feature for testing
|
|
purposes and report the issues so that we can make it stable and
|
|
fully supported in Stein release.
|
|
|
|
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
|
|
-------
|
|
|
|
.. rest_parameters:: images-parameters.yaml
|
|
|
|
- container_format: container_format-in-request
|
|
- disk_format: disk_format-in-request
|
|
- id: id-in-request
|
|
- min_disk: min_disk-in-request
|
|
- min_ram: min_ram-in-request
|
|
- name: name-in-request
|
|
- protected: protected-in-request
|
|
- tags: tags-in-request
|
|
- visibility: visibility-in-request
|
|
|
|
Additionally, you may include additional properties specified as key:value
|
|
pairs, where the value must be a string data type. Keys are limited
|
|
to 255 chars in length. Available key names may be limited by the cloud's
|
|
property protection configuration.
|
|
|
|
Request Example
|
|
---------------
|
|
|
|
.. literalinclude:: samples/image-create-request.json
|
|
:language: json
|
|
|
|
Response Parameters
|
|
-------------------
|
|
|
|
.. rest_parameters:: images-parameters.yaml
|
|
|
|
- Location: Location
|
|
- OpenStack-image-import-methods: import-header
|
|
- OpenStack-image-store-ids: stores-header
|
|
- checksum: checksum
|
|
- container_format: container_format
|
|
- created_at: created_at
|
|
- disk_format: disk_format
|
|
- file: file
|
|
- id: id
|
|
- min_disk: min_disk
|
|
- min_ram: min_ram
|
|
- name: name
|
|
- os_hash_algo: os_hash_algo
|
|
- os_hash_value: os_hash_value
|
|
- os_hidden: os_hidden
|
|
- owner: owner
|
|
- protected: protected
|
|
- schema: schema-image
|
|
- self: self
|
|
- size: size
|
|
- status: status
|
|
- tags: tags
|
|
- updated_at: updated_at
|
|
- virtual_size: virtual_size
|
|
- visibility: visibility
|
|
- direct_url: direct_url
|
|
- locations: locations
|
|
|
|
The response may also include additional properties specified as key:value
|
|
pairs if additional properties were specified in the request.
|
|
|
|
Response Example
|
|
----------------
|
|
|
|
.. literalinclude:: samples/image-create-response.json
|
|
:language: json
|
|
|
|
|
|
Show image
|
|
~~~~~~~~~~
|
|
|
|
.. rest_method:: GET /v2/images/{image_id}
|
|
|
|
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
|
|
-------
|
|
|
|
.. rest_parameters:: images-parameters.yaml
|
|
|
|
- image_id: image_id-in-path
|
|
|
|
|
|
Response Parameters
|
|
-------------------
|
|
|
|
.. rest_parameters:: images-parameters.yaml
|
|
|
|
- checksum: checksum
|
|
- container_format: container_format
|
|
- created_at: created_at
|
|
- disk_format: disk_format
|
|
- file: file
|
|
- id: id
|
|
- min_disk: min_disk
|
|
- min_ram: min_ram
|
|
- name: name
|
|
- os_hash_algo: os_hash_algo
|
|
- os_hash_value: os_hash_value
|
|
- os_hidden: os_hidden
|
|
- owner: owner
|
|
- protected: protected
|
|
- schema: schema-image
|
|
- self: self
|
|
- size: size
|
|
- status: status
|
|
- tags: tags
|
|
- updated_at: updated_at
|
|
- virtual_size: virtual_size
|
|
- visibility: visibility
|
|
- direct_url: direct_url
|
|
- locations: locations
|
|
|
|
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
|
|
----------------
|
|
|
|
.. literalinclude:: samples/image-show-response.json
|
|
:language: json
|
|
|
|
|
|
List images
|
|
~~~~~~~~~~~
|
|
|
|
.. rest_method:: GET /v2/images
|
|
|
|
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``.
|
|
|
|
.. _v2-comparison-ops:
|
|
|
|
**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
|
|
<https://en.wikipedia.org/wiki/ISO_8601>`_. Available comparison operators
|
|
are:
|
|
|
|
.. list-table::
|
|
:header-rows: 1
|
|
|
|
* - 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:
|
|
|
|
.. code-block:: console
|
|
|
|
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:
|
|
|
|
.. code-block:: console
|
|
|
|
GET /v2/images?sort_key=name&sort_dir=asc&sort_key=status&sort_dir=desc
|
|
|
|
Alternatively, specify the ``sort`` query parameter:
|
|
|
|
.. code-block:: console
|
|
|
|
GET /v2/images?sort=name:asc,status:desc
|
|
|
|
.. note::
|
|
Although this call has been available since version 2.0 of this API,
|
|
it has been enhanced from release to release. The filtering and
|
|
sorting functionality and syntax described above apply to the most
|
|
recent release (Newton). Not everything described above will be
|
|
available in prior releases.
|
|
|
|
Normal response codes: 200
|
|
|
|
Error response codes: 400, 401, 403
|
|
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: images-parameters.yaml
|
|
|
|
- limit: limit
|
|
- marker: marker
|
|
- name: name-in-query
|
|
- owner: owner-in-query
|
|
- protected: protected-in-query
|
|
- status: status-in-query
|
|
- tag: tag-in-query
|
|
- visibility: visibility-in-query
|
|
- os_hidden: os_hidden-in-query
|
|
- member_status: member_status-in-query
|
|
- size_max: size_max
|
|
- size_min: size_min
|
|
- created_at: created_at-in-query
|
|
- updated_at: updated_at-in-query
|
|
- sort_dir: sort_dir
|
|
- sort_key: sort_key
|
|
- sort: sort
|
|
|
|
|
|
Response Parameters
|
|
-------------------
|
|
|
|
.. rest_parameters:: images-parameters.yaml
|
|
|
|
- images: images
|
|
- first: first
|
|
- next: next
|
|
- schema: schema-images
|
|
|
|
|
|
|
|
Response Example
|
|
----------------
|
|
|
|
.. literalinclude:: samples/images-list-response.json
|
|
:language: json
|
|
|
|
|
|
.. _v2-image-update:
|
|
|
|
Update image
|
|
~~~~~~~~~~~~
|
|
|
|
.. rest_method:: PATCH /v2/images/{image_id}
|
|
|
|
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 <http://tools.ietf.org/html/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
|
|
<http://specs.openstack.org/openstack/glance-specs/specs/api/v2
|
|
/http-patch-image-api-v2.html>`_.
|
|
|
|
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
|
|
:ref:`Image Schema <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
|
|
-------
|
|
|
|
.. rest_parameters:: images-parameters.yaml
|
|
|
|
- Content-Type: Content-Type-patch
|
|
- image_id: image_id-in-path
|
|
|
|
The request body must conform to the
|
|
``application/openstack-images-v2.1-json-patch`` media type definition (see
|
|
above).
|
|
|
|
|
|
Request Example
|
|
---------------
|
|
|
|
.. literalinclude:: samples/image-update-request.json
|
|
:language: json
|
|
|
|
|
|
Response Parameters
|
|
-------------------
|
|
|
|
.. rest_parameters:: images-parameters.yaml
|
|
|
|
- checksum: checksum
|
|
- container_format: container_format
|
|
- created_at: created_at
|
|
- disk_format: disk_format
|
|
- file: file
|
|
- id: id
|
|
- min_disk: min_disk
|
|
- min_ram: min_ram
|
|
- name: name
|
|
- owner: owner
|
|
- os_hash_algo: os_hash_algo
|
|
- os_hash_value: os_hash_value
|
|
- os_hidden: os_hidden
|
|
- protected: protected
|
|
- schema: schema-image
|
|
- self: self
|
|
- size: size
|
|
- status: status
|
|
- tags: tags
|
|
- updated_at: updated_at
|
|
- visibility: visibility
|
|
- direct_url: direct_url
|
|
- locations: locations
|
|
|
|
|
|
|
|
Response Example
|
|
----------------
|
|
|
|
.. literalinclude:: samples/image-update-response.json
|
|
:language: json
|
|
|
|
|
|
Delete image
|
|
~~~~~~~~~~~~
|
|
|
|
.. rest_method:: DELETE /v2/images/{image_id}
|
|
|
|
(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
|
|
-------
|
|
|
|
.. rest_parameters:: images-parameters.yaml
|
|
|
|
- image_id: image_id-in-path
|
|
|
|
|
|
Deactivate image
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
.. rest_method:: POST /v2/images/{image_id}/actions/deactivate
|
|
|
|
Deactivates an image.
|
|
*(Since Image API v2.3)*
|
|
|
|
By default, this operation is restricted to administrators only.
|
|
|
|
If you try to download a deactivated image, you will receive a 403 (Forbidden)
|
|
response code. Additionally, only administrative users can view image
|
|
locations for deactivated images.
|
|
|
|
The deactivate operation returns an error if the image status is
|
|
not ``active`` or ``deactivated``.
|
|
|
|
Preconditions
|
|
|
|
- The image must exist.
|
|
|
|
Normal response codes: 204
|
|
|
|
Error response codes: 400, 403, 404
|
|
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: images-parameters.yaml
|
|
|
|
- image_id: image_id-in-path
|
|
|
|
|
|
Reactivate image
|
|
~~~~~~~~~~~~~~~~
|
|
|
|
.. rest_method:: POST /v2/images/{image_id}/actions/reactivate
|
|
|
|
Reactivates an image.
|
|
*(Since Image API v2.3)*
|
|
|
|
By default, this operation is restricted to administrators only.
|
|
|
|
The reactivate operation returns an error if the image status is
|
|
not ``active`` or ``deactivated``.
|
|
|
|
Preconditions
|
|
|
|
- The image must exist.
|
|
|
|
Normal response codes: 204
|
|
|
|
Error response codes: 400, 403, 404
|
|
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: images-parameters.yaml
|
|
|
|
- image_id: image_id-in-path
|