kelvin/warewulf
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Simplify and reformat storage documentation

Browse Source 
Signed-off-by: Jonathon Anderson <janderson@ciq.com>
This commit is contained in:
Jonathon Anderson
2024-02-17 01:45:57 -07:00
parent 241883ea32
commit 5ea7e66940
1 changed files with 62 additions and 71 deletions
Download Patch File Download Diff File Expand all files Collapse all files

133
userdocs/contents/disks.rst
View File

@@ -1,94 +1,73 @@
/Exa===============
===============
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](https://coreos.github.io/ignition/) to create the partitions and file systems.
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.
.. _ignition: https://coreos.github.io/ignition/
.. note::
It is not currently possible to manage the root file system with
Warewulf.
Warewulf can be used, for example, to create `swap` partitions or
`/scratch` 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.
Partition and file system creation requires both ``ignition`` and ``sgdisk`` to be installed in the container image.
Mind that the paths and/or package names may differ depending on the os you based your container on.
Rocky Linux
-----------
.. code-block:: shell
dnf install ignition gdisk
openSuse Leap
-------------
.. code-block:: shell
zypper install ignition gptfdisk
Storage objects
===============
The format of the storage objects is inspired by `butane/ignition`;
but, where `butane/ignition` uses lists for holding disks, partitions
and file systems, Warewulf uses maps instead.
The format of the storage objects is inspired by ``butane/ignition``;
but, where ``butane/ignition`` uses lists for holding disks, partitions and file systems, Warewulf uses maps instead.
A node or profile can have several disks, where each disk is
identified by the path to its block device. Every disks holds a map to
its partitions and a `bool` switch to indicate if an existing
partition table should be overwritten if it does not matched the
desired configuration.
A node or profile can have several disks, where each disk is identified by the path to its block device.
Every disks holds a map to its partitions and a ``bool`` switch to indicate if an existing partition table should be overwritten if it does not matched the desired configuration.
Each partition is identified by its label. The partition number can be
omitted, but specifying it is recommended as `ignition` may fail
without it. Partition sizes should also be set (specified in MiB),
except of the last partition: if no size is given, the maximum
available size is used. Each partition has the switches `should_exist`
and `wipe_partition_entry` which control the partition creation
process.
Each partition is identified by its label.
The partition number can be omitted, but specifying it is recommended as ``ignition`` may fail without it.
Partition sizes should also be set (specified in MiB), except of the last partition:
if no size is given, the maximum available size is used.
Each partition has the switches ``should_exist`` and ``wipe_partition_entry`` which control the partition creation process.
File systems are identified by their underlying block device,
preferably using the `/dev/by-partlabel` format. Except for a `swap`
partition, an absolute path for the mount point must be specified for
each file system. Depending on the container used, valid formats are
`btrfs`, `ext3`, `ext4`, and `xfs`. Each file system has the switch
`wipe_filesystem` to control whether an existing file system is wiped.
File systems are identified by their underlying block device, preferably using the ``/dev/by-partlabel`` format.
Except for a ``swap`` partition, an absolute path for the mount point must be specified for each file system.
Depending on the container used, valid formats are ``btrfs``, ``ext3``, ``ext4``, and ``xfs``.
Each file system has the switch ``wipe_filesystem`` to control whether an existing file system is wiped.
Ignition Implementation
=======================
The ignition implementation uses systemd services, as the underlying
`sgdisk` command relies on dbus notifications. All necessary services
are distributed by the `wwinit` overlay and depends on the existence
of the file `/warewulf/ignition.json`. This file is created by the
template function `{{ createIgnitionJson }}` only if the configuration
contains necessary specifications for disks, partitions, and file
systems. If the file `/warewulf/ignition.json` exists, the service
`ignition-disks-ww4.service` calls the ignition binary which takes
creates partitions and file systems. A systemd `.mount` unit is
created for each configured file system, which also creates the
necessary mount points in the root file system. These mount units are
required by the enabled `ww4-disks.target`. Entries in `/etc/fstab`
are created with the `no_auto` option so that file systems can be
easily mounted.
The ignition implementation uses systemd services, as the underlying ``sgdisk`` command relies on dbus notifications.
All necessary services are distributed by the ``wwinit`` overlay and depends on the existence of the file ``/warewulf/ignition.json``.
This file is created by the template function ``{{ createIgnitionJson }}`` only if the configuration contains necessary specifications for disks, partitions, and file systems.
If the file ``/warewulf/ignition.json`` exists, the service ``ignition-disks-ww4.service`` calls the ignition binary which takes creates partitions and file systems.
A systemd ``.mount`` unit is created for each configured file system, which also creates the necessary mount points in the root file system.
These mount units are required by the enabled ``ww4-disks.target``.
Entries in ``/etc/fstab`` are created with the ``no_auto`` option so that file systems can be easily mounted.
Example disk configuration
==========================
The following command will create a `/scratch` file system on the node
`n01`
The following command will create a ``/scratch`` file system on the node ``n01``.
.. code-block:: shell
@@ -108,15 +87,27 @@ A swap partition with 1Gig can be added with
--partname swap --partsize=1024 --partnumber 1 \
--fsname swap --fsformat swap --fspath swap
which has the partition number `1` so that it will be added before the
`/scratch` partition.
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.
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 with ``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
.. code-block:: shell
/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.)
- Sometimes you need to add ``should_exist: "true"`` for the swap partiton as well.