host-select: fix compatibility with force-condemned hosts

changes.d/6623.fix.md

@@ -0,0 +1,4 @@
+Auto restart: The "force condemn" option (that tells workflows running on a
+server to shutdown as opposed to migrate) hasn't worked with the host-selection
+mechanism since Cylc 8.0.0. This has now been fixed and the "force condemn"
+option has been restored in the documentation.

cylc/flow/cfgspec/globalcfg.py

@@ -826,16 +826,54 @@ def default_for(
                    range.
             ''')
             Conf('condemned', VDR.V_ABSOLUTE_HOST_LIST, desc=f'''
-                These hosts will not be used to run jobs.
+                List run hosts that workflows should *not* run on.
 
-                If workflows are already running on
-                condemned hosts, Cylc will shut them down and
-                restart them on different hosts.
+                These will be subtracted from the
+                `available <global.cylc[scheduler][run hosts]>`:
+
+                * Workflows will not start on condemned hosts.
+                * Workflows that are running on condemned hosts will attempt
+                  to migrate to an available host (providing the
+                  `auto restart
+                  <global.cylc[scheduler][main loop][auto restart]>`
+                  plugin is enabled).
+
+                This feature can be used to drain a host for patching, or
+                remove a host that is surplus to requirements.
+
+                If a hostname listed here is followed by a ``!`` character
+                ("force mode"), workflows running on it
+                will shutdown rather than attempting to
+                migrate (providing the
+                `auto restart
+                <global.cylc[scheduler][main loop][auto restart]>` plugin
+                is enabled).
+
+                .. rubric:: Example:
+
+                .. code-block:: cylc
+
+                   [scheduler]
+                       [[run hosts]]
+                           # there are three hosts in the "pool"
+                           available = host1, host2, host3
+
+                           # however two have been taken out:
+                           # * workflows running on "host1" will attempt to
+                           #   restart on "host3"
+                           # * workflows running on "host2" will shutdown
+                           condemned = host1, host2!
 
                 .. seealso::
 
                    :ref:`auto-stop-restart`
 
+                .. versionchanged:: 8.4.2
+
+                   The force-condemn ("!") option caused issues at workflow
+                   startup for Cylc versions between 8.0.0 and 8.4.1
+                   inclusive.
+
                 .. versionchanged:: 8.0.0
 
                    {REPLACES}``[suite servers]condemned hosts``.
@@ -1336,7 +1374,7 @@ def default_for(
                 The means by which task progress messages are reported back to
                 the running workflow.
 
-                ..rubric:: Options:
+                .. rubric:: Options:
 
                 zmq
                    Direct client-server TCP communication via network ports

cylc/flow/host_select.py

@@ -128,6 +128,13 @@
     # be returned with the up-to-date configuration.
     global_config = glbl_cfg(cached=cached)
 
+    # condemned hosts may be suffixed with an "!" to activate "force mode"
+    blacklist = []
+    for host in global_config.get(['scheduler', 'run hosts', 'condemned'], []):
+        if host.endswith('!'):
+            host = host[:-1]
+        blacklist.append(host)
+
     return select_host(
         # list of workflow hosts
         global_config.get([
@@ -138,9 +145,7 @@
             'scheduler', 'run hosts', 'ranking'
         ]),
         # list of condemned hosts
-        blacklist=global_config.get(
-            ['scheduler', 'run hosts', 'condemned']
-        ),
+        blacklist=blacklist,
         blacklist_name='condemned host'
     )
 

tests/functional/restart/43-auto-restart-force-override-normal.t

@@ -50,7 +50,10 @@ create_test_global_config '' "
 ${BASE_GLOBAL_CONFIG}
 [scheduler]
     [[run hosts]]
-        available = ${CYLC_TEST_HOST_1}
+        available = ${CYLC_TEST_HOST_1}, ${CYLC_TEST_HOST_2}
+        # ensure the workflow can start if a host is force-condemned
+        # see #6623
+        condemned = ${CYLC_TEST_HOST_2}!
 "
 
 set_test_number 8