Adding cross refs for config options in scheduler filter guide

Change-Id: I98b5f0d9e18197382bc3a74f8f57d3ba1b11d899
Closes-bug: #1815591

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
+  :oslo.config:option:`cpu_allocation_ratio` setting. If no
-  fall back to the global default ``cpu_allocation_ratio``. If more than one value
+  per-aggregate value is found, it will fall back to the global default
-  is found for a host (meaning the host is in two different aggregates with
+  :oslo.config:option:`cpu_allocation_ratio`.
-  different ratio settings), the minimum value will be used.
+  If more than one value is found for a host (meaning the host is in two
-* |IsolatedHostsFilter| - filter based on ``isolated_images``, ``isolated_hosts``
+  different aggregates with different ratio settings), the minimum value
-  and ``restrict_isolated_hosts_to_isolated_images`` flags.
+  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
+  :oslo.config:option:`ram_allocation_ratio` setting. If no per-aggregate value
-  fall back to the global default ``ram_allocation_ratio``. If more than one value
+  is found, it will fall back to the global default
-  is found for a host (meaning the host is in two different aggregates with
+  :oslo.config:option:`ram_allocation_ratio`.
-  different ratio settings), the minimum value will be used.
+  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
+  :oslo.config:option:`disk_allocation_ratio` setting. The virtual disk to
-  allocation ratio, 1.0 by default. The total allowed allocated disk size will
+  physical disk allocation ratio, 1.0 by default. The total allowed allocated
-  be physical disk multiplied this ratio.
+  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
+  :oslo.config:option:`disk_allocation_ratio` setting. If no per-aggregate value
-  fall back to the global default ``disk_allocation_ratio``. If more than one value
+  is found, it will fall back to the global default
-  is found for a host (meaning the host is in two or more different aggregates with
+  :oslo.config:option:`disk_allocation_ratio`.
-  different ratio settings), the minimum value will be used.
+  If more than one value is found for a host (meaning the host is in two or more
-* |NumInstancesFilter| - filters compute nodes by number of running instances. Nodes
+  different aggregates with different ratio settings), the minimum value will
-  with too many instances will be filtered.
+  be used.
-  ``max_instances_per_host`` setting. Maximum number of instances allowed to run on
+* |NumInstancesFilter| - filters compute nodes by number of running instances.
-  this host. The host will be ignored by the scheduler if more than ``max_instances_per_host``
+  Nodes with too many instances will be filtered.
-  already exist on the host.
+  :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
+  per-aggregate :oslo.config:option:`filter_scheduler.max_instances_per_host`
-  is found, it will fall back to the global default ``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
+  :oslo.config:option:`filter_scheduler.max_io_ops_per_host` setting. Maximum
-  run on this host, the host will be ignored by scheduler if more than ``max_io_ops_per_host``
+  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
+  :oslo.config:option:`filter_scheduler.max_io_ops_per_host` setting. If no
-  fall back to the global default ``max_io_ops_per_host``. If more than
+  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
+Here :oslo.config:option:`ram_allocation_ratio` means the virtual RAM to physical
-ratio (it is ``1.5`` by default).
+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
@@ -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
+checks if :oslo.config:option:`filter_scheduler.isolated_images` flag named
-as the host specified in ``isolated_hosts``. Isolated hosts can run non-isolated
+in instance specifications is the same as the host specified in
-images if the flag ``restrict_isolated_hosts_to_isolated_images`` is set to false.
+: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
+:oslo.config:option:`ram_allocation_ratio` and
-filtering is done in the following manner:
+: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
+of :oslo.config:option:`filter_scheduler.enabled_filters` affects scheduling
-general suggestion is to filter out invalid hosts as soon as possible to avoid
+performance. The general suggestion is to filter out invalid hosts as soon as
-unnecessary costs.  We can sort ``filter_scheduler.enabled_filters`` items by
+possible to avoid unnecessary costs. We can sort
-their costs in reverse order. For example, ComputeFilter is better before any
+:oslo.config:option:`filter_scheduler.enabled_filters`
-resource calculating filters like RamFilter, CoreFilter.
+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
+  :oslo.config:option:`filter_scheduler.ram_weight_multiplier` is found, this
-  weight multiplier. Otherwise, it will fall back to the
+  value would be chosen as the ram weight multiplier. Otherwise, it will fall
-  :oslo.config:option:`filter_scheduler.ram_weight_multiplier`. If more than
+  back to the :oslo.config:option:`filter_scheduler.ram_weight_multiplier`.
-  one value is found for a host in aggregate metadata, the minimum value will
+  If more than one value is found for a host in aggregate metadata, the minimum
-  be used.
+  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
+  :oslo.config:option:`filter_scheduler.cpu_weight_multiplier` is found, this
-  weight multiplier. Otherwise, it will fall back to the
+  value would be chosen as the cpu weight multiplier. Otherwise, it will fall
-  :oslo.config:option:`filter_scheduler.cpu_weight_multiplier`. If more than
+  back to the :oslo.config:option:`filter_scheduler.cpu_weight_multiplier`. If
-  one value is found for a host in aggregate metadata, the minimum value will
+  more than one value is found for a host in aggregate metadata, the minimum
-  be used.
+  value will be used.
-* |DiskWeigher| Hosts are weighted and sorted by free disk space with the largest
+* |DiskWeigher| Hosts are weighted and sorted by free disk space with the
-  weight winning.  If the multiplier is negative, the host with less disk space available
+  largest weight winning.  If the multiplier is negative, the host with less disk
-  will win (useful for stacking hosts, instead of spreading).
+  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
+  :oslo.config:option:`filter_scheduler.disk_weight_multiplier` is found, this
-  weight multiplier. Otherwise, it will fall back to the
+  value would be chosen as the disk weight multiplier. Otherwise, it will fall
-  :oslo.config:option:`filter_scheduler.disk_weight_multiplier`. If more than
+  back to the :oslo.config:option:`filter_scheduler.disk_weight_multiplier`. If
-  one value is found for a host in aggregate metadata, the minimum value will
+  more than one value is found for a host in aggregate metadata, the minimum value
-  be used.
+  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
+  :oslo.config:option:`filter_scheduler.io_ops_weight_multiplier` is found, this
-  ops weight multiplier. Otherwise, it will fall back to the
+  value would be chosen as the IO ops weight multiplier. Otherwise, it will fall
-  :oslo.config:option:`filter_scheduler.io_ops_weight_multiplier`. If more than
+  back to the :oslo.config:option:`filter_scheduler.io_ops_weight_multiplier`.
-  one value is found for a host in aggregate metadata, the minimum value will
+  If more than one value is found for a host in aggregate metadata, the minimum
-  be used.
+  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
+  :oslo.config:option:`filter_scheduler.pci_weight_multiplier` is found, this
-  weight multiplier. Otherwise, it will fall back to the
+  value would be chosen as the pci weight multiplier. Otherwise, it will fall
-  :oslo.config:option:`filter_scheduler.pci_weight_multiplier`. If more than
+  back to the :oslo.config:option:`filter_scheduler.pci_weight_multiplier`.
-  one value is found for a host in aggregate metadata, the minimum value will
+  If more than one value is found for a host in aggregate metadata, the
-  be used.
+  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
+  :oslo.config:option:`filter_scheduler.soft_affinity_weight_multiplier` is
-  as the soft affinity weight multiplier. Otherwise, it will fall back to the
+  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
+  :oslo.config:option:`filter_scheduler.soft_anti_affinity_weight_multiplier`
-  as the soft anti-affinity weight multiplier. Otherwise, it will fall back to
+  is found, this value would be chosen as the soft anti-affinity weight
-  the :oslo.config:option:`filter_scheduler.soft_anti_affinity_weight_multiplier`.
+  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
+  :oslo.config:option:`filter_scheduler.build_failure_weight_multiplier` is found,
-  as the build failure weight multiplier. Otherwise, it will fall back to the
+  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.