.. -*- rst -*- .. _image-import-process: Interoperable image import ************************** An interoperable image import process is introduced in the Image API v2.6. Use the :ref:`API versions call ` to determine what API versions are available in your cloud. 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). Four import methods are defined: * ``glance-direct`` * ``web-download`` * ``copy-image`` * ``glance-download`` .. note:: 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 first step in each interoperable image import method is the same: you must create an image record. This will give you an image id to work with. This image id is how the OpenStack Image service will understand that the other calls you make are referring to this particular image. Thus, the first step is: 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. In a cloud in which multiple storage backends are available, the :ref:`Image Create ` response will include a ``OpenStack-image-store-ids`` header listing the stores available in that cloud. Alternatively, these stores may be determined independently of creating an image by making the :ref:`Stores Discovery ` call. The glance-direct import method ------------------------------- The ``glance-direct`` workflow has **three** parts: 1. Create an image record as described above. 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. You will specify that you are using the ``glance-direct`` import method in the body of the import call. The web-download import method ------------------------------ The ``web-download`` workflow has **two** parts: 1. Create an image record as described above. 2. Issue the :ref:`Image Import ` call to complete the import process. You will specify that you are using the ``web-download`` import method in the body of the import call. The copy-image import method ---------------------------- The ``copy-image`` workflow has **two** parts: 1. Identify the existing image whose data you want to copy to other stores. 2. Issue the :ref:`Image Import ` call to complete the import process. You will specify that you are using the ``copy-image`` import method in the body of the import call. The glance-download import method --------------------------------- The ``glance-download`` workflow has **two** parts: 1. Create an image record as described above. 2. Issue the :ref:`Image Import ` call to complete the import process. You will specify that you are using the ``glance-download`` import method in the body of the import call. .. _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. *(Since 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/my.to-import.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 data that has been made available to the OpenStack image service. *(Since Image API v2.6)* In the ``glance-direct`` workflow, the data has been made available to the Image service via the :ref:`Stage binary image data ` API call. In the ``web-download`` workflow, the data is made available to the Image service by being posted to an accessible location with a URL that you know. In the ``copy-image`` workflow, the data is made available to the Image service by copying existing image data to the staging area. In the ``glance-download`` workflow, the data is made available to the Image service by fetching an image accessible from another glance service specified by a region name and an image id that you know. Beginning with API version 2.8, an optional ``stores`` parameter may be added to the body request. When present, it contains the list of backing store identifiers to import the image binary data to. If at least one store identifier specified is not recognized, a 409 (Conflict) response is returned. When the parameter is not present, the image data is placed into the default backing store. * Store identifiers are site-specific. Use the :ref:`Store Discovery ` call to determine what stores are available in a particular cloud. * The default store may be determined from the :ref:`Store Discovery ` response. * A default store is always defined, so if you do not have a need to use particular stores, simply omit this parameter and the default store will be used. * For API versions before version 2.8, this parameter is silently ignored. For backwards compatibility, if the ``stores`` parameter is not specified, the header 'X-Image-Meta-Store' is evaluated. To import the data into the entire set of stores you may consume from this particular deployment of Glance without specifying each one of them, you can use the optional boolean body parameter ``all_stores``. Note that this can't be used simultaneously with the ``stores`` parameter. To set the behavior of the import workflow in case of error, you can use the optional boolean body parameter ``all_stores_must_succeed``. When set to True (default), if an error occurs during the upload in at least one store, the worfklow fails, the data is deleted from stores where copying is done and the state of the image remains unchanged. When set to False, the workflow will fail only if the upload fails on all stores specified. In case of a partial success, the locations added to the image will be the stores where the data has been correctly uploaded. The JSON request body specifies what import method you wish to use for this image request. **Preconditions** Before you can complete the interoperable 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 record. (This can be done at the time of image creation, or you can make the :ref:`Image Update ` API call. - 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. **Additional Preconditions** If you are using the ``glance-direct`` import method: - The image status must be ``uploading``. (This indicates that the image data has been uploaded to the stage.) - The body of your request must indicate that you are using the ``glance-direct`` import method. If you are using the ``web-download`` import method: - The image status must be ``queued``. (This indicates that no image data has yet been associated with the image.) - The body of your request must indicate that you are using the ``web-download`` import method, and it must contain the URL at which the data is to be found. .. note:: The acceptable set of URLs for the ``web-download`` import method may be restricted in a particular cloud. Consult the cloud's local documentation for details. If you are using the ``copy-image`` import method: - The image status must be ``active``. (This indicates that image data is associated with the image.) - The body of your request must indicate that you are using the ``copy-image`` import method, and it must contain either the list of stores where you want to copy your image or all_stores which will copy the image in all available stores set in glance_api.conf using ``enabled_backends`` configuration option. - If body of your request contains ``all_stores_must_succeed`` (default to True) and an error occurs during the copying in at least one store, the request will be rejected, the data will be deleted from the new stores where copying is done (not staging), and the state of the image remains the same. - If body of your request contains ``all_stores_must_succeed`` set to False and an error occurs, then the request will fail (data deleted from stores, ...) only if the copying fails on all stores specified by the user. In case of a partial success, the locations added to the image will be the stores where the data has been correctly uploaded. - By default, you may perform the copy-image operation only on images that you own. This action is governed by policy, so some users may be granted permission to copy unowned images. Consult your cloud's local documentation for details. If you are using the ``glance-download`` import method: - The image status must be ``queued``. (This indicates that no image data has yet been associated with the image.) - The body of your request must indicate that you are using the ``glance-download`` import method, and it must contain the region name of the remote openstack region and the image id to fetch. You might optionaly set the service interface name (public by default) to request. **Synchronous Postconditions** - With correct permissions, you can see the image status as ``importing`` (only for glance-direct, web-download and glance-download import methods) 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-json - X-Image-Meta-Store: store-header - image_id: image_id-in-path - method: method-in-request - all_stores: all-stores-in-request - all_stores_must_succeed: all-stores-succeed-in-request - stores: stores-in-request Request Example - glance-direct import method --------------------------------------------- .. literalinclude:: samples/image-import-g-d-request.json :language: json Request Example - web-download import method -------------------------------------------- .. literalinclude:: samples/image-import-w-d-request.json :language: json Request Example - copy-image import method -------------------------------------------- .. literalinclude:: samples/image-import-c-i-request.json :language: json Request Example - glance-download import method ----------------------------------------------- .. literalinclude:: samples/image-import-gd-request.json :language: json