166 lines
4.6 KiB
ReStructuredText
166 lines
4.6 KiB
ReStructuredText
.. -*- rst -*-
|
|
|
|
.. _image-data:
|
|
|
|
Image data
|
|
**********
|
|
|
|
Uploads and downloads raw image data.
|
|
|
|
*These operations may be restricted to administrators. Consult your cloud
|
|
operator's documentation for details.*
|
|
|
|
|
|
Upload binary image data
|
|
~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. rest_method:: PUT /v2/images/{image_id}/file
|
|
|
|
Uploads binary image data.
|
|
*(Since Image API v2.0)*
|
|
|
|
Set the ``Content-Type`` request header to ``application/octet-stream``.
|
|
|
|
A multiple store backend support is introduced in the Rocky release
|
|
as a part of the EXPERIMENTAL Image API v2.8.
|
|
|
|
Beginning with API version 2.8, an optional ``X-Image-Meta-Store``
|
|
header may be added to the request. When present, the image data will be
|
|
placed into the backing store whose identifier is the value of this
|
|
header. If the store identifier specified is not recognized, a 400 (Bad
|
|
Request) response is returned. When the header is not present, the image
|
|
data is placed into the default backing store.
|
|
|
|
* Store identifiers are site-specific. Use the :ref:`Store
|
|
Discovery <store-discovery-call>` call to determine what
|
|
stores are available in a particular cloud.
|
|
* The default store may be determined from the :ref:`Store
|
|
Discovery <store-discovery-call>` response.
|
|
* A default store is always defined, so if you do not have a need
|
|
to use a particular store, simply omit this header and the default store
|
|
will be used.
|
|
* For API versions before version 2.8, this header is silently
|
|
ignored.
|
|
|
|
Example call:
|
|
|
|
::
|
|
|
|
curl -i -X PUT -H "X-Auth-Token: $token" \
|
|
-H "X-Image-Meta-Store: {store_identifier}" \
|
|
-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
|
|
-------
|
|
|
|
.. rest_parameters:: images-parameters.yaml
|
|
|
|
- Content-type: Content-Type-data
|
|
- X-Image-Meta-Store: store-header
|
|
- image_id: image_id-in-path
|
|
|
|
|
|
Download binary image data
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
.. rest_method:: GET /v2/images/{image_id}/file
|
|
|
|
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
|
|
-------
|
|
|
|
.. rest_parameters:: images-parameters.yaml
|
|
|
|
- image_id: image_id-in-path
|
|
- Range: Range
|
|
|
|
Response
|
|
--------
|
|
.. rest_parameters:: images-parameters.yaml
|
|
|
|
- Content-Type: Content-Type-data-response
|
|
- Content-Md5: Content-Md5
|
|
- Content-Length: Content-Length
|
|
- Content-Range: Content-Range
|