openstack/nova
Code Issues Proposed changes

docs: Improve documentation on writing custom scheduler filters

Browse Source 
Operators can deploy their own scheduler filters. We currently provide
some minimal instructions for how to do this but it omits things like
the need to package these filters so they can be picked up correctly.

Change-Id: I725801c9c049455a0196e4664d767b81a8d4edf2
Signed-off-by: Stephen Finucane <sfinucan@redhat.com>
This commit is contained in:
Stephen Finucane
2020-02-11 15:37:23 +00:00
parent 6a4cb24d39
commit fa5e1b556f
1 changed files with 52 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files

74
doc/source/user/filter-scheduler.rst
View File

@@ -358,38 +358,68 @@ capability or resource calculating filters can be useful.
Writing Your Own Filter
-----------------------
To create **your own filter** you must inherit from
|BaseHostFilter| and implement one method: ``host_passes``.
This method should return ``True`` if a host passes the filter and return
``False`` elsewhere.
It takes two parameters (named arbitrarily as ``host_state`` and ``spec_obj``):
To create **your own filter**, you must inherit from |BaseHostFilter| and
implement one method: ``host_passes``. This method should return ``True`` if a
host passes the filter and return ``False`` elsewhere. It takes two parameters:
* the ``HostState`` object allows to get attributes of the host.
* the ``HostState`` object allows to get attributes of the host
* the ``RequestSpec`` object describes the user request, including the flavor,
the image and the scheduler hints.
the image and the scheduler hints
For further details about each of those objects and their corresponding
attributes, please refer to the codebase (at least by looking at the other
filters code) or ask for help in the #openstack-nova IRC channel.
attributes, refer to the codebase (at least by looking at the other filters
code) or ask for help in the #openstack-nova IRC channel.
As an example, nova.conf could contain the following scheduler-related
settings:
The module containing your custom filter(s) must be packaged and available in
the same environment that nova, or specifically the :program:`nova-scheduler`
service, is available in. As an example, consider the following sample package,
which is the `minimal structure`__ for a standard, setuptools-based Python
package:
::
__ https://python-packaging.readthedocs.io/en/latest/minimal.html
--scheduler.driver=nova.scheduler.FilterScheduler
--filter_scheduler.available_filters=nova.scheduler.filters.all_filters
--filter_scheduler.available_filters=myfilter.MyFilter
--filter_scheduler.enabled_filters=ComputeFilter,MyFilter
.. code-block:: none
.. note:: When writing your own filter, be sure to add it to the list of available filters
and enable it in the default filters. The "all_filters" setting only includes the
filters shipped with nova.
myfilter/
myfilter/
__init__.py
setup.py
The ``myfilter/myfilter/__init__.py`` could contain something like so:
.. code-block:: python
from nova.scheduler import filters
class MyFilter(filters.BaseHostFilter):
def host_passes(self, host_state, spec_obj):
# do stuff here...
return True
To enable this, you would set the following in :file:`nova.conf`:
.. code-block:: ini
[filter_scheduler]
available_filters = nova.scheduler.filters.all_filters
available_filters = myfilter.MyFilter
enabled_filters = ComputeFilter,MyFilter
.. note::
You **must** add custom filters to the list of available filters using the
:oslo.config:option:`filter_scheduler.available_filters` config option in
addition to enabling them via the
:oslo.config:option:`filter_scheduler.enabled_filters` config option. The
default ``nova.scheduler.filters.all_filters`` value for the former only
includes the filters shipped with nova.
With these settings, nova will use the ``FilterScheduler`` for the scheduler
driver. All of the standard nova filters and MyFilter are available to the
FilterScheduler, but just the ``ComputeFilter`` and ``MyFilter`` will be
used on each request.
driver. All of the standard nova filters and the custom ``MyFilter`` filter are
available to the ``FilterScheduler``, but just the ``ComputeFilter`` and
``MyFilter`` will be used on each request.
Weights
-------