Merge "Add documentation for image import plugins"

Zuul 5 years ago committed by Gerrit Code Review
commit 08e28cd921

@ -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/`` for an example of how to do
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
```` 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`:
.. _`Interoperable Image Import`:
.. _`Stevedore`:
.. _`Taskflow`:
.. _`Taskflow "Task" object`: