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

Split overlays into discrete functionality and test

Browse Source 
- Closes #987

To make the overlays testable in isolation, and after discussion with
the TSC, removed host/time/source from overlay files.

Signed-off-by: Jonathon Anderson <janderson@ciq.com>
This commit is contained in:
Jonathon Anderson
2024-07-15 16:27:49 -06:00
parent b150b6319e
commit 053dd9953a
109 changed files with 3581 additions and 232 deletions
Download Patch File Download Diff File Expand all files Collapse all files

26
userdocs/contents/configuration.rst
View File

@@ -98,7 +98,7 @@ explained as follows:
When ``true``, ``wwclient`` uses TCP port 987.
Changing this option requires rebuilding node overlays and rebooting
compute nodes, to configure them to use a privileged port.
compute nodes to configure them to use a privileged port.
* ``warewulf:update interval``: This defines the frequency (in
seconds) with which the Warewulf client on the compute node fetches
@@ -205,29 +205,7 @@ a "runtime overlay" specified, the respective value from
``defaultnode`` is used. If a network device does not specify a
"device," the device value of the ``dummy`` device is used.
If ``defaults.conf`` does not exist, the following values are used as
compiled into Warewulf at build-time:
.. code-block:: yaml
--
defaultnode:
runtime overlay:
- generic
system overlay:
- wwinit
kernel:
args: quiet crashkernel=no vga=791 net.naming-scheme=v238
init: /sbin/init
root: initramfs
ipxe template: default
profiles:
- default
network devices:
dummy:
device: eth0
type: ethernet
netmask: 255.255.255.0
If ``defaults.conf`` does not exist, compiled-in defaults are used.
There should never be a need to change this file: all site-local
parameters should be specified using either nodes or profiles.

2
userdocs/contents/disks.rst
View File

@@ -57,7 +57,7 @@ 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``.
All necessary services are distributed by the ``ignition`` 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.

8
userdocs/contents/initialization.rst
View File

@@ -22,10 +22,10 @@ properly. Here are the things it will do:
the system service.
* **hostfile**: Update the system's /etc/hosts file based on the
**host** template ``/etc/hosts.ww``.
* **nfs**: Configure the NFS server on the control node as well as the
``/etc/fstab`` in the system overlay based on the configuration in
``/etc/warewulf/warewulf.conf`` and enable the system service. Also
the file ``/etc/exports.ww`` from the **host** template is installed.
* **nfs**: Configure the NFS server on the control node based on the
configuration in ``/etc/warewulf/warewulf.conf`` and enable the NFS
service. Also the file ``/etc/exports.ww`` from the **host** template is
installed.
* **ssh**: Create the appropriate host keys (stored in
``/etc/warewulf/keys/``) and user keys for passwordless ``ssh`` into
the nodes. Addionally the shell profiles

6
userdocs/contents/ipmi.rst
View File

@@ -15,7 +15,7 @@ individual node would be the IP address.
The settings are only written to the IPMI interface if ``--ipmiwrite``
is set to `true`. The write process happens at every boot of the node
through the script ``/warewulf/init.d/50-ipmi`` in the **system**
through the script ``/warewulf/init.d/50-ipmi`` in the wwinit
overlay.
If an individual node has different settings, you can set the IPMI
@@ -99,8 +99,8 @@ Node View
n001 cluster -- --
n001 container default sle-micro-5.3
n001 ipxe -- (default)
n001 runtime -- (generic)
n001 wwinit -- (wwinit)
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)
n001 root -- (initramfs)
n001 discoverable -- --
n001 init -- (/sbin/init)

8
userdocs/contents/nodeconfig.rst
View File

@@ -87,8 +87,8 @@ You can also see the node's full attribute list by specifying the
n001 cluster -- --
n001 container default sle-micro-5.3
n001 ipxe -- (default)
n001 runtime -- (generic)
n001 wwinit -- (wwinit)
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)
n001 root -- (initramfs)
n001 discoverable -- --
n001 init -- (/sbin/init)
@@ -193,8 +193,8 @@ container, kernel, and network:
n001 cluster -- --
n001 container default sle-micro-5.3
n001 ipxe -- (default)
n001 runtime -- (generic)
n001 wwinit -- (wwinit)
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)
n001 root -- (initramfs)
n001 discoverable -- --
n001 init -- (/sbin/init)

149
userdocs/contents/overlays.rst
View File

