From 32f8724f6e84774f7b9028dee3f05960d61bc7f9 Mon Sep 17 00:00:00 2001 From: Brian Rosmaita Date: Thu, 8 Feb 2018 11:07:54 -0500 Subject: [PATCH] Update api-ref for v.2.6 2.6 was experimental in Pike but is current in Queens. Change-Id: I4f8c4ff72808aac1fc52c65673d28530aa9939f2 Closes-bug: #1748218 --- api-ref/source/v2/images-import.inc | 52 +++++++------------ api-ref/source/v2/images-parameters.yaml | 6 +-- api-ref/source/versions/index.rst | 5 ++ .../samples/image-versions-response.json | 4 +- 4 files changed, 28 insertions(+), 39 deletions(-) diff --git a/api-ref/source/v2/images-import.inc b/api-ref/source/v2/images-import.inc index ce33ed28e9..66052f440d 100644 --- a/api-ref/source/v2/images-import.inc +++ b/api-ref/source/v2/images-import.inc @@ -5,27 +5,10 @@ Interoperable image import ************************** -An interoperable image import process is introduced in the Pike release -as part of the EXPERIMENTAL Image API v2.6. +An interoperable image import process is introduced in the 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 +Use the :ref:`API versions call ` to determine what API verisons +are available in your cloud. General information ~~~~~~~~~~~~~~~~~~~ @@ -35,9 +18,14 @@ 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). +Two import methods are defined, ``glance-direct`` and ``web-download``. + .. note:: - In the EXPERIMENTAL Image API v2.6, the only import method available - is ``glance-direct``. + + Use the :ref:`Import Method Discovery ` call + to determine what import methods are available in the cloud to which + you wish to import an image. + The ``glance-direct`` workflow has three parts: @@ -59,10 +47,7 @@ The ``glance-direct`` workflow has three parts: 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. - +.. TODO(rosmaita): describe the web-download workflow .. _image-stage-call: @@ -74,7 +59,7 @@ Stage binary image data 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)* +*(Since Image API v2.6)* Set the ``Content-Type`` request header to ``application/octet-stream``. @@ -84,7 +69,7 @@ Example call: curl -i -X PUT -H "X-Auth-Token: $token" \ -H "Content-Type: application/octet-stream" \ - -d @/home/glance/experimental.qcow2 \ + -d @/home/glance/my.to-import.qcow2 \ $image_url/v2/images/{image_id}/stage **Preconditions** @@ -142,14 +127,15 @@ Import an image Signals the Image Service to complete the image import workflow by processing the previously staged image data. -*(EXPERIMENTAL in Image API v2.6)* +*(Since 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.* +for this image request. + +.. TODO(rosmaita): rewrite to include web-download info Before you can complete the ``glance-direct`` image import workflow, you must meet the following preconditions: @@ -210,10 +196,10 @@ 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)* +*(Since Image API v2.6)* .. note:: - In the EXPERIMENTAL Image API v2.6, this discovery call contains + In the Image API v2.6, this discovery call contains **only** the ``import-methods`` field. Normal response codes: 200 diff --git a/api-ref/source/v2/images-parameters.yaml b/api-ref/source/v2/images-parameters.yaml index a07a03da5e..bb5420a551 100644 --- a/api-ref/source/v2/images-parameters.yaml +++ b/api-ref/source/v2/images-parameters.yaml @@ -52,8 +52,7 @@ Content-Type-patch: 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* + only if image import is enabled in your cloud. *Since Image API v2.6* in: header required: false type: string @@ -436,8 +435,7 @@ method-in-request: 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.* + method. in: body required: true type: object diff --git a/api-ref/source/versions/index.rst b/api-ref/source/versions/index.rst index 2468a1a74a..205830ebb7 100644 --- a/api-ref/source/versions/index.rst +++ b/api-ref/source/versions/index.rst @@ -24,6 +24,11 @@ Image Service Versions Version History *************** +**Queens changes** + +- version 2.6 is CURRENT +- version 2.5 is SUPPORTED + **Pike changes** - version 2.6 is EXPERIMENTAL diff --git a/api-ref/source/versions/samples/image-versions-response.json b/api-ref/source/versions/samples/image-versions-response.json index 8c9fdf886d..4f7d255592 100644 --- a/api-ref/source/versions/samples/image-versions-response.json +++ b/api-ref/source/versions/samples/image-versions-response.json @@ -8,7 +8,7 @@ "rel": "self" } ], - "status": "EXPERIMENTAL" + "status": "CURRENT" }, { "id": "v2.5", @@ -18,7 +18,7 @@ "rel": "self" } ], - "status": "CURRENT" + "status": "SUPPORTED" }, { "id": "v2.4",