From 8005ee994cbbfb25575d13cd2d243e510c5e33d1 Mon Sep 17 00:00:00 2001 From: Brian Rosmaita Date: Tue, 15 Aug 2017 23:54:11 -0400 Subject: [PATCH] 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 | 2 + api-ref/source/v2/images-import.inc | 244 ++++++++++++++++++ api-ref/source/v2/images-parameters.yaml | 26 ++ api-ref/source/v2/index.rst | 1 + .../v2/samples/image-import-request.json | 5 + .../samples/image-info-import-response.json | 9 + api-ref/source/versions/versions.inc | 2 + 7 files changed, 289 insertions(+) create mode 100644 api-ref/source/v2/images-import.inc create mode 100644 api-ref/source/v2/samples/image-import-request.json create mode 100644 api-ref/source/v2/samples/image-info-import-response.json diff --git a/api-ref/source/v2/images-images-v2.inc b/api-ref/source/v2/images-images-v2.inc index b14e35c4d0..c5b52384dd 100644 --- a/api-ref/source/v2/images-images-v2.inc +++ b/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 diff --git a/api-ref/source/v2/images-import.inc b/api-ref/source/v2/images-import.inc new file mode 100644 index 0000000000..ce33ed28e9 --- /dev/null +++ b/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 ` 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 ` + 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 ` 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 ` call. + +2. Upload the image data to a staging area using the :ref:`Image Stage + ` API call. Note that this image data is not + accessible until after the third step has successfully completed. + +3. Issue the :ref:`Image Import ` call to complete + the import process. + +Additionally, there is an :ref:`Import Method Discovery +` 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 ` 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 diff --git a/api-ref/source/v2/images-parameters.yaml b/api-ref/source/v2/images-parameters.yaml index 9054fd6e99..47ca76a4da 100644 --- a/api-ref/source/v2/images-parameters.yaml +++ b/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. diff --git a/api-ref/source/v2/index.rst b/api-ref/source/v2/index.rst index 40c718ef80..e3a0158359 100644 --- a/api-ref/source/v2/index.rst +++ b/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 diff --git a/api-ref/source/v2/samples/image-import-request.json b/api-ref/source/v2/samples/image-import-request.json new file mode 100644 index 0000000000..64589bf46a --- /dev/null +++ b/api-ref/source/v2/samples/image-import-request.json @@ -0,0 +1,5 @@ +{ + "method": { + "name": "glance-direct" + } +} diff --git a/api-ref/source/v2/samples/image-info-import-response.json b/api-ref/source/v2/samples/image-info-import-response.json new file mode 100644 index 0000000000..8f73531988 --- /dev/null +++ b/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" + ] + } +} diff --git a/api-ref/source/versions/versions.inc b/api-ref/source/versions/versions.inc index 6e77818cfc..92c8357627 100644 --- a/api-ref/source/versions/versions.inc +++ b/api-ref/source/versions/versions.inc @@ -1,5 +1,7 @@ .. -*- rst -*- +.. _versions-call: + API versions ************