Formatting changes

Author: MoteHue

docs/production.md

@@ -108,16 +108,17 @@ requires instance deletion/recreation.
 
 ### Environments structure
 
-At least two environments should be created using cookiecutter, which will derive from the `site` base environment:
+At least two environments should be created using cookiecutter, which will
+derive from the `site` base environment:
   - `production`: production environment
   - `staging`: staging environment
 
 A `dev` environment should also be created if considered required, or this can
 be left until later.
 
-In general only the `inventory/groups` file in the `site` environment is needed -
-it can be modified as required to
-enable features for all environments at the site.
+In general only the `inventory/groups` file in the `site` environment is needed
+- it can be modified as required to enable features for all environments at the
+site.
 
 To avoid divergence of configuration all possible overrides for group/role
 vars should be placed in `environments/site/inventory/group_vars/all/*.yml`
@@ -133,14 +134,6 @@ and referenced from the `site` and `production` environments, e.g.:
     import_playbook: "{{ lookup('env', 'APPLIANCES_ENVIRONMENT_ROOT') }}/../site/hooks/pre.yml"
   ```
 
-When setting OpenTofu configurations:
-  - Environment-specific variables (`cluster_name`) should be hardcoded
-    as arguments into the cluster module block at `environments/$ENV/tofu/main.tf`.
-  - Environment-independent variables (e.g. maybe `cluster_net` if the
-    same is used for staging and production) should be set as *defaults*
-    in `environments/site/tofu/variables.tf`, and then don't need to
-    be passed in to the module.
-
 OpenTofu configurations should be defined in the `site` environment and used
 as a module from the other environments. This can be done with the
 cookie-cutter generated configurations:
@@ -278,13 +271,13 @@ Once it completes you can log in to the cluster using:
   either for a specific environment within the cluster module block in
   `environments/$ENV/tofu/main.tf`, or as the site default by changing the
   default in `environments/site/tofu/variables.tf`.
-  
+
   For a development environment allowing OpenTofu to manage the volumes using
   the default value of `"manage"` for those varibles is usually appropriate, as
   it allows for multiple clusters to be created with this environment.
-  
-  If no home volume at all is required because the home directories are provided
-  by a parallel filesystem (e.g. manila) set
+
+  If no home volume at all is required because the home directories are
+  provided by a parallel filesystem (e.g. manila) set
 
       home_volume_provisioning = "none"
 
@@ -302,21 +295,23 @@ Once it completes you can log in to the cluster using:
 
 - Consider whether Prometheus storage configuration is required. By default:
   - A 200GB state volume is provisioned (but see above)
-  - The common environment [sets](../environments/common/inventory/group_vars/all/prometheus.yml)
-    a maximum retention of 100 GB and 31 days
+  - The common environment
+    [sets](../environments/common/inventory/group_vars/all/prometheus.yml) a
+    maximum retention of 100 GB and 31 days.
   These may or may not be appropriate depending on the number of nodes, the
   scrape interval, and other uses of the state volume (primarily the `slurmctld`
-  state and the `slurmdbd` database). See [docs/monitoring-and-logging](./monitoring-and-logging.md)
-  for more options.
+  state and the `slurmdbd` database). See
+  [docs/monitoring-and-logging](./monitoring-and-logging.md) for more options.
 
 - Configure Open OnDemand - see [specific documentation](openondemand.md) which
   notes specific variables required.
 
 - Configure Open OnDemand - see [specific documentation](openondemand.md).
 
-- Remove the `demo_user` user from `environments/$ENV/inventory/group_vars/all/basic_users.yml`.
-  Replace the `hpctests_user` in `environments/$ENV/inventory/group_vars/all/hpctests.yml` with
-  an appropriately configured user.
+- Remove the `demo_user` user from
+  `environments/$ENV/inventory/group_vars/all/basic_users.yml`. Replace the
+  `hpctests_user` in `environments/$ENV/inventory/group_vars/all/hpctests.yml`
+  with an appropriately configured user.
 
 - Consider whether having (read-only) access to Grafana without login is OK. If
   not, remove `grafana_auth_anonymous` in
@@ -325,15 +320,21 @@ Once it completes you can log in to the cluster using:
 - A production deployment may have a more complex networking requirements than
   just a simple network. See the [networks docs](networks.md) for details.
 
-- If floating IPs are required for login nodes, create these in OpenStack and add the IPs into
-  the OpenTofu `login` definition.
-
-- Consider enabling topology aware scheduling. This is currently only supported if your cluster does not include any baremetal nodes. This can be enabled by:
-    1. Creating Availability Zones in your OpenStack project for each physical rack
-    2. Setting the `availability_zone` fields of compute groups in your OpenTofu configuration
-    3. Adding the `compute` group as a child of `topology` in `environments/$ENV/inventory/groups`
-    4. (Optional) If you are aware of the physical topology of switches above the rack-level, override `topology_above_rack_topology` in your groups vars
-       (see [topology docs](../ansible/roles/topology/README.md) for more detail)
+- If floating IPs are required for login nodes, create these in OpenStack and
+  add the IPs into the OpenTofu `login` definition.
+
+- Consider enabling topology aware scheduling. This is currently only supported
+  if your cluster does not include any baremetal nodes. This can be enabled by:
+    1. Creating Availability Zones in your OpenStack project for each physical
+       rack
+    2. Setting the `availability_zone` fields of compute groups in your
+       OpenTofu configuration
+    3. Adding the `compute` group as a child of `topology` in
+       `environments/$ENV/inventory/groups`
+    4. (Optional) If you are aware of the physical topology of switches above
+       the rack-level, override `topology_above_rack_topology` in your groups
+       vars (see [topology docs](../ansible/roles/topology/README.md) for more
+       detail)
 
 - Consider whether mapping of baremetal nodes to ironic nodes is required. See
   [PR 485](https://github.com/stackhpc/ansible-slurm-appliance/pull/485).