From f09c338035a34889c07ef6817b0befb071e5285f Mon Sep 17 00:00:00 2001 From: Abhishek Kekane Date: Mon, 22 Aug 2022 07:54:28 +0000 Subject: [PATCH] Add documentation for glance-download plugin This patch adds documentation and API reference support for glance download plugin. Related blueprint glance-download-import Co-Authored-By: Victor Coutellier Change-Id: Ie36232f3474d398a913025c8d408f08f879874d8 --- api-ref/source/v2/images-import.inc | 39 +++++++++++++-- .../v2/samples/image-import-gd-request.json | 8 ++++ .../admin/interoperable-image-import.rst | 47 +++++++++++++++++-- 3 files changed, 88 insertions(+), 6 deletions(-) create mode 100644 api-ref/source/v2/samples/image-import-gd-request.json diff --git a/api-ref/source/v2/images-import.inc b/api-ref/source/v2/images-import.inc index ec351d0737..4e4af87755 100644 --- a/api-ref/source/v2/images-import.inc +++ b/api-ref/source/v2/images-import.inc @@ -18,11 +18,12 @@ 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). -Three import methods are defined: +Four import methods are defined: * ``glance-direct`` * ``web-download`` * ``copy-image`` +* ``glance-download`` .. note:: @@ -92,6 +93,17 @@ The ``copy-image`` workflow has **two** parts: 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 @@ -183,6 +195,10 @@ 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 @@ -289,11 +305,22 @@ If you are using the ``copy-image`` import method: 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 and web-download import methods) - through API calls. (Be aware, however, that if the import + ``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``.) @@ -335,3 +362,9 @@ 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 diff --git a/api-ref/source/v2/samples/image-import-gd-request.json b/api-ref/source/v2/samples/image-import-gd-request.json new file mode 100644 index 0000000000..c0d77d2a60 --- /dev/null +++ b/api-ref/source/v2/samples/image-import-gd-request.json @@ -0,0 +1,8 @@ +{ + "method": { + "name": "glance-download", + "glance_image_id": "c4705b36-b281-40f6-a01d-bf98883ead8e", + "glance_region": "REGION2", + "glance_service_interface": "public" + } +} diff --git a/doc/source/admin/interoperable-image-import.rst b/doc/source/admin/interoperable-image-import.rst index 882c28f4bb..ba91b1438d 100644 --- a/doc/source/admin/interoperable-image-import.rst +++ b/doc/source/admin/interoperable-image-import.rst @@ -79,9 +79,9 @@ task-related policies: Image Import Methods -------------------- -Glance provides three import methods that you can make available to your -users: ``glance-direct``, ``web-download`` and ``copy-image``. By default, -all three methods are enabled. +Glance provides four import methods that you can make available to your +users: ``glance-direct``, ``web-download``, ``glance-download``, and +``copy-image``. By default, all four methods are enabled. * The ``glance-direct`` import method allows your users to upload image data directly to Glance. @@ -95,6 +95,10 @@ all three methods are enabled. that was available in the Image API v1 but previously absent from v2. Additionally, the Image API v1 was removed in Glance 17.0.0 (Rocky). +* The ``glance-download`` method allows an end user to import an image from a + remote glance. This import method is used to import an image from another + openstack region which is federated by the same keystone. + * The ``copy-image`` method allows and end user to copy existing image to other Glance backends available in deployment. This import method is only used if multiple glance backends are enabled in your deployment. @@ -261,6 +265,43 @@ be either 80 or 443.) subdirectory of the Glance source code tree. Make sure that you are looking in the correct branch for the OpenStack release you are working with. +Configuring the glance-download method +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To enable the ``glance-download`` import method, make sure that it is included +in the list of methods in the ``enabled_import_methods`` option, and that all +the options described above are set properly. + +Additionally, you have the following configuration available. + +Depending your needs on image properties you may configure addional properties +to be copied from the remote image to the local image. + +You can do this by configuring options in the +``[glance_download_opts]`` section of the **glance-image-import.conf** file. + +``extra_properties`` options is a list of properties that should be copied from +the remote image. The properties listed should be read as properties that +"start with" as it allows you to set a namespace instead of explicitly listing +each property of the namespace. + +Default values are : +``['hw_', 'trait:', 'os_distro', 'os_secure_boot', 'os_type']`` + +If you decide to set this option the default values will be totally ignored +unless you explicitly set them. + +.. note:: + The ``extra_properties`` option will ignore namespaces reserved by glance, + meaning that all the properties starting with ``os_glance`` won't be set + on the local image. + +.. note:: + The **glance-image-import.conf** is an optional file. You can find an + example file named glance-image-import.conf.sample in the **etc/** + subdirectory of the Glance source code tree. Make sure that you are looking + in the correct branch for the OpenStack release you are working with. + Configuring the copy-image method ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~