openstack/glance
Code Issues Proposed changes

Merge "Add documentation for image import plugins"

Browse Source
This commit is contained in:
Zuul 2018-01-17 14:53:47 +00:00 committed by Gerrit Code Review
commit 08e28cd921
1 changed files with 57 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

57
doc/source/admin/interoperable-image-import.rst
View File

@ -67,6 +67,63 @@ task-related policies:
"modify_task": "",
"tasks_api_access": "role:admin",
Customizing the image import process
------------------------------------
When a user issues the image-import call, Glance retrieves the staged image
data, processes it, and saves the result in the backing store. You can
customize the nature of this processing by using *plugins*. Some plugins
are provided by the Glance project team, you can use third-party plugins,
or you can write your own.
Technical information
~~~~~~~~~~~~~~~~~~~~~
The import step of interoperable image import is performed by a `Taskflow`_
"flow" object. This object, provided by Glance, will call any plugins you have
specified in the ``glance-image-import.conf`` file. The plugins are loaded by
`Stevedore`_ and must be listed in the entry point registry in the namespace
``glance.image_import.plugins``. (If you are using only plugins provided by
the Glance project team, these are already registered for you.)
A plugin must be written in Python as a `Taskflow "Task" object`_. The file
containing this object must be present in the ``glance/async/flows/plugins``
directory. The plugin file must contain a ``get_flow`` function that returns a
Taskflow Task object wrapped in a linear flow. See the ``no_op`` plugin,
located at ``glance/async/flows/plugins/no_op.py`` for an example of how to do
this.
Specifying the plugins to be used
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
First, the plugin code must exist in the directory
``glance/async/flows/plugins``. The name of a plugin is the filename (without
extension) of the file containing the plugin code. For example, a file named
``fred_mertz.py`` would contain the plugin ``fred_mertz``.
Second, the plugin must be listed in the entry point list for the
``glance.image_import.plugins`` namespace. (If you are using only plugins
provided with Glance, this will have already been done for you, but it never
hurts to check.) The entry point list is in ``setup.cfg``. Find the section
with the heading ``[entry_points]`` and look for the line beginning with
``glance.image_import.plugins =``. It will be followed by a series of lines
of the form::
<plugin-name> = <module-package-name>:get_flow
For example::
no_op = glance.async.flows.plugins.no_op:get_flow
Make sure any plugin you want to use is included here.
Third, the plugin must be listed in the ``glance-image-import.conf`` file as
one of the plugin names in the list providing the value for the
``image_import_plugins`` option. Plugins are executed in the order they are
specified in this list.
.. _`Image Import Refactor`: https://specs.openstack.org/openstack/glance-specs/specs/mitaka/approved/image-import/image-import-refactor.html
.. _`Interoperable Image Import`: https://developer.openstack.org/api-ref/image/v2/index.html#interoperable-image-import
.. _`Stevedore`: https://docs.openstack.org/stevedore
.. _`Taskflow`: https://docs.openstack.org/taskflow
.. _`Taskflow "Task" object`: https://docs.openstack.org/taskflow/latest/user/atoms.html#task