TELCODOCS-1838 Update reference SiteConfig to use rootDeviceHints with consistent naming

Author: kquinn1204

modules/ztp-configuring-disk-partitioning.adoc

@@ -8,39 +8,197 @@
 
 Configure disk partitioning for a managed cluster using a `SiteConfig` CR and {ztp-first}. The  disk partition details in the `SiteConfig` CR must match the underlying disk.
 
-[NOTE]
+[IMPORTANT]
 ====
-Use persistent naming for devices to avoid device names such as `/dev/sda` and `/dev/sdb` being switched at every reboot. You can use `rootDeviceHints` to choose the bootable device and then use same device for further partitioning.
+You must complete this procedure at installation time.
 ====
 
 .Prerequisites
 
-* You have installed the OpenShift CLI (`oc`).
+* Install Butane.
+
+.Procedure
 
-* You have logged in to the hub cluster as a user with `cluster-admin` privileges.
+. Create the `storage.bu` file.
++
+[source,yaml]
+----
+variant: fcos
+version: 1.3.0
+storage:
+  disks:
+  - device: /dev/disk/by-path/pci-0000:01:00.0-scsi-0:2:0:0 <1>
+    wipe_table: false
+    partitions:
+    - label: var-lib-containers
+      start_mib: <start_of_partition> <2>
+      size_mib: <partition_size> <3>
+  filesystems:
+    - path: /var/lib/containers
+      device: /dev/disk/by-partlabel/var-lib-containers
+      format: xfs
+      wipe_filesystem: true
+      with_mount_unit: true
+      mount_options:
+        - defaults
+        - prjquota
+----
+<1> Specify the root disk.
+<2> Specify the start of the partition in MiB. If the value is too small, the installation fails.
+<3> Specify the size of the partition. If the value is too small, the deployments fails.
 
-* You have created a Git repository where you manage your custom site configuration data for use with {ztp-first}.
+. Convert the `storage.bu` to an Ignition file by running the following command:
++
+--
+[source,terminal]
+----
+$ butane storage.bu
+----
 
-.Procedure
+.Example output
+[source,terminal]
+----
+{"ignition":{"version":"3.2.0"},"storage":{"disks":[{"device":"/dev/disk/by-path/pci-0000:01:00.0-scsi-0:2:0:0","partitions":[{"label":"var-lib-containers","sizeMiB":0,"startMiB":250000}],"wipeTable":false}],"filesystems":[{"device":"/dev/disk/by-partlabel/var-lib-containers","format":"xfs","mountOptions":["defaults","prjquota"],"path":"/var/lib/containers","wipeFilesystem":true}]},"systemd":{"units":[{"contents":"# # Generated by Butane\n[Unit]\nRequires=systemd-fsck@dev-disk-by\\x2dpartlabel-var\\x2dlib\\x2dcontainers.service\nAfter=systemd-fsck@dev-disk-by\\x2dpartlabel-var\\x2dlib\\x2dcontainers.service\n\n[Mount]\nWhere=/var/lib/containers\nWhat=/dev/disk/by-partlabel/var-lib-containers\nType=xfs\nOptions=defaults,prjquota\n\n[Install]\nRequiredBy=local-fs.target","enabled":true,"name":"var-lib-containers.mount"}]}}
+----
+--
+
+. Use a tool such as link:https://jsonformatter.org/json-pretty-print[JSON Pretty Print] to convert the output into JSON format. 
 
-. Add the following YAML that describes the host disk partitioning to the `SiteConfig` CR that you use to install the managed cluster:
+. Copy the output into the `.spec.clusters.nodes.ignitionConfigOverride` field in the `SiteConfig` CR.
 +
+.Example
 [source,yaml]
 ----
-nodes:
-    rootDeviceHints:
-      wwn: "0x62cea7f05c98c2002708a0a22ff480ea"
-    diskPartition:
-      - device: /dev/disk/by-id/wwn-0x62cea7f05c98c2002708a0a22ff480ea <1>
-        partitions:
-          - mount_point: /var/imageregistry
-            size: 102500 <2>
-            start: 344844 <3>
+[...]
+spec:
+  clusters:
+    - nodes:
+        - ignitionConfigOverride: |
+          {
+            "ignition": {
+              "version": "3.2.0"
+            },
+            "storage": {
+              "disks": [
+                {
+                  "device": "/dev/disk/by-path/pci-0000:01:00.0-scsi-0:2:0:0",
+                  "partitions": [
+                    {
+                      "label": "var-lib-containers",
+                      "sizeMiB": 0,
+                      "startMiB": 250000
+                    }
+                  ],
+                  "wipeTable": false
+                }
+              ],
+              "filesystems": [
+                {
+                  "device": "/dev/disk/by-partlabel/var-lib-containers",
+                  "format": "xfs",
+                  "mountOptions": [
+                    "defaults",
+                    "prjquota"
+                  ],
+                  "path": "/var/lib/containers",
+                  "wipeFilesystem": true
+                }
+              ]
+            },
+            "systemd": {
+              "units": [
+                {
+                  "contents": "# # Generated by Butane\n[Unit]\nRequires=systemd-fsck@dev-disk-by\\x2dpartlabel-var\\x2dlib\\x2dcontainers.service\nAfter=systemd-fsck@dev-disk-by\\x2dpartlabel-var\\x2dlib\\x2dcontainers.service\n\n[Mount]\nWhere=/var/lib/containers\nWhat=/dev/disk/by-partlabel/var-lib-containers\nType=xfs\nOptions=defaults,prjquota\n\n[Install]\nRequiredBy=local-fs.target",
+                  "enabled": true,
+                  "name": "var-lib-containers.mount"
+                }
+              ]
+            }
+          }   
+[...]
 ----
