diff --git a/doc/source/index.rst b/doc/source/index.rst index 76f8ab0c5..95e119f9c 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -47,6 +47,14 @@ Configuration Guide configuration/index +Architecture Concepts +===================== + +.. toctree:: + :maxdepth: 1 + + user/filter-scheduler + Indices and tables ------------------ diff --git a/doc/source/user/filter-scheduler.rst b/doc/source/user/filter-scheduler.rst new file mode 100644 index 000000000..35cef69a0 --- /dev/null +++ b/doc/source/user/filter-scheduler.rst @@ -0,0 +1,63 @@ +Filter Scheduler +================ + +The **Filter Scheduler** supports `filtering` zun compute hosts to make +decisions on where a new container should be created. + +Filtering +--------- + +Filter Scheduler iterates over all found compute hosts,evaluating each host +against a set of filters. The Scheduler then chooses a host for the requested +container. A specific filter can decide whether to pass or filter out a +specific host. The decision is made based on the user request specification, +the state of the host, and/or some extra information. + +If the Scheduler cannot find candidates for the container, it means that +there are no appropriate host where that container can be scheduled. + +The Filter Scheduler has a set of ``filters`` that are built-in. If the +built-in filters is insufficient, you can implement your own filters with your +filtering algorithm. + +There are many standard filter classes which may be used +(:mod:`zun.scheduler.filters`): + +* CPUFilter - filters based on CPU core utilization. It passes hosts with + sufficient number of CPU cores. +* RamFilter - filters hosts by their RAM. Only hosts with sufficient RAM + to host the instance are passed. +* LabelFilter - filters hosts based on whether host has the CLI specified + labels. + +Configuring Filters +------------------- + +To use filters you specify two settings: + +* ``filter_scheduler.available_filters`` - Defines filter classes made + available to the scheduler. +* ``filter_scheduler.enabled_filters`` - Of the available filters, defines + those that the scheduler uses by default. + +The default values for these settings in zun.conf are: + +:: + + --filter_scheduler.available_filters=zun.scheduler.filters.all_filters + --filter_scheduler.enabled_filters=RamFilter,CPUFilter + +With this configuration, all filters in ``zun.scheduler.filters`` +would be available, and by default the RamFilter and CPUFilter would be +used. + +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 the host passes the +filter. + +P.S.: you can find more examples of using Filter Scheduler and standard filters +in :mod:`zun.tests.scheduler`.