diff --git a/doc/source/user/filter-scheduler.rst b/doc/source/user/filter-scheduler.rst index d807eb8b2a24..d6a44bac3f2c 100644 --- a/doc/source/user/filter-scheduler.rst +++ b/doc/source/user/filter-scheduler.rst @@ -98,49 +98,64 @@ There are many standard filter classes which may be used * |CoreFilter| - DEPRECATED; filters based on CPU core utilization. It passes hosts with sufficient number of CPU cores. * |AggregateCoreFilter| - filters hosts by CPU core number with per-aggregate - ``cpu_allocation_ratio`` setting. If no per-aggregate value is found, it will - fall back to the global default ``cpu_allocation_ratio``. If more than one value - is found for a host (meaning the host is in two different aggregates with - different ratio settings), the minimum value will be used. -* |IsolatedHostsFilter| - filter based on ``isolated_images``, ``isolated_hosts`` - and ``restrict_isolated_hosts_to_isolated_images`` flags. + :oslo.config:option:`cpu_allocation_ratio` setting. If no + per-aggregate value is found, it will fall back to the global default + :oslo.config:option:`cpu_allocation_ratio`. + If more than one value is found for a host (meaning the host is in two + different aggregates with different ratio settings), the minimum value + will be used. +* |IsolatedHostsFilter| - filter based on + :oslo.config:option:`filter_scheduler.isolated_images`, + :oslo.config:option:`filter_scheduler.isolated_hosts` + and :oslo.config:option:`filter_scheduler.restrict_isolated_hosts_to_isolated_images` + flags. * |JsonFilter| - allows simple JSON-based grammar for selecting hosts. * |RamFilter| - DEPRECATED; filters hosts by their RAM. Only hosts with sufficient RAM to host the instance are passed. * |AggregateRamFilter| - filters hosts by RAM with per-aggregate - ``ram_allocation_ratio`` setting. If no per-aggregate value is found, it will - fall back to the global default ``ram_allocation_ratio``. If more than one value - is found for a host (meaning the host is in two different aggregates with - different ratio settings), the minimum value will be used. + :oslo.config:option:`ram_allocation_ratio` setting. If no per-aggregate value + is found, it will fall back to the global default + :oslo.config:option:`ram_allocation_ratio`. + If more than one value is found for a host (meaning the host is in two + different aggregates with different ratio settings), the minimum value + will be used. * |DiskFilter| - DEPRECATED; filters hosts by their disk allocation. Only hosts with sufficient disk space to host the instance are passed. - ``disk_allocation_ratio`` setting. The virtual disk to physical disk - allocation ratio, 1.0 by default. The total allowed allocated disk size will - be physical disk multiplied this ratio. + :oslo.config:option:`disk_allocation_ratio` setting. The virtual disk to + physical disk allocation ratio, 1.0 by default. The total allowed allocated + disk size will be physical disk multiplied this ratio. * |AggregateDiskFilter| - filters hosts by disk allocation with per-aggregate - ``disk_allocation_ratio`` setting. If no per-aggregate value is found, it will - fall back to the global default ``disk_allocation_ratio``. If more than one value - is found for a host (meaning the host is in two or more different aggregates with - different ratio settings), the minimum value will be used. -* |NumInstancesFilter| - filters compute nodes by number of running instances. Nodes - with too many instances will be filtered. - ``max_instances_per_host`` setting. Maximum number of instances allowed to run on - this host. The host will be ignored by the scheduler if more than ``max_instances_per_host`` - already exist on the host. + :oslo.config:option:`disk_allocation_ratio` setting. If no per-aggregate value + is found, it will fall back to the global default + :oslo.config:option:`disk_allocation_ratio`. + If more than one value is found for a host (meaning the host is in two or more + different aggregates with different ratio settings), the minimum value will + be used. +* |NumInstancesFilter| - filters compute nodes by number of running instances. + Nodes with too many instances will be filtered. + :oslo.config:option:`filter_scheduler.max_instances_per_host` setting. + Maximum number of instances allowed to run on this host. The host will be + ignored by the scheduler if more than + :oslo.config:option:`filter_scheduler.max_instances_per_host` already exists + on the host. * |AggregateNumInstancesFilter| - filters hosts by number of instances with - per-aggregate ``max_instances_per_host`` setting. If no per-aggregate value - is found, it will fall back to the global default ``max_instances_per_host``. + per-aggregate :oslo.config:option:`filter_scheduler.max_instances_per_host` + setting. If no per-aggregate value is found, it will fall back to the global + default :oslo.config:option:`filter_scheduler.max_instances_per_host`. If more than one value is found for a host (meaning the host is in two or more different aggregates with different max instances per host settings), the minimum value will be used. * |IoOpsFilter| - filters hosts by concurrent I/O operations on it. hosts with too many concurrent I/O operations will be filtered. - ``max_io_ops_per_host`` setting. Maximum number of I/O intensive instances allowed to - run on this host, the host will be ignored by scheduler if more than ``max_io_ops_per_host`` + :oslo.config:option:`filter_scheduler.max_io_ops_per_host` setting. Maximum + number of I/O intensive instances allowed to run on this host, the host will + be ignored by scheduler if more than + :oslo.config:option:`filter_scheduler.max_io_ops_per_host` instances such as build/resize/snapshot etc are running on it. * |AggregateIoOpsFilter| - filters hosts by I/O operations with per-aggregate - ``max_io_ops_per_host`` setting. If no per-aggregate value is found, it will - fall back to the global default ``max_io_ops_per_host``. If more than + :oslo.config:option:`filter_scheduler.max_io_ops_per_host` setting. If no + per-aggregate value is found, it will fall back to the global default + `:oslo.config:option:`filter_scheduler.max_io_ops_per_host`. If more than one value is found for a host (meaning the host is in two or more different aggregates with different max io operations settings), the minimum value will be used. @@ -199,8 +214,8 @@ code. For example class |RamFilter| has the next realization: used_ram_mb = total_usable_ram_mb - free_ram_mb return total_usable_ram_mb * FLAGS.ram_allocation_ratio - used_ram_mb >= requested_ram -Here ``ram_allocation_ratio`` means the virtual RAM to physical RAM allocation -ratio (it is ``1.5`` by default). +Here :oslo.config:option:`ram_allocation_ratio` means the virtual RAM to physical +RAM allocation ratio (it is ``1.5`` by default). The |AvailabilityZoneFilter| looks at the availability zone of compute node and availability zone from the properties of the request. Each compute service @@ -211,7 +226,7 @@ availability zone mentioned in request is the same on the current compute host. The |ImagePropertiesFilter| filters hosts based on the architecture, hypervisor type and virtual machine mode specified in the -instance. For example, an instance might require a host that supports the ARM +instance. For example, an instance might require a host that supports the ARM architecture on a qemu compute host. The |ImagePropertiesFilter| will only pass hosts that can satisfy this request. These instance properties are populated from properties defined on the instance's image. @@ -236,9 +251,12 @@ enabled and operational. Now we are going to |IsolatedHostsFilter|. There can be some special hosts reserved for specific images. These hosts are called **isolated**. So the images to run on the isolated hosts are also called isolated. The filter -checks if ``isolated_images`` flag named in instance specifications is the same -as the host specified in ``isolated_hosts``. Isolated hosts can run non-isolated -images if the flag ``restrict_isolated_hosts_to_isolated_images`` is set to false. +checks if :oslo.config:option:`filter_scheduler.isolated_images` flag named +in instance specifications is the same as the host specified in +:oslo.config:option:`filter_scheduler.isolated_hosts`. Isolated +hosts can run non-isolated images if the flag +:oslo.config:option:`filter_scheduler.restrict_isolated_hosts_to_isolated_images` +is set to false. |DifferentHostFilter| - method ``host_passes`` returns ``True`` if the host to place an instance on is different from all the hosts used by a set of instances. @@ -292,8 +310,9 @@ described in detail in the related nova-spec document: * http://git.openstack.org/cgit/openstack/nova-specs/tree/specs/juno/implemented/virt-driver-numa-placement.rst and try to match it with the topology exposed by the host, accounting for the -``ram_allocation_ratio`` and ``cpu_allocation_ratio`` for over-subscription. The -filtering is done in the following manner: +:oslo.config:option:`ram_allocation_ratio` and +:oslo.config:option:`cpu_allocation_ratio` for over-subscription. The filtering +is done in the following manner: * Filter will attempt to pack instance cells onto host cells. * It will consider the standard over-subscription limits for each host NUMA cell, @@ -307,9 +326,9 @@ Configuring Filters To use filters you specify two settings: -* ``filter_scheduler.available_filters`` - Defines filter classes made +* :oslo.config:option:`filter_scheduler.available_filters` - Defines filter classes made available to the scheduler. This setting can be used multiple times. -* ``filter_scheduler.enabled_filters`` - Of the available filters, defines +* :oslo.config:option:`filter_scheduler.enabled_filters` - Of the available filters, defines those that the scheduler uses by default. The default values for these settings in nova.conf are: @@ -326,11 +345,12 @@ would be available, and by default the |ComputeFilter|, 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. +of :oslo.config:option:`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 +:oslo.config:option:`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. @@ -404,31 +424,31 @@ The Filter Scheduler weighs hosts based on the config option host with least RAM available will win (useful for stacking hosts, instead of spreading). Starting with the Stein release, if per-aggregate value with the key - `ram_weight_multiplier` is found, this value would be chosen as the ram - weight multiplier. Otherwise, it will fall back to the - :oslo.config:option:`filter_scheduler.ram_weight_multiplier`. If more than - one value is found for a host in aggregate metadata, the minimum value will - be used. + :oslo.config:option:`filter_scheduler.ram_weight_multiplier` is found, this + value would be chosen as the ram weight multiplier. Otherwise, it will fall + back to the :oslo.config:option:`filter_scheduler.ram_weight_multiplier`. + If more than one value is found for a host in aggregate metadata, the minimum + value will be used. * |CPUWeigher| Compute weight based on available vCPUs on the compute node. Sort with the largest weight winning. If the multiplier, :oslo.config:option:`filter_scheduler.cpu_weight_multiplier`, is negative, the host with least CPUs available will win (useful for stacking hosts, instead of spreading). Starting with the Stein release, if per-aggregate value with the key - `cpu_weight_multiplier` is found, this value would be chosen as the cpu - weight multiplier. Otherwise, it will fall back to the - :oslo.config:option:`filter_scheduler.cpu_weight_multiplier`. If more than - one value is found for a host in aggregate metadata, the minimum value will - be used. -* |DiskWeigher| Hosts are weighted and sorted by free disk space with the largest - weight winning. If the multiplier is negative, the host with less disk space available - will win (useful for stacking hosts, instead of spreading). + :oslo.config:option:`filter_scheduler.cpu_weight_multiplier` is found, this + value would be chosen as the cpu weight multiplier. Otherwise, it will fall + back to the :oslo.config:option:`filter_scheduler.cpu_weight_multiplier`. If + more than one value is found for a host in aggregate metadata, the minimum + value will be used. +* |DiskWeigher| Hosts are weighted and sorted by free disk space with the + largest weight winning. If the multiplier is negative, the host with less disk + space available will win (useful for stacking hosts, instead of spreading). Starting with the Stein release, if per-aggregate value with the key - `disk_weight_multiplier` is found, this value would be chosen as the disk - weight multiplier. Otherwise, it will fall back to the - :oslo.config:option:`filter_scheduler.disk_weight_multiplier`. If more than - one value is found for a host in aggregate metadata, the minimum value will - be used. + :oslo.config:option:`filter_scheduler.disk_weight_multiplier` is found, this + value would be chosen as the disk weight multiplier. Otherwise, it will fall + back to the :oslo.config:option:`filter_scheduler.disk_weight_multiplier`. If + more than one value is found for a host in aggregate metadata, the minimum value + will be used. * |MetricsWeigher| This weigher can compute the weight based on the compute node host's various metrics. The to-be weighed metrics and their weighing ratio are specified in the configuration file as the followings:: @@ -446,11 +466,11 @@ The Filter Scheduler weighs hosts based on the config option hosts. If the multiplier is positive, the weigher prefer choosing heavy workload compute hosts, the weighing has the opposite effect of the default. Starting with the Stein release, if per-aggregate value with the key - `io_ops_weight_multiplier` is found, this value would be chosen as the IO - ops weight multiplier. Otherwise, it will fall back to the - :oslo.config:option:`filter_scheduler.io_ops_weight_multiplier`. If more than - one value is found for a host in aggregate metadata, the minimum value will - be used. + :oslo.config:option:`filter_scheduler.io_ops_weight_multiplier` is found, this + value would be chosen as the IO ops weight multiplier. Otherwise, it will fall + back to the :oslo.config:option:`filter_scheduler.io_ops_weight_multiplier`. + If more than one value is found for a host in aggregate metadata, the minimum + value will be used. * |PCIWeigher| Compute a weighting based on the number of PCI devices on the host and the number of PCI devices requested by the instance. For example, @@ -471,18 +491,19 @@ The Filter Scheduler weighs hosts based on the config option scheduling issues. Starting with the Stein release, if per-aggregate value with the key - `pci_weight_multiplier` is found, this value would be chosen as the pci - weight multiplier. Otherwise, it will fall back to the - :oslo.config:option:`filter_scheduler.pci_weight_multiplier`. If more than - one value is found for a host in aggregate metadata, the minimum value will - be used. + :oslo.config:option:`filter_scheduler.pci_weight_multiplier` is found, this + value would be chosen as the pci weight multiplier. Otherwise, it will fall + back to the :oslo.config:option:`filter_scheduler.pci_weight_multiplier`. + If more than one value is found for a host in aggregate metadata, the + minimum value will be used. * |ServerGroupSoftAffinityWeigher| The weigher can compute the weight based on the number of instances that run on the same server group. The largest weight defines the preferred host for the new instance. For the multiplier only a positive value is allowed for the calculation. Starting with the Stein release, if per-aggregate value with the key - `soft_affinity_weight_multiplier` is found, this value would be chosen - as the soft affinity weight multiplier. Otherwise, it will fall back to the + :oslo.config:option:`filter_scheduler.soft_affinity_weight_multiplier` is + found, this value would be chosen as the soft affinity weight multiplier. + Otherwise, it will fall back to the :oslo.config:option:`filter_scheduler.soft_affinity_weight_multiplier`. If more than one value is found for a host in aggregate metadata, the minimum value will be used. @@ -492,9 +513,10 @@ The Filter Scheduler weighs hosts based on the config option value. The largest weight defines the preferred host for the new instance. For the multiplier only a positive value is allowed for the calculation. Starting with the Stein release, if per-aggregate value with the key - `soft_anti_affinity_weight_multiplier` is found, this value would be chosen - as the soft anti-affinity weight multiplier. Otherwise, it will fall back to - the :oslo.config:option:`filter_scheduler.soft_anti_affinity_weight_multiplier`. + :oslo.config:option:`filter_scheduler.soft_anti_affinity_weight_multiplier` + is found, this value would be chosen as the soft anti-affinity weight + multiplier. Otherwise, it will fall back to the + :oslo.config:option:`filter_scheduler.soft_anti_affinity_weight_multiplier`. If more than one value is found for a host in aggregate metadata, the minimum value will be used. @@ -502,8 +524,9 @@ The Filter Scheduler weighs hosts based on the config option It considers the build failure counter and can negatively weigh hosts with recent failures. This avoids taking computes fully out of rotation. Starting with the Stein release, if per-aggregate value with the key - `build_failure_weight_multiplier` is found, this value would be chosen - as the build failure weight multiplier. Otherwise, it will fall back to the + :oslo.config:option:`filter_scheduler.build_failure_weight_multiplier` is found, + this value would be chosen as the build failure weight multiplier. Otherwise, + it will fall back to the :oslo.config:option:`filter_scheduler.build_failure_weight_multiplier`. If more than one value is found for a host in aggregate metadata, the minimum value will be used.