Update disks.rst

userdocs/contents/disks.rst

@@ -4,8 +4,7 @@ Disk Management
 
 Warewulf itself does not manage disks, partitions, or file systems
 directly, but provides structures in the configuration for these
-objects. At the moment warewulf supports `ignition` to create the
-partitions and file systems.
+objects. At the moment warewulf supports [ignition](https://coreos.github.io/ignition/) to create the partitions and file systems.
 
 .. note::
 
@@ -15,6 +14,30 @@ partitions and file systems.
 Warewulf can be used, for example, to create `swap` partitions or
 `/scratch` file systems.
 
+Requirements
+===============
+
+For the creation of partitions and file systems to work you will need to make sure that `ignition` as well as `sgdisk` is available in your container. 
+ 
+ - `sgdisk` should be part of the package `gdisk` in RedHat-flavored OS like Rocky, AlmaLinux, etc. Therefore either add `dnf install gdisk` to your CI/CD-container-build-pipeline or manually install it in your container (`wwctl container shell <mycontainer>`).
+ - check if `ignition` is present in the path `/usr/lib/dracut/modules.d/30ignition`. If it's missing you'll have shell into your container (`wwctl container shell <mycontainer>`) and run 
+   ``` 
+   git clone https://github.com/coreos/ignition.git
+   dnf install go make libblkid-devel
+   cd ignition 
+   make 
+   ``` 
+ Once the build finished you'll find the binary in ./bin/. Proceed with
+   ``` 
+   mkdir -p /usr/lib/dracut/modules.d/30ignition
+   cp bin/ignition /usr/lib/dracut/modules.d/30ignition/
+   cd .. 
+   rm -rf ignition 
+   ```
+ Now your container contains the module `ignition`. You may or may not want to remove `go`, `make`, and `libblkid-devel` before leaving the interactive container shell. 
+
+Mind that the paths and/or package names may differ depending on the os you based your container on. 
+
 Storage objects
 ===============
 
@@ -87,3 +110,13 @@ A swap partition with 1Gig can be added with
 
 which has the partition number `1` so that it will be added before the
 `/scratch` partition.
+
+Troubleshooting
+===============
+
+If the partition creation didn't work as expected you have a few options to investigate: 
+ - add `systemd.log_level=debug` and or `rd.debug` to the kernelArgs of the node you're working on 
+ - after the next boot you should be able to find verbose information on the node in the journal (`journalctl -u ignition-ww4-disks.service`). 
+ - you could also check the content of `/warewulf/ignition.json`
+ - you could try to tinker with `/warewulf/ignition.json` calling `/usr/lib/dracut/modules.d/30ignition/ignition --platform=metal --stage=disks --config-cache /warewulf/ignition.json -log-to-stdout` after each iteration on the node directly until you find the settings you need (make sure to unmount all partitions if `ignition` was partially successful). This would save you the time of the boot cycles. But you'll have to figure the analoge syntax in nodes.conf eventually.  
+ - sometimes you need to add `should_exist: "true"` for the swap-partiton as well in `nodes.conf` either by calling `wwctl node edit` or by editing `nodes.conf` directly with your editor.