345 lines
7.7 KiB
ReStructuredText
345 lines
7.7 KiB
ReStructuredText
.. -*- rst -*-
|
|
|
|
Images
|
|
******
|
|
|
|
|
|
Create image
|
|
~~~~~~~~~~~~
|
|
|
|
.. rest_method:: POST /v1/images
|
|
|
|
Creates a metadata record of a virtual machine (VM) image and optionally
|
|
stores the image data.
|
|
|
|
Image metadata fields are passed as HTTP headers prefixed with one of
|
|
the strings ``x-image-meta-`` or ``x-image-meta-property-``. See the
|
|
API documentation for details.
|
|
|
|
If there is no request body, an image record will be created in status
|
|
``queued``. This is called *reserving an image*. The image data can be
|
|
uploaded later using the `Update image`_ call.
|
|
|
|
If image data will be uploaded as part of this request, then the following
|
|
image metadata must be included among the request headers:
|
|
|
|
- ``name``
|
|
- ``disk_format``
|
|
- ``container_format``
|
|
|
|
Additionally, if image data is uploaded as part of this request, the API
|
|
will return a 400 under the following circumstances:
|
|
|
|
- The ``x-image-meta-size`` header is present and the length in bytes of
|
|
the request body does not match the value of this header.
|
|
- The ``x-image-meta-checksum`` header is present and MD5 checksum generated
|
|
by the backend store while storing the data does not match the value of
|
|
this header.
|
|
|
|
Normal response codes: 201
|
|
|
|
Error response codes: 400, 409
|
|
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- image data: createImage
|
|
- x-image-meta-name: x-image-meta-name
|
|
- x-image-meta-container_format: x-image-meta-container_format
|
|
- x-image-meta-disk_format: x-image-meta-disk_format
|
|
|
|
|
|
Response Parameters
|
|
-------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- location: location
|
|
- image: image-object
|
|
|
|
|
|
Response Example (create with data)
|
|
-----------------------------------
|
|
|
|
::
|
|
|
|
HTTP/1.1 100 Continue
|
|
|
|
HTTP/1.1 201 Created
|
|
Content-Type: application/json
|
|
Content-Length: 491
|
|
Location: http://glance.openstack.example.org/v1/images/de2f2211-3ac7-4260-9142-41db0ecfb425
|
|
Etag: 7b1b10607acc1319506185e7227ca30d
|
|
X-Openstack-Request-Id: req-70adeab4-740c-4db3-a002-fd1559ecf40f
|
|
Date: Tue, 10 May 2016 21:41:41 GMT
|
|
|
|
.. literalinclude:: samples/images-create-with-data-response.json
|
|
:language: json
|
|
|
|
|
|
Response Example (reserve an image)
|
|
-----------------------------------
|
|
|
|
This is an extreme example of reserving an image. It was created by a POST
|
|
with no headers specified and no data passed. Here's the response:
|
|
|
|
::
|
|
|
|
HTTP/1.1 201 Created
|
|
Content-Type: application/json
|
|
Content-Length: 447
|
|
Location: http://glance.openstack.example.org/v1/images/6b3ecfca-d445-4946-a8d1-c4938352b251
|
|
X-Openstack-Request-Id: req-db1ff3c7-3d4f-451f-9ef1-c414343f809d
|
|
Date: Tue, 10 May 2016 21:35:14 GMT
|
|
|
|
.. literalinclude:: samples/images-create-reserve-response.json
|
|
:language: json
|
|
|
|
|
|
|
|
List images
|
|
~~~~~~~~~~~
|
|
|
|
.. rest_method:: GET /v1/images
|
|
|
|
Lists all VM images available to the user making the call. This list will
|
|
include all public images, any images owned by the requestor, and any images
|
|
shared with the requestor.
|
|
|
|
Various query filters can be applied to the URL to restrict the content of
|
|
the response.
|
|
|
|
Normal response codes: 200
|
|
|
|
Error response codes: 400, 403
|
|
|
|
.. note:: need to add info about sorting and pagination
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- name: name-in-query
|
|
- container_format: container_format-in-query
|
|
- disk_format: disk_format-in-query
|
|
- status: status-in-query
|
|
- size_min: size_min
|
|
- size_max: size_max
|
|
- changes-since: changes-since
|
|
|
|
|
|
Response Parameters
|
|
-------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- images: images-list
|
|
|
|
|
|
Response Example
|
|
----------------
|
|
|
|
.. literalinclude:: samples/images-list-response.json
|
|
:language: json
|
|
|
|
|
|
List images with details
|
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. rest_method:: GET /v1/images/detail
|
|
|
|
Lists all available images with details.
|
|
|
|
Various query filters can be applied to the URL to restrict the content of
|
|
the response.
|
|
|
|
Normal response codes: 200
|
|
|
|
Error response codes: 400, 403
|
|
|
|
.. note:: need to add info about sorting and pagination
|
|
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- name: name-in-query
|
|
- container_format: container_format-in-query
|
|
- disk_format: disk_format-in-query
|
|
- status: status-in-query
|
|
- size_min: size_min
|
|
- size_max: size_max
|
|
- changes-since: changes-since
|
|
|
|
|
|
Response Parameters
|
|
-------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- images: images-detail-list
|
|
- previous: previous
|
|
- next: next
|
|
|
|
|
|
Response Example
|
|
----------------
|
|
|
|
.. literalinclude:: samples/images-list-details-response.json
|
|
:language: json
|
|
|
|
|
|
Update image
|
|
~~~~~~~~~~~~
|
|
|
|
.. rest_method:: PUT /v1/images/{image_id}
|
|
|
|
Updates the metadata for an image or uploads an image file.
|
|
|
|
Image metadata is updated by passing HTTP headers prefixed with one of the
|
|
strings ``x-image-meta-`` or ``x-image-meta-property-``. See the API
|
|
documentation for details.
|
|
|
|
If the image is in ``queued`` status, image data may be added by
|
|
including it in the request body. Otherwise, attempting to add data
|
|
will result in a 409 Conflict response.
|
|
|
|
If the request contains a body, the API will return a 400 under the following
|
|
circumstances:
|
|
|
|
- The ``x-image-meta-size`` header is present and the length in bytes of
|
|
the request body does not match the value of this header.
|
|
- The ``x-image-meta-checksum`` header is present and MD5 checksum generated
|
|
by the backend store while storing the data does not match the value of
|
|
this header.
|
|
|
|
Normal response codes: 200
|
|
|
|
Error response codes: 400, 404, 409
|
|
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- image_id: image_id-in-path
|
|
|
|
|
|
Response Parameters
|
|
-------------------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- image: image-object
|
|
|
|
|
|
|
|
Response Example
|
|
----------------
|
|
|
|
.. literalinclude:: samples/image-update-response.json
|
|
:language: json
|
|
|
|
|
|
Show image details and image data
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. rest_method:: GET /v1/images/{image_id}
|
|
|
|
Returns the image metadata as headers; the image data is returned in the
|
|
body of the response.
|
|
|
|
Standard image properties are returned in headers prefixed by
|
|
``x-image-meta-`` (for example, ``x-image-meta-name``). Custom image
|
|
properties are returned in headers prefixed by the string
|
|
``x-image-meta-property-`` (for example, ``x-image-meta-property-foo``).
|
|
|
|
Normal response codes: 200
|
|
|
|
Error response codes: 404, 403
|
|
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- image_id: image_id-in-path
|
|
|
|
|
|
|
|
Show image metadata
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. rest_method:: HEAD /v1/images/{image_id}
|
|
|
|
Returns the image metadata information as response headers.
|
|
|
|
The Image system does not return a response body for the HEAD
|
|
operation.
|
|
|
|
If the request succeeds, the operation returns the ``200`` response
|
|
code.
|
|
|
|
Normal response codes: 200
|
|
|
|
Error response codes: 404, 409
|
|
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- image_id: image_id-in-path
|
|
|
|
|
|
Response Example
|
|
----------------
|
|
|
|
::
|
|
|
|
X-Image-Meta-Checksum: 8a40c862b5735975d82605c1dd395796
|
|
X-Image-Meta-Container_format: aki
|
|
X-Image-Meta-Created_at: 2016-01-06T03:22:20.000000
|
|
X-Image-Meta-Deleted: false
|
|
X-Image-Meta-Disk_format: aki
|
|
X-Image-Meta-Id: 03bc0a8b-659c-4de9-b6bd-13c6e86e6455
|
|
X-Image-Meta-Is_public: true
|
|
X-Image-Meta-Min_disk: 0
|
|
X-Image-Meta-Min_ram: 0
|
|
X-Image-Meta-Name: cirros-0.3.4-x86_64-uec-kernel
|
|
X-Image-Meta-Owner: 13cc6052265b41529e2fd0fc461fa8ef
|
|
X-Image-Meta-Protected: false
|
|
X-Image-Meta-Size: 4979632
|
|
X-Image-Meta-Status: deactivated
|
|
X-Image-Meta-Updated_at: 2016-02-25T03:02:05.000000
|
|
X-Openstack-Request-Id: req-d5208320-28ed-4c22-b628-12dc6456d983
|
|
|
|
|
|
Delete image
|
|
~~~~~~~~~~~~
|
|
|
|
.. rest_method:: DELETE /v1/images/{image_id}
|
|
|
|
Deletes an image.
|
|
|
|
Normal response codes: 204
|
|
|
|
Error response codes: 404, 403
|
|
|
|
|
|
Request
|
|
-------
|
|
|
|
.. rest_parameters:: parameters.yaml
|
|
|
|
- image_id: image_id-in-path
|