From b74e32621219a80a028546cf5d888e76523ce1a5 Mon Sep 17 00:00:00 2001 From: Jonathon Anderson Date: Tue, 1 Jul 2025 00:05:30 -0600 Subject: [PATCH] Move "provision to disk" documentation to "provisioning disks" section Signed-off-by: Jonathon Anderson --- userdocs/nodes/disks.rst | 114 ++++++++++++++++++++++++++++++++ userdocs/server/bootloaders.rst | 114 -------------------------------- 2 files changed, 114 insertions(+), 114 deletions(-) diff --git a/userdocs/nodes/disks.rst b/userdocs/nodes/disks.rst index 353c2a44..43a81bdd 100644 --- a/userdocs/nodes/disks.rst +++ b/userdocs/nodes/disks.rst @@ -146,3 +146,117 @@ file systems once, you may See the `upstream ignition documentation`_ for additional information. .. _upstream ignition documentation: https://coreos.github.io/ignition/operator-notes/#filesystem-reuse-semantics + + +.. _provision to disk: + +Provision to disk +================= + +*New in Warewulf v4.6.2* + +As a tech preview, the Warewulf two-stage boot process can provision the node +image to local storage. + +.. warning:: + + This functionality is a technology preview and should be used with care. Pay + specific attention to ``wipeFilesytem`` and similar settings. + +.. note:: + + Warewulf doesn't install a bootloader to the disk or add UEFI entries. Nodes + still request an image and configuration from the Warewulf server on every + boot. + +.. note:: + + While provisioning to disk should be possible during a single-stage boot, not + all features are available: + + - Warewulf does not perform hardware detection to ensure that necessary + kernel modules are loaded prior to init. + - Warewulf does not load udev to ensure that ``/dev/disk/by-*`` symlinks are + available prior to init. + +With Ignition +------------- + +Warewulf needs a prepared file system to deploy the image to. Warewulf can +provision this file system using Ignition. To use Ignition, include ``ignition`` +in your system overlay. The ignition overlay provisions disks during init and, +optionally, during the first stage of a two-stage boot. This allows the +root file system to be provisioned before the image is loaded. + +.. code-block:: shell + + wwctl node set wwnode1 \ + --diskname /dev/vda --diskwipe \ + --partname rootfs --partcreate --partnumber 1 \ + --fsname rootfs --fsformat ext4 --fspath / + +In order to allow Dracut to provision the disk, partition, and file system, +Ignition must be included in the Dracut image. + +.. code-block:: shell + + wwctl image exec rockylinux-9 -- /usr/bin/dracut --force --no-hostonly --add wwinit --add ignition --regenerate-all + +The necessary file system may alternatively be prepared out-of-band. + +With sfdisk and mkfs +-------------------- + +Systems that do not have access to Ignition (e.g., Rocky Linux 8) can provision +the root file system using a combination of ``sfdisk`` and ``mkfs``. To use +them, include ``sfdisk`` and ``mkfs`` in your system overlay. The ``sfdisk`` and +``mkfs`` overlays provision disk and file systems during the first stage of a +two-stage boot. This allows the root file system to be provisioned before the +image is loaded. + +Configure the ``sfdisk`` and ``mkfs`` overlays using resources: + +.. code-block:: shell + + wwctl node set wwnode1 \ + --diskname /dev/vda --diskwipe \ + --partname rootfs --partcreate --partnumber 1 \ + --fsname rootfs --fsformat ext4 --fspath / + +In order to allow Dracut to provision the disk, partition, and file system, some +additional commands must be included in the Dracut image, depending on which +functionality is used: + +- **sfdisk:** writes the partition table + + - **blockdev:** used to re-read the partition table after writing + + - **udevadm:** used to trigger udev events after writing the partition table + +- **mkfs:** formats file systems (may also require file-system-specific commands like mkfs.ext4) + + - **mkfs.ext4**, **mkfs.btrfs**, etc: used by mkfs to format specific file systems + + - **wipefs:** used to determine if a file system already exists + +.. code-block:: shell + + wwctl image exec rockylinux-8 -- /usr/bin/dracut --force --no-hostonly \ + --add wwinit \ + --install sfdisk \ + --install blockdev \ + --install udevadm \ + --install mkfs \ + --install mkfs.ext4 \ + --install wipefs \ + --regenerate-all + +Configuring the root device +--------------------------- + +Set the desired storage device for the node image using the ``--root`` +parameter. + +.. code-block:: shell + + wwctl node set wwnode1 --root /dev/disk/by-partlabel/rootfs diff --git a/userdocs/server/bootloaders.rst b/userdocs/server/bootloaders.rst index 2a81e6f3..26e09969 100644 --- a/userdocs/server/bootloaders.rst +++ b/userdocs/server/bootloaders.rst @@ -396,117 +396,3 @@ The wwinit module provisions to tmpfs. By default, tmpfs is permitted to use up to 50% of physical memory. This size limit may be adjusted using the kernel argument `wwinit.tmpfs.size`. (This parameter is passed to the `size` option during tmpfs mount. See ``tmpfs(5)`` for more details.) - -.. _provision to disk: - -Provision to disk -================= - -*New in Warewulf v4.6.2* - -As a tech preview, the Warewulf two-stage boot process can provision the node -image to local storage. - -.. warning:: - - This functionality is a technology preview and should be used with care. Pay - specific attention to ``wipeFilesytem`` (ignition) and ``overwrite`` (mkfs) - settings. - -.. note:: - - Warewulf doesn't install a bootloader to the disk or add UEFI entries. Nodes - still request an image and configuration from the Warewulf server on every - boot. - -.. note:: - - While provisioning to disk should be possible during a single-stage boot, not - all features are available: - - - Warewulf does not perform hardware detection to ensure that necessary - kernel modules are loaded prior to init. - - Warewulf does not load udev to ensure that ``/dev/disk/by-*`` symlinks are - available prior to init. - -With Ignition -------------- - -Warewulf needs a prepared file system to deploy the image to. Warewulf can -provision this file system using Ignition. To use Ignition, include ``ignition`` -in your system overlay. The ignition overlay provisions disks during init and, -optionally, during the first stage of a two-stage boot. This allows the -root file system to be provisioned before the image is loaded. - -.. code-block:: shell - - wwctl node set wwnode1 \ - --diskname /dev/vda --diskwipe \ - --partname rootfs --partcreate --partnumber 1 \ - --fsname rootfs --fsformat ext4 --fspath / - -In order to allow Dracut to provision the disk, partition, and file system, -Ignition must be included in the Dracut image. - -.. code-block:: shell - - wwctl image exec rockylinux-9 -- /usr/bin/dracut --force --no-hostonly --add wwinit --add ignition --regenerate-all - -The necessary file system may alternatively be prepared out-of-band. - -With sfdisk and mkfs --------------------- - -Systems that do not have access to Ignition (e.g., Rocky Linux 8) can provision -the root file system using a combination of ``sfdisk`` and ``mkfs``. To use -them, include ``sfdisk`` and ``mkfs`` in your system overlay. The ``sfdisk`` and -``mkfs`` overlays provision disk and file systems during the first stage of a -two-stage boot. This allows the root file system to be provisioned before the -image is loaded. - -Configure the ``sfdisk`` and ``mkfs`` overlays using resources: - -.. code-block:: shell - - wwctl node set wwnode1 \ - --diskname /dev/vda --diskwipe \ - --partname rootfs --partcreate --partnumber 1 \ - --fsname rootfs --fsformat ext4 --fspath / - -In order to allow Dracut to provision the disk, partition, and file system, some -additional commands must be included in the Dracut image, depending on which -functionality is used: - -- **sfdisk:** writes the partition table - - - **blockdev:** used to re-read the partition table after writing - - - **udevadm:** used to trigger udev events after writing the partition table - -- **mkfs:** formats file systems (may also require file-system-specific commands like mkfs.ext4) - - - **mkfs.ext4**, **mkfs.btrfs**, etc: used by mkfs to format specific file systems - - - **wipefs:** used to determine if a file system already exists - -.. code-block:: shell - - wwctl image exec rockylinux-8 -- /usr/bin/dracut --force --no-hostonly \ - --add wwinit \ - --install sfdisk \ - --install blockdev \ - --install udevadm \ - --install mkfs \ - --install mkfs.ext4 \ - --install wipefs \ - --regenerate-all - -Configuring the root device ---------------------------- - -Set the desired storage device for the node image using the ``--root`` -parameter. - -.. code-block:: shell - - wwctl node set wwnode1 --root /dev/disk/by-partlabel/rootfs