d8221bf16f
Update the api-ref for the "Operator maintained images lifecycle" spec implemented in Rocky. Change-Id: I8fcfb84579b655fd44759164508ce4532e4dd205
684 lines
19 KiB
YAML
684 lines
19 KiB
YAML
# variables in header
|
|
Content-Length:
|
|
description: |
|
|
The length of the body in octets (8-bit bytes)
|
|
in: header
|
|
required: true
|
|
type: string
|
|
Content-Md5:
|
|
description: |
|
|
The MD5 checksum of the body.
|
|
in: header
|
|
required: true
|
|
type: string
|
|
Content-Range:
|
|
description: |
|
|
The content range of image data. For details, see
|
|
`Hypertext Transfer Protocol (HTTP/1.1): Range Requests
|
|
<http://tools.ietf.org/html/rfc7233>`_.
|
|
in: header
|
|
required: false
|
|
type: string
|
|
Content-Type-data:
|
|
description: |
|
|
The media type descriptor for the request body. Use
|
|
``application/octet-stream``
|
|
in: header
|
|
required: true
|
|
type: string
|
|
Content-Type-data-response:
|
|
description: |
|
|
The media type descriptor of the response body, namely
|
|
``application/octet-stream``
|
|
in: header
|
|
required: true
|
|
type: string
|
|
Content-Type-json:
|
|
description: |
|
|
The media type descriptor for the request body. Use
|
|
``application/json``.
|
|
in: header
|
|
required: true
|
|
type: string
|
|
Content-Type-patch:
|
|
description: |
|
|
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.)
|
|
in: header
|
|
required: true
|
|
type: string
|
|
import-header:
|
|
description: |
|
|
A comma separated list of import method identifiers. Included
|
|
only if image import is enabled in your cloud. *Since Image API v2.6*
|
|
in: header
|
|
required: false
|
|
type: string
|
|
Location:
|
|
description: |
|
|
The URL to access the image file from the
|
|
external store.
|
|
in: header
|
|
required: true
|
|
type: string
|
|
Range:
|
|
description: |
|
|
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
|
|
<http://tools.ietf.org/html/rfc7233>`_.
|
|
in: header
|
|
required: false
|
|
type: string
|
|
store-header:
|
|
description: |
|
|
A store identifier to upload or import image data. Should only be included
|
|
when making a request to a cloud that supports multiple backing stores. Use
|
|
the :ref:`Store Discovery <store-discovery-call>` call to determine an
|
|
appropriate store identifier. Simply omit this header to use the default
|
|
store. *(Since Image API v2.8)*
|
|
in: header
|
|
required: false
|
|
type: string
|
|
stores-header:
|
|
description: |
|
|
A comma separated list of available store identifiers. If this header
|
|
is missing the cloud does not support multiple backend stores.
|
|
in: header
|
|
required: false
|
|
type: string
|
|
|
|
# variables in path
|
|
image_id-in-path:
|
|
description: |
|
|
The UUID of the image.
|
|
in: path
|
|
required: true
|
|
type: string
|
|
member_id-in-path:
|
|
description: |
|
|
The ID of the image member. An image member is usually the project (also
|
|
called the "tenant") with whom the image is shared.
|
|
in: path
|
|
required: true
|
|
type: string
|
|
tag-in-path:
|
|
description: |
|
|
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.
|
|
in: path
|
|
required: true
|
|
type: string
|
|
|
|
# variables in query
|
|
created_at-in-query:
|
|
description: |
|
|
Specify a *comparison filter* based on the date and time when the resource
|
|
was created. (See :ref:`Time Comparison Filters <v2-comparison-ops>`).
|
|
|
|
The date and time stamp format is `ISO 8601
|
|
<https://en.wikipedia.org/wiki/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.
|
|
in: query
|
|
required: false
|
|
type: string
|
|
limit:
|
|
description: |
|
|
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.
|
|
in: query
|
|
required: false
|
|
type: integer
|
|
marker:
|
|
description: |
|
|
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.
|
|
in: query
|
|
required: false
|
|
type: string
|
|
member_status-in-query:
|
|
description: |
|
|
Filters the response by a member status. A valid value is ``accepted``,
|
|
``pending``, ``rejected``, or ``all``. Default is ``accepted``.
|
|
in: query
|
|
required: false
|
|
type: string
|
|
name-in-query:
|
|
description: |
|
|
Filters the response by a name, as a string. A valid value is the name of
|
|
an image.
|
|
in: query
|
|
required: false
|
|
type: string
|
|
os_hidden-in-query:
|
|
description: |
|
|
When ``true``, filters the response to display only "hidden" images. By
|
|
default, "hidden" images are not included in the image-list response.
|
|
*(Since Image API v2.7)*
|
|
in: query
|
|
required: false
|
|
type: boolean
|
|
owner-in-query:
|
|
description: |
|
|
Filters the response by a project (also called a "tenant") ID. Shows only
|
|
images that are shared with you by the specified owner.
|
|
in: query
|
|
required: false
|
|
type: string
|
|
protected-in-query:
|
|
description: |
|
|
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.
|
|
in: query
|
|
required: false
|
|
type: boolean
|
|
size_max:
|
|
description: |
|
|
Filters the response by a maximum image size, in
|
|
bytes.
|
|
in: query
|
|
required: false
|
|
type: string
|
|
size_min:
|
|
description: |
|
|
Filters the response by a minimum image size, in
|
|
bytes.
|
|
in: query
|
|
required: false
|
|
type: string
|
|
sort:
|
|
description: |
|
|
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:
|
|
|
|
.. code-block:: none
|
|
|
|
GET /v2/images?sort=name:asc,status:desc
|
|
in: query
|
|
required: false
|
|
type: string
|
|
sort_dir:
|
|
description: |
|
|
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``.
|
|
in: query
|
|
required: false
|
|
type: string
|
|
sort_key:
|
|
description: |
|
|
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.
|
|
in: query
|
|
required: false
|
|
type: string
|
|
status-in-query:
|
|
description: |
|
|
Filters the response by an image status.
|
|
in: query
|
|
required: false
|
|
type: integer
|
|
tag-in-query:
|
|
description: |
|
|
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.
|
|
in: query
|
|
required: false
|
|
type: string
|
|
updated_at-in-query:
|
|
description: |
|
|
Specify a *comparison filter* based on the date and time when the resource
|
|
was most recently modified. (See :ref:`Time Comparison Filters
|
|
<v2-comparison-ops>`).
|
|
|
|
The date and time stamp format is `ISO 8601
|
|
<https://en.wikipedia.org/wiki/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.
|
|
in: query
|
|
required: false
|
|
type: string
|
|
visibility-in-query:
|
|
description: |
|
|
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``.
|
|
in: query
|
|
required: false
|
|
type: string
|
|
|
|
# variables in body
|
|
checksum:
|
|
description: |
|
|
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).
|
|
in: body
|
|
required: true
|
|
type: string
|
|
container_format:
|
|
description: |
|
|
|container_format_description|
|
|
in: body
|
|
required: true
|
|
type: enum
|
|
container_format-in-request:
|
|
description: |
|
|
|container_format_description|
|
|
in: body
|
|
required: false
|
|
type: enum
|
|
created_at:
|
|
description: |
|
|
The date and time when the resource was created.
|
|
|
|
The date and time stamp format is `ISO 8601
|
|
<https://en.wikipedia.org/wiki/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: body
|
|
required: true
|
|
type: string
|
|
direct_url:
|
|
description: |
|
|
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.**
|
|
in: body
|
|
required: false
|
|
type: string
|
|
disk_format:
|
|
description: |
|
|
|disk_format_description|
|
|
in: body
|
|
required: true
|
|
type: enum
|
|
disk_format-in-request:
|
|
description: |
|
|
|disk_format_description|
|
|
in: body
|
|
required: false
|
|
type: enum
|
|
file:
|
|
description: |
|
|
The URL for the virtual machine image file.
|
|
in: body
|
|
required: true
|
|
type: string
|
|
first:
|
|
description: |
|
|
The URI for the first page of response.
|
|
in: body
|
|
required: true
|
|
type: string
|
|
id:
|
|
description: |
|
|
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.
|
|
in: body
|
|
required: true
|
|
type: string
|
|
id-in-request:
|
|
description: |
|
|
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.
|
|
in: body
|
|
required: false
|
|
type: string
|
|
image_id-in-body:
|
|
description: |
|
|
The UUID of the image.
|
|
in: body
|
|
required: true
|
|
type: string
|
|
images:
|
|
description: |
|
|
A list of *image* objects, as described by the :ref:`Images Schema
|
|
<images-schema>`.
|
|
in: body
|
|
required: true
|
|
type: array
|
|
import-methods:
|
|
description: |
|
|
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.
|
|
in: body
|
|
required: true
|
|
type: object
|
|
locations:
|
|
description: |
|
|
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.**
|
|
in: body
|
|
required: false
|
|
type: array
|
|
member_id:
|
|
description: |
|
|
The ID of the image member. An image member is usually a project (also
|
|
called the "tenant") with whom the image is shared.
|
|
in: body
|
|
required: true
|
|
type: string
|
|
member_status:
|
|
description: |
|
|
The status of this image member. Value is one of ``pending``,
|
|
``accepted``, ``rejected``.
|
|
in: body
|
|
required: true
|
|
type: string
|
|
members:
|
|
description: |
|
|
A list of *member* objects, as described by the :ref:`Image Members Schema
|
|
<image-members-schema>`. Each *member* object describes a member with whom
|
|
this image is being shared.
|
|
in: body
|
|
required: true
|
|
type: array
|
|
method-in-request:
|
|
description: |
|
|
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.
|
|
in: body
|
|
required: true
|
|
type: object
|
|
min_disk:
|
|
description: |
|
|
Amount of disk space in GB that is required to boot the image.
|
|
The value might be ``null`` (JSON null data type).
|
|
in: body
|
|
required: true
|
|
type: integer
|
|
min_disk-in-request:
|
|
description: |
|
|
Amount of disk space in GB that is required to boot the image.
|
|
in: body
|
|
required: false
|
|
type: integer
|
|
min_ram:
|
|
description: |
|
|
Amount of RAM in MB that is required to boot the image.
|
|
The value might be ``null`` (JSON null data type).
|
|
in: body
|
|
required: true
|
|
type: integer
|
|
min_ram-in-request:
|
|
description: |
|
|
Amount of RAM in MB that is required to boot the image.
|
|
in: body
|
|
required: false
|
|
type: integer
|
|
name:
|
|
description: |
|
|
The name of the image. Value might be ``null`` (JSON null data type).
|
|
in: body
|
|
required: true
|
|
type: string
|
|
name-in-request:
|
|
description: |
|
|
The name of the image.
|
|
in: body
|
|
required: false
|
|
type: string
|
|
next:
|
|
description: |
|
|
The URI for the next page of response. Will not be present on the last
|
|
page of the response.
|
|
in: body
|
|
required: true
|
|
type: string
|
|
os_hash_algo:
|
|
description: |
|
|
The algorithm used to compute a secure hash of the image data for this
|
|
image. The result of the computation is displayed as the value of the
|
|
``os_hash_value`` property. The value might be ``null`` (JSON null
|
|
data type). The algorithm used is chosen by the cloud operator; it
|
|
may not be configured by end users. *(Since Image API v2.7)*
|
|
in: body
|
|
required: true
|
|
type: string
|
|
os_hash_value:
|
|
description: |
|
|
The hexdigest of the secure hash of the image data computed using the
|
|
algorithm whose name is the value of the ``os_hash_algo`` property.
|
|
The value might be ``null`` (JSON null data type) if data has not
|
|
yet been associated with this image, or if the image was created using
|
|
a version of the Image Service API prior to version 2.7.
|
|
*(Since Image API v2.7)*
|
|
in: body
|
|
required: true
|
|
type: string
|
|
os_hidden:
|
|
description: |
|
|
This field controls whether an image is displayed in the default
|
|
image-list response. A "hidden" image is out of date somehow (for
|
|
example, it may not have the latest updates applied) and hence should
|
|
not be a user's first choice, but it's not deleted because it may be
|
|
needed for server rebuilds. By hiding it from the default image list,
|
|
it's easier for end users to find and use a more up-to-date version of
|
|
this image. *(Since Image API v2.7)*
|
|
in: body
|
|
required: true
|
|
type: boolean
|
|
owner:
|
|
description: |
|
|
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).
|
|
in: body
|
|
required: true
|
|
type: string
|
|
protected:
|
|
description: |
|
|
A boolean value that must be ``false`` or the image cannot be deleted.
|
|
in: body
|
|
required: true
|
|
type: boolean
|
|
protected-in-request:
|
|
description: |
|
|
Image protection for deletion. Valid value is ``true`` or ``false``.
|
|
Default is ``false``.
|
|
in: body
|
|
required: false
|
|
type: boolean
|
|
schema-image:
|
|
description: |
|
|
The URL for the schema describing a virtual machine image.
|
|
in: body
|
|
required: true
|
|
type: string
|
|
schema-images:
|
|
description: |
|
|
The URL for the schema describing a list of images.
|
|
in: body
|
|
required: true
|
|
type: string
|
|
schema-member:
|
|
description: |
|
|
The URL for the schema describing an image member.
|
|
in: body
|
|
required: true
|
|
type: string
|
|
schema-members:
|
|
description: |
|
|
The URL for the schema describing an image member list.
|
|
in: body
|
|
required: true
|
|
type: string
|
|
self:
|
|
description: |
|
|
The URL for the virtual machine image.
|
|
in: body
|
|
required: true
|
|
type: string
|
|
size:
|
|
description: |
|
|
The size of the image data, in bytes. The value
|
|
might be ``null`` (JSON null data type).
|
|
in: body
|
|
required: true
|
|
type: integer
|
|
status:
|
|
description: |
|
|
The image status.
|
|
in: body
|
|
required: true
|
|
type: string
|
|
tags:
|
|
description: |
|
|
List of tags for this image, possibly an empty list.
|
|
in: body
|
|
required: true
|
|
type: array
|
|
tags-in-request:
|
|
description: |
|
|
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.
|
|
in: body
|
|
required: false
|
|
type: array
|
|
updated_at:
|
|
description: |
|
|
The date and time when the resource was updated.
|
|
|
|
The date and time stamp format is `ISO 8601
|
|
<https://en.wikipedia.org/wiki/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``.
|
|
in: body
|
|
required: true
|
|
type: string
|
|
url:
|
|
description: |
|
|
The URL to access the image file kept in external
|
|
store.
|
|
in: body
|
|
required: true
|
|
type: string
|
|
value:
|
|
description: |
|
|
Value of image property used in add or replace
|
|
operations expressed in JSON notation. For example, you must
|
|
enclose strings in quotation marks, and you do not enclose numeric
|
|
values in quotation marks.
|
|
in: body
|
|
required: true
|
|
type: string
|
|
virtual_size:
|
|
description: |
|
|
The virtual size of the image. The value might
|
|
be ``null`` (JSON null data type).
|
|
in: body
|
|
required: true
|
|
type: integer
|
|
visibility:
|
|
description: |
|
|
Image visibility, that is, the access permission for the image.
|
|
in: body
|
|
required: true
|
|
type: string
|
|
visibility-in-request:
|
|
description: |
|
|
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``.*
|
|
in: body
|
|
required: false
|
|
type: string
|