diff --git a/api-ref/source/parameters.yaml b/api-ref/source/parameters.yaml index 7a7f0b5da770..25f0f3499c9f 100644 --- a/api-ref/source/parameters.yaml +++ b/api-ref/source/parameters.yaml @@ -3031,7 +3031,7 @@ flavor_disk: description: | The size of the root disk that will be created in GiB. If 0 the root disk will be set to exactly the size of the image used to - deploy the instance. However, in this case filter scheduler cannot + deploy the instance. However, in this case the scheduler cannot select the compute host based on the virtual image size. Therefore, 0 should only be used for volume booted instances or for testing purposes. Volume-backed instances can be enforced for flavors with diff --git a/doc/source/_extra/.htaccess b/doc/source/_extra/.htaccess index a3d2c5729b05..5d361fc91c9c 100644 --- a/doc/source/_extra/.htaccess +++ b/doc/source/_extra/.htaccess @@ -15,12 +15,12 @@ redirectmatch 301 ^/nova/([^/]+)/conductor.html$ /nova/$1/user/conductor.html redirectmatch 301 ^/nova/([^/]+)/development.environment.html$ /nova/$1/contributor/development-environment.html redirectmatch 301 ^/nova/([^/]+)/devref/api.html /nova/$1/contributor/api.html redirectmatch 301 ^/nova/([^/]+)/devref/cells.html /nova/$1/user/cells.html -redirectmatch 301 ^/nova/([^/]+)/devref/filter_scheduler.html /nova/$1/user/filter-scheduler.html +redirectmatch 301 ^/nova/([^/]+)/devref/filter_scheduler.html /nova/$1/admin/scheduling.html # catch all, if we hit something in devref assume it moved to # reference unless we have already triggered a hit above. redirectmatch 301 ^/nova/([^/]+)/devref/([^/]+).html /nova/$1/reference/$2.html redirectmatch 301 ^/nova/([^/]+)/feature_classification.html$ /nova/$1/user/feature-classification.html -redirectmatch 301 ^/nova/([^/]+)/filter_scheduler.html$ /nova/$1/user/filter-scheduler.html +redirectmatch 301 ^/nova/([^/]+)/filter_scheduler.html$ /nova/$1/admin/scheduling.html redirectmatch 301 ^/nova/([^/]+)/gmr.html$ /nova/$1/reference/gmr.html redirectmatch 301 ^/nova/([^/]+)/how_to_get_involved.html$ /nova/$1/contributor/how-to-get-involved.html redirectmatch 301 ^/nova/([^/]+)/i18n.html$ /nova/$1/reference/i18n.html @@ -66,6 +66,7 @@ redirectmatch 301 ^/nova/([^/]+)/upgrade.html$ /nova/$1/admin/upgrades.html redirectmatch 301 ^/nova/([^/]+)/user/aggregates.html$ /nova/$1/admin/aggregates.html redirectmatch 301 ^/nova/([^/]+)/user/cellsv2_layout.html$ /nova/$1/user/cellsv2-layout.html redirectmatch 301 ^/nova/([^/]+)/user/config-drive.html$ /nova/$1/user/metadata.html +redirectmatch 301 ^/nova/([^/]+)/user/filter-scheduler.html$ /nova/$1/admin/scheduling.html redirectmatch 301 ^/nova/([^/]+)/user/metadata-service.html$ /nova/$1/user/metadata.html redirectmatch 301 ^/nova/([^/]+)/user/placement.html$ /placement/$1/ redirectmatch 301 ^/nova/([^/]+)/user/upgrade.html$ /nova/$1/admin/upgrades.html @@ -75,6 +76,7 @@ redirectmatch 301 ^/nova/([^/]+)/vendordata.html$ /nova/$1/user/metadata.html redirectmatch 301 ^/nova/([^/]+)/vmstates.html$ /nova/$1/reference/vm-states.html redirectmatch 301 ^/nova/([^/]+)/wsgi.html$ /nova/$1/user/wsgi.html redirectmatch 301 ^/nova/([^/]+)/admin/adv-config.html$ /nova/$1/admin/index.html +redirectmatch 301 ^/nova/([^/]+)/admin/configuration/schedulers.html$ /nova/$1/admin/scheduling.html redirectmatch 301 ^/nova/([^/]+)/admin/system-admin.html$ /nova/$1/admin/index.html redirectmatch 301 ^/nova/([^/]+)/admin/port_with_resource_request.html$ /nova/$1/admin/ports-with-resource-requests.html redirectmatch 301 ^/nova/([^/]+)/admin/manage-users.html$ /nova/$1/admin/arch.html diff --git a/doc/source/admin/configuration/index.rst b/doc/source/admin/configuration/index.rst index d91c72f9de9f..233597b1fe4a 100644 --- a/doc/source/admin/configuration/index.rst +++ b/doc/source/admin/configuration/index.rst @@ -25,6 +25,5 @@ A list of config options based on different topics can be found below: /admin/configuration/fibre-channel /admin/configuration/iscsi-offload /admin/configuration/hypervisors - /admin/configuration/schedulers /admin/configuration/logs /admin/configuration/samples/index diff --git a/doc/source/admin/configuration/schedulers.rst b/doc/source/admin/configuration/schedulers.rst deleted file mode 100644 index f99223070327..000000000000 --- a/doc/source/admin/configuration/schedulers.rst +++ /dev/null @@ -1,1080 +0,0 @@ -================== -Compute schedulers -================== - -Compute uses the ``nova-scheduler`` service to determine how to dispatch -compute requests. For example, the ``nova-scheduler`` service determines on -which host a VM should launch. In the context of filters, the term ``host`` -means a physical node that has a ``nova-compute`` service running on it. You -can configure the scheduler through a variety of options. - -Compute is configured with the following default scheduler options in the -``/etc/nova/nova.conf`` file: - -.. code-block:: ini - - [scheduler] - driver = filter_scheduler - - [filter_scheduler] - available_filters = nova.scheduler.filters.all_filters - enabled_filters = ComputeFilter, ComputeCapabilitiesFilter, ImagePropertiesFilter, ServerGroupAntiAffinityFilter, ServerGroupAffinityFilter - -By default, the scheduler ``driver`` is configured as a filter scheduler, as -described in the next section. In the default configuration, this scheduler -considers hosts that meet all the following criteria: - -* Are in the requested :term:`Availability Zone` (``AvailabilityZoneFilter``). - -* Can service the request (``ComputeFilter``). - -* Satisfy the extra specs associated with the instance type - (``ComputeCapabilitiesFilter``). - -* Satisfy any architecture, hypervisor type, or virtual machine mode properties - specified on the instance's image properties (``ImagePropertiesFilter``). - -* Are on a different host than other instances of a group (if requested) - (``ServerGroupAntiAffinityFilter``). - -* Are in a set of group hosts (if requested) (``ServerGroupAffinityFilter``). - -The scheduler chooses a new host when an instance is migrated. - -When evacuating instances from a host, the scheduler service honors the target -host defined by the administrator on the :command:`nova evacuate` command. If -a target is not defined by the administrator, the scheduler determines the -target host. For information about instance evacuation, see -:ref:`Evacuate instances `. - -.. _compute-scheduler-filters: - -Prefiltering -~~~~~~~~~~~~ - -As of the Rocky release, the scheduling process includes a prefilter step to -increase the efficiency of subsequent stages. These prefilters are largely -optional, and serve to augment the request that is sent to placement to reduce -the set of candidate compute hosts based on attributes that placement is able -to answer for us ahead of time. In addition to the prefilters listed here, also -see :ref:`tenant-isolation-with-placement` and -:ref:`availability-zones-with-placement`. - - -Compute Image Type Support --------------------------- - -Starting in the Train release, there is a prefilter available for -excluding compute nodes that do not support the ``disk_format`` of the -image used in a boot request. This behavior is enabled by setting -:oslo.config:option:`[scheduler]/query_placement_for_image_type_support=True -`. For -example, the libvirt driver, when using ceph as an ephemeral backend, -does not support ``qcow2`` images (without an expensive conversion -step). In this case (and especially if you have a mix of ceph and -non-ceph backed computes), enabling this feature will ensure that the -scheduler does not send requests to boot a ``qcow2`` image to computes -backed by ceph. - -Compute Disabled Status Support -------------------------------- - -Starting in the Train release, there is a mandatory `pre-filter -`_ -which will exclude disabled compute nodes similar to (but does not fully -replace) the `ComputeFilter`_. Compute node resource providers with the -``COMPUTE_STATUS_DISABLED`` trait will be excluded as scheduling candidates. -The trait is managed by the ``nova-compute`` service and should mirror the -``disabled`` status on the related compute service record in the -`os-services`_ API. For example, if a compute service's status is ``disabled``, -the related compute node resource provider(s) for that service should have the -``COMPUTE_STATUS_DISABLED`` trait. When the service status is ``enabled`` the -``COMPUTE_STATUS_DISABLED`` trait shall be removed. - -If the compute service is down when the status is changed, the trait will be -synchronized by the compute service when it is restarted. Similarly, if an -error occurs when trying to add or remove the trait on a given resource -provider, the trait will be synchronized when the ``update_available_resource`` -periodic task runs - which is controlled by the -:oslo.config:option:`update_resources_interval` configuration option. - -.. _os-services: https://docs.openstack.org/api-ref/compute/#compute-services-os-services - -Isolate Aggregates ------------------- - -Starting in the Train release, there is an optional placement pre-request filter -:doc:`/reference/isolate-aggregates` -When enabled, the traits required in the server's flavor and image must be at -least those required in an aggregate's metadata in order for the server to be -eligible to boot on hosts in that aggregate. - -Filter scheduler -~~~~~~~~~~~~~~~~ - -The filter scheduler (``nova.scheduler.filter_scheduler.FilterScheduler``) is -the default scheduler for scheduling virtual machine instances. It supports -filtering and weighting to make informed decisions on where a new instance -should be created. - -When the filter scheduler receives a request for a resource, it first applies -filters to determine which hosts are eligible for consideration when -dispatching a resource. Filters are binary: either a host is accepted by the -filter, or it is rejected. Hosts that are accepted by the filter are then -processed by a different algorithm to decide which hosts to use for that -request, described in the :ref:`weights` section. - -**Filtering** - -.. figure:: /_static/images/filtering-workflow-1.png - -The ``available_filters`` configuration option in ``nova.conf`` -provides the Compute service with the list of the filters that are available -for use by the scheduler. The default setting specifies all of the filters that -are included with the Compute service: - -.. code-block:: ini - - [filter_scheduler] - available_filters = nova.scheduler.filters.all_filters - -This configuration option can be specified multiple times. For example, if you -implemented your own custom filter in Python called ``myfilter.MyFilter`` and -you wanted to use both the built-in filters and your custom filter, your -``nova.conf`` file would contain: - -.. code-block:: ini - - [filter_scheduler] - available_filters = nova.scheduler.filters.all_filters - available_filters = myfilter.MyFilter - -The :oslo.config:option:`filter_scheduler.enabled_filters` configuration option -in ``nova.conf`` defines the list of filters that are applied by the -``nova-scheduler`` service. - -Compute filters -~~~~~~~~~~~~~~~ - -The following sections describe the available compute filters. - -.. _AggregateImagePropertiesIsolation: - -AggregateImagePropertiesIsolation ---------------------------------- - -.. versionchanged:: 12.0.0 (Liberty) - - Prior to 12.0.0 Liberty, it was possible to specify and use arbitrary - metadata with this filter. Starting in Liberty, nova only parses - :glance-doc:`standard metadata `. If - you wish to use arbitrary metadata, consider using the - :ref:`AggregateInstanceExtraSpecsFilter` filter instead. - -Matches properties defined in an image's metadata against those of aggregates -to determine host matches: - -* If a host belongs to an aggregate and the aggregate defines one or more - metadata that matches an image's properties, that host is a candidate to boot - the image's instance. - -* If a host does not belong to any aggregate, it can boot instances from all - images. - -For example, the following aggregate ``myWinAgg`` has the Windows operating -system as metadata (named 'windows'): - -.. code-block:: console - - $ openstack aggregate show myWinAgg - +-------------------+----------------------------+ - | Field | Value | - +-------------------+----------------------------+ - | availability_zone | zone1 | - | created_at | 2017-01-01T15:36:44.000000 | - | deleted | False | - | deleted_at | None | - | hosts | [u'sf-devel'] | - | id | 1 | - | name | myWinAgg | - | properties | os_distro='windows' | - | updated_at | None | - +-------------------+----------------------------+ - -In this example, because the following Win-2012 image has the ``windows`` -property, it boots on the ``sf-devel`` host (all other filters being equal): - -.. code-block:: console - - $ openstack image show Win-2012 - +------------------+------------------------------------------------------+ - | Field | Value | - +------------------+------------------------------------------------------+ - | checksum | ee1eca47dc88f4879d8a229cc70a07c6 | - | container_format | bare | - | created_at | 2016-12-13T09:30:30Z | - | disk_format | qcow2 | - | ... | - | name | Win-2012 | - | ... | - | properties | os_distro='windows' | - | ... | - -You can configure the ``AggregateImagePropertiesIsolation`` filter by using the -following options in the ``nova.conf`` file: - -.. code-block:: ini - - [scheduler] - # Considers only keys matching the given namespace (string). - # Multiple values can be given, as a comma-separated list. - aggregate_image_properties_isolation_namespace = - - # Separator used between the namespace and keys (string). - aggregate_image_properties_isolation_separator = . - -.. note:: - - This filter has limitations as described in `bug 1677217 - `_ - which are addressed in placement :doc:`/reference/isolate-aggregates` - request filter. - -Refer to :doc:`/admin/aggregates` for more information. - - -.. _AggregateInstanceExtraSpecsFilter: - -AggregateInstanceExtraSpecsFilter ---------------------------------- - -Matches properties defined in extra specs for an instance type against -admin-defined properties on a host aggregate. Works with specifications that -are scoped with ``aggregate_instance_extra_specs``. Multiple values can be -given, as a comma-separated list. For backward compatibility, also works with -non-scoped specifications; this action is highly discouraged because it -conflicts with :ref:`ComputeCapabilitiesFilter` filter when you enable both -filters. - -Refer to :doc:`/admin/aggregates` for more information. - - -.. _AggregateIoOpsFilter: - -AggregateIoOpsFilter --------------------- - -Filters host by disk allocation with a per-aggregate ``max_io_ops_per_host`` -value. If the per-aggregate value is not found, the value falls back to the -global setting. If the host is in more than one aggregate and more than one -value is found, the minimum value will be used. - -Refer to :doc:`/admin/aggregates` and :ref:`IoOpsFilter` for more information. - - -.. _AggregateMultiTenancyIsolation: - -AggregateMultiTenancyIsolation ------------------------------- - -Ensures hosts in tenant-isolated host aggregates will only be available to a -specified set of tenants. If a host is in an aggregate that has the -``filter_tenant_id`` metadata key, the host can build instances from only that -tenant or comma-separated list of tenants. A host can be in different -aggregates. If a host does not belong to an aggregate with the metadata key, -the host can build instances from all tenants. This does not restrict the -tenant from creating servers on hosts outside the tenant-isolated aggregate. - -For example, consider there are two available hosts for scheduling, HostA and -HostB. HostB is in an aggregate isolated to tenant X. A server create request -from tenant X will result in either HostA *or* HostB as candidates during -scheduling. A server create request from another tenant Y will result in only -HostA being a scheduling candidate since HostA is not part of the -tenant-isolated aggregate. - -.. note:: - - There is a `known limitation - `_ with the number of tenants - that can be isolated per aggregate using this filter. This limitation does - not exist, however, for the :ref:`tenant-isolation-with-placement` - filtering capability added in the 18.0.0 Rocky release. - - -.. _AggregateNumInstancesFilter: - -AggregateNumInstancesFilter ---------------------------- - -Filters host by number of instances with a per-aggregate -``max_instances_per_host`` value. If the per-aggregate value is not found, the -value falls back to the global setting. If the host is in more than one -aggregate and thus more than one value is found, the minimum value will be -used. - -Refer to :doc:`/admin/aggregates` and :ref:`NumInstancesFilter` for more -information. - - -.. _AggregateTypeAffinityFilter: - -AggregateTypeAffinityFilter ---------------------------- - -This filter passes hosts if no ``instance_type`` key is set or the -``instance_type`` aggregate metadata value contains the name of the -``instance_type`` requested. The value of the ``instance_type`` metadata entry -is a string that may contain either a single ``instance_type`` name or a -comma-separated list of ``instance_type`` names, such as ``m1.nano`` or -``m1.nano,m1.small``. - -Refer to :doc:`/admin/aggregates` for more information. - - -AllHostsFilter --------------- - -This is a no-op filter. It does not eliminate any of the available hosts. - -.. _AvailabilityZoneFilter: - -AvailabilityZoneFilter ----------------------- - -.. deprecated:: 24.0.0 (Xena) - - The functionality of this filter has been replaced by - :ref:`availability-zones-with-placement`. - -Filters hosts by availability zone. - -Refer to :doc:`/admin/availability-zones` for more information. - -.. _ComputeCapabilitiesFilter: - -ComputeCapabilitiesFilter -------------------------- - -Matches properties defined in extra specs for an instance type against compute -capabilities. If an extra specs key contains a colon (``:``), anything before -the colon is treated as a namespace and anything after the colon is treated as -the key to be matched. If a namespace is present and is not ``capabilities``, -the filter ignores the namespace. For backward compatibility, also treats the -extra specs key as the key to be matched if no namespace is present; this -action is highly discouraged because it conflicts with -:ref:`AggregateInstanceExtraSpecsFilter` filter when you enable both filters. - -Some virt drivers support reporting CPU traits to the Placement service. With that -feature available, you should consider using traits in flavors instead of -ComputeCapabilitiesFilter, because traits provide consistent naming for CPU -features in some virt drivers and querying traits is efficient. For more detail, please see -`Support Matrix `_, -:ref:`Required traits `, -:ref:`Forbidden traits ` and -`Report CPU features to the Placement service `_. - -Also refer to `Compute capabilities as traits`_. - -.. _ComputeFilter: - -ComputeFilter -------------- - -Passes all hosts that are operational and enabled. - -In general, you should always enable this filter. - -DifferentHostFilter -------------------- - -Schedules the instance on a different host from a set of instances. To take -advantage of this filter, the requester must pass a scheduler hint, using -``different_host`` as the key and a list of instance UUIDs as the value. This -filter is the opposite of the ``SameHostFilter``. Using the -:command:`openstack server create` command, use the ``--hint`` flag. For -example: - -.. code-block:: console - - $ openstack server create --image cedef40a-ed67-4d10-800e-17455edce175 \ - --flavor 1 --hint different_host=a0cf03a5-d921-4877-bb5c-86d26cf818e1 \ - --hint different_host=8c19174f-4220-44f0-824a-cd1eeef10287 server-1 - -With the API, use the ``os:scheduler_hints`` key. For example: - -.. code-block:: json - - { - "server": { - "name": "server-1", - "imageRef": "cedef40a-ed67-4d10-800e-17455edce175", - "flavorRef": "1" - }, - "os:scheduler_hints": { - "different_host": [ - "a0cf03a5-d921-4877-bb5c-86d26cf818e1", - "8c19174f-4220-44f0-824a-cd1eeef10287" - ] - } - } - -.. _ImagePropertiesFilter: - -ImagePropertiesFilter ---------------------- - -Filters hosts based on properties defined on the instance's image. It passes -hosts that can support the specified image properties contained in the -instance. Properties include the architecture, hypervisor type, hypervisor -version, and virtual machine mode. - -For example, an instance might require a host that runs an ARM-based processor, -and QEMU as the hypervisor. You can decorate an image with these properties by -using: - -.. code-block:: console - - $ openstack image set --architecture arm --property img_hv_type=qemu \ - img-uuid - -The image properties that the filter checks for are: - -``hw_architecture`` - Describes the machine architecture required by the image. Examples are - ``i686``, ``x86_64``, ``arm``, and ``ppc64``. - - .. versionchanged:: 12.0.0 (Liberty) - - This was previously called ``architecture``. - -``img_hv_type`` - Describes the hypervisor required by the image. Examples are ``qemu`` - and ``hyperv``. - - .. note:: - - ``qemu`` is used for both QEMU and KVM hypervisor types. - - .. versionchanged:: 12.0.0 (Liberty) - - This was previously called ``hypervisor_type``. - -``img_hv_requested_version`` - Describes the hypervisor version required by the image. The property is - supported for HyperV hypervisor type only. It can be used to enable support for - multiple hypervisor versions, and to prevent instances with newer HyperV tools - from being provisioned on an older version of a hypervisor. If available, the - property value is compared to the hypervisor version of the compute host. - - To filter the hosts by the hypervisor version, add the - ``img_hv_requested_version`` property on the image as metadata and pass an - operator and a required hypervisor version as its value: - - .. code-block:: console - - $ openstack image set --property hypervisor_type=hyperv --property \ - hypervisor_version_requires=">=6000" img-uuid - - .. versionchanged:: 12.0.0 (Liberty) - - This was previously called ``hypervisor_version_requires``. - -``hw_vm_mode`` - describes the hypervisor application binary interface (ABI) required by the - image. Examples are ``xen`` for Xen 3.0 paravirtual ABI, ``hvm`` for native - ABI, and ``exe`` for container virt executable ABI. - - .. versionchanged:: 12.0.0 (Liberty) - - This was previously called ``vm_mode``. - -IsolatedHostsFilter -------------------- - -Allows the admin to define a special (isolated) set of images and a special -(isolated) set of hosts, such that the isolated images can only run on the -isolated hosts, and the isolated hosts can only run isolated images. The flag -``restrict_isolated_hosts_to_isolated_images`` can be used to force isolated -hosts to only run isolated images. - -The logic within the filter depends on the -``restrict_isolated_hosts_to_isolated_images`` config option, which defaults -to True. When True, a volume-backed instance will not be put on an isolated -host. When False, a volume-backed instance can go on any host, isolated or -not. - -The admin must specify the isolated set of images and hosts in the -``nova.conf`` file using the ``isolated_hosts`` and ``isolated_images`` -configuration options. For example: - -.. code-block:: ini - - [filter_scheduler] - isolated_hosts = server1, server2 - isolated_images = 342b492c-128f-4a42-8d3a-c5088cf27d13, ebd267a6-ca86-4d6c-9a0e-bd132d6b7d09 - -.. _IoOpsFilter: - -IoOpsFilter ------------ - -The IoOpsFilter filters hosts by concurrent I/O operations on it. Hosts with -too many concurrent I/O operations will be filtered out. The -``max_io_ops_per_host`` option specifies the maximum number of I/O intensive -instances allowed to run on a host. A host will be ignored by the scheduler if -more than ``max_io_ops_per_host`` instances in build, resize, snapshot, -migrate, rescue or unshelve task states are running on it. - -JsonFilter ----------- - -.. warning:: This filter is not enabled by default and not comprehensively - tested, and thus could fail to work as expected in non-obvious ways. - Furthermore, the filter variables are based on attributes of the - `HostState`_ class which could change from release to release so usage - of this filter is generally not recommended. Consider using other filters - such as the :ref:`ImagePropertiesFilter` or - :ref:`traits-based scheduling `. - -The JsonFilter allows a user to construct a custom filter by passing a -scheduler hint in JSON format. The following operators are supported: - -* = -* < -* > -* in -* <= -* >= -* not -* or -* and - -The filter supports any attribute in the `HostState`_ class such as the -following variables: - -* ``$free_ram_mb`` -* ``$free_disk_mb`` -* ``$hypervisor_hostname`` -* ``$total_usable_ram_mb`` -* ``$vcpus_total`` -* ``$vcpus_used`` - -Using the :command:`openstack server create` command, use the ``--hint`` flag: - -.. code-block:: console - - $ openstack server create --image 827d564a-e636-4fc4-a376-d36f7ebe1747 \ - --flavor 1 --hint query='[">=","$free_ram_mb",1024]' server1 - -With the API, use the ``os:scheduler_hints`` key: - -.. code-block:: json - - { - "server": { - "name": "server-1", - "imageRef": "cedef40a-ed67-4d10-800e-17455edce175", - "flavorRef": "1" - }, - "os:scheduler_hints": { - "query": "[\">=\",\"$free_ram_mb\",1024]" - } - } - -.. _HostState: https://opendev.org/openstack/nova/src/branch/master/nova/scheduler/host_manager.py - -MetricsFilter -------------- - -Filters hosts based on meters ``weight_setting``. Only hosts with the -available meters are passed so that the metrics weigher will not fail due to -these hosts. - -NUMATopologyFilter ------------------- - -Filters hosts based on the NUMA topology that was specified for the instance -through the use of flavor ``extra_specs`` in combination with the image -properties, as described in detail in the `related nova-spec document -`_. Filter -will try to match the exact NUMA cells of the instance to those of the host. It -will consider the standard over-subscription limits for each host NUMA cell, -and provide limits to the compute host accordingly. - -.. note:: - - If instance has no topology defined, it will be considered for any host. If - instance has a topology defined, it will be considered only for NUMA capable - hosts. - -.. _NumInstancesFilter: - -NumInstancesFilter ------------------- - -Hosts that have more instances running than specified by the -``max_instances_per_host`` option are filtered out when this filter is in -place. - -PciPassthroughFilter --------------------- - -The filter schedules instances on a host if the host has devices that meet the -device requests in the ``extra_specs`` attribute for the flavor. - -SameHostFilter --------------- - -Schedules the instance on the same host as another instance in a set of -instances. To take advantage of this filter, the requester must pass a -scheduler hint, using ``same_host`` as the key and a list of instance UUIDs as -the value. This filter is the opposite of the ``DifferentHostFilter``. Using -the :command:`openstack server create` command, use the ``--hint`` flag: - -.. code-block:: console - - $ openstack server create --image cedef40a-ed67-4d10-800e-17455edce175 \ - --flavor 1 --hint same_host=a0cf03a5-d921-4877-bb5c-86d26cf818e1 \ - --hint same_host=8c19174f-4220-44f0-824a-cd1eeef10287 server-1 - -With the API, use the ``os:scheduler_hints`` key: - -.. code-block:: json - - { - "server": { - "name": "server-1", - "imageRef": "cedef40a-ed67-4d10-800e-17455edce175", - "flavorRef": "1" - }, - "os:scheduler_hints": { - "same_host": [ - "a0cf03a5-d921-4877-bb5c-86d26cf818e1", - "8c19174f-4220-44f0-824a-cd1eeef10287" - ] - } - } - -.. _ServerGroupAffinityFilter: - -ServerGroupAffinityFilter -------------------------- - -The ServerGroupAffinityFilter ensures that an instance is scheduled on to a -host from a set of group hosts. To take advantage of this filter, the requester -must create a server group with an ``affinity`` policy, and pass a scheduler -hint, using ``group`` as the key and the server group UUID as the value. Using -the :command:`openstack server create` command, use the ``--hint`` flag. For -example: - -.. code-block:: console - - $ openstack server group create --policy affinity group-1 - $ openstack server create --image IMAGE_ID --flavor 1 \ - --hint group=SERVER_GROUP_UUID server-1 - -.. _ServerGroupAntiAffinityFilter: - -ServerGroupAntiAffinityFilter ------------------------------ - -The ServerGroupAntiAffinityFilter ensures that each instance in a group is on a -different host. To take advantage of this filter, the requester must create a -server group with an ``anti-affinity`` policy, and pass a scheduler hint, using -``group`` as the key and the server group UUID as the value. Using the -:command:`openstack server create` command, use the ``--hint`` flag. For -example: - -.. code-block:: console - - $ openstack server group create --policy anti-affinity group-1 - $ openstack server create --image IMAGE_ID --flavor 1 \ - --hint group=SERVER_GROUP_UUID server-1 - -SimpleCIDRAffinityFilter ------------------------- - -Schedules the instance based on host IP subnet range. To take advantage of -this filter, the requester must specify a range of valid IP address in CIDR -format, by passing two scheduler hints: - -``build_near_host_ip`` - The first IP address in the subnet (for example, ``192.168.1.1``) - -``cidr`` - The CIDR that corresponds to the subnet (for example, ``/24``) - -Using the :command:`openstack server create` command, use the ``--hint`` flag. -For example, to specify the IP subnet ``192.168.1.1/24``: - -.. code-block:: console - - $ openstack server create --image cedef40a-ed67-4d10-800e-17455edce175 \ - --flavor 1 --hint build_near_host_ip=192.168.1.1 --hint cidr=/24 server-1 - -With the API, use the ``os:scheduler_hints`` key: - -.. code-block:: json - - { - "server": { - "name": "server-1", - "imageRef": "cedef40a-ed67-4d10-800e-17455edce175", - "flavorRef": "1" - }, - "os:scheduler_hints": { - "build_near_host_ip": "192.168.1.1", - "cidr": "24" - } - } - -.. _weights: - -Weights -~~~~~~~ - -When resourcing instances, the filter scheduler filters and weights each host -in the list of acceptable hosts. Each time the scheduler selects a host, it -virtually consumes resources on it, and subsequent selections are adjusted -accordingly. This process is useful when the customer asks for the same large -amount of instances, because weight is computed for each requested instance. - -All weights are normalized before being summed up; the host with the largest -weight is given the highest priority. - -**Weighting hosts** - -.. figure:: /_static/images/nova-weighting-hosts.png - -Hosts are weighted based on the following options in the -``/etc/nova/nova.conf`` file: - -.. list-table:: Host weighting options - :header-rows: 1 - :widths: 10, 25, 60 - - * - Section - - Option - - Description - * - [DEFAULT] - - ``ram_weight_multiplier`` - - By default, the scheduler spreads instances across all hosts evenly. - Set the ``ram_weight_multiplier`` option to a negative number if you - prefer stacking instead of spreading. Use a floating-point value. - If the per aggregate ``ram_weight_multiplier`` - metadata is set, this multiplier will override the configuration option - value. - * - [DEFAULT] - - ``disk_weight_multiplier`` - - By default, the scheduler spreads instances across all hosts evenly. - Set the ``disk_weight_multiplier`` option to a negative number if you - prefer stacking instead of spreading. Use a floating-point value. - If the per aggregate ``disk_weight_multiplier`` - metadata is set, this multiplier will override the configuration option - value. - * - [DEFAULT] - - ``cpu_weight_multiplier`` - - By default, the scheduler spreads instances across all hosts evenly. - Set the ``cpu_weight_multiplier`` option to a negative number if you - prefer stacking instead of spreading. Use a floating-point value. - If the per aggregate ``cpu_weight_multiplier`` metadata is set, this - multiplier will override the configuration option value. - * - [DEFAULT] - - ``scheduler_host_subset_size`` - - New instances are scheduled on a host that is chosen randomly from a - subset of the N best hosts. This property defines the subset size from - which a host is chosen. A value of 1 chooses the first host returned by - the weighting functions. This value must be at least 1. A value less - than 1 is ignored, and 1 is used instead. Use an integer value. - * - [DEFAULT] - - ``scheduler_weight_classes`` - - Defaults to ``nova.scheduler.weights.all_weighers``. Hosts are then - weighted and sorted with the largest weight winning. - * - [DEFAULT] - - ``io_ops_weight_multiplier`` - - Multiplier used for weighing host I/O operations. A negative value means - a preference to choose light workload compute hosts. - If the per aggregate ``io_ops_weight_multiplier`` - metadata is set, this multiplier will override the configuration option - value. - * - [filter_scheduler] - - ``soft_affinity_weight_multiplier`` - - Multiplier used for weighing hosts for group soft-affinity. Only a - positive value is allowed. - * - [filter_scheduler] - If the per aggregate ``soft_affinity_weight_multiplier`` - metadata is set, this multiplier will override the configuration option - value. - - ``soft_anti_affinity_weight_multiplier`` - - Multiplier used for weighing hosts for group soft-anti-affinity. Only a - positive value is allowed. - If the per aggregate ``soft_anti_affinity_weight_multiplier`` - metadata is set, this multiplier will override the configuration option - value. - * - [filter_scheduler] - - ``build_failure_weight_multiplier`` - - Multiplier used for weighing hosts which have recent build failures. A - positive value increases the significance of build failures reported by - the host recently, making them less likely to be chosen. - If the per aggregate ``build_failure_weight_multiplier`` - metadata is set, this multiplier will override the configuration option - value. - * - [filter_scheduler] - - ``cross_cell_move_weight_multiplier`` - - Multiplier used for weighing hosts during a cross-cell move. By default, - prefers hosts within the same source cell when migrating a server. - If the per aggregate ``cross_cell_move_weight_multiplier`` - metadata is set, this multiplier will override the configuration option - value. - * - [metrics] - - ``weight_multiplier`` - - Multiplier for weighting meters. Use a floating-point value. - If the per aggregate ``metrics_weight_multiplier`` - metadata is set, this multiplier will override the configuration option - value. - * - [metrics] - - ``weight_setting`` - - Determines how meters are weighted. Use a comma-separated list of - metricName=ratio. For example: ``name1=1.0, name2=-1.0`` results in: - ``name1.value * 1.0 + name2.value * -1.0`` - * - [metrics] - - ``required`` - - Specifies how to treat unavailable meters: - - * True - Raises an exception. To avoid the raised exception, you should - use the scheduler filter ``MetricFilter`` to filter out hosts with - unavailable meters. - * False - Treated as a negative factor in the weighting process (uses - the ``weight_of_unavailable`` option). - * - [metrics] - - ``weight_of_unavailable`` - - If ``required`` is set to False, and any one of the meters set by - ``weight_setting`` is unavailable, the ``weight_of_unavailable`` value - is returned to the scheduler. - -For example: - -.. code-block:: ini - - [DEFAULT] - scheduler_host_subset_size = 1 - scheduler_weight_classes = nova.scheduler.weights.all_weighers - ram_weight_multiplier = 1.0 - io_ops_weight_multiplier = 2.0 - soft_affinity_weight_multiplier = 1.0 - soft_anti_affinity_weight_multiplier = 1.0 - [metrics] - weight_multiplier = 1.0 - weight_setting = name1=1.0, name2=-1.0 - required = false - weight_of_unavailable = -10000.0 - -Utilization aware scheduling -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -It is possible to schedule VMs using advanced scheduling decisions. These -decisions are made based on enhanced usage statistics encompassing data like -memory cache utilization, memory bandwidth utilization, or network bandwidth -utilization. This is disabled by default. The administrator can configure how -the metrics are weighted in the configuration file by using the -``weight_setting`` configuration option in the ``nova.conf`` configuration -file. For example to configure metric1 with ratio1 and metric2 with ratio2: - -.. code-block:: ini - - weight_setting = "metric1=ratio1, metric2=ratio2" - -Allocation ratios -~~~~~~~~~~~~~~~~~ - -The following configuration options exist to control allocation ratios -per compute node to support over-commit of resources: - -* :oslo.config:option:`cpu_allocation_ratio`: allows overriding the VCPU - inventory allocation ratio for a compute node -* :oslo.config:option:`ram_allocation_ratio`: allows overriding the MEMORY_MB - inventory allocation ratio for a compute node -* :oslo.config:option:`disk_allocation_ratio`: allows overriding the DISK_GB - inventory allocation ratio for a compute node - -Prior to the 19.0.0 Stein release, if left unset, the ``cpu_allocation_ratio`` -defaults to 16.0, the ``ram_allocation_ratio`` defaults to 1.5, and the -``disk_allocation_ratio`` defaults to 1.0. - -Starting with the 19.0.0 Stein release, the following configuration options -control the initial allocation ratio values for a compute node: - -* :oslo.config:option:`initial_cpu_allocation_ratio`: the initial VCPU - inventory allocation ratio for a new compute node record, defaults to 16.0 -* :oslo.config:option:`initial_ram_allocation_ratio`: the initial MEMORY_MB - inventory allocation ratio for a new compute node record, defaults to 1.5 -* :oslo.config:option:`initial_disk_allocation_ratio`: the initial DISK_GB - inventory allocation ratio for a new compute node record, defaults to 1.0 - -Scheduling considerations -------------------------- - -The allocation ratio configuration is used both during reporting of compute -node `resource provider inventory`_ to the placement service and during -scheduling. - -.. _resource provider inventory: https://docs.openstack.org/api-ref/placement/?expanded=#resource-provider-inventories - -Usage scenarios ---------------- - -Since allocation ratios can be set via nova configuration, host aggregate -metadata and the placement API, it can be confusing to know which should be -used. This really depends on your scenario. A few common scenarios are detailed -here. - -1. When the deployer wants to **always** set an override value for a resource - on a compute node, the deployer would ensure that the - ``[DEFAULT]/cpu_allocation_ratio``, ``[DEFAULT]/ram_allocation_ratio`` and - ``[DEFAULT]/disk_allocation_ratio`` configuration options are set to a - non-None value (or greater than 0.0 before the 19.0.0 Stein release). This - will make the ``nova-compute`` service overwrite any externally-set - allocation ratio values set via the placement REST API. - -2. When the deployer wants to set an **initial** value for a compute node - allocation ratio but wants to allow an admin to adjust this afterwards - without making any configuration file changes, the deployer would set the - ``[DEFAULT]/initial_cpu_allocation_ratio``, - ``[DEFAULT]/initial_ram_allocation_ratio`` and - ``[DEFAULT]/initial_disk_allocation_ratio`` configuration options and then - manage the allocation ratios using the placement REST API (or - `osc-placement`_ command line interface). For example: - - .. code-block:: console - - $ openstack resource provider inventory set --resource VCPU:allocation_ratio=1.0 --amend 815a5634-86fb-4e1e-8824-8a631fee3e06 - -3. When the deployer wants to **always** use the placement API to set - allocation ratios, then the deployer should ensure that - ``[DEFAULT]/xxx_allocation_ratio`` options are all set to None (the - default since 19.0.0 Stein, 0.0 before Stein) and then - manage the allocation ratios using the placement REST API (or - `osc-placement`_ command line interface). - - This scenario is the workaround for - `bug 1804125 `_. - -.. _osc-placement: https://docs.openstack.org/osc-placement/latest/index.html - -.. _hypervisor-specific-considerations: - -Hypervisor-specific considerations ----------------------------------- - -Nova provides three configuration options, -:oslo.config:option:`reserved_host_cpus`, -:oslo.config:option:`reserved_host_memory_mb`, and -:oslo.config:option:`reserved_host_disk_mb`, that can be used to set aside some -number of resources that will not be consumed by an instance, whether these -resources are overcommitted or not. Some virt drivers may benefit from the use -of these options to account for hypervisor-specific overhead. - -HyperV - Hyper-V creates a VM memory file on the local disk when an instance starts. - The size of this file corresponds to the amount of RAM allocated to the - instance. - - You should configure the - :oslo.config:option:`reserved_host_disk_mb` config option to - account for this overhead, based on the amount of memory available - to instances. - -Cells considerations -~~~~~~~~~~~~~~~~~~~~ - -By default cells are enabled for scheduling new instances but they can be -disabled (new schedulings to the cell are blocked). This may be useful for -users while performing cell maintenance, failures or other interventions. It is -to be noted that creating pre-disabled cells and enabling/disabling existing -cells should either be followed by a restart or SIGHUP of the nova-scheduler -service for the changes to take effect. - -Command-line interface ----------------------- - -The :command:`nova-manage` command-line client supports the cell-disable -related commands. To enable or disable a cell, use -:command:`nova-manage cell_v2 update_cell` and to create pre-disabled cells, -use :command:`nova-manage cell_v2 create_cell`. See the -:ref:`man-page-cells-v2` man page for details on command usage. - - -.. _compute-capabilities-as-traits: - -Compute capabilities as traits -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Starting with the 19.0.0 Stein release, the ``nova-compute`` service will -report certain ``COMPUTE_*`` traits based on its compute driver capabilities -to the placement service. The traits will be associated with the resource -provider for that compute service. These traits can be used during scheduling -by configuring flavors with -:ref:`Required traits ` or -:ref:`Forbidden traits `. For example, if you -have a host aggregate with a set of compute nodes that support multi-attach -volumes, you can restrict a flavor to that aggregate by adding the -``trait:COMPUTE_VOLUME_MULTI_ATTACH=required`` extra spec to the flavor and -then restrict the flavor to the aggregate -:ref:`as normal `. - -Here is an example of a libvirt compute node resource provider that is -exposing some CPU features as traits, driver capabilities as traits, and a -custom trait denoted by the ``CUSTOM_`` prefix: - -.. code-block:: console - - $ openstack --os-placement-api-version 1.6 resource provider trait list \ - > d9b3dbc4-50e2-42dd-be98-522f6edaab3f --sort-column name - +---------------------------------------+ - | name | - +---------------------------------------+ - | COMPUTE_DEVICE_TAGGING | - | COMPUTE_NET_ATTACH_INTERFACE | - | COMPUTE_NET_ATTACH_INTERFACE_WITH_TAG | - | COMPUTE_TRUSTED_CERTS | - | COMPUTE_VOLUME_ATTACH_WITH_TAG | - | COMPUTE_VOLUME_EXTEND | - | COMPUTE_VOLUME_MULTI_ATTACH | - | CUSTOM_IMAGE_TYPE_RBD | - | HW_CPU_X86_MMX | - | HW_CPU_X86_SSE | - | HW_CPU_X86_SSE2 | - | HW_CPU_X86_SVM | - +---------------------------------------+ - -**Rules** - -There are some rules associated with capability-defined traits. - -1. The compute service "owns" these traits and will add/remove them when the - ``nova-compute`` service starts and when the ``update_available_resource`` - periodic task runs, with run intervals controlled by config option - :oslo.config:option:`update_resources_interval`. - -2. The compute service will not remove any custom traits set on the resource - provider externally, such as the ``CUSTOM_IMAGE_TYPE_RBD`` trait in the - example above. - -3. If compute-owned traits are removed from the resource provider externally, - for example by running ``openstack resource provider trait delete ``, - the compute service will add its traits again on restart or SIGHUP. - -4. If a compute trait is set on the resource provider externally which is not - supported by the driver, for example by adding the ``COMPUTE_VOLUME_EXTEND`` - trait when the driver does not support that capability, the compute service - will automatically remove the unsupported trait on restart or SIGHUP. - -5. Compute capability traits are standard traits defined in the `os-traits`_ - library. - -.. _os-traits: https://opendev.org/openstack/os-traits/src/branch/master/os_traits/compute - -:ref:`Further information on capabilities and traits -` can be found in the -:doc:`Technical Reference Deep Dives section `. diff --git a/doc/source/admin/cpu-topologies.rst b/doc/source/admin/cpu-topologies.rst index a012d6b7aed3..8995e5f50b16 100644 --- a/doc/source/admin/cpu-topologies.rst +++ b/doc/source/admin/cpu-topologies.rst @@ -93,7 +93,7 @@ guest OS. In all cases where NUMA awareness is used, the ``NUMATopologyFilter`` filter must be enabled. Details on this filter are provided in -:doc:`/admin/configuration/schedulers`. +:doc:`/admin/scheduling`. .. caution:: diff --git a/doc/source/admin/index.rst b/doc/source/admin/index.rst index 055bbe5e4120..960034ab8ff3 100644 --- a/doc/source/admin/index.rst +++ b/doc/source/admin/index.rst @@ -77,6 +77,7 @@ responsibilities of services and drivers are: remote-console-access service-groups node-down + scheduling upgrades diff --git a/doc/source/admin/scheduling.rst b/doc/source/admin/scheduling.rst new file mode 100644 index 000000000000..0b93792ac7ac --- /dev/null +++ b/doc/source/admin/scheduling.rst @@ -0,0 +1,1416 @@ +================== +Compute schedulers +================== + +Compute uses the ``nova-scheduler`` service to determine how to dispatch +compute requests. For example, the ``nova-scheduler`` service determines on +which host or node a VM should launch. You can configure the scheduler through +a variety of options. + +In the default configuration, this scheduler considers hosts that meet all the +following criteria: + +* Are in the requested :term:`Availability Zone` (``AvailabilityZoneFilter``). + +* Can service the request meaning the nova-compute service handling the target + node is available and not disabled (``ComputeFilter``). + +* Satisfy the extra specs associated with the instance type + (``ComputeCapabilitiesFilter``). + +* Satisfy any architecture, hypervisor type, or virtual machine mode properties + specified on the instance's image properties (``ImagePropertiesFilter``). + +* Are on a different host than other instances of a group (if requested) + (``ServerGroupAntiAffinityFilter``). + +* Are in a set of group hosts (if requested) (``ServerGroupAffinityFilter``). + +The scheduler chooses a new host when an instance is migrated, resized, +evacuated or unshelved after being shelve offloaded. + +When evacuating instances from a host, the scheduler service honors the target +host defined by the administrator on the :command:`nova evacuate` command. If +a target is not defined by the administrator, the scheduler determines the +target host. For information about instance evacuation, see +:ref:`Evacuate instances `. + + +.. _compute-scheduler-filters: + +Prefilters +---------- + +As of the Rocky release, the scheduling process includes a prefilter step to +increase the efficiency of subsequent stages. These *prefilters* are largely +optional and serve to augment the request that is sent to placement to reduce +the set of candidate compute hosts based on attributes that placement is able +to answer for us ahead of time. In addition to the prefilters listed here, also +see :ref:`tenant-isolation-with-placement` and +:ref:`availability-zones-with-placement`. + +Compute Image Type Support +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 20.0.0 (Train) + +Starting in the Train release, there is a prefilter available for +excluding compute nodes that do not support the ``disk_format`` of the +image used in a boot request. This behavior is enabled by setting +:oslo.config:option:`scheduler.query_placement_for_image_type_support` to +``True``. For example, the libvirt driver, when using ceph as an ephemeral +backend, does not support ``qcow2`` images (without an expensive conversion +step). In this case (and especially if you have a mix of ceph and +non-ceph backed computes), enabling this feature will ensure that the +scheduler does not send requests to boot a ``qcow2`` image to computes +backed by ceph. + +Compute Disabled Status Support +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 20.0.0 (Train) + +Starting in the Train release, there is a mandatory `pre-filter +`_ +which will exclude disabled compute nodes similar to (but does not fully +replace) the `ComputeFilter`_. Compute node resource providers with the +``COMPUTE_STATUS_DISABLED`` trait will be excluded as scheduling candidates. +The trait is managed by the ``nova-compute`` service and should mirror the +``disabled`` status on the related compute service record in the +`os-services`_ API. For example, if a compute service's status is ``disabled``, +the related compute node resource provider(s) for that service should have the +``COMPUTE_STATUS_DISABLED`` trait. When the service status is ``enabled`` the +``COMPUTE_STATUS_DISABLED`` trait shall be removed. + +If the compute service is down when the status is changed, the trait will be +synchronized by the compute service when it is restarted. Similarly, if an +error occurs when trying to add or remove the trait on a given resource +provider, the trait will be synchronized when the ``update_available_resource`` +periodic task runs - which is controlled by the +:oslo.config:option:`update_resources_interval` configuration option. + +.. _os-services: https://docs.openstack.org/api-ref/compute/#compute-services-os-services + +Isolate Aggregates +~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 20.0.0 (Train) + +Starting in the Train release, there is an optional placement pre-request filter +:doc:`/reference/isolate-aggregates` +When enabled, the traits required in the server's flavor and image must be at +least those required in an aggregate's metadata in order for the server to be +eligible to boot on hosts in that aggregate. + + +The Filter Scheduler +-------------------- + +.. versionchanged:: 23.0.0 (Wallaby) + + Support for custom filters was removed. Only the filter scheduler is now + supported by nova. + +Nova's scheduler, known as the *filter scheduler*, supports filtering and +weighting to make informed decisions on where a new instance should be created. + +When the scheduler receives a request for a resource, it first applies filters +to determine which hosts are eligible for consideration when dispatching a +resource. Filters are binary: either a host is accepted by the filter, or it is +rejected. Hosts that are accepted by the filter are then processed by a +different algorithm to decide which hosts to use for that request, described in +the :ref:`weights` section. + +**Filtering** + +.. figure:: /_static/images/filtering-workflow-1.png + +The :oslo.config:option:`filter_scheduler.available_filters` config option +provides the Compute service with the list of the filters that are available +for use by the scheduler. The default setting specifies all of the filters that +are included with the Compute service. This configuration option can be +specified multiple times. For example, if you implemented your own custom +filter in Python called ``myfilter.MyFilter`` and you wanted to use both the +built-in filters and your custom filter, your :file:`nova.conf` file would +contain: + +.. code-block:: ini + + [filter_scheduler] + available_filters = nova.scheduler.filters.all_filters + available_filters = myfilter.MyFilter + +The :oslo.config:option:`filter_scheduler.enabled_filters` configuration option +in ``nova.conf`` defines the list of filters that are applied by the +``nova-scheduler`` service. + + +Filters +------- + +The following sections describe the available compute filters. + +Filters are configured using the following config options: + +- :oslo.config:option:`filter_scheduler.available_filters` - Defines filter + classes made available to the scheduler. This setting can be used multiple + times. +- :oslo.config:option:`filter_scheduler.enabled_filters` - Of the available + filters, defines those that the scheduler uses by default. + +Each filter selects hosts in a different way and has different costs. The order +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 ``NUMATopologyFilter``. + +In medium/large environments having AvailabilityZoneFilter before any +capability or resource calculating filters can be useful. + +.. _AggregateImagePropertiesIsolation: + +``AggregateImagePropertiesIsolation`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. versionchanged:: 12.0.0 (Liberty) + + Prior to 12.0.0 Liberty, it was possible to specify and use arbitrary + metadata with this filter. Starting in Liberty, nova only parses + :glance-doc:`standard metadata `. If + you wish to use arbitrary metadata, consider using the + :ref:`AggregateInstanceExtraSpecsFilter` filter instead. + +Matches properties defined in an image's metadata against those of aggregates +to determine host matches: + +* If a host belongs to an aggregate and the aggregate defines one or more + metadata that matches an image's properties, that host is a candidate to boot + the image's instance. + +* If a host does not belong to any aggregate, it can boot instances from all + images. + +For example, the following aggregate ``myWinAgg`` has the Windows operating +system as metadata (named 'windows'): + +.. code-block:: console + + $ openstack aggregate show myWinAgg + +-------------------+----------------------------+ + | Field | Value | + +-------------------+----------------------------+ + | availability_zone | zone1 | + | created_at | 2017-01-01T15:36:44.000000 | + | deleted | False | + | deleted_at | None | + | hosts | ['sf-devel'] | + | id | 1 | + | name | myWinAgg | + | properties | os_distro='windows' | + | updated_at | None | + +-------------------+----------------------------+ + +In this example, because the following Win-2012 image has the ``windows`` +property, it boots on the ``sf-devel`` host (all other filters being equal): + +.. code-block:: console + + $ openstack image show Win-2012 + +------------------+------------------------------------------------------+ + | Field | Value | + +------------------+------------------------------------------------------+ + | checksum | ee1eca47dc88f4879d8a229cc70a07c6 | + | container_format | bare | + | created_at | 2016-12-13T09:30:30Z | + | disk_format | qcow2 | + | ... | + | name | Win-2012 | + | ... | + | properties | os_distro='windows' | + | ... | + +You can configure the ``AggregateImagePropertiesIsolation`` filter by using the +following options in the ``nova.conf`` file: + +- :oslo.config:option:`filter_scheduler.aggregate_image_properties_isolation_namespace` +- :oslo.config:option:`filter_scheduler.aggregate_image_properties_isolation_separator` + +.. note:: + + This filter has limitations as described in `bug 1677217 + `_ + which are addressed in placement :doc:`/reference/isolate-aggregates` + request filter. + +Refer to :doc:`/admin/aggregates` for more information. + + +.. _AggregateInstanceExtraSpecsFilter: + +``AggregateInstanceExtraSpecsFilter`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Matches properties defined in extra specs for an instance type against +admin-defined properties on a host aggregate. Works with specifications that +are scoped with ``aggregate_instance_extra_specs``. Multiple values can be +given, as a comma-separated list. For backward compatibility, also works with +non-scoped specifications; this action is highly discouraged because it +conflicts with :ref:`ComputeCapabilitiesFilter` filter when you enable both +filters. + +Refer to :doc:`/admin/aggregates` for more information. + + +.. _AggregateIoOpsFilter: + +``AggregateIoOpsFilter`` +~~~~~~~~~~~~~~~~~~~~~~~~ + +Filters host by disk allocation with a per-aggregate ``max_io_ops_per_host`` +value. If the per-aggregate value is not found, the value falls back to the +global setting defined by the +`:oslo.config:option:`filter_scheduler.max_io_ops_per_host` config option. +If the host is in more than one aggregate and more than one value is found, the +minimum value will be used. + +Refer to :doc:`/admin/aggregates` and :ref:`IoOpsFilter` for more information. + + +.. _AggregateMultiTenancyIsolation: + +``AggregateMultiTenancyIsolation`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Ensures hosts in tenant-isolated host aggregates will only be available to a +specified set of tenants. If a host is in an aggregate that has the +``filter_tenant_id`` metadata key, the host can build instances from only that +tenant or comma-separated list of tenants. A host can be in different +aggregates. If a host does not belong to an aggregate with the metadata key, +the host can build instances from all tenants. This does not restrict the +tenant from creating servers on hosts outside the tenant-isolated aggregate. + +For example, consider there are two available hosts for scheduling, ``HostA`` +and ``HostB``. ``HostB`` is in an aggregate isolated to tenant ``X``. A server +create request from tenant ``X`` will result in either ``HostA`` *or* ``HostB`` +as candidates during scheduling. A server create request from another tenant +``Y`` will result in only ``HostA`` being a scheduling candidate since +``HostA`` is not part of the tenant-isolated aggregate. + +.. note:: + + There is a `known limitation + `_ with the number of tenants + that can be isolated per aggregate using this filter. This limitation does + not exist, however, for the :ref:`tenant-isolation-with-placement` + filtering capability added in the 18.0.0 Rocky release. + + +.. _AggregateNumInstancesFilter: + +``AggregateNumInstancesFilter`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Filters host in an aggregate by number of instances with a per-aggregate +``max_instances_per_host`` value. If the per-aggregate value is not found, the +value falls back to the global setting defined by the +:oslo.config:option:`filter_scheduler.max_instances_per_host` config option. +If the host is in more than one aggregate and thus more than one value is +found, the minimum value will be used. + +Refer to :doc:`/admin/aggregates` and :ref:`NumInstancesFilter` for more +information. + + +.. _AggregateTypeAffinityFilter: + +``AggregateTypeAffinityFilter`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Filters hosts in an aggregate if the name of the instance's flavor matches that +of the ``instance_type`` key set in the aggregate's metadata or if the +``instance_type`` key is not set. + +The value of the ``instance_type`` metadata entry is a string that may contain +either a single ``instance_type`` name or a comma-separated list of +``instance_type`` names, such as ``m1.nano`` or ``m1.nano,m1.small``. + +.. note:: + + Instance types are a historical name for flavors. + +Refer to :doc:`/admin/aggregates` for more information. + + +``AllHostsFilter`` +~~~~~~~~~~~~~~~~~~ + +This is a no-op filter. It does not eliminate any of the available hosts. + + +.. _AvailabilityZoneFilter: + +``AvailabilityZoneFilter`` +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Filters hosts by availability zone. It passes hosts matching the availability +zone specified in the instance properties. Use a comma to specify multiple +zones. The filter will then ensure it matches any zone specified. + +You must enable this filter for the scheduler to respect availability zones in +requests. + +Refer to :doc:`/admin/availability-zones` for more information. + +.. _ComputeCapabilitiesFilter: + +``ComputeCapabilitiesFilter`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Filters hosts by matching properties defined in flavor extra specs against compute +capabilities. If an extra specs key contains a colon (``:``), anything before +the colon is treated as a namespace and anything after the colon is treated as +the key to be matched. If a namespace is present and is not ``capabilities``, +the filter ignores the namespace. +For example ``capabilities:cpu_info:features`` is a valid scope format. +For backward compatibility, the filter also treats the +extra specs key as the key to be matched if no namespace is present; this +action is highly discouraged because it conflicts with +:ref:`AggregateInstanceExtraSpecsFilter` filter when you enable both filters. + +The extra specifications can have an operator at the beginning of the value +string of a key/value pair. If there is no operator specified, then a +default operator of ``s==`` is used. Valid operators are: + +* ``=`` (equal to or greater than as a number; same as vcpus case) +* ``==`` (equal to as a number) +* ``!=`` (not equal to as a number) +* ``>=`` (greater than or equal to as a number) +* ``<=`` (less than or equal to as a number) +* ``s==`` (equal to as a string) +* ``s!=`` (not equal to as a string) +* ``s>=`` (greater than or equal to as a string) +* ``s>`` (greater than as a string) +* ``s<=`` (less than or equal to as a string) +* ``s<`` (less than as a string) +* ```` (substring) +* ```` (all elements contained in collection) +* ```` (find one of these) + +Examples are: ``>= 5``, ``s== 2.1.0``, `` gcc``, `` aes mmx``, and +`` fpu gpu`` + +Some of attributes that can be used as useful key and their values contains: + +* ``free_ram_mb`` (compared with a number, values like ``>= 4096``) +* ``free_disk_mb`` (compared with a number, values like ``>= 10240``) +* ``host`` (compared with a string, values like `` compute``, ``s== compute_01``) +* ``hypervisor_type`` (compared with a string, values like ``s== QEMU``, ``s== powervm``) +* ``hypervisor_version`` (compared with a number, values like ``>= 1005003``, ``== 2000000``) +* ``num_instances`` (compared with a number, values like ``<= 10``) +* ``num_io_ops`` (compared with a number, values like ``<= 5``) +* ``vcpus_total`` (compared with a number, values like ``= 48``, ``>=24``) +* ``vcpus_used`` (compared with a number, values like ``= 0``, ``<= 10``) + +Some virt drivers support reporting CPU traits to the Placement service. With +that feature available, you should consider using traits in flavors instead of +``ComputeCapabilitiesFilter`` because traits provide consistent naming for CPU +features in some virt drivers and querying traits is efficient. For more +details, refer to :doc:`/user/support-matrix`, +:ref:`Required traits `, +:ref:`Forbidden traits ` and +`Report CPU features to the Placement service `_. + +Also refer to `Compute capabilities as traits`_. + + +.. _ComputeFilter: + +``ComputeFilter`` +----------------- + +Passes all hosts that are operational and enabled. + +In general, you should always enable this filter. + + +``DifferentHostFilter`` +----------------------- + +Schedules the instance on a different host from a set of instances. To take +advantage of this filter, the requester must pass a scheduler hint, using +``different_host`` as the key and a list of instance UUIDs as the value. This +filter is the opposite of the ``SameHostFilter``. + +For example, when using the :command:`openstack server create` command, use the +``--hint`` flag: + +.. code-block:: console + + $ openstack server create \ + --image cedef40a-ed67-4d10-800e-17455edce175 --flavor 1 \ + --hint different_host=a0cf03a5-d921-4877-bb5c-86d26cf818e1 \ + --hint different_host=8c19174f-4220-44f0-824a-cd1eeef10287 \ + server-1 + +With the API, use the ``os:scheduler_hints`` key. For example: + +.. code-block:: json + + { + "server": { + "name": "server-1", + "imageRef": "cedef40a-ed67-4d10-800e-17455edce175", + "flavorRef": "1" + }, + "os:scheduler_hints": { + "different_host": [ + "a0cf03a5-d921-4877-bb5c-86d26cf818e1", + "8c19174f-4220-44f0-824a-cd1eeef10287" + ] + } + } + + +.. _ImagePropertiesFilter: + +``ImagePropertiesFilter`` +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Filters hosts based on properties defined on the instance's image. It passes +hosts that can support the specified image properties contained in the +instance. Properties include the architecture, hypervisor type, hypervisor +version, and virtual machine mode. + +For example, an instance might require a host that runs an ARM-based processor, +and QEMU as the hypervisor. You can decorate an image with these properties by +using: + +.. code-block:: console + + $ openstack image set --architecture arm --property img_hv_type=qemu \ + img-uuid + +The image properties that the filter checks for are: + +``hw_architecture`` + Describes the machine architecture required by the image. Examples are + ``i686``, ``x86_64``, ``arm``, and ``ppc64``. + + .. versionchanged:: 12.0.0 (Liberty) + + This was previously called ``architecture``. + +``img_hv_type`` + Describes the hypervisor required by the image. Examples are ``qemu`` + and ``hyperv``. + + .. note:: + + ``qemu`` is used for both QEMU and KVM hypervisor types. + + .. versionchanged:: 12.0.0 (Liberty) + + This was previously called ``hypervisor_type``. + +``img_hv_requested_version`` + Describes the hypervisor version required by the image. The property is + supported for HyperV hypervisor type only. It can be used to enable support for + multiple hypervisor versions, and to prevent instances with newer HyperV tools + from being provisioned on an older version of a hypervisor. If available, the + property value is compared to the hypervisor version of the compute host. + + To filter the hosts by the hypervisor version, add the + ``img_hv_requested_version`` property on the image as metadata and pass an + operator and a required hypervisor version as its value: + + .. code-block:: console + + $ openstack image set --property hypervisor_type=hyperv --property \ + hypervisor_version_requires=">=6000" img-uuid + + .. versionchanged:: 12.0.0 (Liberty) + + This was previously called ``hypervisor_version_requires``. + +``hw_vm_mode`` + describes the hypervisor application binary interface (ABI) required by the + image. Examples are ``xen`` for Xen 3.0 paravirtual ABI, ``hvm`` for native + ABI, and ``exe`` for container virt executable ABI. + + .. versionchanged:: 12.0.0 (Liberty) + + This was previously called ``vm_mode``. + + +``IsolatedHostsFilter`` +~~~~~~~~~~~~~~~~~~~~~~~ + +Allows the admin to define a special (isolated) set of images and a special +(isolated) set of hosts, such that the isolated images can only run on the +isolated hosts, and the isolated hosts can only run isolated images. The flag +``restrict_isolated_hosts_to_isolated_images`` can be used to force isolated +hosts to only run isolated images. + +The logic within the filter depends on the +``restrict_isolated_hosts_to_isolated_images`` config option, which defaults +to True. When True, a volume-backed instance will not be put on an isolated +host. When False, a volume-backed instance can go on any host, isolated or +not. + +The admin must specify the isolated set of images and hosts using the +:oslo.config:option:`filter_scheduler.isolated_hosts` and +:oslo.config:option:`filter_scheduler.isolated_images` config options. +For example: + +.. code-block:: ini + + [filter_scheduler] + isolated_hosts = server1, server2 + isolated_images = 342b492c-128f-4a42-8d3a-c5088cf27d13, ebd267a6-ca86-4d6c-9a0e-bd132d6b7d09 + +You can also specify that isolated host only be used for specific isolated +images using the +:oslo.config:option:`filter_scheduler.restrict_isolated_hosts_to_isolated_images` +config option. + + +.. _IoOpsFilter: + +``IoOpsFilter`` +~~~~~~~~~~~~~~~ + +Filters hosts by concurrent I/O operations on it. Hosts with too many +concurrent I/O operations will be filtered out. The +:oslo.config:option:`filter_scheduler.max_io_ops_per_host` option specifies the +maximum number of I/O intensive instances allowed to run on a host. +A host will be ignored by the scheduler if more than +:oslo.config:option:`filter_scheduler.max_io_ops_per_host` instances in build, +resize, snapshot, migrate, rescue or unshelve task states are running on it. + + +``JsonFilter`` +~~~~~~~~~~~~~~~ + +.. warning:: + + This filter is not enabled by default and not comprehensively + tested, and thus could fail to work as expected in non-obvious ways. + Furthermore, the filter variables are based on attributes of the + `HostState`_ class which could change from release to release so usage + of this filter is generally not recommended. Consider using other filters + such as the :ref:`ImagePropertiesFilter` or + :ref:`traits-based scheduling `. + +Allows a user to construct a custom filter by passing a +scheduler hint in JSON format. The following operators are supported: + +* ``=`` +* ``<`` +* ``>`` +* ``in`` +* ``<=`` +* ``>=`` +* ``not`` +* ``or`` +* ``and`` + +Unlike most other filters that rely on information provided via scheduler +hints, this filter filters on attributes in the `HostState`_ class such as the +following variables: + +* ``$free_ram_mb`` +* ``$free_disk_mb`` +* ``$hypervisor_hostname`` +* ``$total_usable_ram_mb`` +* ``$vcpus_total`` +* ``$vcpus_used`` + +Using the :command:`openstack server create` command, use the ``--hint`` flag: + +.. code-block:: console + + $ openstack server create --image 827d564a-e636-4fc4-a376-d36f7ebe1747 \ + --flavor 1 --hint query='[">=","$free_ram_mb",1024]' server1 + +With the API, use the ``os:scheduler_hints`` key: + +.. code-block:: json + + { + "server": { + "name": "server-1", + "imageRef": "cedef40a-ed67-4d10-800e-17455edce175", + "flavorRef": "1" + }, + "os:scheduler_hints": { + "query": "[\">=\",\"$free_ram_mb\",1024]" + } + } + +.. _HostState: https://opendev.org/openstack/nova/src/branch/master/nova/scheduler/host_manager.py + + +``MetricsFilter`` +~~~~~~~~~~~~~~~~~ + +Use in collaboration with the ``MetricsWeigher`` weigher. Filters hosts that +do not report the metrics specified in +:oslo.config:option:`metrics.weight_setting`, thus ensuring the metrics +weigher will not fail due to these hosts. + + +.. _NUMATopologyFilter: + +``NUMATopologyFilter`` +~~~~~~~~~~~~~~~~~~~~~~ + +Filters hosts based on the NUMA topology that was specified for the instance +through the use of flavor ``extra_specs`` in combination with the image +properties, as described in detail in :doc:`/admin/cpu-topologies`. The filter +will try to match the exact NUMA cells of the instance to those of the host. It +will consider the standard over-subscription limits for each host NUMA cell, +and provide limits to the compute host accordingly. + +This filter is essential if using instances with features that rely on NUMA, +such as instance NUMA topologies or CPU pinning. + +.. note:: + + If instance has no topology defined, it will be considered for any host. If + instance has a topology defined, it will be considered only for NUMA capable + hosts. + + +.. _NumInstancesFilter: + +``NumInstancesFilter`` +~~~~~~~~~~~~~~~~~~~~~~ + +Filters hosts based on the number of instances running on them. Hosts that have +more instances running than specified by the +:oslo.config:option:`filter_scheduler.max_instances_per_host` config option are +filtered out. + + +.. _PciPassthroughFilter: + +``PciPassthroughFilter`` +~~~~~~~~~~~~~~~~~~~~~~~~ + +The filter schedules instances on a host if the host has devices that meet the +device requests in the ``extra_specs`` attribute for the flavor. + +This filter is essential if using instances with PCI device requests or where +SR-IOV-based networking is in use on hosts. + + +``SameHostFilter`` +~~~~~~~~~~~~~~~~~~ + +Schedules an instance on the same host as all other instances in a set of +instances. To take advantage of this filter, the requester must pass a +scheduler hint, using ``same_host`` as the key and a list of instance UUIDs as +the value. This filter is the opposite of the ``DifferentHostFilter``. + +For example, when using the :command:`openstack server create` command, use the +``--hint`` flag: + +.. code-block:: console + + $ openstack server create \ + --image cedef40a-ed67-4d10-800e-17455edce175 --flavor 1 \ + --hint same_host=a0cf03a5-d921-4877-bb5c-86d26cf818e1 \ + --hint same_host=8c19174f-4220-44f0-824a-cd1eeef10287 \ + server-1 + +With the API, use the ``os:scheduler_hints`` key: + +.. code-block:: json + + { + "server": { + "name": "server-1", + "imageRef": "cedef40a-ed67-4d10-800e-17455edce175", + "flavorRef": "1" + }, + "os:scheduler_hints": { + "same_host": [ + "a0cf03a5-d921-4877-bb5c-86d26cf818e1", + "8c19174f-4220-44f0-824a-cd1eeef10287" + ] + } + } + + +.. _ServerGroupAffinityFilter: + +``ServerGroupAffinityFilter`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Restricts instances belonging to a server group to the same host(s). To take +advantage of this filter, the requester must create a server group with an +``affinity`` policy, and pass a scheduler hint, using ``group`` as the key and +the server group UUID as the value. + +For example, when using the :command:`openstack server create` command, use the +``--hint`` flag: + +.. code-block:: console + + $ openstack server group create --policy affinity group-1 + $ openstack server create --image IMAGE_ID --flavor 1 \ + --hint group=SERVER_GROUP_UUID server-1 + + +.. _ServerGroupAntiAffinityFilter: + +``ServerGroupAntiAffinityFilter`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Restricts instances belonging to a server group to separate hosts. +To take advantage of this filter, the requester must create a +server group with an ``anti-affinity`` policy, and pass a scheduler hint, using +``group`` as the key and the server group UUID as the value. + +For example, when using the :command:`openstack server create` command, use the +``--hint`` flag: + +.. code-block:: console + + $ openstack server group create --policy anti-affinity group-1 + $ openstack server create --image IMAGE_ID --flavor 1 \ + --hint group=SERVER_GROUP_UUID server-1 + + +``SimpleCIDRAffinityFilter`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. todo:: + + Does this filter still work with neutron? + +Schedules the instance based on host IP subnet range. To take advantage of +this filter, the requester must specify a range of valid IP address in CIDR +format, by passing two scheduler hints: + +``build_near_host_ip`` + The first IP address in the subnet (for example, ``192.168.1.1``) + +``cidr`` + The CIDR that corresponds to the subnet (for example, ``/24``) + +When using the :command:`openstack server create` command, use the ``--hint`` +flag. For example, to specify the IP subnet ``192.168.1.1/24``: + +.. code-block:: console + + $ openstack server create \ + --image cedef40a-ed67-4d10-800e-17455edce175 --flavor 1 \ + --hint build_near_host_ip=192.168.1.1 --hint cidr=/24 \ + server-1 + +With the API, use the ``os:scheduler_hints`` key: + +.. code-block:: json + + { + "server": { + "name": "server-1", + "imageRef": "cedef40a-ed67-4d10-800e-17455edce175", + "flavorRef": "1" + }, + "os:scheduler_hints": { + "build_near_host_ip": "192.168.1.1", + "cidr": "24" + } + } + + +.. _weights: + +Weights +------- + +.. figure:: /_static/images/nova-weighting-hosts.png + +When resourcing instances, the filter scheduler filters and weights each host +in the list of acceptable hosts. Each time the scheduler selects a host, it +virtually consumes resources on it and subsequent selections are adjusted +accordingly. This process is useful when the customer asks for the same large +amount of instances because a weight is computed for each requested instance. + +In order to prioritize one weigher against another, all the weighers have to +define a multiplier that will be applied before computing the weight for a node. +All the weights are normalized beforehand so that the multiplier can be applied +easily.Therefore the final weight for the object will be:: + + weight = w1_multiplier * norm(w1) + w2_multiplier * norm(w2) + ... + +Hosts are weighted based on the following config options: + +- :oslo.config:option:`filter_scheduler.host_subset_size` +- :oslo.config:option:`filter_scheduler.weight_classes` + + +``RAMWeigher`` +~~~~~~~~~~~~~~ + +Compute weight based on available RAM on the compute node. +Sort with the largest weight winning. If the multiplier, +:oslo.config:option:`filter_scheduler.ram_weight_multiplier`, is negative, the +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. + + +``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). + +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. + + +``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 using the :oslo.config:option:`metrics.weight_setting` config +option. For example: + +.. code-block:: ini + + [metrics] + weight_setting = name1=1.0, name2=-1.0 + +You can specify the metrics that are required, along with the weight of those +that are not and are not available using the +:oslo.config:option:`metrics.required` and +:oslo.config:option:`metrics.weight_of_unavailable` config options, +respectively. + +Starting with the Stein release, if per-aggregate value with the key +`metrics_weight_multiplier` is found, this value would be chosen as the +metrics weight multiplier. Otherwise, it will fall back to the +:oslo.config:option:`metrics.weight_multiplier`. If more than +one value is found for a host in aggregate metadata, the minimum value will +be used. + + +``IoOpsWeigher`` +~~~~~~~~~~~~~~~~ + +The weigher can compute the weight based on the compute node +host's workload. The default is to preferably choose light workload compute +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. + +``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, +given three hosts - one with a single PCI device, one with many PCI devices, +and one with no PCI devices - nova should prioritise these differently based +on the demands of the instance. If the instance requests a single PCI device, +then the first of the hosts should be preferred. Similarly, if the instance +requests multiple PCI devices, then the second of these hosts would be +preferred. Finally, if the instance does not request a PCI device, then the +last of these hosts should be preferred. + +For this to be of any value, at least one of the :ref:`PciPassthroughFilter` or +:ref:`NUMATopologyFilter` filters must be enabled. + +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. + +.. important:: + + Only positive values are allowed for the multiplier of this weigher as a + negative value would force non-PCI instances away from non-PCI hosts, thus, + causing future scheduling issues. + +``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`. +If more than one value is found for a host in aggregate metadata, the +minimum value will be used. + +``ServerGroupSoftAntiAffinityWeigher`` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The weigher can compute the weight based on the number of instances that run on +the same server group as a negative 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`. +If more than one value is found for a host in aggregate metadata, the minimum +value will be used. + +``BuildFailureWeigher`` +~~~~~~~~~~~~~~~~~~~~~~~ + +Weigh hosts by the number of recent failed boot attempts. +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`. If +more than one value is found for a host in aggregate metadata, the minimum +value will be used. + +.. _cross-cell-weigher: + +``CrossCellWeigher`` +~~~~~~~~~~~~~~~~~~~~ + +.. versionadded:: 21.0.0 (Ussuri) + +Weighs hosts based on which cell they are in. "Local" cells are preferred when +moving an instance. Use configuration option +:oslo.config:option:`filter_scheduler.cross_cell_move_weight_multiplier` to +control the weight. If per-aggregate value with the key +`cross_cell_move_weight_multiplier` is found, this value would be chosen as the +cross-cell move weight multiplier. Otherwise, it will fall back to the +:oslo.config:option:`filter_scheduler.cross_cell_move_weight_multiplier`. If +more than one value is found for a host in aggregate metadata, the minimum +value will be used. + + +Utilization-aware scheduling +---------------------------- + +.. warning:: + + This feature is poorly tested and may not work as expected. It may be + removed in a future release. Use at your own risk. + +It is possible to schedule instances using advanced scheduling decisions. These +decisions are made based on enhanced usage statistics encompassing data like +memory cache utilization, memory bandwidth utilization, or network bandwidth +utilization. This is disabled by default. The administrator can configure how +the metrics are weighted in the configuration file by using the +:oslo.config:option:`metrics.weight_setting` config option. For example to +configure ``metric1`` with ``ratio1`` and ``metric2`` with ``ratio2``: + +.. code-block:: ini + + [metrics] + weight_setting = "metric1=ratio1, metric2=ratio2" + + +Allocation ratios +----------------- + +Allocation ratios allow for the overcommit of host resources. +The following configuration options exist to control allocation ratios +per compute node to support this overcommit of resources: + +* :oslo.config:option:`cpu_allocation_ratio` allows overriding the ``VCPU`` + inventory allocation ratio for a compute node +* :oslo.config:option:`ram_allocation_ratio` allows overriding the ``MEMORY_MB`` + inventory allocation ratio for a compute node +* :oslo.config:option:`disk_allocation_ratio` allows overriding the ``DISK_GB`` + inventory allocation ratio for a compute node + +Prior to the 19.0.0 Stein release, if left unset, the ``cpu_allocation_ratio`` +defaults to 16.0, the ``ram_allocation_ratio`` defaults to 1.5, and the +``disk_allocation_ratio`` defaults to 1.0. + +Starting with the 19.0.0 Stein release, the following configuration options +control the initial allocation ratio values for a compute node: + +* :oslo.config:option:`initial_cpu_allocation_ratio` the initial VCPU + inventory allocation ratio for a new compute node record, defaults to 16.0 +* :oslo.config:option:`initial_ram_allocation_ratio` the initial MEMORY_MB + inventory allocation ratio for a new compute node record, defaults to 1.5 +* :oslo.config:option:`initial_disk_allocation_ratio` the initial DISK_GB + inventory allocation ratio for a new compute node record, defaults to 1.0 + +Scheduling considerations +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The allocation ratio configuration is used both during reporting of compute +node `resource provider inventory`_ to the placement service and during +scheduling. + +.. _resource provider inventory: https://docs.openstack.org/api-ref/placement/?expanded=#resource-provider-inventories + +Usage scenarios +~~~~~~~~~~~~~~~ + +Since allocation ratios can be set via nova configuration, host aggregate +metadata and the placement API, it can be confusing to know which should be +used. This really depends on your scenario. A few common scenarios are detailed +here. + +1. When the deployer wants to **always** set an override value for a resource + on a compute node, the deployer should ensure that the + :oslo.config:option:`DEFAULT.cpu_allocation_ratio`, + :oslo.config:option:`DEFAULT.ram_allocation_ratio` and + :oslo.config:option:`DEFAULT.disk_allocation_ratio` configuration options + are set to a non-None value. + This will make the ``nova-compute`` service overwrite any externally-set + allocation ratio values set via the placement REST API. + +2. When the deployer wants to set an **initial** value for a compute node + allocation ratio but wants to allow an admin to adjust this afterwards + without making any configuration file changes, the deployer should set the + :oslo.config:option:`DEFAULT.initial_cpu_allocation_ratio`, + :oslo.config:option:`DEFAULT.initial_ram_allocation_ratio` and + :oslo.config:option:`DEFAULT.initial_disk_allocation_ratio` configuration + options and then manage the allocation ratios using the placement REST API + (or `osc-placement`_ command line interface). + For example: + + .. code-block:: console + + $ openstack resource provider inventory set \ + --resource VCPU:allocation_ratio=1.0 \ + --amend 815a5634-86fb-4e1e-8824-8a631fee3e06 + +3. When the deployer wants to **always** use the placement API to set + allocation ratios, then the deployer should ensure that the + :oslo.config:option:`DEFAULT.cpu_allocation_ratio`, + :oslo.config:option:`DEFAULT.ram_allocation_ratio` and + :oslo.config:option:`DEFAULT.disk_allocation_ratio` configuration options + are set to a None and then manage the allocation ratios using the placement + REST API (or `osc-placement`_ command line interface). + + This scenario is the workaround for + `bug 1804125 `_. + +.. versionchanged:: 19.0.0 (Stein) + + The :oslo.config:option:`DEFAULT.initial_cpu_allocation_ratio`, + :oslo.config:option:`DEFAULT.initial_ram_allocation_ratio` and + :oslo.config:option:`DEFAULT.initial_disk_allocation_ratio` configuration + options were introduced in Stein. Prior to this release, setting any of + :oslo.config:option:`DEFAULT.cpu_allocation_ratio`, + :oslo.config:option:`DEFAULT.ram_allocation_ratio` or + :oslo.config:option:`DEFAULT.disk_allocation_ratio` to a non-null value + would ensure the user-configured value was always overriden. + +.. _osc-placement: https://docs.openstack.org/osc-placement/latest/index.html + +.. _hypervisor-specific-considerations: + +Hypervisor-specific considerations +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Nova provides three configuration options that can be used to set aside some +number of resources that will not be consumed by an instance, whether these +resources are overcommitted or not: + +- :oslo.config:option:`reserved_host_cpus`, +- :oslo.config:option:`reserved_host_memory_mb` +- :oslo.config:option:`reserved_host_disk_mb` + +Some virt drivers may benefit from the use of these options to account for +hypervisor-specific overhead. + +HyperV + Hyper-V creates a VM memory file on the local disk when an instance starts. + The size of this file corresponds to the amount of RAM allocated to the + instance. + + You should configure the + :oslo.config:option:`reserved_host_disk_mb` config option to + account for this overhead, based on the amount of memory available + to instances. + + +Cells considerations +-------------------- + +By default cells are enabled for scheduling new instances but they can be +disabled (new schedules to the cell are blocked). This may be useful for +users while performing cell maintenance, failures or other interventions. It is +to be noted that creating pre-disabled cells and enabling/disabling existing +cells should either be followed by a restart or SIGHUP of the nova-scheduler +service for the changes to take effect. + +Command-line interface +~~~~~~~~~~~~~~~~~~~~~~ + +The :command:`nova-manage` command-line client supports the cell-disable +related commands. To enable or disable a cell, use +:command:`nova-manage cell_v2 update_cell` and to create pre-disabled cells, +use :command:`nova-manage cell_v2 create_cell`. See the +:ref:`man-page-cells-v2` man page for details on command usage. + + +.. _compute-capabilities-as-traits: + +Compute capabilities as traits +------------------------------ + +.. versionadded:: 19.0.0 (Stein) + +The ``nova-compute`` service will report certain ``COMPUTE_*`` traits based on +its compute driver capabilities to the placement service. The traits will be +associated with the resource provider for that compute service. These traits +can be used during scheduling by configuring flavors with +:ref:`Required traits ` or +:ref:`Forbidden traits `. For example, if you +have a host aggregate with a set of compute nodes that support multi-attach +volumes, you can restrict a flavor to that aggregate by adding the +``trait:COMPUTE_VOLUME_MULTI_ATTACH=required`` extra spec to the flavor and +then restrict the flavor to the aggregate +:ref:`as normal `. + +Here is an example of a libvirt compute node resource provider that is +exposing some CPU features as traits, driver capabilities as traits, and a +custom trait denoted by the ``CUSTOM_`` prefix: + +.. code-block:: console + + $ openstack --os-placement-api-version 1.6 resource provider trait list \ + > d9b3dbc4-50e2-42dd-be98-522f6edaab3f --sort-column name + +---------------------------------------+ + | name | + +---------------------------------------+ + | COMPUTE_DEVICE_TAGGING | + | COMPUTE_NET_ATTACH_INTERFACE | + | COMPUTE_NET_ATTACH_INTERFACE_WITH_TAG | + | COMPUTE_TRUSTED_CERTS | + | COMPUTE_VOLUME_ATTACH_WITH_TAG | + | COMPUTE_VOLUME_EXTEND | + | COMPUTE_VOLUME_MULTI_ATTACH | + | CUSTOM_IMAGE_TYPE_RBD | + | HW_CPU_X86_MMX | + | HW_CPU_X86_SSE | + | HW_CPU_X86_SSE2 | + | HW_CPU_X86_SVM | + +---------------------------------------+ + +**Rules** + +There are some rules associated with capability-defined traits. + +1. The compute service "owns" these traits and will add/remove them when the + ``nova-compute`` service starts and when the ``update_available_resource`` + periodic task runs, with run intervals controlled by config option + :oslo.config:option:`update_resources_interval`. + +2. The compute service will not remove any custom traits set on the resource + provider externally, such as the ``CUSTOM_IMAGE_TYPE_RBD`` trait in the + example above. + +3. If compute-owned traits are removed from the resource provider externally, + for example by running ``openstack resource provider trait delete ``, + the compute service will add its traits again on restart or SIGHUP. + +4. If a compute trait is set on the resource provider externally which is not + supported by the driver, for example by adding the ``COMPUTE_VOLUME_EXTEND`` + trait when the driver does not support that capability, the compute service + will automatically remove the unsupported trait on restart or SIGHUP. + +5. Compute capability traits are standard traits defined in the `os-traits`_ + library. + +.. _os-traits: https://opendev.org/openstack/os-traits/src/branch/master/os_traits/compute + +:ref:`Further information on capabilities and traits +` can be found in the +:doc:`Technical Reference Deep Dives section `. + + +.. _custom-scheduler-filters: + +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: + +* 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, refer to the codebase (at least by looking at the other filters +code) or ask for help in the ``#openstack-nova`` IRC channel. + +In addition, if your custom filter uses non-standard extra specs, you must +register validators for these extra specs. Examples of validators can be found +in the ``nova.api.validation.extra_specs`` module. These should be registered +via the ``nova.api.extra_spec_validator`` `entrypoint`__. + +The module containing your custom filter(s) must be packaged and available in +the same environment(s) that the nova controllers, or specifically the +:program:`nova-scheduler` and :program:`nova-api` services, are available in. +As an example, consider the following sample package, which is the `minimal +structure`__ for a standard, setuptools-based Python package: + +.. code-block:: none + + acmefilter/ + acmefilter/ + __init__.py + validators.py + setup.py + +Where ``__init__.py`` contains: + +.. code-block:: python + + from oslo_log import log as logging + from nova.scheduler import filters + + LOG = logging.getLogger(__name__) + + class AcmeFilter(filters.BaseHostFilter): + + def host_passes(self, host_state, spec_obj): + extra_spec = spec_obj.flavor.extra_specs.get('acme:foo') + LOG.info("Extra spec value was '%s'", extra_spec) + + # do meaningful stuff here... + + return True + +``validators.py`` contains: + +.. code-block:: python + + from nova.api.validation.extra_specs import base + + def register(): + validators = [ + base.ExtraSpecValidator( + name='acme:foo', + description='My custom extra spec.' + value={ + 'type': str, + 'enum': [ + 'bar', + 'baz', + ], + }, + ), + ] + + return validators + +``setup.py`` contains: + +.. code-block:: python + + from setuptools import setup + + setup( + name='acmefilter', + version='0.1', + description='My custom filter', + packages=[ + 'acmefilter' + ], + entry_points={ + 'nova.api.extra_spec_validators': [ + 'acme = acmefilter.validators', + ], + }, + ) + +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 = acmefilter.AcmeFilter + enabled_filters = ComputeFilter,AcmeFilter + +.. 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, all of the standard nova filters and the custom +``AcmeFilter`` filter are available to the scheduler, but just the +``ComputeFilter`` and ``AcmeFilter`` will be used on each request. + +__ https://packaging.python.org/specifications/entry-points/ +__ https://python-packaging.readthedocs.io/en/latest/minimal.html + +Writing your own weigher +------------------------ + +To create your own weigher, you must inherit from |BaseHostWeigher| +A weigher can implement both the ``weight_multiplier`` and ``_weight_object`` +methods or just implement the ``weight_objects`` method. ``weight_objects`` +method is overridden only if you need access to all objects in order to +calculate weights, and it just return a list of weights, and not modify the +weight of the object directly, since final weights are normalized and computed +by ``weight.BaseWeightHandler``. + + +.. |BaseHostFilter| replace:: :class:`BaseHostFilter ` +.. |BaseHostWeigher| replace:: :class:`BaseHostFilter ` diff --git a/doc/source/admin/virtual-gpu.rst b/doc/source/admin/virtual-gpu.rst index 5fbdd55adcf6..9bef6889c8a8 100644 --- a/doc/source/admin/virtual-gpu.rst +++ b/doc/source/admin/virtual-gpu.rst @@ -111,11 +111,6 @@ provided by compute nodes. $ openstack server create --flavor vgpu_1 --image cirros-0.3.5-x86_64-uec --wait test-vgpu -.. note:: - - As of the Queens release, only the *FilterScheduler* scheduler driver - uses the Placement API. - How to discover a GPU type -------------------------- diff --git a/doc/source/configuration/extra-specs.rst b/doc/source/configuration/extra-specs.rst index 8e7c8614df5f..45dbf2a94dfc 100644 --- a/doc/source/configuration/extra-specs.rst +++ b/doc/source/configuration/extra-specs.rst @@ -9,7 +9,7 @@ default configuration. Other services and virt drivers may provide additional extra specs not listed here. In addition, it is possible to register your own extra specs. - For more information on the latter, refer to :doc:`/user/filter-scheduler`. + For more information on the latter, refer to :doc:`/admin/scheduling`. Placement --------- diff --git a/doc/source/contributor/testing/eventlet-profiling.rst b/doc/source/contributor/testing/eventlet-profiling.rst index a7ebece82acc..460778aea298 100644 --- a/doc/source/contributor/testing/eventlet-profiling.rst +++ b/doc/source/contributor/testing/eventlet-profiling.rst @@ -31,7 +31,7 @@ Profiling the entire service will produce mostly noise and the output will be confusing because different tasks will operate during the profile run. It is better to begin the process with a candidate task or method *within* the service that can be associated with an identifier. For example, -``select_destinations`` in the ``FilterScheduler`` can be associated with the +``select_destinations`` in the ``SchedulerManager`` can be associated with the list of ``instance_uuids`` passed to it and it runs only once for that set of instance UUIDs. diff --git a/doc/source/index.rst b/doc/source/index.rst index 61a505695c53..01ed1d7a1c23 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -182,7 +182,7 @@ Once you are running nova, the following information is extremely useful. * :doc:`Quotas `: Managing project quotas in nova. * :doc:`Aggregates `: Aggregates are a useful way of grouping hosts together for scheduling purposes. -* :doc:`Filter Scheduler `: How the filter scheduler is +* :doc:`Scheduling `: How the scheduler is configured, and how that will impact where compute instances land in your environment. If you are seeing unexpected distribution of compute instances in your hosts, you'll want to dive into this configuration. @@ -200,7 +200,6 @@ Once you are running nova, the following information is extremely useful. user/flavors admin/upgrades user/quotas - user/filter-scheduler admin/vendordata Reference Material diff --git a/doc/source/reference/scheduler-hints-vs-flavor-extra-specs.rst b/doc/source/reference/scheduler-hints-vs-flavor-extra-specs.rst index c09e9d5b3b79..28f89a9f03fc 100644 --- a/doc/source/reference/scheduler-hints-vs-flavor-extra-specs.rst +++ b/doc/source/reference/scheduler-hints-vs-flavor-extra-specs.rst @@ -57,7 +57,7 @@ Similarities ------------ * Both scheduler hints and flavor extra specs can be used by - :doc:`scheduler filters `. + :doc:`scheduler filters `. * Both are totally customizable, meaning there is no whitelist within Nova of acceptable hints or extra specs, unlike image properties [1]_. diff --git a/doc/source/reference/scheduling.rst b/doc/source/reference/scheduling.rst index 1dea07ab3038..a73710ce7a6d 100644 --- a/doc/source/reference/scheduling.rst +++ b/doc/source/reference/scheduling.rst @@ -16,7 +16,7 @@ ============ This is an overview of how scheduling works in nova from Pike onwards. For -information on the scheduler itself, refer to :doc:`/user/filter-scheduler`. +information on the scheduler itself, refer to :doc:`/admin/scheduling`. For an overview of why we've changed how the scheduler works, refer to :doc:`/reference/scheduler-evolution`. diff --git a/doc/source/user/filter-scheduler.rst b/doc/source/user/filter-scheduler.rst deleted file mode 100644 index e7f2425087b4..000000000000 --- a/doc/source/user/filter-scheduler.rst +++ /dev/null @@ -1,634 +0,0 @@ -Filter Scheduler -================ - -The **Filter Scheduler** supports `filtering` and `weighting` to make informed -decisions on where a new instance should be created. This Scheduler supports -working with Compute Nodes only. - -Filtering ---------- - -.. image:: /_static/images/filtering-workflow-1.png - -During its work Filter Scheduler iterates over all found compute nodes, -evaluating each against a set of filters. The list of resulting hosts is -ordered by weighers. The Scheduler then chooses hosts for the requested -number of instances, choosing the most weighted hosts. For a specific -filter to succeed for a specific host, the filter matches the user -request against the state of the host plus some extra magic as defined -by each filter (described in more detail below). - -If the Scheduler cannot find candidates for the next instance, it means that -there are no appropriate hosts where that instance can be scheduled. - -The Filter Scheduler has to be quite flexible to support the required variety -of `filtering` and `weighting` strategies. If this flexibility is insufficient -you can implement `your own filtering algorithm`. - -There are many standard filter classes which may be used -(:mod:`nova.scheduler.filters`): - -* |AllHostsFilter| - does no filtering. It passes all the available hosts. -* |ImagePropertiesFilter| - filters hosts based on properties defined - on the instance's image. It passes hosts that can support the properties - specified on the image used by the instance. -* |AvailabilityZoneFilter| - filters hosts by availability zone. It passes - hosts matching the availability zone specified in the instance properties. - Use a comma to specify multiple zones. The filter will then ensure it matches - any zone specified. -* |ComputeCapabilitiesFilter| - checks that the capabilities provided by the - host compute service satisfy any extra specifications associated with the - instance type. It passes hosts that can create the specified instance type. - - If an extra specs key contains a colon (:), anything before the colon is - treated as a namespace and anything after the colon is treated as the key to - be matched. If a namespace is present and is not ``capabilities``, the filter - ignores the namespace. For example ``capabilities:cpu_info:features`` is - a valid scope format. For backward compatibility, when a key doesn't contain - a colon (:), the key's contents are important. If this key is an attribute of - HostState object, like ``free_disk_mb``, the filter also treats the extra - specs key as the key to be matched. If not, the filter will ignore the key. - - The extra specifications can have an operator at the beginning of the value - string of a key/value pair. If there is no operator specified, then a - default operator of ``s==`` is used. Valid operators are: - - :: - - * = (equal to or greater than as a number; same as vcpus case) - * == (equal to as a number) - * != (not equal to as a number) - * >= (greater than or equal to as a number) - * <= (less than or equal to as a number) - * s== (equal to as a string) - * s!= (not equal to as a string) - * s>= (greater than or equal to as a string) - * s> (greater than as a string) - * s<= (less than or equal to as a string) - * s< (less than as a string) - * (substring) - * (all elements contained in collection) - * (find one of these) - - Examples are: ">= 5", "s== 2.1.0", " gcc", " aes mmx", and " fpu gpu" - - some of attributes that can be used as useful key and their values contains: - - :: - - * free_ram_mb (compared with a number, values like ">= 4096") - * free_disk_mb (compared with a number, values like ">= 10240") - * host (compared with a string, values like: " compute","s== compute_01") - * hypervisor_type (compared with a string, values like: "s== QEMU", "s== powervm") - * hypervisor_version (compared with a number, values like : ">= 1005003", "== 2000000") - * num_instances (compared with a number, values like: "<= 10") - * num_io_ops (compared with a number, values like: "<= 5") - * vcpus_total (compared with a number, values like: "= 48", ">=24") - * vcpus_used (compared with a number, values like: "= 0", "<= 10") - -* |AggregateInstanceExtraSpecsFilter| - checks that the aggregate metadata - satisfies any extra specifications associated with the instance type (that - have no scope or are scoped with ``aggregate_instance_extra_specs``). - It passes hosts that can create the specified instance type. - The extra specifications can have the same operators as - |ComputeCapabilitiesFilter|. To specify multiple values for the same key - use a comma. E.g., "value1,value2". All hosts are passed if no extra_specs - are specified. -* |ComputeFilter| - passes all hosts that are operational and enabled. -* |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. -* |NumInstancesFilter| - filters compute nodes by number of instances. - Nodes with too many instances will be filtered. The host will be - ignored by the scheduler if more than - :oslo.config:option:`filter_scheduler.max_instances_per_host` already exist - on the host. -* |AggregateNumInstancesFilter| - filters hosts by number of instances with - 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. - :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 - :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. -* |PciPassthroughFilter| - Filter that schedules instances on a host if the host - has devices to meet the device requests in the 'extra_specs' for the flavor. -* |SimpleCIDRAffinityFilter| - allows a new instance on a host within - the same IP block. -* |DifferentHostFilter| - allows the instance on a different host from a - set of instances. -* |SameHostFilter| - puts the instance on the same host as another instance in - a set of instances. -* |AggregateTypeAffinityFilter| - limits instance_type by aggregate. - This filter passes hosts if no instance_type key is set or - the instance_type aggregate metadata value contains the name of the - instance_type requested. The value of the instance_type metadata entry is - a string that may contain either a single instance_type name or a comma - separated list of instance_type names. e.g. 'm1.nano' or "m1.nano,m1.small" -* |ServerGroupAntiAffinityFilter| - This filter implements anti-affinity for a - server group. First you must create a server group with a policy of - 'anti-affinity' via the server groups API. Then, when you boot a new server, - provide a scheduler hint of 'group=' where is the UUID of the - server group you created. This will result in the server getting added to the - group. When the server gets scheduled, anti-affinity will be enforced among - all servers in that group. -* |ServerGroupAffinityFilter| - This filter works the same way as - ServerGroupAntiAffinityFilter. The difference is that when you create the server - group, you should specify a policy of 'affinity'. -* |AggregateMultiTenancyIsolation| - isolate tenants in specific aggregates. - To specify multiple tenants use a comma. Eg. "tenant1,tenant2" -* |AggregateImagePropertiesIsolation| - isolates hosts based on image - properties and aggregate metadata. Use a comma to specify multiple values for the - same property. The filter will then ensure at least one value matches. -* |MetricsFilter| - filters hosts based on metrics weight_setting. Only hosts with - the available metrics are passed. -* |NUMATopologyFilter| - filters hosts based on the NUMA topology requested by the - instance, if any. - -Now we can focus on these standard filter classes in some detail. Some filters -such as |AllHostsFilter| and |NumInstancesFilter| are relatively simple and can be -understood from the code. For example, |NumInstancesFilter| has the following -implementation: - -.. code-block:: python - - class NumInstancesFilter(filters.BaseHostFilter): - """Filter out hosts with too many instances.""" - - def _get_max_instances_per_host(self, host_state, spec_obj): - return CONF.filter_scheduler.max_instances_per_host - - def host_passes(self, host_state, spec_obj): - num_instances = host_state.num_instances - max_instances = self._get_max_instances_per_host(host_state, spec_obj) - passes = num_instances < max_instances - return passes - -Here :oslo.config:option:`filter_scheduler.max_instances_per_host` means the -maximum number of instances that can be on a host. - -The |AvailabilityZoneFilter| looks at the availability zone of compute node -and availability zone from the properties of the request. Each compute service -has its own availability zone. So deployment engineers have an option to run -scheduler with availability zones support and can configure availability zones -on each compute host. This class's method ``host_passes`` returns ``True`` if -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 -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. -E.g. an image can be decorated with these properties using -``glance image-update img-uuid --property architecture=arm --property -hypervisor_type=qemu`` -Only hosts that satisfy these requirements will pass the -|ImagePropertiesFilter|. - -|ComputeCapabilitiesFilter| checks if the host satisfies any ``extra_specs`` -specified on the instance type. The ``extra_specs`` can contain key/value pairs. -The key for the filter is either non-scope format (i.e. no ``:`` contained), or -scope format in capabilities scope (i.e. ``capabilities:xxx:yyy``). One example -of capabilities scope is ``capabilities:cpu_info:features``, which will match -host's cpu features capabilities. The |ComputeCapabilitiesFilter| will only -pass hosts whose capabilities satisfy the requested specifications. All hosts -are passed if no ``extra_specs`` are specified. - -|ComputeFilter| is quite simple and passes any host whose compute service is -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 :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. - -|SameHostFilter| does the opposite to what |DifferentHostFilter| does. -``host_passes`` returns ``True`` if the host we want to place an instance on is -one of the hosts used by a set of instances. - -|SimpleCIDRAffinityFilter| looks at the subnet mask and investigates if -the network address of the current host is in the same sub network as it was -defined in the request. - -|JsonFilter| - this filter provides the opportunity to write complicated -queries for the hosts capabilities filtering, based on simple JSON-like syntax. -There can be used the following operations for the host states properties: -``=``, ``<``, ``>``, ``in``, ``<=``, ``>=``, that can be combined with the following -logical operations: ``not``, ``or``, ``and``. For example, the following query can be -found in tests: - -:: - - ['and', - ['>=', '$free_ram_mb', 1024], - ['>=', '$free_disk_mb', 200 * 1024] - ] - -This query will filter all hosts with free RAM greater or equal than 1024 MB -and at the same time with free disk space greater or equal than 200 GB. - -Many filters use data from ``scheduler_hints``, that is defined in the moment of -creation of the new server for the user. The only exception for this rule is -|JsonFilter|, that takes data from the schedulers ``HostState`` data structure -directly. Variable naming, such as the ``$free_ram_mb`` example above, should -be based on those attributes. - -The |NUMATopologyFilter| considers the NUMA topology that was specified for the instance -through the use of flavor extra_specs in combination with the image properties, as -described in detail in the related nova-spec document: - -* https://opendev.org/openstack/nova-specs/src/branch/master/specs/juno/implemented/virt-driver-numa-placement.rst - -and try to match it with the topology exposed by the host, accounting for the -: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, - and provide limits to the compute host accordingly (as mentioned above). -* If instance has no topology defined, it will be considered for any host. -* If instance has a topology defined, it will be considered only for NUMA - capable hosts. - -Configuring Filters -------------------- - -To use filters you specify two settings: - -* :oslo.config:option:`filter_scheduler.available_filters` - Defines filter classes made - available to the scheduler. This setting can be used multiple times. -* :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: - -:: - - --filter_scheduler.available_filters=nova.scheduler.filters.all_filters - --filter_scheduler.enabled_filters=ComputeFilter,AvailabilityZoneFilter,ComputeCapabilitiesFilter,ImagePropertiesFilter,ServerGroupAntiAffinityFilter,ServerGroupAffinityFilter - -With this configuration, all filters in ``nova.scheduler.filters`` -would be available, and by default the |ComputeFilter|, -|AvailabilityZoneFilter|, |ComputeCapabilitiesFilter|, -|ImagePropertiesFilter|, |ServerGroupAntiAffinityFilter|, -and |ServerGroupAffinityFilter| would be used. - -Each filter selects hosts in a different way and has different costs. The order -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 ``NUMATopologyFilter``. - -In medium/large environments having AvailabilityZoneFilter before any -capability or resource calculating filters can be useful. - -.. _custom-scheduler-filters: - -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: - -* 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, refer to the codebase (at least by looking at the other filters -code) or ask for help in the #openstack-nova IRC channel. - -In addition, if your custom filter uses non-standard extra specs, you must -register validators for these extra specs. Examples of validators can be found -in the ``nova.api.validation.extra_specs`` module. These should be registered -via the ``nova.api.extra_spec_validator`` `entrypoint`__. - -The module containing your custom filter(s) must be packaged and available in -the same environment(s) that the nova controllers, or specifically the -:program:`nova-scheduler` and :program:`nova-api` services, are available in. -As an example, consider the following sample package, which is the `minimal -structure`__ for a standard, setuptools-based Python package: - -__ https://packaging.python.org/specifications/entry-points/ -__ https://python-packaging.readthedocs.io/en/latest/minimal.html - -.. code-block:: none - - acmefilter/ - acmefilter/ - __init__.py - validators.py - setup.py - -Where ``__init__.py`` contains: - -.. code-block:: python - - from oslo_log import log as logging - from nova.scheduler import filters - - LOG = logging.getLogger(__name__) - - class AcmeFilter(filters.BaseHostFilter): - - def host_passes(self, host_state, spec_obj): - extra_spec = spec_obj.flavor.extra_specs.get('acme:foo') - LOG.info("Extra spec value was '%s'", extra_spec) - - # do meaningful stuff here... - - return True - -``validators.py`` contains: - -.. code-block:: python - - from nova.api.validation.extra_specs import base - - def register(): - validators = [ - base.ExtraSpecValidator( - name='acme:foo', - description='My custom extra spec.' - value={ - 'type': str, - 'enum': [ - 'bar', - 'baz', - ], - }, - ), - ] - - return validators - -``setup.py`` contains: - -.. code-block:: python - - from setuptools import setup - - setup( - name='acmefilter', - version='0.1', - description='My custom filter', - packages=[ - 'acmefilter' - ], - entry_points={ - 'nova.api.extra_spec_validators': [ - 'acme = acmefilter.validators', - ], - }, - ) - -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 = acmefilter.AcmeFilter - enabled_filters = ComputeFilter,AcmeFilter - -.. 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 the custom ``AcmeFilter`` filter -are available to the ``FilterScheduler``, but just the ``ComputeFilter`` and -``AcmeFilter`` will be used on each request. - -Weights -------- - -Filter Scheduler uses the so-called **weights** during its work. A weigher is a -way to select the best suitable host from a group of valid hosts by giving -weights to all the hosts in the list. - -In order to prioritize one weigher against another, all the weighers have to -define a multiplier that will be applied before computing the weight for a node. -All the weights are normalized beforehand so that the multiplier can be applied -easily. Therefore the final weight for the object will be:: - - weight = w1_multiplier * norm(w1) + w2_multiplier * norm(w2) + ... - -A weigher should be a subclass of ``weights.BaseHostWeigher`` and they can implement -both the ``weight_multiplier`` and ``_weight_object`` methods or just implement the -``weight_objects`` method. ``weight_objects`` method is overridden only if you need -access to all objects in order to calculate weights, and it just return a list of weights, -and not modify the weight of the object directly, since final weights are normalized -and computed by ``weight.BaseWeightHandler``. - -The Filter Scheduler weighs hosts based on the config option -`filter_scheduler.weight_classes`, this defaults to -`nova.scheduler.weights.all_weighers`, which selects the following weighers: - -* |RAMWeigher| Compute weight based on available RAM on the compute node. - Sort with the largest weight winning. If the multiplier, - :oslo.config:option:`filter_scheduler.ram_weight_multiplier`, is negative, the - 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. -* |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). - 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. -* |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:: - - metrics_weight_setting = name1=1.0, name2=-1.0 - - Starting with the Stein release, if per-aggregate value with the key - `metrics_weight_multiplier` is found, this value would be chosen as the - metrics weight multiplier. Otherwise, it will fall back to the - :oslo.config:option:`metrics.weight_multiplier`. If more than - one value is found for a host in aggregate metadata, the minimum value will - be used. -* |IoOpsWeigher| The weigher can compute the weight based on the compute node - host's workload. The default is to preferably choose light workload compute - 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. - -* |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, - given three hosts - one with a single PCI device, one with many PCI devices, - and one with no PCI devices - nova should prioritise these differently based - on the demands of the instance. If the instance requests a single PCI device, - then the first of the hosts should be preferred. Similarly, if the instance - requests multiple PCI devices, then the second of these hosts would be - preferred. Finally, if the instance does not request a PCI device, then the - last of these hosts should be preferred. - - For this to be of any value, at least one of the |PciPassthroughFilter| or - |NUMATopologyFilter| filters must be enabled. - - :Configuration Option: ``[filter_scheduler] pci_weight_multiplier``. Only - positive values are allowed for the multiplier as a negative value would - force non-PCI instances away from non-PCI hosts, thus, causing future - 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. -* |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`. - If more than one value is found for a host in aggregate metadata, the - minimum value will be used. - -* |ServerGroupSoftAntiAffinityWeigher| The weigher can compute the weight based - on the number of instances that run on the same server group as a negative - 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`. - If more than one value is found for a host in aggregate metadata, the - minimum value will be used. - -* |BuildFailureWeigher| Weigh hosts by the number of recent failed boot attempts. - 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`. - If more than one value is found for a host in aggregate metadata, the - minimum value will be used. - -.. _cross-cell-weigher: - -* |CrossCellWeigher| Weighs hosts based on which cell they are in. "Local" - cells are preferred when moving an instance. Use configuration option - :oslo.config:option:`filter_scheduler.cross_cell_move_weight_multiplier` to - control the weight. If per-aggregate value with the key - `cross_cell_move_weight_multiplier` is found, this value would be chosen - as the cross-cell move weight multiplier. Otherwise, it will fall back to the - :oslo.config:option:`filter_scheduler.cross_cell_move_weight_multiplier`. - If more than one value is found for a host in aggregate metadata, the - minimum value will be used. - -Filter Scheduler makes a local list of acceptable hosts by repeated filtering and -weighing. Each time it chooses a host, it virtually consumes resources on it, -so subsequent selections can adjust accordingly. It is useful if the customer -asks for a large block of instances, because weight is computed for -each instance requested. - -.. image:: /_static/images/filtering-workflow-2.png - -At the end Filter Scheduler sorts selected hosts by their weight and attempts -to provision instances on the chosen hosts. - -P.S.: you can find more examples of using Filter Scheduler and standard filters -in :mod:`nova.tests.scheduler`. - -.. |AllHostsFilter| replace:: :class:`AllHostsFilter ` -.. |ImagePropertiesFilter| replace:: :class:`ImagePropertiesFilter ` -.. |AvailabilityZoneFilter| replace:: :class:`AvailabilityZoneFilter ` -.. |BaseHostFilter| replace:: :class:`BaseHostFilter ` -.. |ComputeCapabilitiesFilter| replace:: :class:`ComputeCapabilitiesFilter ` -.. |ComputeFilter| replace:: :class:`ComputeFilter ` -.. |IsolatedHostsFilter| replace:: :class:`IsolatedHostsFilter ` -.. |JsonFilter| replace:: :class:`JsonFilter ` -.. |NumInstancesFilter| replace:: :class:`NumInstancesFilter ` -.. |AggregateNumInstancesFilter| replace:: :class:`AggregateNumInstancesFilter ` -.. |IoOpsFilter| replace:: :class:`IoOpsFilter ` -.. |AggregateIoOpsFilter| replace:: :class:`AggregateIoOpsFilter ` -.. |PciPassthroughFilter| replace:: :class:`PciPassthroughFilter ` -.. |SimpleCIDRAffinityFilter| replace:: :class:`SimpleCIDRAffinityFilter ` -.. |DifferentHostFilter| replace:: :class:`DifferentHostFilter ` -.. |SameHostFilter| replace:: :class:`SameHostFilter ` -.. |AggregateTypeAffinityFilter| replace:: :class:`AggregateTypeAffinityFilter ` -.. |ServerGroupAntiAffinityFilter| replace:: :class:`ServerGroupAntiAffinityFilter ` -.. |ServerGroupAffinityFilter| replace:: :class:`ServerGroupAffinityFilter ` -.. |AggregateInstanceExtraSpecsFilter| replace:: :class:`AggregateInstanceExtraSpecsFilter ` -.. |AggregateMultiTenancyIsolation| replace:: :class:`AggregateMultiTenancyIsolation ` -.. |NUMATopologyFilter| replace:: :class:`NUMATopologyFilter ` -.. |RAMWeigher| replace:: :class:`RAMWeigher ` -.. |CPUWeigher| replace:: :class:`CPUWeigher ` -.. |AggregateImagePropertiesIsolation| replace:: :class:`AggregateImagePropertiesIsolation ` -.. |MetricsFilter| replace:: :class:`MetricsFilter ` -.. |MetricsWeigher| replace:: :class:`MetricsWeigher ` -.. |IoOpsWeigher| replace:: :class:`IoOpsWeigher ` -.. |PCIWeigher| replace:: :class:`PCIWeigher ` -.. |ServerGroupSoftAffinityWeigher| replace:: :class:`ServerGroupSoftAffinityWeigher ` -.. |ServerGroupSoftAntiAffinityWeigher| replace:: :class:`ServerGroupSoftAntiAffinityWeigher ` -.. |DiskWeigher| replace:: :class:`DiskWeigher ` -.. |BuildFailureWeigher| replace:: :class:`BuildFailureWeigher ` -.. |CrossCellWeigher| replace:: :class:`CrossCellWeigher ` diff --git a/doc/source/user/flavors.rst b/doc/source/user/flavors.rst index a36cfc38e425..946ac241a619 100644 --- a/doc/source/user/flavors.rst +++ b/doc/source/user/flavors.rst @@ -41,7 +41,7 @@ Root Disk GB The root disk is an ephemeral disk that the base image is copied into. When booting from a persistent volume it is not used. The ``0`` size is a special case which uses the native base image size as the size of the ephemeral root - volume. However, in this case the filter scheduler cannot select the compute + volume. However, in this case the scheduler cannot select the compute host based on the virtual image size. As a result, ``0`` should only be used for volume booted instances or for testing purposes. Volume-backed instances can be enforced for flavors with zero root disk via the @@ -185,9 +185,6 @@ Required traits below). Any other value will be considered invalid. - The FilterScheduler is currently the only scheduler driver that supports - this feature. - Traits can be managed using the `osc-placement plugin`__. __ https://docs.openstack.org/osc-placement/latest/index.html @@ -207,9 +204,6 @@ Forbidden traits - ``trait:HW_CPU_X86_AVX2=forbidden`` - ``trait:STORAGE_DISK_SSD=forbidden`` - The FilterScheduler is currently the only scheduler driver that supports - this feature. - Traits can be managed using the `osc-placement plugin`__. __ https://docs.openstack.org/osc-placement/latest/index.html diff --git a/doc/source/user/index.rst b/doc/source/user/index.rst index 6da9ae060628..5facf792ad51 100644 --- a/doc/source/user/index.rst +++ b/doc/source/user/index.rst @@ -80,7 +80,7 @@ Once you are running nova, the following information is extremely useful. arbitrary factors, such as location (country, datacenter, rack), network layout and/or power source. -* :doc:`Filter Scheduler `: How the filter scheduler is +* :doc:`Scheduling `: How the scheduler is configured, and how that will impact where compute instances land in your environment. If you are seeing unexpected distribution of compute instances in your hosts, you'll want to dive into this configuration. diff --git a/doc/test/redirect-tests.txt b/doc/test/redirect-tests.txt index ef65b8940d24..4ee7d865c990 100644 --- a/doc/test/redirect-tests.txt +++ b/doc/test/redirect-tests.txt @@ -15,12 +15,12 @@ /nova/latest/development.environment.html 301 /nova/latest/contributor/development-environment.html /nova/latest/devref/api.html 301 /nova/latest/contributor/api.html /nova/latest/devref/cells.html 301 /nova/latest/user/cells.html -/nova/latest/devref/filter_scheduler.html 301 /nova/latest/user/filter-scheduler.html +/nova/latest/devref/filter_scheduler.html 301 /nova/latest/admin/scheduling.html # catch all, if we hit something in devref assume it moved to # reference unless we have already triggered a hit above. /nova/latest/devref/any-page.html 301 /nova/latest/reference/any-page.html /nova/latest/feature_classification.html 301 /nova/latest/user/feature-classification.html -/nova/latest/filter_scheduler.html 301 /nova/latest/user/filter-scheduler.html +/nova/latest/filter_scheduler.html 301 /nova/latest/admin/scheduling.html /nova/latest/gmr.html 301 /nova/latest/reference/gmr.html /nova/latest/how_to_get_involved.html 301 /nova/latest/contributor/how-to-get-involved.html /nova/latest/i18n.html 301 /nova/latest/reference/i18n.html @@ -66,6 +66,7 @@ /nova/latest/user/aggregates.html 301 /nova/latest/admin/aggregates.html /nova/latest/user/cellsv2_layout.html 301 /nova/latest/user/cellsv2-layout.html /nova/latest/user/config-drive.html 301 /nova/latest/user/metadata.html +/nova/latest/user/filter-scheduler.html 301 /nova/latest/admin/scheduling.html /nova/latest/user/metadata-service.html 301 /nova/latest/user/metadata.html /nova/latest/user/placement.html 301 /placement/latest/ /nova/latest/user/user-data.html 301 /nova/latest/user/metadata.html @@ -75,6 +76,7 @@ /nova/latest/vmstates.html 301 /nova/latest/reference/vm-states.html /nova/latest/wsgi.html 301 /nova/latest/user/wsgi.html /nova/latest/admin/adv-config.html 301 /nova/latest/admin/index.html +/nova/latest/admin/configuration/schedulers.html 301 /nova/latest/admin/scheduling.html /nova/latest/admin/system-admin.html 301 /nova/latest/admin/index.html /nova/latest/admin/port_with_resource_request.html 301 /nova/latest/admin/ports-with-resource-requests.html /nova/latest/admin/manage-users.html 301 /nova/latest/admin/arch.html