Deprecate RetryFilter

Since blueprint return-alternate-hosts in Queens, the scheduler
returns a primary selected host and some alternate hosts based
on the max_attempts config option. The only reschedules we have
are during server create and resize/cold migrate. The list of
alternative hosts are passed down from conductor through compute
and back to conductor on reschedule and if conductor gets a list
of alternate hosts on reschedule it will not call the scheduler
again. This means the RetryFilter is effectively useless now since
it shouldn't ever filter out hosts on the first schedule attempt
and because we're using alternates for reschedules, we shouldn't
go back to the scheduler on a reschedule. As a result this change
deprecates the RetryFilter and removes it from the default list
of enabled filters.

Change-Id: Ic0a03e89903bf925638fa26cca3dac7db710dca3

doc/source/admin/configuration/schedulers.rst

@@ -18,14 +18,12 @@ Compute is configured with the following default scheduler options in the
 
    [filter_scheduler]
    available_filters = nova.scheduler.filters.all_filters
-   enabled_filters = RetryFilter, AvailabilityZoneFilter, ComputeFilter, ComputeCapabilitiesFilter, ImagePropertiesFilter, ServerGroupAntiAffinityFilter, ServerGroupAffinityFilter
+   enabled_filters = AvailabilityZoneFilter, 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:
 
-* Have not been attempted for scheduling purposes (``RetryFilter``).
-
 * Are in the requested availability zone (``AvailabilityZoneFilter``).
 
 * Can service the request (``ComputeFilter``).
@@ -720,13 +718,22 @@ free RAM.
 RetryFilter
 -----------
 
+.. deprecated:: 20.0.0
+
+   Since the 17.0.0 (Queens) release, the scheduler has provided alternate
+   hosts for rescheduling so the scheduler does not need to be called during
+   a reschedule which makes the ``RetryFilter`` useless. See the
+   `Return Alternate Hosts`_ spec for details.
+
 Filters out hosts that have already been attempted for scheduling purposes.  If
 the scheduler selects a host to respond to a service request, and the host
 fails to respond to the request, this filter prevents the scheduler from
 retrying that host for the service request.
 
-This filter is only useful if the ``scheduler_max_attempts`` configuration
-option is set to a value greater than zero.
+This filter is only useful if the :oslo.config:option:`scheduler.max_attempts`
+configuration option is set to a value greater than one.
+
+.. _Return Alternate Hosts: https://specs.openstack.org/openstack/nova-specs/specs/queens/implemented/return-alternate-hosts.html
 
 SameHostFilter
 --------------

doc/source/user/filter-scheduler.rst

@@ -167,8 +167,8 @@ There are many standard filter classes which may be used
   set of instances.
 * |SameHostFilter| - puts the instance on the same host as another instance in
   a set of instances.
-* |RetryFilter| - filters hosts that have been attempted for scheduling.
-  Only passes hosts that have not been previously attempted.
+* |RetryFilter| - DEPRECATED; filters hosts that have been attempted for
+  scheduling. Only passes hosts that have not been previously attempted.
 * |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
@@ -303,6 +303,15 @@ exception even if the problem is related to 1:N compute nodes. If you see that
 case in the scheduler logs, then your problem is most likely related to a
 compute problem and you should check the compute logs.
 
+.. note:: The ``RetryFilter`` is deprecated since the 20.0.0 (Train) release
+          and will be removed in an upcoming release. Since the 17.0.0 (Queens)
+          release, the scheduler has provided alternate hosts for rescheduling
+          so the scheduler does not need to be called during a reschedule which
+          makes the ``RetryFilter`` useless. See the `Return Alternate Hosts`_
+          spec for details.
+
+.. _Return Alternate Hosts: https://specs.openstack.org/openstack/nova-specs/specs/queens/implemented/return-alternate-hosts.html
+
 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:

nova/conf/scheduler.py

@@ -311,7 +311,6 @@ Related options:
         # Tempest's scheduler_enabled_filters to keep the default values in
         # sync.
         default=[
-          "RetryFilter",
           "AvailabilityZoneFilter",
           "ComputeFilter",
           "ComputeCapabilitiesFilter",

nova/scheduler/filters/retry_filter.py

@@ -29,6 +29,14 @@ class RetryFilter(filters.BaseHostFilter):
     # related to rebuild.
     RUN_ON_REBUILD = False
 
+    def __init__(self):
+        super(RetryFilter, self).__init__()
+        LOG.warning('The RetryFilter is deprecated since the 20.0.0 Train '
+                    'release. Since the 17.0.0 (Queens) release, the '
+                    'scheduler has provided alternate hosts for rescheduling '
+                    'so the scheduler does not need to be called during a '
+                    'reschedule which makes the RetryFilter useless.')
+
     def host_passes(self, host_state, spec_obj):
         """Skip nodes that have already been attempted."""
         retry = spec_obj.retry

nova/tests/unit/scheduler/filters/test_retry_filters.py

@@ -21,6 +21,8 @@ class TestRetryFilter(test.NoDBTestCase):
     def setUp(self):
         super(TestRetryFilter, self).setUp()
         self.filt_cls = retry_filter.RetryFilter()
+        self.assertIn('The RetryFilter is deprecated',
+                      self.stdlog.logger.output)
 
     def test_retry_filter_disabled(self):
         # Test case where retry/re-scheduling is disabled.

releasenotes/notes/deprecate-retry-filter-4d1dba39a2c21836.yaml

@@ -0,0 +1,10 @@
+---
+deprecations:
+  - |
+    The ``RetryFilter`` is deprecated and will be removed in an upcoming
+    release. Since the 17.0.0 (Queens) release, the scheduler has provided
+    alternate hosts for rescheduling so the scheduler does not need to be
+    called during a reschedule which makes the ``RetryFilter`` useless.
+    See the `Return Alternate Hosts`_ spec for details.
+
+    .. _Return Alternate Hosts: https://specs.openstack.org/openstack/nova-specs/specs/queens/implemented/return-alternate-hosts.html