diff --git a/doc/source/admin/interoperable-image-import.rst b/doc/source/admin/interoperable-image-import.rst index de08b9d6f6..424f527024 100644 --- a/doc/source/admin/interoperable-image-import.rst +++ b/doc/source/admin/interoperable-image-import.rst @@ -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:: + + = :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