api-ref: add interoperable image import docs

Adds documentation of the interoperable image import process
introduced in Pike in the EXPERIMENTAL Image API v2.6.

Change-Id: Ifbedc2e5e566db084bc7028ed4239485f0d68b18
This commit is contained in:
Brian Rosmaita 2017-08-15 23:54:11 -04:00
parent d009e188a2
commit 8005ee994c
7 changed files with 289 additions and 0 deletions

View File

@ -129,6 +129,7 @@ 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 an image
~~~~~~~~~~~~~~~
@ -183,6 +184,7 @@ Response Parameters
.. rest_parameters:: images-parameters.yaml
- Location: Location
- OpenStack-image-import-methods: import-header
- checksum: checksum
- container_format: container_format
- created_at: created_at

View File

@ -0,0 +1,244 @@
.. -*- rst -*-
.. _image-import-process:
Interoperable image import
**************************
An interoperable image import process is introduced in the Pike release
as part of the EXPERIMENTAL Image API v2.6.
*This EXPERIMENTAL API is optional and may not be enabled in your
cloud. Consult your cloud operator's documentation for details.*
In version 2.5 of the API, these calls return a 404 (Not Found).
Use the :ref:`API versions call <versions-call>` to determine
what API verisons are available in your cloud.
.. note::
This EXPERIMENTAL API is subject to change. It is a partial implementation
of what's described in the Glance design document `Image Import Refactor`_.
We expect any changes to be expansive and to be in accord with what's
described in that document, but we are releasing version 2.6 in
EXPERIMENTAL status in the Pike release so that we can reserve the right to
make backward-incompatible changes in light of feedback from users and
operators. Our intent is that these calls will be finalized before the
Queens release and the EXPERIMENTAL status will be lifted at that time.
.. _`Image Import Refactor`: https://specs.openstack.org/openstack/glance-specs/specs/mitaka/approved/image-import/image-import-refactor.html
General information
~~~~~~~~~~~~~~~~~~~
The exact workflow you use for interoperable image import depends upon
the import methods available in the cloud in which you want to import
an image. Each of these methods is well defined (which is what makes
this process interoperable among different OpenStack clouds).
.. note::
In the EXPERIMENTAL Image API v2.6, the only import method available
is ``glance-direct``.
The ``glance-direct`` workflow has three parts:
1. Create an image record using the :ref:`Image Create <image-create>`
API call. You must do this first so that you have an image id to
work with for the other calls.
In a cloud in which interoperable image import is enabled, the
:ref:`Image Create <image-create>` response will include a
``OpenStack-image-import-methods`` header listing the types of
import methods available in that cloud. Alternatively, these
methods may be determined independently of creating an image by making
the :ref:`Import Method Discovery <import-discovery-call>` call.
2. Upload the image data to a staging area using the :ref:`Image Stage
<image-stage-call>` API call. Note that this image data is not
accessible until after the third step has successfully completed.
3. Issue the :ref:`Image Import <image-import-call>` call to complete
the import process.
Additionally, there is an :ref:`Import Method Discovery
<import-discovery-call>` call that allows you to determine what import
methods are available in the cloud to which you wish to import an image.
.. _image-stage-call:
Stage binary image data
~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: PUT /v2/images/{image_id}/stage
Places the binary image data in a staging area. It is not stored in
the storage backend and is not accessible for download until after
the :ref:`Image Import <image-import-call>` call is made.
*(EXPERIMENTAL in Image API v2.6)*
Set the ``Content-Type`` request header to ``application/octet-stream``.
Example call:
::
curl -i -X PUT -H "X-Auth-Token: $token" \
-H "Content-Type: application/octet-stream" \
-d @/home/glance/experimental.qcow2 \
$image_url/v2/images/{image_id}/stage
**Preconditions**
Before you can stage binary image data, you must meet the following
preconditions:
- The image record must exist.
- 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
``uploading`` through API calls.
**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, 405, 409, 410, 413, 415, 503
If the image import process is not enabled in your cloud, this request
will result in a 404 response code with an appropriate message.
Request
-------
.. rest_parameters:: images-parameters.yaml
- Content-type: Content-Type-data
- image_id: image_id-in-path
.. _image-import-call:
Import an image
~~~~~~~~~~~~~~~
.. rest_method:: POST /v2/images/{image_id}/import
Signals the Image Service to complete the image import workflow
by processing the previously staged image data.
*(EXPERIMENTAL in Image API v2.6)*
Example call: ``curl -i -X POST -H "X-Auth-Token: $token"
$image_url/v2/images/{image_id}/import``
The JSON request body specifies what import method you wish to use
for this image request. *Note: In the EXPERIMENTAL Image API v2.6,
the only method available is glance-direct.*
Before you can complete the ``glance-direct`` image import workflow, you
must meet the following preconditions:
- The image record must exist.
- You must set the disk and container formats in the image.
- The image status must be ``uploading``. (This indicates that the image
data has been uploaded to the stage.)
- 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
``importing`` through API calls. (Be aware, however, that if the import
process completes before you make the API call, the image may already
show as ``active``.)
Normal response codes: 202
Error response codes: 400, 401, 403, 404, 405, 409, 410, 413, 415, 503
If the image import process is not enabled in your cloud, this request
will result in a 404 response code with an appropriate message.
Request
-------
.. rest_parameters:: images-parameters.yaml
- Content-type: Content-Type-data
- image_id: image_id-in-path
- method: method-in-request
Request Example
----------------
.. literalinclude:: samples/image-import-request.json
:language: json
.. _import-discovery-call:
Import methods and values discovery
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. rest_method:: GET /v2/info/import
Returns information concerning the constraints around image import in
the cloud in which the call is made, for example, supported container
formats, supported disk formats, maximum image size, etc. This call
contains a ``import-methods`` field consisting of an array of string
identifiers indicating what import methods are supported in the cloud
in which the call is made.
*(EXPERIMENTAL in Image API v2.6)*
.. note::
In the EXPERIMENTAL Image API v2.6, this discovery call contains
**only** the ``import-methods`` field.
Normal response codes: 200
Error response codes: 400, 401, 403
Request
-------
There are no request parameters.
This call does not allow a request body.
Response Parameters
-------------------
.. rest_parameters:: images-parameters.yaml
- import-methods: import-methods
Response Example
----------------
.. literalinclude:: samples/image-info-import-response.json
:language: json

View File

@ -49,6 +49,14 @@ Content-Type-patch:
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. *Introduced
in the EXPERIMENTAL Image API v2.6*
in: header
required: false
type: string
Location:
description: |
The URL to access the image file from the
@ -376,6 +384,14 @@ images:
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
@ -411,6 +427,16 @@ members:
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. *(Note: In the EXPERIMENTAL Image API v2.6, the only supported
import method is glance-direct.*
in: body
required: true
type: object
min_disk:
description: |
Amount of disk space in GB that is required to boot the image.

View File

@ -28,5 +28,6 @@ Image Service API v2 (CURRENT)
.. include:: images-tags.inc
.. include:: images-schemas.inc
.. include:: images-data.inc
.. include:: images-import.inc
.. include:: tasks.inc
.. include:: tasks-schemas.inc

View File

@ -0,0 +1,5 @@
{
"method": {
"name": "glance-direct"
}
}

View File

@ -0,0 +1,9 @@
{
"import-methods": {
"description": "Import methods available.",
"type": "array",
"value": [
"glance-direct"
]
}
}

View File

@ -1,5 +1,7 @@
.. -*- rst -*-
.. _versions-call:
API versions
************