@@ -2,7 +2,7 @@
Warewulf Overlays
=================
So at this point, we have discussed how Warewulf is designed to
At this point we have discussed how Warewulf is designed to
scalably provision and manage thousands of cluster nodes by utilizing
identical stateless boot images. And there-in lies a problem to
solve. If these boot images are completely identical, then how do we
@@ -19,57 +19,114 @@ through the provisioning process. A node or profile can configure an
overlay in two different ways:
* An overlay can be configured to run during boot as part of the
``wwinit`` process. These overlays are called **system overlay** or
**wwinit overlays**.
``wwinit`` process. These overlays are called **system overlays**.
* An overlay can be configured to run periodically while the system is
running. These overlays are called **runtime overlays** or **generic
overlays**.
running. These overlays are called **runtime overlays**.
The default profile has both a **wwinit** and a **runtime** overlay
configured.
Overlays are compiled for each compute node individually.
Defined Overlays
================
Provided overlays
=================
System or wwinit overlay
------------------------
These overlays are provided as part of Warewulf.
This overlay contains all the necessary scripts to provision a
Warewulf node. It is available before the ``systemd`` or other init is
called and contains all configurations which are needed to bring up
the compute node. It is not updated during run time. Besides the
network configurations for
wwinit
------
* wicked
* NetworkManager
* EL legacy network scripts
The **wwinit** overlay performs initial configuration of the Warewulf node.
Its `wwinit` script runs before ``systemd`` or other init is called and
contains all configurations which are needed to boot.
it also contains udev rules, which will set the interface names
based on the hardware addresses configured for the node.
Before the ``systemd`` init is called, the overlay loops through the scripts in
``/wwinit/warwulf/init.d/*`` which will setup
In particular:
* Ipmi
* wwclient
* selinux
- Configure the loopback interface
- Configure the BMC based on the node's configuration
- Update PAM configuration to allow missing shadow entries
- Relabel the file system for SELinux
Runtime Overlay or generic Overlay
----------------------------------
Other overlays may place additional scripts in ``/warewulf/init.d/`` to affect
node configuration in this pre-boot environment.
The runtime overlay is updated by the ``wwclient`` service on a
regular basis (by default, once per minute). In the standard
configuration it includes updates for ``/etc/passwd``, ``/etc/group``
and ``/etc/hosts``. Additionally the ``authorized_keys`` file of the
root user is updated. It is recommended to use this overlay for
dynamic configuration files like ``slurm.conf``. Once the system is
provisioned and booted, the ``wwclient`` program (which is provisioned
as part of the ``wwinit`` system overlay) will continuously update the
node with updates in the runtime overlay.
wwclient
--------
Host Overlay
------------
All configured overlays are provisioned initially along with the node image
itself; but **wwclient** periodically fetches and applies the runtime overlay
to allow configuration of some settings without a reboot.
Network interfaces
------------------
Warewulf ships with support for many different network interface configuration
systems. All of these are applied by default; but the list may be trimmed to
the desired system.
- ifcfg
- NetworkManager
- debian.interfaces
- wicked
Warewulf also configures both systemd and udev with the intended names of
configured network interfaces, typically based on a known MAC address.
- systemd.netname
- udev.netname
Basics
------
The **hostname** overlay sets the hostname based on the configured Warewulf
node name.
The **hosts** overlay configures ``/etc/hosts`` to include all Warewulf nodes.
The **issue** overlay configures a standard Warewulf status message for display
during login.
The **resolv** overlay configures ``/etc/resolv.conf`` based on the value of
"DNS" nettags. (In most situations this should be unnecessary, as the network
interface configuration should handle this dynamically.)
fstab
-----
The **fstab** overlay configures ``/etc/fstab`` to mount NFS shares defined in
``/etc/warewulf.conf`` and file systems created by Ignition.
ssh
---
Two SSH overlays configure host keys (one set for all node in the cluster) and
``authorized_keys`` for the root account.
- ssh.authorized_keys
- ssh.host_keys
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
image to synchronize its user and group IDs with those of the server.
ignition
--------
The **ignition** overlay defines partitions and file systems on local disks.
debug
-----
The **debug** overlay is not intended to be used in configuration, but can be
used as an example and applied with ``wwctl overlay show --render <nodename>
debug /warewulf/template-variables.md.ww``.
host
----
Configuration files used for the configuration of the Warewulf host /
server are stored in the **host** overlay. Unlike other overlays, it
@@ -91,25 +148,25 @@ The following services get configuration files via the host overlay:
Combining Overlays
==================
When changing the overlays, it is recommended not to change them, but
to add the changed files to a new overlay and combine them in the
We recommended not changing the provided overlays. Rather,
add the changed files to a new overlay and combine them in the
configuration. This is possible as the configuration fields for the
**wwinit** and **runtime** overlays are lists and can contain several
system and runtime overlays are lists and can contain several
overlays. As an example for this, we will overwrite the
``/etc/issue`` file from the **wwinit** overlay. For this we will
create a new overlay called welcome and import the file ``/etc/issue``
``/etc/issue`` file from the "issue" overlay. For this we will
create a new overlay called "welcome" and import the file ``/etc/issue``
from the host to it. This overlay is then combined with the existing
**wwinit** overlay.
overlays.
.. code-block:: console
# wwctl overlay create welcome
# wwctl overlay mkdir welcome /etc
# wwctl overlay import welcome /etc/issue
# wwctl profile set default --wwinit=wwinit,welcome
# wwctl profile set default --wwinit=wwinit,wwclient,welcome
? Are you sure you want to modify 1 profile(s)? [y/N] y
# wwctl profile list default -a |grep welcome
default SystemOverlay wwinit,welcome
default SystemOverlay wwinit,wwclient,welcome
Templates
=========
@@ -143,7 +200,7 @@ permissions, etc.
..
note::
There is no possibility to delete files with an overlay!
It is not possible to delete files with an overlay.
Build
-----

4
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 system overlay
#. The kernel, container 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
@@ -81,7 +81,7 @@ through the following command :
# wwctl node status
NODENAME STAGE SENT LASTSEEN (s)
================================================================================
c001 RUNTIME_OVERLAY generic.img.gz 16
c001 RUNTIME_OVERLAY __RUNTIME__.img.gz 16
For each node, there is 4 different stages :

4
userdocs/contents/setup.rst
View File

@@ -118,8 +118,8 @@ You can check the result with ``wwctl node list``.
deliverynet Comment default This profile is automatically included for each node
deliverynet ContainerName default leap15.5
deliverynet Ipxe -- (default)
deliverynet RuntimeOverlay -- (generic)
deliverynet SystemOverlay -- (wwinit)
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)
deliverynet Root -- (initramfs)
deliverynet Init -- (/sbin/init)
deliverynet Kernel.Args -- (quiet crashkernel=no vga=791 net.naming-scheme=v238)

2
userdocs/contents/templating.rst
View File

@@ -8,7 +8,7 @@ on demand.
In Warewulf, you can find templates both for the provisioning services
(e.g. ``/etc/warewulf/ipxe/``, ``/etc/warewulf/dhcp/``, and
``/etc/warewulf/hosts.tmpl``) as well as within the runtime and system
``/etc/warewulf/hosts.tmpl``) as well as within many of the provided
overlays.
(more documentation coming soon)

2
userdocs/contents/wwctl.rst
View File

@@ -12,7 +12,7 @@ component of Warewulf's functionality.
* ``node`` manages nodes in the cluster
* ``profiles`` defines configuration which can be applied to multiple
nodes
* ``overlays`` manages nodes
* ``overlays`` manages overlays
* ``power`` turns nodes on and off
* ``ssh`` provides basic parallel ssh functionality

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

@@ -98,8 +98,8 @@ Build and install Warewulf on wwdev
# Configure system service automatically
sudo wwctl configure dhcp # Create the default dhcpd.conf file and start/enable service
sudo wwctl configure tftp # Install the base tftp/PXE boot files and start/enable service
sudo wwctl configure nfs # Configure the exports and create an fstab in the default system overlay
sudo wwctl configure ssh # Build the basic ssh keys to be included by the default system overlay
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

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

@@ -113,8 +113,8 @@ I have VirtualBox running on my desktop.
# Configure system service automatically
sudo wwctl configure dhcp --persist # Create the default dhcpd.conf file and start/enable service
sudo wwctl configure tftp --persist # Install the base tftp/PXE boot files and start/enable service
sudo wwctl configure nfs --persist # Configure the exports and create an fstab in the default system overlay
sudo wwctl configure ssh --persist # Build the basic ssh keys to be included by the default system overlay
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

2
userdocs/quickstart/debian12.rst
View File

@@ -201,7 +201,7 @@ typing the following:
sudo wwctl node list -a n0000.cluster
To make node changes effective, it is a good practice to update warewulf
To make node changes effective, it is a good practice to update Warewulf
overlays with the following command:
.. code-block:: bash

2
userdocs/quickstart/suse15.rst
View File

@@ -177,7 +177,7 @@ called. This enables us to prepopulate node configurations with
content that is node specific like networking and service
configurations.
Runtime overlays are provisioned after the node has booted and
Runtime overlays are re-applied
periodically during the normal runtime of the node. Because these
overlays are provisioned at periodic intervals, they are very useful
for content that changes, like users and groups.