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 <victor.coutellier@gmail.com> Change-Id: Ie36232f3474d398a913025c8d408f08f879874d8
This commit is contained in:
parent
157a677989
commit
f09c338035
|
@ -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
|
an image. Each of these methods is well defined (which is what makes
|
||||||
this process interoperable among different OpenStack clouds).
|
this process interoperable among different OpenStack clouds).
|
||||||
|
|
||||||
Three import methods are defined:
|
Four import methods are defined:
|
||||||
|
|
||||||
* ``glance-direct``
|
* ``glance-direct``
|
||||||
* ``web-download``
|
* ``web-download``
|
||||||
* ``copy-image``
|
* ``copy-image``
|
||||||
|
* ``glance-download``
|
||||||
|
|
||||||
.. note::
|
.. note::
|
||||||
|
|
||||||
|
@ -92,6 +93,17 @@ The ``copy-image`` workflow has **two** parts:
|
||||||
the import process. You will specify that you are using the
|
the import process. You will specify that you are using the
|
||||||
``copy-image`` import method in the body of the import call.
|
``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 <image-import-call>` 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:
|
.. _image-stage-call:
|
||||||
|
|
||||||
Stage binary image data
|
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
|
In the ``copy-image`` workflow, the data is made available to the Image
|
||||||
service by copying existing image data to the staging area.
|
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
|
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
|
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
|
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
|
permission to copy unowned images. Consult your cloud's local
|
||||||
documentation for details.
|
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**
|
**Synchronous Postconditions**
|
||||||
|
|
||||||
- With correct permissions, you can see the image status as
|
- With correct permissions, you can see the image status as
|
||||||
``importing`` (only for glance-direct and web-download import methods)
|
``importing`` (only for glance-direct, web-download and glance-download
|
||||||
through API calls. (Be aware, however, that if the import
|
import methods) through API calls. (Be aware, however, that if the import
|
||||||
process completes before you make the API call, the image may already
|
process completes before you make the API call, the image may already
|
||||||
show as ``active``.)
|
show as ``active``.)
|
||||||
|
|
||||||
|
@ -335,3 +362,9 @@ Request Example - copy-image import method
|
||||||
|
|
||||||
.. literalinclude:: samples/image-import-c-i-request.json
|
.. literalinclude:: samples/image-import-c-i-request.json
|
||||||
:language: json
|
:language: json
|
||||||
|
|
||||||
|
Request Example - glance-download import method
|
||||||
|
-----------------------------------------------
|
||||||
|
|
||||||
|
.. literalinclude:: samples/image-import-gd-request.json
|
||||||
|
:language: json
|
||||||
|
|
|
@ -0,0 +1,8 @@
|
||||||
|
{
|
||||||
|
"method": {
|
||||||
|
"name": "glance-download",
|
||||||
|
"glance_image_id": "c4705b36-b281-40f6-a01d-bf98883ead8e",
|
||||||
|
"glance_region": "REGION2",
|
||||||
|
"glance_service_interface": "public"
|
||||||
|
}
|
||||||
|
}
|
|
@ -79,9 +79,9 @@ task-related policies:
|
||||||
Image Import Methods
|
Image Import Methods
|
||||||
--------------------
|
--------------------
|
||||||
|
|
||||||
Glance provides three import methods that you can make available to your
|
Glance provides four import methods that you can make available to your
|
||||||
users: ``glance-direct``, ``web-download`` and ``copy-image``. By default,
|
users: ``glance-direct``, ``web-download``, ``glance-download``, and
|
||||||
all three methods are enabled.
|
``copy-image``. By default, all four methods are enabled.
|
||||||
|
|
||||||
* The ``glance-direct`` import method allows your users to upload image data
|
* The ``glance-direct`` import method allows your users to upload image data
|
||||||
directly to Glance.
|
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.
|
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).
|
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
|
* The ``copy-image`` method allows and end user to copy existing image to
|
||||||
other Glance backends available in deployment. This import method is
|
other Glance backends available in deployment. This import method is
|
||||||
only used if multiple glance backends are enabled in your deployment.
|
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
|
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.
|
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
|
Configuring the copy-image method
|
||||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue