From 803e65e9c1ca4a492604e85fdfda635e127ecf09 Mon Sep 17 00:00:00 2001 From: Jonathon Anderson Date: Mon, 20 Jan 2025 03:27:36 -0700 Subject: [PATCH] Document building images from scratch with Apptainer - Closes #1485 Signed-off-by: Jonathon Anderson --- CHANGELOG.md | 1 + userdocs/contents/images.rst | 101 ++++++++++++++--------------------- 2 files changed, 42 insertions(+), 60 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index dc7bc724..ce84f15e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -38,6 +38,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/). - New `fstab` resource configures mounts in fstab overlay, including NFS mounts. #515 - Add Dev Container support #1653 - Add man pages and command reference to userdocs. #1488 +- Document building images from scratch with Apptainer. #1485 ### Changed diff --git a/userdocs/contents/images.rst b/userdocs/contents/images.rst index 1a22d509..60d10e73 100644 --- a/userdocs/contents/images.rst +++ b/userdocs/contents/images.rst @@ -322,79 +322,60 @@ remove any package repository caches that may have been generated. Creating Images From Scratch ============================ -You can also create images from scratch and import those -images into Warewulf as previous versions of Warewulf did. +It is absolutely possible to create an `OCI base image`_ from scratch, but it is +particularly easy to do with Apptainer. -Building An Image From Your Host --------------------------------- +.. _OCI base image: https://docs.docker.com/build/building/base-images/ -RPM based distributions, as well as Debian variants can all bootstrap -mini ``chroot()`` directories which can then be used to bootstrap your -node's image. +Consider the following file called `warewulf-rockylinux-9.def`: -For example, on an RPM based Linux distribution with YUM or DNF, you -can do something like the following: +.. code-block:: singularity + + Bootstrap: yum + MirrorURL: https://download.rockylinux.org/pub/rocky/9/BaseOS/x86_64/os/ + Include: dnf + + %post + dnf -y install --allowerasing \ + NetworkManager \ + basesystem \ + bash \ + curl-minimal \ + kernel \ + nfs-utils \ + openssh-server \ + systemd + + dnf -y remove \ + glibc-gconv-extra + rm -rf /boot/* /run/* + dnf clean all + +Warewulf cannot directly import a container image from an Apptainer SIF yet, so +an Apptainer image must be built as a *sandbox*. .. code-block:: console - # yum install --installroot /tmp/newroot basesystem bash \ - chkconfig coreutils e2fsprogs ethtool filesystem findutils \ - gawk grep initscripts iproute iputils net-tools nfs-utils pam \ - psmisc rsync sed setup shadow-utils rsyslog tzdata util-linux \ - words zlib tar less gzip which util-linux openssh-clients \ - openssh-server dhclient pciutils vim-minimal shadow-utils \ - strace cronie crontabs cpio wget rocky-release ipmitool yum \ - NetworkManager + # apptainer build --sandbox warewulf-rockylinux-9 warewulf-rockylinux-9.def + [...] + INFO: Creating sandbox directory... + INFO: Build complete: warewulf-rockylinux-9 -You can do something similar with Debian-based distributions: +Once a sandbox container image has been built, it can be imported into Warewulf. .. code-block:: console - # apt-get install debootstrap - # debootstrap stable /tmp/newroot http://ftp.us.debian.org/debian + # wwctl container import ./warewulf-rockylinux-9 rockylinux-9 -Once you have created and modified your new ``chroot()``, you can -import it into Warewulf with the following command: +.. note:: -.. code-block:: console + Although warewulf does not currently support importing a SIF directly, a SIF can be converted to + a sandbox with Apptainer and then imported into Warewulf. + + .. code-block:: console - # wwctl image import /tmp/newroot imagename - -Building An Image Using 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 -`_. - -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 an image sandbox and importing -into Warewulf can be done with the following steps: - -.. code-block:: console - - # yum install epel-release - # yum install Apptainer - # Apptainer build --sandbox /tmp/newroot /path/to/Apptainer/recipe.def - # wwctl image import /tmp/newroot imagename - -Building An Image Using Podman ------------------------------- - -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 image and import it to Warewulf: - -.. code-block:: console - - # podman build -f images/Docker/openSUSE/Imagefile --tag leap-ww - # podman save localhost/leap-ww:latest -o ~/leap-ww.tar - # wwctl image import file://root/leap-ww.tar leap-ww + # apptainer build --sandbox my-sandbox my-image.sif + # wwctl container import ./my-sandbox my-image Duplicating an image ====================