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

api-ref/source/v2/images-images-v2.inc

@@ -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

api-ref/source/v2/images-import.inc

@@ -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

api-ref/source/v2/images-parameters.yaml

@@ -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.

api-ref/source/v2/index.rst

@@ -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

api-ref/source/v2/samples/image-import-request.json

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

api-ref/source/v2/samples/image-info-import-response.json

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

api-ref/source/versions/versions.inc

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