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

Rename "container" to "image"

Browse Source 
- Updated `wwctl upgrade` to handle updates
- Maintained `.Container` and `.ContainerName` in tstruct
- Added `ContainerName()` methods to node and profile objects
- Added `--container`, `-C` aliases to wwctl commands (`<node|profile> <add|set>`)
- Added `wwctl container` alias
- Added support for `container_exit.sh` if `image_exit.sh` is not found

Signed-off-by: Jonathon Anderson <janderson@ciq.com>
This commit is contained in:
Jonathon Anderson
2025-01-18 17:34:48 -07:00
parent 96396ed47e
commit 45a690ca4e
142 changed files with 2212 additions and 2183 deletions
Download Patch File Download Diff File Expand all files Collapse all files

40
userdocs/contents/boot-management.rst
View File

@@ -6,7 +6,7 @@ Warewulf uses iPXE to for network boot by default. As a tech preview, support
for GRUB is also available, which adds support for secure boot.
Also as a tech preview, Warewulf may also use iPXE to boot a dracut
initramfs as an initial stage before loading the container image.
initramfs as an initial stage before loading the image.
Booting with iPXE
=================
@@ -28,7 +28,7 @@ Booting with iPXE
bios->iPXE [lhead=cluster0,label="iPXE.efi"];
kernel [shape=record label="{kernel|ramdisk (root fs)|wwinit overlay}|extracted from node container"];
kernel [shape=record label="{kernel|ramdisk (root fs)|wwinit overlay}|extracted from node image"];
ipxe_cfg->kernel[ltail=cluster0,label="http"];
}
@@ -216,7 +216,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 container"];
kernel [shape=record label="{kernel|ramdisk (root fs)|wwinit overlay}|extracted from node image"];
grubcfg->kernel[ltail=cluster1,label="http"];
}
@@ -258,22 +258,22 @@ If secure boot is enabled at every step a signature is checked and the boot
process fails if this check fails. The shim typically only includes the key for
a single operating system, which means that each distribution needs separate
`shim` and `grub` executables. Warewulf extracts these binaries from the
containers. If the node is unknown to Warewulf or can't be identified during
images. If the node is unknown to Warewulf or can't be identified during
the TFTP boot phase, the shim/grub binaries of the host in which Warewulf is
running are used.
Install shim and efi
--------------------
`shim.efi` and `grub.efi` must be installed in the container for it to be
`shim.efi` and `grub.efi` must be installed in the image for it to be
booted by GRUB.
.. code-block:: console
# wwctl container shell leap15.5
# wwctl image shell leap15.5
[leap15.5] Warewulf> zypper install grub2 shim
# wwctl container shell rocky9
# wwctl image shell rocky9
[rocky9] Warewulf> dnf install shim-x64.x86_64 grub2-efi-x64.x86_64
These packages must also be installed on the Warewulf server host to enable
@@ -290,16 +290,16 @@ 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 container}"];
grub [shape=record label="{grub.efi|checks for grub.cfg|extracted from node container}"]
kernel [shape=record label="{kernel|ramdisk (root fs)|wwinit overlay}|extracted from node container"];
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"];
efi->shim [label="http"];
shim->grub [label="http"];
grub->kernel [label="http"];
}
Warewulf delivers the initial `shim.efi` and `grub.efi` via http as taken
directly from the node's assigned container.
directly from the node's assigned image.
.. _booting with dracut:
@@ -307,19 +307,19 @@ Booting with dracut
===================
Some systems, typically due to limitations in their BIOS or EFI
firmware, are unable to load container image of a certain size
firmware, are unable to load image of a certain size
directly with a traditional bootloader, either iPXE or GRUB. As a
workaround for such systems, Warewulf can be configured to load a
dracut initramfs from the container and to use that initramfs to load
the full container image.
dracut initramfs from the image and to use that initramfs to load
the full image.
Warewulf provides a dracut module to configure the dracut initramfs to
load the container image. This module is available in the
load the image. This module is available in the
``warewulf-dracut`` subpackage, which must be installed in the
container image.
image.
With the ``warewulf-dracut`` package installed, you can build an
initramfs inside the container.
initramfs inside the image.
.. code-block:: shell
@@ -369,9 +369,9 @@ dracut semantics, set a ``GrubMenuEntry`` tag for the node.
The ``GrubMenuEntry`` variable may be set at the node or profile level.
During boot, ``warewulfd`` will detect and dynamically serve an
initramfs from a node's container image in much the same way that it
can serve a kernel from a container image. This image is loaded by
iPXE (or GRUB) which directs dracut to fetch the node's container image
initramfs from a node's image in much the same way that it
can serve a kernel from an image. This image is loaded by
iPXE (or GRUB) which directs dracut to fetch the node's image
during boot.
The wwinit module provisions to tmpfs. By default, tmpfs is permitted

14
userdocs/contents/configuration.rst
View File

@@ -40,7 +40,7 @@ Warewulf (4.5.8):
- path: /opt
export options: ro,sync,no_root_squash
systemd name: nfs-server
container mounts:
image mounts:
- source: /etc/resolv.conf
dest: /etc/resolv.conf
readonly: true
@@ -114,8 +114,8 @@ explained as follows:
* ``nfs:export paths``: Warewulf can automatically set up these NFS
exports.
* ``container mounts``: These paths are mounted into the container
during ``container exec`` or ``container shell``, typically to allow
* ``image mounts``: These paths are mounted into the image
during ``image exec`` or ``image shell``, typically to allow
them to operate in the host environment prior to deployment.
Paths
@@ -123,7 +123,7 @@ Paths
*New in Warewulf v4.5.0*
Default paths to containers, overlays, and other Warewulf components
Default paths to images, overlays, and other Warewulf components
may be overridden using ``warewulf.conf:paths``.
.. code-block:: yaml
@@ -145,9 +145,9 @@ may be overridden using ``warewulf.conf:paths``.
* ``wwoverlaydir``: The source for Warewulf overlays.
* ``wwchrootdir``: The source for Warewulf containers.
* ``wwchrootdir``: The source for Warewulf images.
* ``wwprovisiondir``: Where to store built overlays, built containers, and imported kernels.
* ``wwprovisiondir``: Where to store built overlays, built images, and imported kernels.
* ``wwclientdir``: Where the Warewulf client looks for its configuration on a provisioned node.
@@ -192,7 +192,7 @@ command.
.. note::
When ``nodes.conf`` is edited directly, ``warewulfd`` does not know that the container profile has been changed. Therefore the changes to ``nodes.conf`` are not taken into account by ``warewulfd`` until it is restarted.
When ``nodes.conf`` is edited directly, ``warewulfd`` does not know that the image profile has been changed. Therefore the changes to ``nodes.conf`` are not taken into account by ``warewulfd`` until it is restarted.
Once you restart ``warewulfd``, the ``nodes.conf`` file is then successfully reloaded.
This also goes for ``warewulf.conf`` as well - any changes made also require ``warewulfd`` to be restarted.
The restart should be done using the following command: ``systemctl restart warewulfd``

