added a guide to writing a platform configuration.

src/7-to-8/major-changes/platforms.rst

@@ -16,11 +16,11 @@ Platforms
    .. code-block:: cylc
 
       [runtime]
-         [[task_name]]
-            [[[job]]]
-               batch system = slurm
-            [[[remote]]]
-               host = my_supercomputer
+          [[task_name]]
+              [[[job]]]
+                  batch system = slurm
+              [[[remote]]]
+                  host = my_supercomputer
 
    Read this section if your workflow's jobs run on a remote computer or if
    you see the following warning on running ``cylc validate``:
@@ -29,6 +29,21 @@ Platforms
 
       WARNING - Task <task>: deprecated "host" and "batch system" will be removed at Cylc 9
 
+   If you currently use the ``rose host-select`` utility or a similar host
+   selection or load balancing utility the intelligent host selection
+   functionality of Cylc 8 may be used instead:
+
+   .. code-block:: cylc
+
+      [runtime]
+          [[task_name]]
+              [[[remote]]]
+                  host = $(rose host-select my-computer)
+          [[another_task]]
+              # An example of a home-rolled host selector
+              [[[remote]]]
+                  host = $(test $((RANDOM%2)) -eq 0 && echo "host_a" || echo "host_b")
+
 
 Overview
 --------
@@ -41,6 +56,22 @@ Cylc 8 allows site administrators (and users) to configure
   multiple hosts with associated platform-specific settings. Users only need to
   select the platform for their task jobs.
 
+  Platforms also define how hosts are selected from each platform:
+
+  - Randomly (default)
+  - By definition order
+
+There may be cases where sets of platforms (for example a group of
+standalone compute servers, or a pair of mirrored HPC's) might be equally
+suitable for a task, but not share files systems to allow them to constitute
+a single platform. Such platforms can be set up to be ``platform groups``
+
+
+.. seealso::
+
+   :ref:`AdminGuide.PlatformConfigs` for detailed examples of platform
+   configurations.
+
 .. warning::
 
    Cylc 8 contains upgrade logic which handles Cylc 7
@@ -52,8 +83,10 @@ Cylc 8 allows site administrators (and users) to configure
 Examples
 --------
 
-See :cylc:conf:`global.cylc[platforms]` for a detailed explanation of how
-platforms are defined.
+.. seealso::
+
+   :cylc:conf:`global.cylc[platforms]` has a detailed explanation of how
+   platforms and platform groups are defined.
 
 Showing how the global config changes
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -127,16 +160,17 @@ In Cylc 8 the equivalent might be:
 .. code-block:: cylc
 
    [runtime]
-      [[mytask_cylc_server]]
+       [[mytask_cylc_server]]
 
-      [[mytask_big_server]]
-         platform = linuxbox42
+       [[mytask_big_server]]
+           platform = linuxbox42
 
-      [[mytask_submit_local_to_remote_computer]]
-         platform = pbs_local
+       [[mytask_submit_local_to_remote_computer]]
+           platform = pbs_local
 
-      [[mytask_login_to_hpc_and_submit]]
-         platform = $(supercomputer_login_node_selector_script)
+       [[mytask_login_to_hpc_and_submit]]
+           # This is still legal, but you could also use host selection.
+           platform = $(supercomputer_login_node_selector_script)
 
 The platform settings for these examples might be:
 
@@ -147,9 +181,9 @@ The platform settings for these examples might be:
            # Without a hosts, platform name is used as a single host.
 
        [[pbs_local]]
-          job runner = pbs
-          hosts = localhost
+           job runner = pbs
+           hosts = localhost
 
        [[slurm_supercomputer]]
-          hosts = login_node01, login_node02  # Cylc will pick a host.
-          job runner = slurm
+           hosts = login_node01, login_node02  # Cylc will pick a host.
+           job runner = slurm

src/7-to-8/summary.rst

@@ -144,7 +144,8 @@ Platform Awareness
 
 .. seealso::
 
-   :ref:`Platforms at Cylc 8.<majorchangesplatforms>`
+   - :ref:`Platforms at Cylc 8. <majorchangesplatforms>`
+   - :ref:`System admin's guide to writing platforms. <AdminGuide.PlatformConfigs>`
 
 Cylc 7 was aware of individual job hosts.
 

src/glossary.rst

@@ -656,6 +656,11 @@ Glossary
 
       * :term:`job host`
       * :term:`job runner`
+      * :term:`platform group`
+
+   platform group
+
+      A set of :term:`platforms <platform>`
 
    scheduler
       When we say that a :term:`workflow` is "running" we mean that the cylc

src/reference/config/index.rst

@@ -7,3 +7,4 @@ Configuration
    workflow
    global
    types
+   writing-platform-configs