CASMINST-2969: Clarify some install steps; Miscellaneous doc linting

Author: mitcharf

README.md

@@ -15,9 +15,9 @@ for Markdown tools will provide a long list of these tools. Some of the tools ar
 at displaying the images and allowing you to follow the navigational links.
 
 The exploration of the CSM documentation begins with the Table of Contents in
-the [Cray System Management Installation Guide](index.md) which introduces 
+the [Cray System Management Installation Guide](index.md) which introduces
 topics related to CSM software installation, upgrade, and operational use. Notice that the
-previous sentence had a link to the index.md file for the Cray System Management Installation Guide. 
+previous sentence had a link to the index.md file for the Cray System Management Installation Guide.
 If the link does not work, then a better Markdown viewer is needed.
 
 Within this README.md file, these topics are described.
@@ -59,7 +59,7 @@ review serves to keep core contributors in alignment while maintaining coherency
 the documentation.
 
 <a name="releases"></a>
-### Releases 
+### Releases
 
 This guide follows a basic release model for enabling amendments and maintenance across releases.
 

background/certificate_authority.md

@@ -13,13 +13,13 @@ installation, there is no supported method to rotate or change the platform CA i
 <a name="overview"></a>
 ## Overview
 
-At *install time*, a PKI certificate authority (CA) can either be generated for a system, or a customer can opt to supply their own (intermediate) CA. 
+At *install time*, a PKI certificate authority (CA) can either be generated for a system, or a customer can opt to supply their own (intermediate) CA.
 
-> Outside of a new installation, there is currently no supported method to rotate (change) the platform CA. The ability to rotate CAs is anticipated as part of a future release. 
+> Outside of a new installation, there is currently no supported method to rotate (change) the platform CA. The ability to rotate CAs is anticipated as part of a future release.
 
 Sealed Secrets, part of shasta-cfg, are used by the installation process to inject CA material in an encrypted form. Vault (cray-vault instance) ultimately sources and stores the CA from a K8S secret (result of decrypting the corresponding Sealed Secret).
 
-The resulting CA will be used to sign multiple workloads on the platform (Ingress, mTLS for PostgreSQL Clusters, Spire, ...). 
+The resulting CA will be used to sign multiple workloads on the platform (Ingress, mTLS for PostgreSQL Clusters, Spire, ...).
 
 > Management of Sealed Secrets should ideally take place on a secure workstation.
 
@@ -63,21 +63,21 @@ spec:
             ...
 ```
 
-> The ```platform_ca``` generator will produce RSA CAs with a 3072-bit modulus, using SHA256 as the base signature algorithm. 
+> The ```platform_ca``` generator will produce RSA CAs with a 3072-bit modulus, using SHA256 as the base signature algorithm.
 
 <a name="customize_platform_generated_ca"></a>
 ## Customize Platform Generated CA
 
-The ```platform_ca``` generator inputs can be customized, if desired. Notably, the ```root_days```, ```int_days```, ```root_cn```, and ```int_cn``` fields can be modified. While the shasta-cfg documentation on the use of generators supplies additional detail, the ```*_days``` settings control the validity period and the ```*_cn``` settings control the common name value for the resulting CA certificates. Ensure the Sealed Secret name reference in ```spec.kubernetes.services.cray-vault.sealedSecrets``` is updated if you opt to use a different name. 
+The ```platform_ca``` generator inputs can be customized, if desired. Notably, the ```root_days```, ```int_days```, ```root_cn```, and ```int_cn``` fields can be modified. While the shasta-cfg documentation on the use of generators supplies additional detail, the ```*_days``` settings control the validity period and the ```*_cn``` settings control the common name value for the resulting CA certificates. Ensure the Sealed Secret name reference in ```spec.kubernetes.services.cray-vault.sealedSecrets``` is updated if you opt to use a different name.
 
-> Outside of a new installation, there is currently no supported method to rotate (change) the platform CA. Please set validity periods accordingly. The ability to rotate CAs is anticipated as part of a future release. 
+> Outside of a new installation, there is currently no supported method to rotate (change) the platform CA. Please set validity periods accordingly. The ability to rotate CAs is anticipated as part of a future release.
 
 <a name="use_external_ca"></a>
 ## Use External CA
 
-The ```static_platform_ca``` generator, part of shasta-cfg, can be used to supply an external CA private key, certificate, and associated upstream CAs that form the trust chain. The generator will attempt to prevent you from supplying a root CA. You must also supply the entire trust chain up to the root CA certificate. 
+The ```static_platform_ca``` generator, part of shasta-cfg, can be used to supply an external CA private key, certificate, and associated upstream CAs that form the trust chain. The generator will attempt to prevent you from supplying a root CA. You must also supply the entire trust chain up to the root CA certificate.
 
-> Outside of a new installation, there is currently no supported method to rotate (change) the platform CA. Please ensure validity periods are set accordingly for external CAs you use in this process. The ability to rotate CAs is anticipated as part of a future release. 
+> Outside of a new installation, there is currently no supported method to rotate (change) the platform CA. Please ensure validity periods are set accordingly for external CAs you use in this process. The ability to rotate CAs is anticipated as part of a future release.
 
 Here is an example ```customizations.yaml``` snippet illustrating the generator input to inject a static CA:
 
@@ -203,4 +203,4 @@ spec:
             ...
 ```
 
