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

Distinguish between OS images and overlay images in documentation

Browse Source 
Signed-off-by: Jonathon Anderson <janderson@ciq.com>
This commit is contained in:
Jonathon Anderson
2026-03-18 08:10:49 -06:00
parent 1fd8b65ebf
commit 7909598a3d
20 changed files with 89 additions and 87 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
userdocs/getting-started/el-quickstart.rst
View File

@@ -155,10 +155,10 @@ configure --all``.
you may need to run ``restorecon -Rv /var/lib/tftpboot/`` to label
files written to ``tftpboot``.
Add a base node image
=====================
Add an OS image
===============
This will pull a basic node image from Docker Hub
This will pull a basic OS image from Docker Hub
and set it for the "default" node profile.
.. code-block:: bash

25
userdocs/getting-started/glossary.rst
View File

@@ -12,13 +12,7 @@ External services
configures a DHCP server (either ISC DHCP or dnsmasq) and a TFTP server.
Image
The node images that Warewulf manages and provisions. Images may be imported
from OCI image registries, OCI image archives, Apptainer sandboxes, and
manual chroot directories.
Warewulf images are maintained as an uncompressed "virtual node file system"
(VNFS, sometimes also referred to as a "chroot"). These virtual file systems
are then built as single-file images which may be used to provision a node.
See "Operating System (OS) Image" or "Overlay Image."
Kernel
In addition to an image, Warewulf also requires a kernel (typically a Linux
@@ -42,6 +36,14 @@ nodes.conf
This file is sometimes referred to as the "nodes database" or "node
registry."
Operating System (OS) Image
An operating system image (or OS image) contains a bootable operating
system. When provisioning a cluster node, Warewulf combines the OS image
with the node's overlay images to provision the complete, configured image.
OS images may be imported from OCI image registries, OCI image archives,
Apptainer sandboxes, and manual chroot directories.
Overlay
Warewulf overlays provide customization for the provisioned image. Overlays
may be configured on nodes or profiles, as either **system** or **runtime**
@@ -56,6 +58,15 @@ Overlay
Warewulf includes a number of **distribution overlays**; but additional
**site overlays** can be added to a Warewulf environment.
Overlay Image
An overlay image contains the rendered contents of multiple overlays for a
given cluster node. Nodes have a "system overlay" image and a "runtime
overlay" image, based on the system and runtime overlays associated with each
node.
Overlay images are not managed directly, but are built by the ``wwctl
overlay build`` command.
Profile
Warewulf profiles are abstract nodes that carry the same configuration
attributes but do not provision any specific node. Warewulf nodes may then

16
userdocs/getting-started/introduction.rst
View File

@@ -9,10 +9,10 @@ Warewulf is known for its massive scalability and simple management of stateless
(disk optional) provisioning.
Warewulf leverages a simple administrative model centralizing administration
around virtual node images which are used to provision out to the cluster nodes.
This means you can have hundreds or thousands of cluster nodes all booting and
running on the same node image. As of Warewulf v4, the node image can be managed
using industry-standard container tooling and/or CI/CD pipelines. This can be as
around virtual OS images which are used to provision cluster nodes. This means
you can have hundreds or thousands of cluster nodes all booting and running on
the same OS image. As of Warewulf v4, the OS image can be managed using
industry-standard container tooling and/or CI/CD pipelines. This can be as
simple as DockerHub or your own private GitLab CI infrastructure. With this
architecture, Warewulf combines the best of High Performance Computing (HPC),
Cloud, Hyperscale, and Enterprise deployment principles to create and maintain
@@ -47,7 +47,7 @@ flexible provisioning system for all types of clusters.
any environment.
* **Secure**: Warewulf supports SELinux out-of-the-box. Just install SELinux in
your node image and let Warewulf do the rest!
your OS image and let Warewulf do the rest!
* **Open Source**: Warewulf is and has always been open source. It can be used
in any environment, whether public, private, non-profit, or commercial. And
@@ -70,14 +70,14 @@ configuration and image and overlay assignments.
**Node profiles** provide a flexible abstraction for applying configuration to
multiple nodes.
**Node images** provide a bootable operating system image, including the kernel
that will be used to boot the cluster node. Node images provide a base operating
**Operating system images** provide a bootable image, including the kernel
that will be used to boot the cluster node. OS images provide the base operating
system and, by default, run entirely in memory. This means that when you
reboot the node, the node retains no information about Warewulf or how it
booted; but it also means that they return to their initial known-good state.
**Overlays** customize the provisioned operating system image with static files
and dynamic templates applied with the node image and, optionally, periodically
and dynamic templates applied with the OS image and, optionally, periodically
at runtime.
Beowulf overview

22
userdocs/images/images.rst
View File

@@ -1,15 +1,15 @@
.. _images:
===========
Node Images
===========
=========
OS Images
=========
Warewulf node images are a "Virtual Node File System" (VNFS) that serves as a
base image for cluster nodes. This is similar to a "golden master" image, except
Warewulf operating system (OS) images are a "Virtual Node File System" (VNFS)
that serves as an image for cluster nodes. This is similar to a "golden master" image, except
that the image source exists mutably within a directory on the Warewulf control
node (e.g. a ``chroot()``).
Warewulf node images have several similarities to Linux containers; so Warewulf
Warewulf OS images have several similarities to Linux containers; so Warewulf
v4 integrates directly within the container ecosystem to facilitate the process
of image creation and image management: images can be built, for example, with
Docker, Podman, or Apptainer, and imported directly from OCI registries or local
@@ -58,7 +58,7 @@ or Apptainer sandbox.
OCI Registry
------------
You can import node images from an OCI registry, public or private.
You can import OS images from an OCI registry, public or private.
.. code-block:: console
@@ -76,10 +76,10 @@ You can import node images from an OCI registry, public or private.
Most images in Docker Hub are not "bootable": they typically do not include
a kernel, and likely don't include any init system. For this reason, don't
expect a base image from DockerHub (e.g. ``docker://rockylinux`` or
expect just any image from DockerHub (e.g. ``docker://rockylinux`` or
``docker://debian``) to boot properly with Warewulf.
The Warewulf project maintains a set of `example node images
The Warewulf project maintains a set of `example OS images
<https://github.com/warewulf/warewulf-node-images>`_ that are configured to
boot when used with Warewulf. These images can be imported directly into
Warewulf or used as base images for local custom images.
@@ -300,7 +300,7 @@ Exit Script
Warewulf executes the script ``/etc/warewulf/image_exit.sh`` in the image after
a ``wwctl image shell`` or ``wwctl image exec`` and prior to (re)building the
final node image for delivery. This is typically used to remove cache or log
final OS image for delivery. This is typically used to remove cache or log
files that may have been generated by the executed command or interactive
session.
@@ -310,7 +310,7 @@ package repository caches that may have been generated.
Defining New Images
===================
It is absolutely possible to import a base image into Warewulf and make all
It is absolutely possible to import an OS image into Warewulf and make all
changes interactively with ``wwctl image shell``; but it is often better to
define new images with a container image definition file. This can be done using
the OCI and Singularity (Apptainer) ecosystems.

4
userdocs/images/selinux.rst
View File

@@ -16,8 +16,8 @@ for SELinux context labeling.)
.. note::
Versions of Warewulf prior to v4.5.8 also required a kernel argument
"rootfstype=ramfs" in order for wwinit to copy the node image to tmpfs; but
this is no longer required.
"rootfstype=ramfs" in order for wwinit to copy the image to tmpfs; but this
is no longer required.
Once that is done, enable SELinux in ``/etc/sysconfig/selinux`` and install the
appropriate packages in the image. `An example`_ of such an image is available

2
userdocs/index.rst
View File

@@ -45,7 +45,7 @@ Welcome to the Warewulf User Guide!
:maxdepth: 1
:caption: Images
Node Images <images/images>
OS Images <images/images>
Image Kernels <images/kernel>
Syncuser <images/syncuser>
SELinux <images/selinux>

23
userdocs/nodes/disks.rst
View File

@@ -12,11 +12,6 @@ sfdisk, mkfs, and mkswap during boot.
Ignition can, for example, create ``swap`` partitions or ``/scratch`` file
systems.
.. note::
Warewulf is not currently able to provision the node image onto an explicitly
provisioned root file system.
Requirements
============
@@ -153,7 +148,7 @@ See the `upstream ignition documentation`_ for additional information.
Swap and image memory usage
===========================
Warewulf node images run entirely in memory. Configuring a local swap partition
Warewulf images run entirely in memory. Configuring a local swap partition
can allow the kernel to reclaim that RAM for applications — but only under the
right conditions. Whether swap can free image memory depends on which root
filesystem type the node uses.
@@ -162,7 +157,7 @@ tmpfs root
----------
When the root filesystem is ``tmpfs`` (the default for two-stage dracut boot, or
when ``--root=tmpfs`` is set explicitly), the node image lives in the page cache.
when ``--root=tmpfs`` is set explicitly), the image lives in the page cache.
The Linux kernel can swap ``tmpfs`` pages to a local swap device exactly as it
would any other anonymous memory. Adding swap therefore lets the kernel evict
cold image pages to disk and reclaim that RAM for running workloads.
@@ -176,7 +171,7 @@ initramfs root (single-stage boot default)
The default single-stage boot places the image in an ``initramfs`` root, which
is an instance of ``ramfs``. Unlike ``tmpfs``, ``ramfs`` pages are pinned in
memory: the kernel will never swap them out. Configuring swap on a node with an
``initramfs`` root will **not** free any memory used by the node image.
``initramfs`` root will **not** free any memory used by the image.
If you are using single-stage boot and want swap to help with image memory,
switch to ``tmpfs`` root first:
@@ -284,9 +279,9 @@ needs memory, first note the image size with ``df -h /``:
df -h /
This shows how much tmpfs space the image occupies — that is the amount of RAM
currently holding the node image.
currently holding the image.
Now apply memory pressure using ``stress-ng`` (install it in the node image if
Now apply memory pressure using ``stress-ng`` (install it in the OS image if
not already present). The allocation must exceed **available** RAM — not just
total RAM — to force the kernel to evict image pages. Compute the target from
``MemTotal``:
@@ -310,7 +305,7 @@ While ``stress-ng`` is running, observe memory usage:
Mem: 15Gi 15Gi 32Mi 120Mi 512Mi 192Mi
Swap: 8.0Gi 4.2Gi 3.8Gi
The ``Swap: used`` value has grown by roughly the size of the node image. The
The ``Swap: used`` value has grown by roughly the size of the image. The
kernel has evicted cold image pages to swap, making that RAM available to the
application. The application can access the full physical memory of the node,
not just what is left over after the image is loaded.
@@ -320,7 +315,7 @@ they are accessed again, so ``free -h`` will continue to show swap usage until
the node is under less pressure and pages are faulted back in as needed.
Moving image pages to swap proactively
---------------------------------------
--------------------------------------
Rather than simulating a workload, you can instruct the kernel to push image
pages to swap directly. On Linux 6.1 and later with cgroup v2, write the
@@ -352,7 +347,7 @@ systemd unit to a custom overlay that runs at ``local-fs.target``:
.. code-block:: ini
[Unit]
Description=Reclaim node image memory to swap
Description=Reclaim OS image memory to swap
After=local-fs.target
ConditionPathExists=/sys/fs/cgroup/memory.reclaim
@@ -472,7 +467,7 @@ functionality is used:
Configuring the root device
---------------------------
Set the desired storage device for the node image using the ``--root``
Set the desired storage device for the image using the ``--root``
parameter.
.. code-block:: shell

8
userdocs/overlays/overlays.rst
View File

@@ -2,7 +2,7 @@
Overlays
========
Warewulf supplements provisioned node images with an "overlay" system. Overlays
Warewulf supplements provisioned OS images with an "overlay" system. Overlays
are collections of files and :ref:`templates` that are rendered
and built per-node and then applied over the image during the provisioning
process.
@@ -239,7 +239,7 @@ provisioning actions:
wwclient
--------
All configured overlays are provisioned initially along with the node image
All configured overlays are provisioned initially along with the OS image
itself; but **wwclient** periodically fetches and applies the runtime overlay to
allow configuration of some settings without a reboot.
@@ -521,8 +521,8 @@ include wipefs to detect existing file systems.
wwctl image exec rockylinux-9 -- /usr/bin/dracut --force --no-hostonly --add wwinit --install mkswap --regenerate-all
For a complete walkthrough of configuring swap to free memory consumed by the
in-memory node image, including which root filesystem types support swap
reclamation, see :ref:`swap-and-image-memory`.
in-memory image, including which root filesystem types support swap reclamation,
see :ref:`swap-and-image-memory`.
systemd mounts
--------------

2
userdocs/release/v4.6.2.rst
View File

@@ -3,7 +3,7 @@ v4.6.2 Release Notes
====================
v4.6.2 is a regularly-scheduled minor release in the v4.6.x series. It also
includes a preview implementation of the ability to provision the node image to
includes a preview implementation of the ability to provision the OS image to
a local disk.
Significant changes are described below. Additional changes are listed in the

2
userdocs/release/v4.6.5.rst
View File

@@ -95,7 +95,7 @@ systems to mount properly. The ``wwinit`` dracut module also no longer runs the
wwinit module if root is not set to ``root=wwclient*``.
These fixes require installing the updated ``warewulf-dracut`` package in the
node image.
OS image.
Other fixes
===========

10
userdocs/server/bootloaders.rst
View File

@@ -32,7 +32,7 @@ the Warewulf configuration process to configure the ``ipxe`` service.
bios->iPXE [lhead=cluster0,label="iPXE.efi"];
kernel [shape=record label="{kernel|ramdisk (root fs)|wwinit overlay}|extracted from node image"];
kernel [shape=record label="{kernel|ramdisk (root fs)|wwinit overlay}|extracted from OS image"];
ipxe_cfg->kernel[ltail=cluster0,label="http"];
}
@@ -235,7 +235,7 @@ Warewulf as a technology preview.
grubcfg[shape=record label="{grub.cfg|static under TFTP root}"];
grub->grubcfg[label="TFTP"];
}
kernel [shape=record label="{kernel|ramdisk (root fs)|wwinit overlay}|extracted from node image"];
kernel [shape=record label="{kernel|ramdisk (root fs)|wwinit overlay}|extracted from OS image"];
grubcfg->kernel[ltail=cluster1,label="http"];
}
@@ -308,9 +308,9 @@ diagram is the following:
digraph G{
node [shape=box];
efi [shape=record label="{EFI|boots from URI defined in filename}"];
shim [shape=record label="{shim.efi|replaces shim.efi with grubx64.efi in URI|extracted from node image}"];
grub [shape=record label="{grub.efi|checks for grub.cfg|extracted from node image}"]
kernel [shape=record label="{kernel|ramdisk (root fs)|wwinit overlay}|extracted from node image"];
shim [shape=record label="{shim.efi|replaces shim.efi with grubx64.efi in URI|extracted from OS image}"];
grub [shape=record label="{grub.efi|checks for grub.cfg|extracted from OS image}"]
kernel [shape=record label="{kernel|ramdisk (root fs)|wwinit overlay}|extracted from OS image"];
efi->shim [label="http"];
shim->grub [label="http"];
grub->kernel [label="http"];

2
userdocs/server/routes.rst
View File

@@ -93,7 +93,7 @@ kernel is taken from the node's assigned image.
``/image/{wwid}``
-----------------
Serves the raw node image file for the node identified by ``{wwid}``.
Serves the raw OS image file for the node identified by ``{wwid}``.
**Query parameters:** ``assetkey``, ``uuid``, ``compress``

4
userdocs/server/security.rst
View File

@@ -11,7 +11,7 @@ Provisioning Security
Provisioning is, by default, a relatively "insecure" process: there is generally
nothing preventing a user on a cluster node from spoofing a provision request
and downloading the node image and overlays for inspection. If any of these
and downloading the OS image and overlays for inspection. If any of these
include secrets (e.g., private keys) they are at risk of exposure.
There are multiple ways to secure the Warewulf provisioning process:
@@ -50,7 +50,7 @@ SELinux
The Warewulf server can be run with SELinux enabled in "targeted" and
"enforcing" mode.
For more information about running SELinux-enabled cluster node images, see
For more information about running SELinux-enabled cluster OS images, see
:ref:`SELinux-Enabled Images <selinux_images>`.
firewalld

4
userdocs/troubleshooting/known-issues.rst
View File

@@ -63,7 +63,7 @@ v4.6.0. <https://github.com/warewulf/warewulf/issues/892>`_
Image Size Considerations
=========================
Node images can grow quickly as packages and other files are added to them. Even
OS images can grow quickly as packages and other files are added to them. Even
these larger images are often not an issue in modern environments; but some
architectural limits exist that can impede the use of images larger than a few
gigabytes. Workarounds exist for these issues in most circumstances:
@@ -94,7 +94,7 @@ gigabytes. Workarounds exist for these issues in most circumstances:
* Some BIOS / firmware retain a "memory hole" feature for legacy devices, e.g.,
reserving a 1MB block of memory at the 15MB-16MB address range. This feature
can interfere with booting stateless node images.
can interfere with booting stateless OS images.
If you are still getting "Not enough memory" or "No space left on device"
errors, try disabling any "memory hole" features or updating your system BIOS

12
userdocs/troubleshooting/troubleshooting.rst
View File

@@ -66,7 +66,7 @@ cluster node's MAC address in place of 00:00:00:00:00:00.)
- The ``kernel`` command fetches a kernel for later booting.
- The ``imgextract`` command fetches and decompresses the images that will make
up the booted node image. In a typical environment this is used to load a
up the booted OS image. In a typical environment this is used to load a
minimal "initial ramdisk" which, then, boots the rest of the system. Warewulf,
by default, loads the entire image as an initial ramdisk, and also loads the
system and runtime overlays at this time.
@@ -91,7 +91,7 @@ enabled. To do so, substitute the ``boot`` command above.
You may be more familiar with specifying ``init=`` on the kernel command
line. ``rdinit`` indicates "ramdisk init." Since Warewulf, by default, boots
the node image as an initial ramdisk, we must use ``rdinit=`` here.
the OS image as an initial ramdisk, we must use ``rdinit=`` here.
GRUB
====
@@ -149,7 +149,7 @@ enabled. To do so, substitute the ``linux`` command above.
You may be more familiar with specifying ``init=`` on the kernel command
line. ``rdinit`` indicates "ramdisk init." Since Warewulf, by default, boots
the node image as an initial ramdisk, we must use ``rdinit=`` here.
the OS image as an initial ramdisk, we must use ``rdinit=`` here.
Dracut
======
@@ -217,8 +217,8 @@ the new configuration.
.. note::
The node image itself must have Podman (or the desired container runtime)
installed. See :ref:`images` for guidance on customizing node images.
The OS image itself must have Podman (or the desired container runtime)
installed. See :ref:`images` for guidance on customizing OS images.
For information on tuning tmpfs memory usage and NUMA interleaving behavior,
see :ref:`tmpfs-and-numa` below.
@@ -231,7 +231,7 @@ tmpfs and NUMA
Warewulf can optionally mount the root filesystem as ``tmpfs`` instead of the
default ``initramfs``. Warewulf will add ``mpol=interleave`` to the mount point
which will distribute the memory across all NUMA nodes. This avoids the
hotspotting that occurs when the default initramfs stores large node images on a
hotspotting that occurs when the default initramfs stores large OS images on a
single NUMA node. To enable this, set the rootfs type to tmpfs:
.. code-block:: shell