4
userdocs/contents/disks.rst
View File

@@ -17,7 +17,7 @@ Warewulf can be used, for example, to create ``swap`` partitions or ``/scratch``
Requirements
============
Partition and file system creation requires both ``ignition`` and ``sgdisk`` to be installed in the container image.
Partition and file system creation requires both ``ignition`` and ``sgdisk`` to be installed in the image.
Rocky Linux
-----------
@@ -55,7 +55,7 @@ Each partition has the switches ``should_exist`` and ``wipe_partition_entry`` wh
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``.
Depending on the image 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

27
userdocs/contents/glossary.rst
View File

@@ -2,15 +2,12 @@
Glossary
========
Container
Warewulf containers are the node images that it manages and provisions.
The use of the term "container" alludes to Warewulf's support for importing OCI containers, OCI container archives, and Apptainer sandboxes to initialize its node images.
Image
The node images that Warewulf manages and provisions.
Images may be mported from OCI image registries, OCI image archives, Apptainer sandboxes, and manual chroot directories.
Warewulf containers are maintained as an uncompressed "virtual node file system" or VNFS, (sometimes also referred to as a "chroot").
These containers are then built as images which may then be used to provision a node.
It is important to note, however, that Warewulf does not provision virtualized or nested "containers" in the common sense;
Warewulf nodes run a decompressed image on "bare metal" loaded directly into system memory.
Warewulf images are maintained as an uncompressed "virtual node file system" or VNFS, (sometimes also referred to as a "chroot").
These images are then built as images which may then be used to provision a node.
Controller
The Warewulf controller runs the Warewulf daemon (``warewulfd``) and is responsible for the management, control, and administration of the cluster.
@@ -20,11 +17,11 @@ Controller
though these services may be managed separately and on separate servers.
Kernel
In addition to a container, Warewulf also requires a kernel (typically a Linux kernel) in order to provision a node.
In addition to an image, Warewulf also requires a kernel (typically a Linux kernel) in order to provision a node.
Kernels may be imported independently into Warewulf, either from the controller or from a container;
however, recent versions of Warewulf (after v4.3.0) support automatically provisioning with a kernel detected and extracted from the container itself.
In most cases, kernels may be installed in the container using normal system packages, and no special consideration is necessary.
Kernels may be imported independently into Warewulf, either from the controller or from an image;
however, recent versions of Warewulf (after v4.3.0) support automatically provisioning with a kernel detected and extracted from the image itself.
In most cases, kernels may be installed in the image using normal system packages, and no special consideration is necessary.
Node
Warewulf nodes are the systems that are being provisioned by Warewulf.
@@ -32,10 +29,10 @@ Node
nodes.conf
One of two primary Warewulf configuration files, ``nodes.conf`` is a YAML document which records all configuration parameters for Warewulf's nodes and profiles.
It does not contain the containers or overlays, but refers to them by name.
It does not contain the images or overlays, but refers to them by name.
Overlay
Warewulf overlays provide customization for the provisioned container image.
Warewulf overlays provide customization for the provisioned image.
Overlays may be configured on nodes or profiles, as either **system** or **runtime** overlays.
**System overlays** are applied only once, when a node is first provisioned.
@@ -49,7 +46,7 @@ Profile
and this configuration may be mixed with configuration from other profiles.
wwctl
The main administrative interface for Warewulf is the ``wwctl`` command, which provides commands to manage nodes, profiles, containers, overlays, kernels, and more.
The main administrative interface for Warewulf is the ``wwctl`` command, which provides commands to manage nodes, profiles, images, overlays, kernels, and more.
wwinit
Warewulf performs some setup during the provisioning process before control is passed to the provisioned operating system.

217
userdocs/contents/containers.rst → userdocs/contents/images.rst
View File

