From 9526802915e7eaeabe098013b3bbe8442b672e03 Mon Sep 17 00:00:00 2001 From: Sylvain Bauza Date: Thu, 15 Feb 2018 11:21:32 +0100 Subject: [PATCH] doc: Clarify how to create your own filter The filter-scheduler doc was pretty old and I was recently asked to give some guidance on how to create a custom filter. A doc is better than any chat, so let's make that better. Change-Id: I64d24fb4337bb8c1e59a04818307b43f181e2ad2 --- doc/source/user/filter-scheduler.rst | 36 +++++++++++++++++----------- 1 file changed, 22 insertions(+), 14 deletions(-) diff --git a/doc/source/user/filter-scheduler.rst b/doc/source/user/filter-scheduler.rst index 6bf1c6e7105e..e9113adb4136 100644 --- a/doc/source/user/filter-scheduler.rst +++ b/doc/source/user/filter-scheduler.rst @@ -325,14 +325,32 @@ would be available, and by default the |ComputeFilter|, |ImagePropertiesFilter|, |ServerGroupAntiAffinityFilter|, and |ServerGroupAffinityFilter| would be used. +Each filter selects hosts in a different way and has different costs. The order +of ``filter_scheduler.enabled_filters`` affects scheduling performance. The +general suggestion is to filter out invalid hosts as soon as possible to avoid +unnecessary costs. We can sort ``filter_scheduler.enabled_filters`` items by +their costs in reverse order. For example, ComputeFilter is better before any +resource calculating filters like RamFilter, CoreFilter. + +In medium/large environments having AvailabilityZoneFilter before any +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. It -takes ``host_state`` (describing the host) and ``filter_properties`` dictionary as the -parameters. +|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``): + +* 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. + +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. As an example, nova.conf could contain the following scheduler-related settings: @@ -353,16 +371,6 @@ driver. All of the standard nova filters and MyFilter are available to the FilterScheduler, but just the RamFilter, ComputeFilter, and MyFilter will be used on each request. -Each filter selects hosts in a different way and has different costs. The order -of ``filter_scheduler.enabled_filters`` affects scheduling performance. The -general suggestion is to filter out invalid hosts as soon as possible to avoid -unnecessary costs. We can sort ``filter_scheduler.enabled_filters`` items by -their costs in reverse order. For example, ComputeFilter is better before any -resource calculating filters like RamFilter, CoreFilter. - -In medium/large environments having AvailabilityZoneFilter before any -capability or resource calculating filters can be useful. - Weights -------