-> Only RSA-based CAs with 3072- or 4096-bit moduli, using RSA256 as a signature/digest algorithm have been tested/are supported. Also note, the generator does not support password-protected private keys.  
+> Only RSA-based CAs with 3072- or 4096-bit moduli, using RSA256 as a signature/digest algorithm have been tested/are supported. Also note, the generator does not support password-protected private keys.

background/cloud-init_basecamp_configuration.md

@@ -268,7 +268,7 @@ data:
 <a name="ntp"></a>
 ## NTP
 
-cloud-init modifications to NTP. 
+cloud-init modifications to NTP.
 
 > script: `/srv/cray/scripts/metal/set-ntp-config.sh`
 ---

background/cray_site_init_files.md

@@ -2,16 +2,16 @@
 
 This page describes administrative knowledge around the pre-config files to `csi` or the output files from `csi`.
 
-> Information for collecting certain files starts in [Configuration Payload](../install/prepare_configuration_payload.md) 
+> Information for collecting certain files starts in [Configuration Payload](../install/prepare_configuration_payload.md)
 
    * [`application_node_config.yaml`](../install/prepare_configuration_payload.md#application_node_config_yaml)
    * [`cabinets.yaml`](../install/prepare_configuration_payload.md#cabinets_yaml)
    * [`hmn_connections.json`](../install/prepare_configuration_payload.md#hmn_connections_json)
    * [`ncn_metadata.csv`](../install/prepare_configuration_payload.md#ncn_metadata_csv)
    * [`switch_metadata.csv`](../install/prepare_configuration_payload.md#switch_metadata_csv)
 
-### Topics: 
-  
+### Topics:
+
    * [Save-File / Avoiding Parameters](#save-file--avoiding-parameters)
 
 ## Details

background/index.md

@@ -30,8 +30,8 @@ software, but provides background which might be helpful for troubleshooting an
    * [`switch_metadata.csv`](../install/prepare_configuration_payload.md#switch_metadata_csv)
 
    In addition, after running `csi` with those pre-config files, `csi` creates an output `system_config.yaml`
-   file which can be passed to `csi` when reinstalling this software release. 
-   
+   file which can be passed to `csi` when reinstalling this software release.
+
    See [Cray Site Init Files](cray_site_init_files.md) for more information about these files.
 
 <a name="certificate_authority"></a>

background/ncn_bios.md

@@ -12,7 +12,7 @@ This page denotes BIOS settings that are desirable for non-compute nodes.
 | Intel® Hyper-Threading (e.g. HT) | `Enabled` | Enables two-threads per physical core. | Leverage the full performance of the CPU, the higher thread-count assists with parallel tasks within the processor(s). | Within the Processor or the PCH Menu.
 | Intel® Virtualization Technology (e.g. VT-x, VT) and AMD Virtualization Technology (e.g. AMD-V)| `Enabled` | Enables Virtual Machine extensions. | Provides added CPU support for hypervisors and more for the virtualized plane within Shasta. | Within the Processor or the PCH Menu.
 | PXE Retry Count | 1 or 2 (default: 1) | Attempts done on a single boot-menu option (note: 2 should be set for systems with unsolved network congestion). | If networking is working nominally, then the interface either works or does not. Retrying the same NIC should not work, if it does then there are networking problems that need to be addressed. | Within the Networking Menu, and then under Network Boot.
-| PXE Timeout | 5 Seconds (or less, never more) | The time that the PXE ROM will wait for a DHCP handshake to complete before moving on to the next boot device. | If DHCP is working nominally, then the DHCP handshake should not take longer than 5 seconds. This timeout could be increased where networking faults cannot be reconciled, but ideally this should be tuned to 3 or 2 seconds. | 
+| PXE Timeout | 5 Seconds (or less, never more) | The time that the PXE ROM will wait for a DHCP handshake to complete before moving on to the next boot device. | If DHCP is working nominally, then the DHCP handshake should not take longer than 5 seconds. This timeout could be increased where networking faults cannot be reconciled, but ideally this should be tuned to 3 or 2 seconds. |
 | Continuous Boot | `Disabled` | Whether boot-group (e.g. all network devices, or all disk devices) should continuously retry. This prevents fall-through to the fallback disks. | We want deterministic nodes in Shasta, if the boot fails the first tier we want the node to try the next tier of boot mediums before failing at a shell or menu for intervention. |
 
 > **`NOTE`** **PCIe** options can be found in [PCIe : Setting Expected Values](switch_pxe_boot_from_onboard_nic_to_pcie.md#setting-expected-values).

background/ncn_boot_workflow.md

@@ -23,7 +23,7 @@ Non-compute nodes boot two ways:
 There are two different methods for determining whether a management node is booted using disk or
 PXE. The method to use will vary depending on the system environment.
 
-1. Check kernel parameters. 
+1. Check kernel parameters.
 
    ```bash
    ncn# cat /proc/cmdline
@@ -126,7 +126,7 @@ Setting the boot order with efibootmgr will ensure that the desired network inte
    > <a name="hewlett-packard-enterprise"></a>
    > #### Hewlett-Packard Enterprise
    >
-   > 
+   >
    > ##### Masters
    >
    > ```bash
@@ -139,7 +139,7 @@ Setting the boot order with efibootmgr will ensure that the desired network inte
    > ncn-m# efibootmgr -o $(cat /tmp/bbs* | awk '!x[$0]++' | sed 's/^Boot//g' | awk '{print $1}' | tr -t '*' ',' | tr -d '\n' | sed 's/,$//') | grep -i bootorder
    > BootOrder: 0014,0018,0021,0022
    > ```
-   > 
+   >
    > ##### Storage
    >
    > ```bash
@@ -152,7 +152,7 @@ Setting the boot order with efibootmgr will ensure that the desired network inte
    > ncn-s# efibootmgr -o $(cat /tmp/bbs* | awk '!x[$0]++' | sed 's/^Boot//g' | awk '{print $1}' | tr -t '*' ',' | tr -d '\n' | sed 's/,$//') | grep -i bootorder
    > BootOrder: 001C,001D,0002,0020
    > ```
-   > 
+   >
    > ##### Workers
    >
    > ```bash
@@ -165,7 +165,7 @@ Setting the boot order with efibootmgr will ensure that the desired network inte
    > ncn-w# efibootmgr -o $(cat /tmp/bbs* | awk '!x[$0]++' | sed 's/^Boot//g' | awk '{print $1}' | tr -t '*' ',' | tr -d '\n' | sed 's/,$//') | grep -i bootorder
    > BootOrder: 0012,0017,0018
    > ```
-   > 
+   >
    > <a name="intel-corporation"></a>
    > #### Intel Corporation
    >
@@ -315,7 +315,7 @@ Reset the BIOS. Refer to vendor documentation for resetting the BIOS or attempt
 > ```
 
 1. Reset BIOS with ipmitool
- 
+
    ```bash
    ncn# ipmitool chassis bootdev none options=clear-cmos
    ```

background/ncn_images.md

@@ -47,7 +47,7 @@ To boot an NCN, you need 3 artifacts for each node-type (kubernetes-manager/work
    /var/www/ephemeral/data/ceph:
    total 4
    drwxr-xr-x 2 root root 4096 Dec 17 21:42 0.0.7
-   
+
    /var/www/ephemeral/data/k8s:
    total 4
    drwxr-xr-x 2 root root 4096 Dec 17 21:26 0.0.8
@@ -119,57 +119,57 @@ To boot an NCN, you need 3 artifacts for each node-type (kubernetes-manager/work
    -rw-r--r-- 1 dnsmasq tftp 700352 Dec 15 09:35 ipxe.efi.stable
    -rw-r--r-- 1 root    root   6157 Dec 15 05:12 script.ipxe
    -rw-r--r-- 1 root    root   6284 Dec 17 13:21 script.ipxe.rpmnew
-   
+
    ephemeral:
    total 32
    drwxr-xr-x 2 root root  4096 Dec  6 22:18 configs
    drwxr-xr-x 4 root root  4096 Dec  7 04:29 data
    drwx------ 2 root root 16384 Dec  2 04:25 lost+found
    drwxr-xr-x 4 root root  4096 Dec  3 02:31 prep
    drwxr-xr-x 2 root root  4096 Dec  2 04:45 static
-   
+
    ncn-m001:
    total 4
    lrwxrwxrwx 1 root root 53 Dec 26 06:11 filesystem.squashfs -> ../ephemeral/data/k8s/0.0.8/kubernetes-0.0.8.squashfs
    lrwxrwxrwx 1 root root 47 Dec 26 06:11 initrd.img.xz -> ../ephemeral/data/k8s/0.0.8/initrd.img-0.0.8.xz
    lrwxrwxrwx 1 root root 61 Dec 26 06:11 kernel -> ../ephemeral/data/k8s/0.0.8/5.3.18-24.37-default-0.0.8.kernel
-   
+
    ncn-m002:
    total 4
    lrwxrwxrwx 1 root root 53 Dec 26 06:11 filesystem.squashfs -> ../ephemeral/data/k8s/0.0.8/kubernetes-0.0.8.squashfs
    lrwxrwxrwx 1 root root 47 Dec 26 06:11 initrd.img.xz -> ../ephemeral/data/k8s/0.0.8/initrd.img-0.0.8.xz
    lrwxrwxrwx 1 root root 61 Dec 26 06:11 kernel -> ../ephemeral/data/k8s/0.0.8/5.3.18-24.37-default-0.0.8.kernel
-   
+
    ncn-m003:
    total 4
    lrwxrwxrwx 1 root root 53 Dec 26 06:11 filesystem.squashfs -> ../ephemeral/data/k8s/0.0.8/kubernetes-0.0.8.squashfs
    lrwxrwxrwx 1 root root 47 Dec 26 06:11 initrd.img.xz -> ../ephemeral/data/k8s/0.0.8/initrd.img-0.0.8.xz
    lrwxrwxrwx 1 root root 61 Dec 26 06:11 kernel -> ../ephemeral/data/k8s/0.0.8/5.3.18-24.37-default-0.0.8.kernel
-   
+
    ncn-s001:
    total 4
    lrwxrwxrwx 1 root root 56 Dec 26 06:11 filesystem.squashfs -> ../ephemeral/data/ceph/0.0.7/storage-ceph-0.0.7.squashfs
    lrwxrwxrwx 1 root root 48 Dec 26 06:11 initrd.img.xz -> ../ephemeral/data/ceph/0.0.7/initrd.img-0.0.7.xz
    lrwxrwxrwx 1 root root 62 Dec 26 06:11 kernel -> ../ephemeral/data/ceph/0.0.7/5.3.18-24.37-default-0.0.7.kernel
-   
+
    ncn-s002:
    total 4
    lrwxrwxrwx 1 root root 56 Dec 26 06:11 filesystem.squashfs -> ../ephemeral/data/ceph/0.0.7/storage-ceph-0.0.7.squashfs
    lrwxrwxrwx 1 root root 48 Dec 26 06:11 initrd.img.xz -> ../ephemeral/data/ceph/0.0.7/initrd.img-0.0.7.xz
    lrwxrwxrwx 1 root root 62 Dec 26 06:11 kernel -> ../ephemeral/data/ceph/0.0.7/5.3.18-24.37-default-0.0.7.kernel
-   
+
    ncn-s003:
    total 4
    lrwxrwxrwx 1 root root 56 Dec 26 06:11 filesystem.squashfs -> ../ephemeral/data/ceph/0.0.7/storage-ceph-0.0.7.squashfs
    lrwxrwxrwx 1 root root 48 Dec 26 06:11 initrd.img.xz -> ../ephemeral/data/ceph/0.0.7/initrd.img-0.0.7.xz
    lrwxrwxrwx 1 root root 62 Dec 26 06:11 kernel -> ../ephemeral/data/ceph/0.0.7/5.3.18-24.37-default-0.0.7.kernel
-   
+
    ncn-w002:
    total 4
    lrwxrwxrwx 1 root root 53 Dec 26 06:11 filesystem.squashfs -> ../ephemeral/data/k8s/0.0.8/kubernetes-0.0.8.squashfs
    lrwxrwxrwx 1 root root 47 Dec 26 06:11 initrd.img.xz -> ../ephemeral/data/k8s/0.0.8/initrd.img-0.0.8.xz
    lrwxrwxrwx 1 root root 61 Dec 26 06:11 kernel -> ../ephemeral/data/k8s/0.0.8/5.3.18-24.37-default-0.0.8.kernel
-   
+
    ncn-w003:
    total 4
    lrwxrwxrwx 1 root root 53 Dec 26 06:11 filesystem.squashfs -> ../ephemeral/data/k8s/0.0.8/kubernetes-0.0.8.squashfs

background/ncn_mounts_and_file_systems.md

@@ -42,7 +42,7 @@ Partitioning is controlled by two aspects:
 | Node Type | No. of "small" disks (0.5 TiB) | No. of "large" disks (1.9 TiB) |
 | --- |:---:|:---:|
 | k8s-master nodes | 3 | 0
-| k8s-worker nodes | 2 | 1 
+| k8s-worker nodes | 2 | 1
 | ceph-storage nodes | 2 | 3+
 
 Disks are chosen by dracut. Kubernetes and storage nodes use different dracut modules.
@@ -54,7 +54,7 @@ Disks are chosen by dracut. Kubernetes and storage nodes use different dracut mo
 
 The master nodes and worker nodes use the same artifacts, and thus have the same dracut modules assimilating disks. Therefore, it is important
 to beware of:
-- k8s-master nodes with one or more extra "large" disk(s); these disks help but are unnecessary 
+- k8s-master nodes with one or more extra "large" disk(s); these disks help but are unnecessary
 - ceph-storage nodes do not run the same dracut modules because they have different disk demands
 
 <a name="worker-nodes-with-etcd"></a>
@@ -66,7 +66,7 @@ easily.
 <a name="disable-luks"></a>
 ##### Disable Luks
 
-> **`NOTE`** This is broken, use the [expand RAID](#expand-the-raid) option instead. (MTL-1309) 
+> **`NOTE`** This is broken, use the [expand RAID](#expand-the-raid) option instead. (MTL-1309)
 
 All NCNs (master/worker/storage) have the same kernel parameters, but are not always necessary. This method works by toggling the dependency
 for the metal ETCD module, disabling LUKs will disable ETCD bare-metal creation.
@@ -140,7 +140,7 @@ The above table's rows with overlayFS map their "Mount Paths" to the "Upper Dire
 
 > The "OverlayFS Name" is the name used in fstab and seen in the output of `mount`.
 
-| OverlayFS Name | Upper Directory | Lower Directory (or more) 
+| OverlayFS Name | Upper Directory | Lower Directory (or more)
 | --- | --- | --- |
 | `etcd_overlayfs` | `/run/lib-etcd` | `/var/lib/etcd` |
 | `containerd_overlayfs` | `/run/lib-containerd` | `/var/lib/containerd` |
@@ -164,7 +164,7 @@ There are a few overlays used for NCN image boots. These enable two critical fun
 > 2. `losetup -a` will show where the squashFS is mounted from
 > 3. `mount | grep ' / '` will show you the overlay being layered atop the squashFS
 
-Let us pick apart the `SQFSRAID` and `ROOTRAID` overlays. 
+Let us pick apart the `SQFSRAID` and `ROOTRAID` overlays.
 - `/run/rootfsbase` is the SquashFS image itself
 - `/run/initramfs/live` is the squashFS's storage array, where one or more squashFS can live
 - `/run/initramfs/overlayfs` is the overlayFS storage array, where the persistent directories live
@@ -359,7 +359,7 @@ There are two options one can leave enabled to accomplish this:
 
 For long-term usage, `rd.live.overlay.readonly=1` should be added to the command line.
 
-The `reset=1` toggle is usually used to fix a problematic overlay. If you want to refresh 
+The `reset=1` toggle is usually used to fix a problematic overlay. If you want to refresh
 and purge the overlay completely, then use `rd.live.overlay.reset`.
 
 
@@ -391,7 +391,7 @@ rd.live.overlay.size=307200
 
 # Use a 1 TiB overlayFS
 rd.live.overlay.size=1000000
-``` 
+```
 
 <a name="thin-overlay-feature"></a>
 ##### Thin Overlay Feature

background/ncn_networking.md

@@ -1,6 +1,6 @@
 # NCN Networking
 
-Non-compute nodes and compute nodes have different network interfaces used for booting, this topic focuses on 
+Non-compute nodes and compute nodes have different network interfaces used for booting, this topic focuses on
 the network interfaces for management nodes.
 
 ### Topics:
@@ -72,11 +72,11 @@ lspci | grep c6:00.0
 ```
 
 The Device and Vendor IDs are used in iPXE for bootstrapping the nodes, this allows generators to
-swap IDs out for certain systems until smarter logic can be added to cloud-init. 
+swap IDs out for certain systems until smarter logic can be added to cloud-init.
 
 The following table includes popular vendor and device IDs.
 
-> The bolded numbers are the defaults that live in metal-ipxe's boot script.
+> The bolded numbers are the defaults that live in `metal-ipxe`'s boot script.
 
 | Vendor | Model | Device ID | Vendor ID |
 | :---- | :---- | :-----: | :---------: |