@@ -1,6 +1,6 @@
====================
Container Management
====================
================
Image Management
================
Since the inception of Warewulf over 20 years ago, Warewulf has used
the model of the "Virtual Node File System" (VNFS) as a template image
@@ -8,12 +8,11 @@ for the compute nodes. This is similar to a golden master image,
except that the node file system exists within a directory on the
Warewulf control node (e.g. a ``chroot()``).
In hindsight, we've been using containers all along, but the buzzword
just didn't exist. Over the last 5-6 years, the enterprise has created
Meanwhile, the enterprise has created
a lot of tooling and standards around defining, building,
distributing, securing, and managing containers, so Warewulf v4 now
integrates directly within the container ecosystem to facilitate the
process of VNFS image management.
process of image management.
If you are not currently leveraging the container ecosystem in any
other way, you can still build your own chroot directories and use
@@ -21,24 +20,24 @@ Warewulf as before.
It is important to understand that Warewulf is not running a container
runtime on cluster nodes. While it is absolutely possible to run
containers on cluster nodes, Warewulf is provisioning the container
image to the bare metal and booting it. This container will be used as
containers on cluster nodes, Warewulf is provisioning the
image to the bare metal and booting it. This image will be used as
the base operating system and, by default, it will run entirely in
memory. This means that when you reboot the node, the node retains no
information about Warewulf or how it booted.
Container Tools
===============
Tools
=====
There are different container managment tools available. Docker is
probably the most recognizable one in the enterprise. Podman is
another one that is gaining traction on the RHEL platforms. In HPC,
Apptainer is the most utilized container management tool. You can use
Apptainer is the most utilized image management tool. You can use
any of these to create and manage the containers to be later imported
into Warewulf.
Importing Containers
====================
Importing Images
================
Warewulf supports importing an image from any OCI compliant
registry. This means you can import from a public registry or from a
@@ -48,32 +47,32 @@ Here is an example of importing from Docker Hub.
.. code-block:: console
# wwctl container import docker://ghcr.io/warewulf/warewulf-rockylinux:8 rocky-8
# wwctl image import docker://ghcr.io/warewulf/warewulf-rockylinux:8 rocky-8
Getting image source signatures
Copying blob d7f16ed6f451 done
Copying config da2ca70704 done
Writing manifest to image destination
Storing signatures
[LOG] info unpack layer: sha256:d7f16ed6f45129c7f4adb3773412def4ba2bf9902de42e86e77379a65d90a984
Updating the container's /etc/resolv.conf
Building container: rocky-8
Updating the image's /etc/resolv.conf
Building image: rocky-8
.. note::
Most containers in Docker Hub are not "bootable", in that, they
Most images in Docker Hub are not "bootable", in that, they
have a limited version of Systemd to make them lighter weight for
container purposes. For this reason, don't expect any base Docker
container (e.g. ``docker://rockylinux`` or ``docker://debian``) to
image purposes. For this reason, don't expect any base Docker
image (e.g. ``docker://rockylinux`` or ``docker://debian``) to
boot properly. They will not, as they will get stuck into a single
user mode. The containers in `https://hub.docker.com/u/warewulf
<https://hub.docker.com/u/warewulf>`_ are not limited and thus
user mode. The images in `https://github.com/warewulf/warewulf-node-images
<https://github.com/warewulf/warewulf-node-images>`_ are not limited and thus
they boot as you would expect.
Platform
--------
By default,
Warewulf will try to import a container of the same platform
Warewulf will try to import an image of the same platform
(e.g., amd64, arm64)
as the local system.
To specify the platform to import,
@@ -115,7 +114,7 @@ table.
Local Files
-----------
It is also possible to import a container from a local file or
It is also possible to import an image from a local file or
directory. For example, Podman can save a `.tar` archive of an OCI
image. This archive can be directly imported into Warewulf, no
registry required.
@@ -123,7 +122,7 @@ registry required.
.. code-block:: console
# podman save alpine:latest >alpine.tar
# wwctl container import alpine.tar alpine
# wwctl image import alpine.tar alpine
Chroot directories and Apptainer sandbox images can also be imported
directly.
@@ -131,7 +130,7 @@ directly.
.. code-block:: console
$ apptainer build --sandbox ./rockylinux-8/ docker://ghcr.io/warewulf/warewulf-rockylinux:8
$ sudo wwctl container import ./rockylinux-8/ rockylinux-8
$ sudo wwctl image import ./rockylinux-8/ rockylinux-8
.. note::
@@ -152,12 +151,12 @@ HTTP proxies
------------
You can set ``HTTP_PROXY``, ``HTTPS_PROXY``, and ``NO_PROXY`` (or their
lower-case versions) to use a proxy during ``wwctl container import``.
lower-case versions) to use a proxy during ``wwctl image import``.
.. code-block:: shell
export HTTPS_PROXY=squid.localdomain
wwctl container import docker://ghcr.io/warewulf/warewulf-rockylinux:8
wwctl image import docker://ghcr.io/warewulf/warewulf-rockylinux:8
See ProxyFromEnvironment_ For more information.
@@ -172,64 +171,64 @@ Syncuser
========
At import time Warewulf checks if the names of the users on the host
match the users and UIDs/GIDs in the imported container. If there is
match the users and UIDs/GIDs in the imported image. If there is
mismatch, the import command will print out a warning. By setting the
``--syncuser`` flag you advise Warewulf to try to syncronize the users
from the host to the container, which means that ``/etc/passwd`` and
``/etc/group`` of the imported container are updated and all the files
from the host to the image, which means that ``/etc/passwd`` and
``/etc/group`` of the imported image are updated and all the files
belonging to these UIDs and GIDs will also be updated.
A check if the users of the host and container matches can be
A check if the users of the host and image matches can be
triggered with the ``syncuser`` command.
.. code-block:: console
# wwctl container syncuser container-name
# wwctl image syncuser image-name
With the ``--write`` flag it will update the container to match the
With the ``--write`` flag it will update the image to match the
user database of the host as described above.
.. code-block:: console
wwctl container syncuser --write container-name
wwctl image syncuser --write image-name
Listing All Imported Containers
===============================
Listing All Imported Images
===========================
Once the container has been imported, you can list them all with the
Once the image has been imported, you can list them all with the
following command:
.. code-block:: console
# wwctl container list
CONTAINER NAME BUILT NODES
rocky-8 true 0
# wwctl image list
IMAGE NAME
----------
rocky-8
Once a container has been imported and showing up in this list you can
Once an image has been imported and showing up in this list you can
configure it to boot compute nodes.
Making Changes To Containers
============================
Making Changes To Images
========================
Warewulf has a minimal container runtime built into it. This means you
can run commands inside of any of the containers and make changes to
You can run commands inside of any of the images and make changes to
them as follows:
.. code-block:: console
# wwctl container exec rocky-8 /bin/sh
# wwctl image exec rocky-8 /bin/sh
[rocky-8] Warewulf> cat /etc/rocky-release
Rocky Linux release 8.4 (Green Obsidian)
[rocky-8] Warewulf> exit
Rebuilding container...
[INFO] Skipping (VNFS is current)
Rebuilding image...
[INFO] Skipping (image is current)
You can also ``--bind`` directories from your host into the container
You can also ``--bind`` directories from your host into the image
when using the exec command. This works as follows:
.. code-block:: console
# wwctl container shell --bind /tmp:/mnt rocky-8
# wwctl image shell --bind /tmp:/mnt rocky-8
[rocky-8] Warewulf>
.. note::
@@ -239,12 +238,12 @@ when using the exec command. This works as follows:
location, as it is almost always present and empty in every Linux
distribution (as prescribed by the LSB file hierarchy standard).
Files which should always be present in a container image like ``resolv.conf``
Files which should always be present in an image like ``resolv.conf``
can be specified in ``warewulf.conf``:
.. code-block:: yaml
container mounts:
image mounts:
- source: /etc/resolv.conf
dest: /etc/resolv.conf
readonly: true
@@ -252,26 +251,26 @@ can be specified in ``warewulf.conf``:
.. note::
Instead of ``readonly: true`` you can set ``copy: true``. This causes the
source file to be copied to the container and removed if it was not
source file to be copied to the image and removed if it was not
modified. This can be useful for files used for registrations.
When the command completes, if anything within the container changed,
the container will be rebuilt into a bootable static object
automatically. (To skip the automatic container rebuild, specify ``--build=false``.)
When the command completes, if anything within the image changed,
the image will be rebuilt into a bootable static object
automatically. (To skip the automatic image rebuild, specify ``--build=false``.)
If the files ``/etc/passwd`` or ``/etc/group`` were updated, there
will be an additional check to confirm if the users are in sync as
described in `Syncuser`_ section.
Excluding Files from a Container
--------------------------------
Excluding Files from an Image
-----------------------------
Warewulf can exclude files from a source container to prevent them
Warewulf can exclude files from an image source to prevent them
from being delivered to the compute node. This is typically used to
reduce the size of the image when some files are unnecessary.
Patterns for excluded files are read from the file
``/etc/warewulf/excludes`` in the container image itself. For example,
``/etc/warewulf/excludes`` in the image itself. For example,
the default Rocky Linux images exclude these paths:
.. code-block::
@@ -282,11 +281,11 @@ the default Rocky Linux images exclude these paths:
``/etc/warewulf/excludes`` supports the patterns implemented by
`filepath.Match <https://pkg.go.dev/path/filepath#Match>`_.
Preparing a container for build
-------------------------------
Preparing an image for build
----------------------------
Warewulf executes the script ``/etc/warewulf/container_exit.sh`` after
a ``wwctl container shell`` or ``wwctl container exec`` and prior to
Warewulf executes the script ``/etc/warewulf/image_exit.sh`` 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 files that may have been generated by the
executed command or interactive session.
@@ -294,18 +293,18 @@ executed command or interactive session.
For example, the default Rocky Linux images runs ``dnf clean all`` to
remove any package repository caches that may have been generated.
Creating Containers From Scratch
================================
Creating Images From Scratch
============================
You can also create containers from scratch and import those
containers into Warewulf as previous versions of Warewulf did.
You can also create images from scratch and import those
images into Warewulf as previous versions of Warewulf did.
Building A Container From Your Host
-----------------------------------
Building An Image From Your Host
--------------------------------
RPM based distributions, as well as Debian variants can all bootstrap
mini ``chroot()`` directories which can then be used to bootstrap your
node's container.
node's image.
For example, on an RPM based Linux distribution with YUM or DNF, you
can do something like the following:
@@ -333,21 +332,21 @@ import it into Warewulf with the following command:
.. code-block:: console
# wwctl container import /tmp/newroot containername
# wwctl image import /tmp/newroot imagename
Building A Container Using Apptainer
------------------------------------
Building An Image Using Apptainer
---------------------------------
Apptainer, a container platform for HPC and performance intensive
applications, can also be used to create node containers for
Warewulf. There are several Apptainer container recipes in the
``containers/Apptainer/`` directory and can be found on GitHub at
`https://github.com/warewulf/warewulf/tree/main/containers/Apptainer
<https://github.com/warewulf/warewulf/tree/main/containers/Apptainer>`_.
Apptainer, an image platform for HPC and performance intensive
applications, can also be used to create node images for
Warewulf. There are several Apptainer image recipes in the
``images/Apptainer/`` directory and can be found on GitHub at
`https://github.com/warewulf/warewulf/tree/main/images/Apptainer
<https://github.com/warewulf/warewulf/tree/main/images/Apptainer>`_.
You can use these as starting points and adding any additional steps
you want in the ``%post`` section of the recipe file. Once you've done
that, installing Apptainer, building a container sandbox and importing
that, installing Apptainer, building an image sandbox and importing
into Warewulf can be done with the following steps:
.. code-block:: console
@@ -355,26 +354,26 @@ into Warewulf can be done with the following steps:
# yum install epel-release
# yum install Apptainer
# Apptainer build --sandbox /tmp/newroot /path/to/Apptainer/recipe.def
# wwctl container import /tmp/newroot containername
# wwctl image import /tmp/newroot imagename
Building A Container Using Podman
---------------------------------
Building An Image Using Podman
------------------------------
You can also build a container using podman via a ``Dockerfile``. For
this step the container must be exported to a tar archive, which then
You can also build an image using podman via a ``Dockerfile``. For
this step the image must be exported to a tar archive, which then
can be imported to Warewulf. The following steps will create an
openSUSE Leap container and import it to Warewulf:
openSUSE Leap image and import it to Warewulf:
.. code-block:: console
# podman build -f containers/Docker/openSUSE/Containerfile --tag leap-ww
# podman build -f images/Docker/openSUSE/Imagefile --tag leap-ww
# podman save localhost/leap-ww:latest -o ~/leap-ww.tar
# wwctl container import file://root/leap-ww.tar leap-ww
# wwctl image import file://root/leap-ww.tar leap-ww
Container Size Considerations
=============================
Image Size Considerations
=========================
Base compute node container images start quite small (a few hundred
Base compute node images start quite small (a few hundred
megabytes), but can grow quickly as packages and other files are added
to them. Even these larger images are typically not an issue in modern
environments; but some architectural limits exist that can impede the
@@ -409,38 +408,38 @@ issues in most circumstances:
device" errors, try disabling any "memory hole" features or updating
your system BIOS or firmware.
Duplicating a container
=======================
Duplicating an image
====================
It is possible to duplicate an installed image by using:
.. code-block:: console
# wwctl container copy CONTAINER_NAME DUPLICATED_CONTAINER_NAME
# wwctl image copy IMAGE_NAME DUPLICATED_IMAGE_NAME
This kind of duplication can be useful if you are looking for canary tests.
.. note::
If a source container includes persistent sockets, these sockets may cause the copy operation to fail.
If an image source includes persistent sockets, these sockets may cause the copy operation to fail.
.. code-block:: console
Copying sources...
ERROR : could not duplicate image: lchown /var/lib/warewulf/chroots/rocky-8/rootfs/run/user/0/gnupg/d.kg8ijih5tq41ixoeag4p1qup/S.gpg-agent: no such file or directory
To resolve this, remove the sockets from the source container.
To resolve this, remove the sockets from the image source.
.. code-block:: bash
find $(wwctl container show rocky-8) -type s -delete
find $(wwctl image show rocky-8) -type s -delete
Multi-arch container management
===============================
Multi-arch image management
===========================
It is possible to build, edit, and provision containers of different
It is possible to build, edit, and provision images of different
architectures (i.e. aarch64) from an x86_64 host by using QEMU. Simply
run the appropriate command below based on your container management tools.
run the appropriate command below based on your image management tools.
.. code-block:: console
@@ -448,10 +447,10 @@ run the appropriate command below based on your container management tools.
# sudo podman run --rm --privileged multiarch/qemu-user-static --reset -p yes
# sudo singularity run docker://multiarch/qemu-user-static --reset -p yes
Then, ``wwctl container exec`` will work regardless of the architecture of the container.
Then, ``wwctl image exec`` will work regardless of the architecture of the image.
For more information about QEMU, see their `GitHub <https://github.com/multiarch/qemu-user-static>`_
To use wwclient on a booted container using a different architecture,
To use wwclient on a booted image using a different architecture,
wwclient must be compiled for the specific architecture. This requires GOLang build
tools 1.21 or newer. Below is an example for building wwclient for arm64:
@@ -465,13 +464,13 @@ tools 1.21 or newer. Below is an example for building wwclient for arm64:
Then, apply the new "wwclient_arm64" system overlay to your arm64 node/profile
Read-only containers
====================
Read-only images
================
A container may be marked "read-only" by creating a ``readonly`` file in its
An image may be marked "read-only" by creating a ``readonly`` file in its
source directory, typically next to ``rootfs``.
.. note::
Read-only containers are a preview feature primarily meant to enable future
support for container subscriptions and updates.
Read-only images are a preview feature primarily meant to enable future
support for image subscriptions and updates.

7
userdocs/contents/introduction.rst
View File

@@ -28,8 +28,7 @@ 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,
identical virtual node file system image. As of Warewulf v4, the
virtual node image is a standard container image which means all
compute resources within a cluster can be managed using any existing
virtual node image can be managed using any existing
container tooling and/or CI pipelines that are being used. This can be
as simple as DockerHub or your own private GitLab CI infrastructure.
@@ -67,8 +66,8 @@ Features
CentOS, and RHEL, Warewulf can do it all.
* **Secure**: Warewulf is the only stateless provisioning system that
will support SELinux out of the box. Just enable your node operating
system container to support SELinux, and Warewulf do the rest!
will support SELinux out of the box. Just enable your node image to
support SELinux, and let Warewulf do the rest!
* **Open Source**: For the last 20 years, Warewulf has remained open
source and continues to be the golden standard for cluster

4
userdocs/contents/ipmi.rst
View File

@@ -69,7 +69,7 @@ Profile View
default Id -- default
default comment -- This profile is automatically included for each node
default cluster -- --
default container -- sle-micro-5.3
default image -- sle-micro-5.3
default ipxe -- --
default runtime -- --
default wwinit -- --
@@ -101,7 +101,7 @@ Node View
n001 Id -- n001
n001 comment default This profile is automatically included for each node
n001 cluster -- --
n001 container default sle-micro-5.3
n001 image default sle-micro-5.3
n001 ipxe -- (default)
n001 runtime -- (hosts,ssh.authorized_keys,syncuser)
n001 wwinit -- (wwinit,wwclient,fstab,hostname,ssh.host_keys,issue,resolv,udev.netname,systemd.netname,ifcfg,NetworkManager,debian.interfaces,wicked,ignition)

16
userdocs/contents/kernel.rst
View File

@@ -3,18 +3,18 @@ Kernel Management
=================
Warewulf nodes require a Linux kernel to boot. As of Warewulf v4.6, the kernel
you wish to use must be present in the relevant container. Warewulf locates and
you wish to use must be present in the relevant image. Warewulf locates and
provisions the kernel automatically for any node configured to use that
container image.
image.
You can see what kernels are available in imported containers by using the
``wwctl container kernels`` command:
You can see what kernels are available in imported images by using the
``wwctl image kernels`` command:
.. code-block:: console
# wwctl container kernels
Container Kernel Version Default Nodes
--------- ------ ------- ------- -----
# wwctl image kernels
Image Kernel Version Default Nodes
----- ------ ------- ------- -----
newroot-test /boot/vmlinuz-5.14.0-427.37.1.el9_4.aarch64 5.14.0-427.37.1 true 0
newroot-test /lib/modules/5.14.0-427.37.1.el9_4.aarch64/vmlinuz 5.14.0-427.37.1 false 0
rocky-8 /boot/vmlinuz-4.18.0-372.13.1.el8_6.x86_64 4.18.0-372.13.1 true 2
@@ -25,7 +25,7 @@ You can see what kernels are available in imported containers by using the
Kernel Version
==============
If a container includes multiple kernels, the desired kernel may be selected by
If an image includes multiple kernels, the desired kernel may be selected by
specifying the desired version or an explicit path.
.. code-block:: console

16
userdocs/contents/known-issues.rst
View File

@@ -17,21 +17,21 @@ To ensure that dracut runs the full ``wwinit`` process, pass ``init=/init`` or
# wwctl profile set default --kernelargs="init=/init"
Containers are read-only
========================
Images are read-only
====================
Warewulf v4.5 uses the permissions on a container's ``rootfs/`` to determine a "read-only" state of
the container: if the root directory of the container image is ``u-w``, it will be mounted read-only
during ``wwctl container <exec|shell``, preventing interactive changes to the container image.
Warewulf v4.5 uses the permissions on an image's ``rootfs/`` to determine a "read-only" state of
the image: if the root directory of the image is ``u-w``, it will be mounted read-only
during ``wwctl image <exec|shell``, preventing interactive changes to the image.
In the past, the root directory was ``u+w``, but Enterprise Linux 9.5 (including Red Hat, Rocky, _et
al._) includes an update to the ``filesystem`` package that marks the root directory ``u-w``. This
causes Warewulf container images to be "read only" by default.
causes Warewulf images to be "read only" by default.
To mark a Warewulf container as writeable, use `chmod u+w`.
To mark a Warewulf image as writeable, use `chmod u+w`.
.. code-block:: bash
# chmod u+w $(wwctl container show rockylinux-9.5)
# chmod u+w $(wwctl image show rockylinux-9.5)
This behavior is changed in v4.6 to use an explicit ``readonly`` file stored outside of ``rootfs/``.

22
userdocs/contents/nodeconfig.rst
View File

@@ -85,7 +85,7 @@ You can also see the node's full attribute list by specifying the
n001 Id -- n001
n001 comment default This profile is automatically included for each node
n001 cluster -- --
n001 container default sle-micro-5.3
n001 image default sle-micro-5.3
n001 ipxe -- (default)
n001 runtime -- (hosts,ssh.authorized_keys,syncuser)
n001 wwinit -- (wwinit,wwclient,fstab,hostname,ssh.host_keys,issue,resolv,udev.netname,systemd.netname,ifcfg,NetworkManager,debian.interfaces,wicked,ignition)
@@ -124,9 +124,9 @@ You can also see the node's full attribute list by specifying the
Setting Node Attributes
=======================
In the above output we can see that there is no kernel or container
In the above output we can see that there is no kernel or image
defined for this node. To provision a node, the minimum requirements
are a kernel and container, and for that node to be useful, we will
are a kernel and image, and for that node to be useful, we will
also need to configure the network so the nodes are reachable after
they boot.
@@ -134,20 +134,20 @@ Node configurations are set using the ``wwctl node set`` command. To
see a list of all configuration attributes, use the command ``wwctl
node set --help``.
Configuring the Node's Container Image
======================================
Configuring the Node's Image
============================
.. code-block:: console
# wwctl node set --container rocky-8 n001
# wwctl node set --image rocky-8 n001
Are you sure you want to modify 1 nodes(s): y
And you can check that the container name is set for ``n001``:
And you can check that the image name is set for ``n001``:
.. code-block:: console
# wwctl node list -a n001 | grep Container
n0000 Container -- rocky-8
# wwctl node list -a n001 | grep Image
n0000 Image -- rocky-8
Configuring the Node's Network
------------------------------
@@ -161,7 +161,7 @@ provide the network information as follows:
Are you sure you want to modify 1 nodes(s): y
You can now see that the node contains configuration attributes for
container, kernel, and network:
image, kernel, and network:
.. code-block:: console
@@ -170,7 +170,7 @@ container, kernel, and network:
n001 Id -- n001
n001 comment default This profile is automatically included for each node
n001 cluster -- --
n001 container default sle-micro-5.3
n001 image default sle-micro-5.3
n001 ipxe -- (default)
n001 runtime -- (hosts,ssh.authorized_keys,syncuser)
n001 wwinit -- (wwinit,wwclient,fstab,hostname,ssh.host_keys,issue,resolv,udev.netname,systemd.netname,ifcfg,NetworkManager,debian.interfaces,wicked,ignition)

6
userdocs/contents/overlays.rst
View File

@@ -11,7 +11,7 @@ configuration management on a provisioned Warewulf cluster node. But these are h
solutions to a simple problem.
Warewulf addresses cluster node configuration with its **overlay** system. Overlays are collections
of files and templates that are rendered and built per-node and then applied over the container
of files and templates that are rendered and built per-node and then applied over the image
image during the provisioning process.
System and runtime overlays
@@ -131,8 +131,8 @@ syncuser
--------
The **syncuser** overlay updates ``/etc/passwd`` and ``/etc/group`` to include
all users on both the Warewulf server and from the container image. To function
properly, ``wwctl container syncuser`` must have also been run on the container
all users on both the Warewulf server and from the image. To function
properly, ``wwctl image syncuser`` must have also been run on the image
image to synchronize its user and group IDs with those of the server.
ignition

8
userdocs/contents/profiles.rst
View File

@@ -7,8 +7,8 @@ together. Instead of redundant configurations for each node, you can
put that into a profile and the nodes will inherit these
configurations. This is very handy if you have groups of node specific
customizations. For example, a few hundred nodes that are running a
particular container or kernel, and another group of nodes that are
running a different kernel or container.
particular image or kernel, and another group of nodes that are
running a different kernel or image.
Profiles may, themselves, reference other profiles, supporting complex
mixtures of profile configuration and negation.
@@ -42,7 +42,7 @@ And with the ``-a`` flag:
default Id -- default
default Comment -- This profile is automatically included for each node
default Cluster -- --
default Container -- --
default Image -- --
default Kernel -- --
default KernelArgs -- --
default Init -- --
@@ -197,7 +197,7 @@ But if you do wish to use profiles, the best way to use them is to
manage "fixed" configurations of groups of cluster nodes. For example,
if you have multiple sub-clusters in your cluster, it might be
advantageous to have a ``cluster_name`` profile which includes things
like network configurations, and/or a specific kernel, container, boot
like network configurations, and/or a specific kernel, image, boot
arguments, etc.
Node specific information, like HW/MAC addresses and IP addresses

8
userdocs/contents/provisioning.rst
View File

@@ -56,7 +56,7 @@ occur:
#. The Warewulf server will generate the iPXE configuration which
will include directions of what else is necessary to download
and how to boot.
#. The kernel, container image, kernel modules, and overlays
#. The kernel, image, kernel modules, and overlays
are all downloaded over REST HTTP from the Warewulf Server
#. iPXE executes the kernel and processes the overlays to provide
a unified root file system
@@ -65,9 +65,9 @@ occur:
#. File System (re)configuration
#. SELinux
#. ``wwclient`` is called as a background daemon and sleeps until network is ready
#. The Warewulf bootstrap execs the container's ``/sbin/init``
#. Container:
#. The container now boots exactly as any operating system would
#. The Warewulf bootstrap execs the image's ``/sbin/init``
#. Image:
#. The image now boots exactly as any operating system would
expect

4
userdocs/contents/security.rst
View File

@@ -29,7 +29,7 @@ The Warewulf server itself was developed with SELinux enabled in
"targeted" and "enforcing" mode and with the firewall active.
The provisioning process also fully supports booting SELinux-enabled
containers, though nodes must be configured to use tmpfs for init. ("ramfs"
images, though nodes must be configured to use tmpfs for init. ("ramfs"
(often used by default) does not support extended file attributes.)
.. code-block:: bash
@@ -44,7 +44,7 @@ containers, though nodes must be configured to use tmpfs for init. ("ramfs"
Once that is done, you just need to enable SELinux in
``/etc/sysconfig/selinux`` and install the appropriate profiles into the
container. `An example`_ of such a container is available in the
image. `An example`_ of such an image is available in the
warewulf-node-images repository.
.. _An example: https://github.com/warewulf/warewulf-node-images/tree/main/examples/rockylinux-9-selinux

2
userdocs/contents/setup.rst
View File

@@ -116,7 +116,7 @@ You can check the result with ``wwctl node list``.
NODE FIELD PROFILE VALUE
deliverynet Id -- deliverynet
deliverynet Comment default This profile is automatically included for each node
deliverynet ContainerName default leap15.5
deliverynet ImageName default leap15.5
deliverynet Ipxe -- (default)
deliverynet RuntimeOverlay -- (hosts,ssh.authorized_keys,syncuser)
deliverynet SystemOverlay -- (wwinit,wwclient,fstab,hostname,ssh.host_keys,issue,resolv,udev.netname,systemd.netname,ifcfg,NetworkManager,debian.interfaces,wicked,ignition)

4
userdocs/contents/templating.rst
View File

@@ -150,11 +150,11 @@ A file from the host can be include with following template
IncludeFrom
^^^^^^^^^^^
With following snippet a file from a given container can be included
With following snippet a file from a given image can be included
.. code-block::
{{ IncludeFrom container file }}
{{ IncludeFrom image file }}
IncludeBlock
^^^^^^^^^^^^

12
userdocs/contents/troubleshooting.rst
View File

@@ -21,13 +21,13 @@ and substitute your cluster node's MAC addres in place of 00:00:00:00:00:00.)
set uri http://10.0.0.1:9873/provision/00:00:00:00:00:00
kernel --name kernel ${uri}?stage=kernel
imgextract --name container ${uri}?stage=container&compress=gz
imgextract --name image ${uri}?stage=image&compress=gz
imgextract --name system ${uri}?stage=system&compress=gz
imgextract --name runtime ${uri}?stage=runtime&compress=gz
boot kernel initrd=container initrd=system initrd=runtime
boot kernel initrd=image initrd=system initrd=runtime
- The ``uri`` variable points to ``warewulfd`` for future reference.
This includes the cluster node's MAC address so that Warewulf knows what container and overlays to provide.
This includes the cluster node's MAC address so that Warewulf knows what image and overlays to provide.
- The ``kernel`` command fetches a kernel for later booting.
@@ -48,7 +48,7 @@ To do so, substitute the ``boot`` command above.
.. code-block::
boot kernel initrd=container initrd=system initrd=runtime rdinit=/bin/sh
boot kernel initrd=image initrd=system initrd=runtime rdinit=/bin/sh
.. note::
@@ -73,12 +73,12 @@ and update the port number if you have changed it from the default of 9873.)
uri="(http,10.0.0.1:9873)/provision/${net_default_mac}"
linux "${uri}?stage=kernel" wwid=${net_default_mac}
initrd "${uri}?stage=container&compress=gz" "${uri}?stage=system&compress=gz" "${uri}?stage=runtime&compress=gz"
initrd "${uri}?stage=image&compress=gz" "${uri}?stage=system&compress=gz" "${uri}?stage=runtime&compress=gz"
boot
- The ``uri`` variable points to ``warewulfd`` for future reference.
``${net_default_mac}`` provides Warewulf with the MAC address of the booting node,
so that Warewulf knows what container and overlays to provide it.
so that Warewulf knows what image and overlays to provide it.
- The ``linux`` command tells GRUB what kernel to boot, as provided by ``warewulfd``.
The ``wwid`` kernel argument helps ``wwclient`` identify the node during runtime.

2
userdocs/contents/wwctl.rst
View File

@@ -7,7 +7,7 @@ Warewulf's command-line interface is based primarily around the
component of Warewulf's functionality.
* ``configure`` configures system services that Warewulf depends on
* ``container`` configures containers (node images)
* ``image`` configures images (node images)
* ``kernel`` configures override kernels
* ``node`` manages nodes in the cluster
* ``profiles`` defines configuration which can be applied to multiple

2
userdocs/contributing/debugging.rst
View File

@@ -239,7 +239,7 @@ Example debugging session
altvalue: []string len: 0, cap: 0, nil,
from: "",
def: []string len: 0, cap: 0, nil,},
ContainerName: github.com/warewulf/warewulf/internal/pkg/node.Entry {
ImageName: github.com/warewulf/warewulf/internal/pkg/node.Entry {
value: []string len: 0, cap: 0, nil,
altvalue: []string len: 0, cap: 0, nil,
from: "",

4
userdocs/contributing/development-environment-kvm.rst
View File

@@ -101,8 +101,8 @@ Build and install Warewulf on wwdev
sudo wwctl configure nfs # Configure NFS exports
sudo wwctl configure ssh # Build the basic ssh keys to be included by the ssh overlays
# Pull and build the VNFS container and kernel
sudo wwctl container import docker://ghcr.io/warewulf/warewulf-centos:7 centos-7 --setdefault
# Pull and build the image and kernel
sudo wwctl image import docker://ghcr.io/warewulf/warewulf-centos:7 centos-7 --setdefault
sudo wwctl kernel import build $(uname -r) --setdefault
# Set up the default node profile

4
userdocs/contributing/development-environment-vagrant.rst
View File

@@ -223,8 +223,8 @@ Vagrantfile
wwctl configure --all
wwctl container import docker://ghcr.io/warewulf/warewulf-rockylinux:9 rocky-9
wwctl profile set --yes --container rocky-9 "default"
wwctl image import docker://ghcr.io/warewulf/warewulf-rockylinux:9 rocky-9
wwctl profile set --yes --image rocky-9 "default"
wwctl profile set --yes --netdev eth1 --netmask 255.255.255.0 --gateway 192.168.200.254 "default"
wwctl node add n0001.cluster -I 192.168.200.101 --discoverable true

4
userdocs/contributing/development-environment-vbox.rst
View File

@@ -116,8 +116,8 @@ I have VirtualBox running on my desktop.
sudo wwctl configure nfs --persist # Configure the NFS exports
sudo wwctl configure ssh --persist # Build the basic ssh keys to be included by the SSH overlay
# Pull and build the VNFS container and kernel
sudo wwctl container import docker://ghcr.io/warewulf/warewulf-centos:7 centos-7 --setdefault
# Pull and build the image and kernel
sudo wwctl image import docker://ghcr.io/warewulf/warewulf-centos:7 centos-7 --setdefault
sudo wwctl kernel import build $(uname -r) --setdefault
# Set up the default node profile

2
userdocs/index.rst
View File

@@ -16,7 +16,7 @@ Welcome to the Warewulf User Guide!
Warewulf Configuration <contents/configuration>
Controlling Warewulf (wwctl) <contents/wwctl>
Warewulf Initialization <contents/initialization>
Container Management <contents/containers>
Image Management <contents/images>
Kernel Management <contents/kernel>
Boot Management <contents/boot-management>
Node Configuration <contents/nodeconfig>

12
userdocs/quickstart/debian12.rst
View File

@@ -126,16 +126,16 @@ instructions.
to run ``$ sudo restorecon -Rv /var/lib/tftpboot/`` if there are
errors with TFTP still.
Pull and build the VNFS container (including the kernel)
========================================================
Pull and build the image (including the kernel)
===============================================
This will pull a basic VNFS container from Docker Hub and import the
This will pull a basic image from Docker Hub and import the
default running kernel from the controller node and set both in the
"default" node profile.
.. code-block:: bash
wwctl container import docker://ghcr.io/warewulf/warewulf-debian:12.0 debian-12.0
wwctl image import docker://ghcr.io/warewulf/warewulf-debian:12.0 debian-12.0
Set up the default node profile
@@ -145,12 +145,12 @@ Node configurations can be set via node profiles. Each node by default
is configured to be part of the ``default`` node profile, so any
changes you make to that profile will affect all nodes.
The following command will set the container we just imported above to
The following command will set the image we just imported above to
the ``default`` node profile:
.. code-block:: bash
sudo wwctl profile set --yes --container debian-12.0 "default"
sudo wwctl profile set --yes --image debian-12.0 "default"
Next we set some default networking configurations for the first

12
userdocs/quickstart/el.rst
View File

@@ -93,7 +93,7 @@ address of your cluster's private network interface.
- path: /opt
export options: ro,sync,no_root_squash
systemd name: nfs-server
container mounts:
image mounts:
- source: /etc/resolv.conf
dest: /etc/resolv.conf
readonly: true
@@ -143,17 +143,17 @@ configure --all``.
you may need to run ``restorecon -Rv /var/lib/tftpboot/`` to label
files written to q`tftpboot``.
Add a base node image container
===============================
Add a base node image
=====================
This will pull a basic node image container from Docker Hub and import the
This will pull a basic node image from Docker Hub and import the
default running kernel from the controller node and set both in the
"default" node profile.
.. code-block:: bash
wwctl container import docker://ghcr.io/warewulf/warewulf-rockylinux:9 rockylinux-9 --build
wwctl profile set default --container rockylinux-9
wwctl image import docker://ghcr.io/warewulf/warewulf-rockylinux:9 rockylinux-9 --build
wwctl profile set default --image rockylinux-9
Configure the default node profile
==================================

10
userdocs/quickstart/suse15.rst
View File

@@ -72,7 +72,7 @@ address of your cluster's private network interface:
- path: /opt
export options: ro,sync,no_root_squash
systemd name: nfs-server
container mounts:
image mounts:
- source: /etc/resolv.conf
dest: /etc/resolv.conf
readonly: true
@@ -109,16 +109,16 @@ instructions.
sudo wwctl configure --all
Pull and build the VNFS container and kernel
============================================
Pull and build the image and kernel
===================================
This will pull a basic VNFS container from Docker Hub and import the
This will pull a basic image from Docker Hub and import the
default running kernel from the controller node and set both in the
"default" node profile.
.. code-block:: bash
$ sudo wwctl container import docker://registry.opensuse.org/science/warewulf/leap-15.4/containers/kernel:latest leap15.4 --setdefault
$ sudo wwctl image import docker://registry.opensuse.org/science/warewulf/leap-15.4/images/kernel:latest leap15.4 --setdefault
Set up the default node profile
===============================