-<1> This setting depends on the hardware. The setting can be a serial number or device name. The value must match the value set for `rootDeviceHints`.
-<2> The minimum value for `size` is 102500 MiB.
-<3> The minimum value for `start` is 25000 MiB. The total value of `size` and `start` must not exceed the disk size, or the installation will fail.
++
+[NOTE]
+====
+If the `.spec.clusters.nodes.ignitionConfigOverride` field does not exist, create it.  
+====
 
-. Save the `SiteConfig` CR and push it to the site configuration repo.
+.Verification
 
-The {ztp} pipeline provisions the cluster using the `SiteConfig` CR and configures the disk partition.
+.  During or after installation, verify on the hub cluster that the `BareMetalHost` object shows the annotation by running the following command:
++
+--
+[source,terminal]
+----
+$ oc get bmh -n my-sno-ns my-sno -ojson | jq '.metadata.annotations["bmac.agent-install.openshift.io/ignition-config-overrides"]
+----
+
+.Example output
+[source,terminal]
+----
+"{\"ignition\":{\"version\":\"3.2.0\"},\"storage\":{\"disks\":[{\"device\":\"/dev/disk/by-id/wwn-0x6b07b250ebb9d0002a33509f24af1f62\",\"partitions\":[{\"label\":\"var-lib-containers\",\"sizeMiB\":0,\"startMiB\":250000}],\"wipeTable\":false}],\"filesystems\":[{\"device\":\"/dev/disk/by-partlabel/var-lib-containers\",\"format\":\"xfs\",\"mountOptions\":[\"defaults\",\"prjquota\"],\"path\":\"/var/lib/containers\",\"wipeFilesystem\":true}]},\"systemd\":{\"units\":[{\"contents\":\"# Generated by Butane\\n[Unit]\\nRequires=systemd-fsck@dev-disk-by\\\\x2dpartlabel-var\\\\x2dlib\\\\x2dcontainers.service\\nAfter=systemd-fsck@dev-disk-by\\\\x2dpartlabel-var\\\\x2dlib\\\\x2dcontainers.service\\n\\n[Mount]\\nWhere=/var/lib/containers\\nWhat=/dev/disk/by-partlabel/var-lib-containers\\nType=xfs\\nOptions=defaults,prjquota\\n\\n[Install]\\nRequiredBy=local-fs.target\",\"enabled\":true,\"name\":\"var-lib-containers.mount\"}]}}"
+----
+--
+
+. After installation, check the {sno} disk status. 
+
+.. Enter into a debug session on the {sno} node by running the following command. This step instantiates a debug pod called `<node_name>-debug`:
++
+--
+[source,terminal]
+----
+$ oc debug node/my-sno-node
+----
+
+.. Set `/host` as the root directory within the debug shell by running the following command. The debug pod mounts the host’s root file system in `/host` within the pod. By changing the root directory to `/host`, you can run binaries contained in the host’s executable paths:
++
+[source,terminal]
+----
+# chroot /host
+----
+
+.. List information about all available block devices by running the following command:
++
+[source,terminal]
+----
+# lsblk
+----
++
+.Example output
+[source,terminal]
+----
+NAME   MAJ:MIN RM   SIZE RO TYPE MOUNTPOINTS
+sda      8:0    0 446.6G  0 disk
+├─sda1   8:1    0     1M  0 part
+├─sda2   8:2    0   127M  0 part
+├─sda3   8:3    0   384M  0 part /boot
+├─sda4   8:4    0 243.6G  0 part /var
+│                                /sysroot/ostree/deploy/rhcos/var
+│                                /usr
+│                                /etc
+│                                /
+│                                /sysroot
+└─sda5   8:5    0 202.5G  0 part /var/lib/containers
+----
+
+.. Display information about the file system disk space usage by running the following command:
++
+[source,terminal]
+----
+# df -h
+----
++
+.Example output
+[source,terminal]
+----
+Filesystem      Size  Used Avail Use% Mounted on
+devtmpfs        4.0M     0  4.0M   0% /dev
+tmpfs           126G   84K  126G   1% /dev/shm
+tmpfs            51G   93M   51G   1% /run
+/dev/sda4       244G  5.2G  239G   3% /sysroot
+tmpfs           126G  4.0K  126G   1% /tmp
+/dev/sda5       203G  119G   85G  59% /var/lib/containers
+/dev/sda3       350M  110M  218M  34% /boot
+tmpfs            26G     0   26G   0% /run/user/1000
+----
+--

modules/ztp-deploying-a-site.adoc

@@ -73,7 +73,7 @@ include::snippets/ztp_example-sno.yaml[]
 +
 [NOTE]
 ====
-For more information about BMC addressing, see the "Additional resources" section.
+For more information about BMC addressing, see the "Additional resources" section. The `installConfigOverrides` and  `ignitionConfigOverride` fields are expanded in the example for ease of readability.   
 ====
 
 .. You can inspect the default set of extra-manifest `MachineConfig` CRs in `out/argocd/extra-manifest`. It is automatically applied to the cluster when it is installed.