92492cf504
The import image api now supports a list of stores to import data into. This list can be specified through a new "stores" field that has been added to the request body. During import stage, Glance iterates overs this list and send the data to each store one by one. If an invalid backend is requested by the user, an exception is raised. If an errors occurs during verify, already pushed data is removed and image state is unchanged. Change-Id: Id3ac19488c0a693d7042be4a3c83f3b9f12313d0 Implements: blueprint import-multi-stores
715 lines
20 KiB
YAML
715 lines
20 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
|
|
all-stores-in-request:
|
|
description: |
|
|
When set to True the data will be imported to the set of stores you may
|
|
consume from this particular deployment of Glance (ie: the same set of
|
|
stores returned to a call to /v2/info/stores on the glance-api the request
|
|
hits).
|
|
This can't be used simultaneously with the ``stores`` parameter.
|
|
in: body
|
|
required: false
|
|
type: boolean
|
|
all-stores-succeed-in-request:
|
|
description: |
|
|
A boolean parameter indicating the behavior of the import workflow when an
|
|
error occurs.
|
|
When set to True, if an error occurs during the upload in at least one
|
|
store, the worfklow fails, the data is deleted from stores where copying
|
|
is done (not staging), and the state of the image is unchanged.
|
|
When set to False, the workflow will fail (data deleted from stores, ...)
|
|
only if the import fails on all stores specified by the user. In case of a
|
|
partial success, the locations added to the image will be the stores where
|
|
the data has been correctly uploaded.
|
|
in: body
|
|
required: false
|
|
type: boolean
|
|
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
|
|
stores-in-request:
|
|
description: |
|
|
If present contains the list of store id to import the image binary data
|
|
to.
|
|
in: body
|
|
required: false
|
|
type: array
|
|
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
|