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

Documentation reorg for v4.6.0

Browse Source 
Signed-off-by: Jonathon Anderson <janderson@ciq.com>
This commit is contained in:
Jonathon Anderson
2025-02-18 16:26:05 -07:00
parent 98695cbbff
commit 9e41378e1c
65 changed files with 3493 additions and 4654 deletions
Download Patch File Download Diff File Expand all files Collapse all files

BIN
userdocs/getting-started/beowulf_architecture.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 91 KiB

198
userdocs/getting-started/debian-quickstart.rst Normal file
View File

@@ -0,0 +1,198 @@
=================
Debian Quickstart
=================
Deploying Warewulf for Debian 12.
Install the basic services
==========================
.. code-block:: bash
sudo apt install firewalld nfs-kernel-server tftpd-hpa isc-dhcp-server
.. note::
If you get an error message concerning *isc-dhcp-server.service* you
probably need to configure the network intarface that isc-dhcp-server
will listen to. Run ``sudo dpkg-reconfigure isc-dhcp-server`` and enter
the name of your cluster's private network interface (e.g. enp2s0). After that, you might also need to run ``sudo systemctl enable isc-dhcp-server``.
Install Warewulf and dependencies
=================================
.. code-block:: bash
sudo apt install build-essential curl unzip
sudo apt install git golang libnfs-utils libgpgme-dev libassuan-dev
mkdir ~/git
cd ~/git
git clone https://github.com/warewulf/warewulf.git
cd warewulf
git checkout main # or switch to a tag like 'v4.6.0rc3'
make all && sudo make install
Configure firewalld
===================
Restart firewalld to register the added service file, add the service
to the default zone, and reload.
.. code-block:: bash
sudo systemctl restart firewalld
sudo firewall-cmd --permanent --add-service warewulf
sudo firewall-cmd --permanent --add-service dhcp
sudo firewall-cmd --permanent --add-service nfs
sudo firewall-cmd --permanent --add-service tftp
sudo firewall-cmd --reload
Configure the controller
========================
Edit the file ``/etc/warewulf/warewulf.conf`` and ensure that you've
set the appropriate configuration parameters. Here are some of the
defaults for reference assuming that ``192.168.200.1`` is the IP
address of your cluster's private network interface:
.. code-block:: yaml
ipaddr: 192.168.200.1
netmask: 255.255.255.0
network: 192.168.200.0
warewulf:
port: 9873
secure: false
update interval: 60
autobuild overlays: true
host overlay: true
dhcp:
enabled: true
range start: 192.168.200.50
range end: 192.168.200.99
systemd name: isc-dhcp-server
tftp:
enabled: true
systemd name: tftpd-hpa
nfs:
enabled: true
export paths:
- path: /home
export options: rw,sync
- path: /opt
export options: ro,sync,no_root_squash
systemd name: nfs-server
.. note::
The DHCP range ends at ``192.168.200.99`` and as you will see
below, the first node static IP address (post boot) is configured
to ``192.168.200.100``.
Start and enable the Warewulf service
=====================================
.. code-block:: bash
# Start and enable the warewulfd service
sudo systemctl enable --now warewulfd
Configure system services automatically
=======================================
There are a number of services and configurations that Warewulf relies
on to operate. If you wish to configure all services, you can do so
individually (omitting the ``--all``) will print a help and usage
instructions.
.. code-block:: bash
sudo wwctl configure --all
.. note::
If you just installed the system fresh and have SELinux enforcing,
you may need to reboot the system at this stage to properly set the
contexts of the TFTP contents. After rebooting, you might also need
to run ``$ sudo restorecon -Rv /var/lib/tftpboot/`` if there are
errors with TFTP still.
Pull and build the image
========================
This will pull a basic image from Docker Hub
and set it for the "default" node profile.
.. code-block:: bash
wwctl image import docker://ghcr.io/warewulf/warewulf-debian:12.0 debian-12.0
wwctl profile set default --image=debian-12.0
Set up the default node profile
===============================
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 image we just imported above to
the ``default`` node profile:
.. code-block:: bash
sudo wwctl profile set --yes --image debian-12.0 "default"
Next we set some default networking configurations for the first
ethernet device. On modern Linux distributions, the name of the device
is not critical, as it will be setup according to the HW
address. Because all nodes will share the netmask and gateway
configuration, we can set them in the default profile as follows:
.. code-block:: bash
sudo wwctl profile set --yes --netdev eth0 --netmask 255.255.255.0 --gateway 192.168.200.1 "default"
Once those configurations have been set, you can view the changes by
listing the profiles as follows:
.. code-block:: bash
sudo wwctl profile list -a
Add a node
==========
Adding nodes can be done while setting configurations in one
command. Here we are setting the IP address of ``eth0`` and setting
this node to be discoverable, which will then automatically have the
HW address added to the configuration as the node boots.
Node names must be unique. If you have node groups and/or multiple
clusters, designate them using dot notation.
Note that the full node configuration comes from both cascading
profiles and node configurations which always supersede profile
configurations.
.. code-block:: bash
sudo wwctl node add n0000.cluster --ipaddr 192.168.200.100 --discoverable true
At this point you can view the basic configuration of this node by
typing the following:
.. code-block:: bash
sudo wwctl node list -a n0000.cluster
To make node changes effective, it is a good practice to update Warewulf
overlays with the following command:
.. code-block:: bash
sudo wwctl overlay build
Now, turn on your compute node and watch it boot!

219
userdocs/getting-started/el-quickstart.rst Normal file
View File

@@ -0,0 +1,219 @@
===========================
Enterprise Linux Quickstart
===========================
Deploying Warewulf for Rocky Linux, CentOS, RHEL, and other related
distributions.
Install Warewulf
================
The preferred way to install Warewulf on Enterprise Linux is using the
the RPMs published in `GitHub releases`_. For example, to install the
v4.6.0rc3 release on Enterprise Linux 9:
.. code-block:: bash
dnf install https://github.com/warewulf/warewulf/releases/download/v4.6.0rc3/warewulf-4.6.0rc3-1.el9.x86_64.rpm
Packages are available for el8 and el9.
.. _GitHub releases: https://github.com/warewulf/warewulf/releases
Install Warewulf from source
----------------------------
If you prefer, you can also install Warewulf from source.
.. code-block:: shell
dnf install git
dnf install epel-release
dnf install golang {libassuan,gpgme}-devel unzip tftp-server dhcp-server nfs-utils ipxe-bootimgs-{x86,aarch64}
git clone https://github.com/warewulf/warewulf.git
cd warewulf
PREFIX=/usr/local make defaults
make install
.. note::
Some packages, like ``libassuan-devel`` and ``gpgme-devel``, require either
PowerTools (EL8) or CodeReady Builder (EL9) repositories.
.. code-block::
dnf config-manager --set-enabled PowerTools # EL8
dnf config-manager --set-enabled crb # EL9
Configure firewalld
===================
Restart firewalld to register the added service file, add the service
to the default zone, and reload.
.. code-block:: bash
systemctl restart firewalld
firewall-cmd --permanent --add-service=warewulf
firewall-cmd --permanent --add-service=dhcp
firewall-cmd --permanent --add-service=nfs
firewall-cmd --permanent --add-service=tftp
firewall-cmd --reload
Configure Warewulf
==================
Edit the file ``/etc/warewulf/warewulf.conf`` and ensure that you've
set the appropriate configuration parameters. Here are some of the
defaults for reference assuming that ``10.0.0.1/22`` is the IP
address of your cluster's private network interface.
.. code-block:: yaml
ipaddr: 10.0.0.1
netmask: 255.255.252.0
network: 10.0.0.0
warewulf:
port: 9873
secure: false
update interval: 60
autobuild overlays: true
host overlay: true
datastore: /usr/share
grubboot: false
dhcp:
enabled: true
template: default
range start: 10.0.1.1
range end: 10.0.1.255
systemd name: dhcpd
tftp:
enabled: true
tftproot: /var/lib/tftpboot
systemd name: tftp
ipxe:
"00:00": undionly.kpxe
"00:07": ipxe-snponly-x86_64.efi
"00:09": ipxe-snponly-x86_64.efi
00:0B: arm64-efi/snponly.efi
nfs:
enabled: true
export paths:
- path: /home
export options: rw,sync
- path: /opt
export options: ro,sync,no_root_squash
systemd name: nfs-server
image mounts:
- source: /etc/resolv.conf
dest: /etc/resolv.conf
readonly: true
paths:
bindir: /usr/bin
sysconfdir: /etc
localstatedir: /var/lib
ipxesource: /usr/share/ipxe
srvdir: /var/lib
firewallddir: /usr/lib/firewalld/services
systemddir: /usr/lib/systemd/system
wwoverlaydir: /var/lib/warewulf/overlays
wwchrootdir: /var/lib/warewulf/chroots
wwprovisiondir: /var/lib/warewulf/provision
wwclientdir: /warewulf
.. note::
The DHCP range from ``10.0.1.1`` to ``10.0.1.255`` is dedicated for
DHCP during node boot and should not overlap with any static IP
address assignments.
Enable and start the Warewulf service
=====================================
Warewulf provides a service, ``warewulfd``, which responds to node
boot requests.
.. code-block:: bash
systemctl enable --now warewulfd
Configure system services automatically
=======================================
There are a number of services and configurations that Warewulf relies
on to operate. You can configure all such services with ``wwctl
configure --all``.
.. code-block:: bash
wwctl configure --all
.. note::
If you just installed the system fresh and have SELinux enforcing,
you may need to run ``restorecon -Rv /var/lib/tftpboot/`` to label
files written to q`tftpboot``.
Add a base node image
=====================
This will pull a basic node image from Docker Hub
and set it for the "default" node profile.
.. code-block:: bash
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
==================================
In this example, all nodes share the netmask and gateway
configuration, so we can set them in the default profile.
.. code-block:: bash
wwctl profile set -y default --netmask=255.255.252.0 --gateway=10.0.0.1
wwctl profile list
Add a node
==========
Adding nodes can be done while setting configurations in one
command. Here we set the IP address of the default interface; and
setting the node to be discoverable causes the HW address to be added
to the configuration as the node boots.
Node names must be unique. If you are managing multiple clusters with
overlapping names, distinguish them using dot notation.
.. code-block:: bash
wwctl node add n1 --ipaddr=10.0.2.1 --discoverable=true
wwctl node list -a n1
The full node configuration comes from both cascading profiles and
node configurations which always supersede profile configurations.
Build overlays
==============
The default configuration should cause node overlays to be built automatically
when they are required; but you can build them explicitly, just to be sure.
.. warning::
Overlay autobuild has been broken at various times prior to v4.5.6; so it's
a reasonable practice to rebuild overlays manually after changes to the
cluster.
.. code-block:: bash
# you can also supply an `n1` argument to build for the specific node
wwctl overlay build
Boot
====
Turn on your compute node and watch it boot!

103
userdocs/getting-started/glossary.rst Normal file
View File

@@ -0,0 +1,103 @@
========
Glossary
========
Cluster network
A dedicated network for the Warewulf cluster. Used for provisioning
communication between cluster nodes and the Warewulf server.
External services
The Warewulf server can configure external services to support the
provisioning process. For example, the Warewulf server typically deploys and
configures a DHCP server (either ISC DHCP or dnsqmasq) 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.
Kernel
In addition to an image, Warewulf also requires a kernel (typically a Linux
kernel) in order to provision a node.
Warewulf (after v4.3.0) automatically provisions 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. The
roles of these systems could be "compute", "storage", "GPU", "IO", etc.
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 images or overlays, but refers to them by
name.
This file is sometimes referred to as the "nodes database" or "node
registry."
Overlay
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.
**Runtime overlays** are applied when a node is first provisioned and
periodically during the runtime of the node. (The default period is 1
minute.)
Warewulf includes a number of **distribution overlays**; but additional
**site overlays** can be added to a Warewulf environment.
Profile
Warewulf profiles are abstract nodes that carry the same configuration
attributes but do not provision any specific node. Warewulf nodes may then
refer to one or more such profiles for their configuration. In this way,
profiles provide a simple mechanism for applying configuration to a group of
nodes, and this configuration may be mixed with configuration from other
profiles.
Server, Warewulf
The Warewulf controller runs the Warewulf daemon (``warewulfd``) and is
responsible for the management, control, and administration of the cluster.
This system may also sometimes be referred to as the "master," "head," or
"admin" node.
A typical Warewulf controller also runs a DHCP service and a TFTP service,
and often an NFS service; though these services may be managed separately
and on separate servers.
Two-stage boot
A two-stage boot uses an intermediate image (often called "initrd," or
"initramfs") to initialize hardware and load the final image. This contrasts
with Warewulf's default "single stage" behavior, which effectively uses the
final image as a large initial root file system.
The Warewulf two-stage boot process currently supports Dracut-based images.
warewulf.conf
One of two primary Warewulf configuration files, ``warewulf.conf`` is a YAML
document which records all configuration parameters for the Warewulf server
and its optional subservices.
wwclient
Warewulf adds a ``wwclient`` daemon to provisioned nodes. This daemon is
responsible for periodically fetching and applying runtime overlays.
wwctl
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. This process is referred to
as "wwinit," and is implemented and configured by a script and overlay of
the same name.

111
userdocs/getting-started/introduction.rst Normal file
View File

@@ -0,0 +1,111 @@
============
Introduction
============
Warewulf is an operating system provisioning platform for Linux clusters. Since
its initial release in 2001, Warewulf has become the most popular open source
and vendor-agnostic provisioning system within the global HPC community.
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
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 principals to create and maintain
large scalable stateless clusters.
Warewulf is used most prominently in High Performance Computing (HPC) clusters,
but its architecture is flexible enough to be used in most any clustered Linux
environment, including clustered web servers, rendering farms, and even
Kubernetes and cloud deployments.
Warewulf design
===============
Warewulf has had a number of iterations since its inception in 2001, but its
design tenets have always remained the same: a simple, scalable, stateless, and
flexible provisioning system for all types of clusters.
* **Lightweight**: Warewulf provisions stateless operating system images and
then gets out of the way. There are no underlying system dependencies or
requisite changes to the provisioned cluster node operating system.
* **Simple**: Warewulf is used by hobbyists, researchers, scientists, engineers
and systems administrators alike.
* **Flexible**: Warewulf can address the needs of any environment--from a
computer lab with graphical workstations, to under-the-desk clusters, to
supercomputing centers providing HPC services to thousands of users.
* **Agnostic**: From the Linux distribution of choice to the underlying
hardware, Warewulf is agnostic and standards compliant. From ARM to x86, Atos
to Dell, Debian, SUSE, Rocky, CentOS, and RHEL, Warewulf can be used in most
any environment.
* **Secure**: Warewulf support SELinux out-of-the-box. Just install SELinux in
your node 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
the Warewulf project is always welcoming of contribution from its community of
users, with major features often beginning as external contributions.
Warewulf architecture
=====================
Warewulf v4 has a simple but flexible base architecture:
A **Warewulf server** stores information about the cluster and the nodes in it,
and provides a command-line interface (``wwctl``) for managing nodes, their
images, and their overlays.
**Cluster nodes** are defined in a flexible `YAML
<https://en.wikipedia.org/wiki/YAML>`_ file, including their network
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
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
at runtime.
Beowulf overview
================
Warewulf is designed to support the original `Beowulf Cluster
<https://en.wikipedia.org/wiki/Beowulf_cluster>`_ concept. (Thus its name, a
soft\ **WARE** implementation of the beo\ **WULF**.) The architecture is
characterized by a group of similar cluster nodes all connected together using
standard commodity equipment on an internal cluster network. The server node
(often historically referred to as the "master" or "head" node) is "dual homed"
(i.e., it has two network interfaces) with one of these network interfaces
attached to an external network and the other connected to the internal cluster
network.
.. image:: beowulf_architecture.png
:alt: Beowulf architecture
This simple topology is the foundation for creating a scalable HPC cluster
resource. Even today, almost 30 years after the inception of this architecture,
this is the baseline architecture that virtually all HPC systems are built to.
An HPC cluster often includes dedicated storage, scheduling and resource
management, monitoring, interactive systems, and other components. For smaller
systems, many of these components can be deployed to a single server node; but,
as the system scales, it may be better to have groups of nodes dedicated to
these different services.
Warewulf is flexible enough to start with a simple "head node" Beowulf style
cluster deployment and to grow as needs for the cluster and its environment
change.

165
userdocs/getting-started/network.rst Normal file
View File

@@ -0,0 +1,165 @@
================
Network Planning
================
A clustered resource depends on a cluster network. This network can be either
persistent (it is always "up" even after provisioning) or temporary, only used
for provisioning and/or out of band system control and management (e.g., IPMI).
The cluster network must be dedicated to the cluster because Warewulf uses
network services (particularly DHCP) which may conflict with services on another
mixed-use network. A dedicated cluster network is also important for security,
as the cluster network often has an implicit level of trust associated with it.
The Warewulf server is often "dual homed," meaning that it has separate network
interfaces connected to each of the cluster network and an external network. But
it is also possible for the cluster network to be routable from other, more
general-purpose networks.
Many clusters have more than one internal network. This is common for
performance critical HPC clusters that implement a high speed and low latency
network like InfiniBand. In this case, this network is used for high speed data
transfers for inter-process communication between compute nodes and file system
IO.
Warewulf will need to be configured to use the private cluster management
network. Warewulf will use this network for booting the nodes over PXE. There
are three network protocols used to accomplish this DHCP/BOOT, TFTP, and HTTP on
port ``9873``. Warewulf will use the operating system's provided version of DHCP
(ISC-DHCP) and TFTP for the PXE bootstrap to iPXE, and then iPXE will use
Warewulf's internal HTTP services to transfer the larger files for provisioning.
Addressing
==========
The addressing scheme of your private cluster network is 100% up to the system
integrator, but for large clusters, many organizations like to organize the
address allocations. Below is a recommended IP addressing scheme which we will
use for the rest of this document.
* ``10.0.0.1``: Private network address IP
* ``255.255.252.0``: Private network subnet mask (``10.0.0.0/22``)
Here is an example of how the cluster's address can be divided for a 255 node
cluster:
* ``10.0.0.1 - 10.0.0.255``: Cluster infrastructure including this
host, schedulers, file systems, routers, switches, etc.
* ``10.0.1.1 - 10.0.1.255``: DHCP range for booting nodes
* ``10.0.2.1 - 10.0.2.255``: Static node addresses
* ``10.0.3.1 - 10.0.3.255``: IPMI and/or out of band addresses for the
compute nodes
Multiple networks
=================
It is possible to configure several networks not just for the nodes but also for
the management of ``dhcpd`` and ``tftp``. There are two ways to achieve this:
* Add the networks to the templates of ``dhcpd`` and/or the ``dnsmasq`` template
directly.
* Add the networks to a dummy node and change the templates of ``dhcp`` and
``dnsmasq`` accordingly.
The first method is relatively trivial. The second method is described below.
As first the first step, add the dummy node.
.. code-block:: shell
wwctl node add deliverynet
Add the delivery networks to this node.
.. code-block:: shell
wwctl node set \
--ipaddr 10.0.20.250 \
--netmask 255.255.255.0 \
--netname deliver1 \
--nettagadd network=10.0.20.0,dynstart=10.10.20.10,dynend=10.10.20.50 \
deliverynet
wwctl node set \
--ipaddr 10.0.30.250 \
--netmask 255.255.255.0 \
--netname deliver2 \
--nettagadd network=10.0.30.0,dynstart=10.10.30.10,dynend=10.10.30.50 \
deliverynet
The ip address is used as the network address of host in the delivery network
and an additional tags is used for definition of the network itself and the
dynamic dhcp range. You can check the result with ``wwctl node list``.
.. code-block:: console
# wwctl node list -a deliverynet
NODE FIELD PROFILE VALUE
deliverynet Id -- deliverynet
deliverynet Comment default This profile is automatically included for each node
deliverynet ImageName default leap15.5
deliverynet Ipxe -- (default)
deliverynet RuntimeOverlay -- (hosts,ssh.authorized_keys)
deliverynet SystemOverlay -- (wwinit,wwclient,hostname,ssh.host_keys,systemd.netname,NetworkManager)
deliverynet Root -- (initramfs)
deliverynet Init -- (/sbin/init)
deliverynet Kernel.Args -- (quiet crashkernel=no net.ifnames=1)
deliverynet Profiles -- default
deliverynet PrimaryNetDev -- (deliver1)
deliverynet NetDevs[deliver2].Type -- (ethernet)
deliverynet NetDevs[deliver2].OnBoot -- (true)
deliverynet NetDevs[deliver2].Ipaddr -- 10.0.30.250
deliverynet NetDevs[deliver2].Netmask -- 255.255.255.0
deliverynet NetDevs[deliver2].Tags[dynend] -- 10.10.30.50
deliverynet NetDevs[deliver2].Tags[dynstart] -- 10.10.30.10
deliverynet NetDevs[deliver2].Tags[network] -- 10.0.30.0
deliverynet NetDevs[deliver1].Type -- (ethernet)
deliverynet NetDevs[deliver1].OnBoot -- (true)
deliverynet NetDevs[deliver1].Ipaddr -- 10.0.20.250
deliverynet NetDevs[deliver1].Netmask -- 255.255.255.0
deliverynet NetDevs[deliver1].Primary -- (true)
deliverynet NetDevs[deliver1].Tags[network] -- 10.0.20.0
deliverynet NetDevs[deliver1].Tags[dynend] -- 10.10.20.50
deliverynet NetDevs[deliver1].Tags[dynstart] -- 10.10.20.10
Now the templates of ``dhcpd`` and/or ``dnsmasq`` must be modified.
.. code-block:: shell
wwctl overlay edit host etc/dhcpd.conf.ww
wwctl overlay edit host etc/dnsmasq.d/ww4-hosts.ww
For the ``dhcp`` template you should add following lines
.. code-block::
{{/* multiple networks */}}
{{- range $node := $.AllNodes}}
{{- if eq $node.Id.Get "deliverynet" }}
{{- range $netname, $netdev := $node.NetDevs}}
# network {{ $netname }}
subnet {{$netdev.Tags.network.Get}} netmask {{$netdev.Netmask.Get}} {
max-lease-time 120;
range {{$netdev.Tags.dynstart.Get}} {{$netdev.Tags.dynend.Get}};
next-server {{$netdev.Ipaddr.Get}};
}
{{- end }}
{{- end }}
{{- end }}
and for the ``dnsmasq`` the following lines should be added
.. code-block::
{{/* multiple networks */}}
{{- range $node := $.AllNodes}}
{{- if eq $node.Id.Get "deliverynet" }}
{{- range $netname, $netdev := $node.NetDevs}}
# network {{ $netname }}
dhcp-range={{$netdev.Tags.dynstart.Get}},{{$netdev.Tags.dynend.Get}},{{$netdev.Netmask.Get}},6h
{{- end }}
{{- end }}
{{- end }}
Note that the ``{{- if eq $node.Id.Get "deliverynet" }}`` is used to identify
the dummy host which carries the network information.

93
userdocs/getting-started/provisioning.rst Normal file
View File

@@ -0,0 +1,93 @@
====================
Cluster Provisioning
====================
Clusters have many scalability factors to consider. Often overlooked among them
is "administrative scaling"-- the systems administration overhead of a person or
team maintaining a large number of systems. While homogeneous configurations do
improve administrative scaling, each installed server is still subject to
version and configuration drift, eventually becoming a point of discrete
administration and debugging. The larger the cluster, the harder this problem is
to solve.
This is the problem that Warewulf was created solve.
Provisioning Overview
=====================
Provisioning is the process of preparing a system for use, typically by
providing and configuring an operating system. There are many ways to accomplish
this, from copying hard drives, to scripted installs, to automated installs.
Each has its place, and there are many tools available to facilitate each
method.
Before dedicated cluster provisioning systems, administrators would visit each
cluster node and install it from scratch, with an ISO, CD, or USB flash drive.
This is obviously not scalable. Because the nodes in a cluster environment are
typically identical, it is much more efficient to group sets of nodes together
to be provisioned in bulk.
Why Stateless Provisioning
==========================
Warewulf further improves on the automated provisioning process by skipping the
installation completely; it boots directly into the runtime operating system
without ever doing an installation.
Stateless provisioning means you never have to install another compute node.
Think of it like booting a LiveOS or LiveISO on nodes over the network. This
means that no node requires discrete administration, but rather the entire
cluster is administrated as a single unit. There is no version drift, because it
is not possible for nodes to fall out of sync. Every reboot makes it exactly the
same as its neighbors.
Cluster Node Requirements
=========================
The only requirement to provision a node with Warewulf is that the node is set
to PXE boot. You may need to change the boot order if there is a local disk
present and bootable. This is a configuration change you will have to make in
the BIOS of the cluster node.
This configuration is different for each vendor platform. For more information,
consult your system documentation or contact your hardware vendor support.
.. note::
Hardware vendors are often able to preconfigure your cluster nodes with
values of your choosing. Ask them to provide a text file that includes all of
the network interface MAC addresses of the clusters nodes in the order they
are racked--this simplifies the process of adding nodes to Warewulf.
The Provisioning Process
========================
When a cluster node boots from Warewulf, the following process occurs:
#. The system firmware (either BIOS or UEFI) initializes hardware, including
local network interfaces.
#. The system uses an in-firmware PXE client to obtain a BOOTP/DHCP address from
the network.
#. The DHCP server (hosted either on the Warewulf server or externally) responds
with an address suitable for provisioning, along with a "next-server" option
directing the cluster node to download (via TFTP) and execute a bootloader
(either iPXE or GRUB) with a Warewulf-provided configuration.
#. The bootloader configuration directs the cluster node to download and
bootstrap the configured kernel, image, and overlays from the Warewulf (HTTP)
server.
* In a single-stage provisioning configuration, the desired image and
overlays are combined and provisioned immediately by the bootloader as the
kernel's initial root file system. This is straightfoward, but does not
work in all environments: some systems have memory layouts that are not
handled properly by either iPXE or GRUB for sufficiently large image sizes,
leading to strange, unpredictable results.
* In a two-stage provisioning configuration, a small initial root fs (created
by dracut) is provisioned first, and this image uses the provisioned Linux
kernel to retrieve and deploy the full image and overlays. Perhaps
counter-intuitively, the two-stage provisioning process is often quicker
than the single-stage process, because the Linux environment is more I/O
efficient than the bootloader itself.
#. Optionally included in a configured overlay, ``wwclient`` is left resident on
the cluster node and periodically refreshes configured runtime overlays.

200
userdocs/getting-started/suse-quickstart.rst Normal file
View File

@@ -0,0 +1,200 @@
===============
SUSE Quickstart
===============
Deploying Warewulf for openSUSE Leap and SLES 15.
Install Warewulf and dependencies
=================================
.. code-block:: bash
sudo zypper install -t pattern devel_basis
sudo zypper install go
sudo zypper install tftp dhcp-server nfs-kernel-server
sudo systemctl stop firewalld
sudo systemctl disable firewalld
git clone https://github.com/warewulf/warewulf.git
cd warewulf
PREFIX=/usr SYSCONFDIR=/etc TFTPDIR=/srv/tftproot LOCALSTATEDIR=/var/lib make clean defaults
make all
sudo make install
The standard configuration template for the dhcpd service is installed
at the wrong location, you have to fix this with
.. code-block:: bash
mv /var/lib/warewulf/overlays/host/etc/dhcp/dhcpd.conf.ww /var/lib/warewulf/overlays/host/etc/dhcpd.conf.ww
Install Warewulf from the open build service
============================================
You can also just install the 'warewulf4' package with ``zypper`` from
the openbuild service. Up to date versions are available on the devel
project
``https://build.opensuse.org/project/show/network:cluster``
Configure the controller
========================
Edit the file ``/etc/warewulf/warewulf.conf`` and ensure that you've
set the appropriate configuration paramaters. Here are some of the
defaults for reference assuming that ``192.168.200.1`` is the IP
address of your cluster's private network interface:
.. code-block:: yaml
ipaddr: 192.168.200.1
netmask: 255.255.255.0
network: 192.168.200.0
warewulf:
port: 9873
secure: false
update interval: 60
autobuild overlays: true
host overlay: true
dhcp:
enabled: true
range start: 192.168.200.50
range end: 192.168.200.99
systemd name: dhcpd
tftp:
enabled: true
systemd name: tftp
nfs:
enabled: true
export paths:
- path: /home
export options: rw,sync
- path: /opt
export options: ro,sync,no_root_squash
systemd name: nfs-server
image mounts:
- source: /etc/resolv.conf
dest: /etc/resolv.conf
readonly: true
.. note::
The DHCP range ends at ``192.168.200.99`` and as you will see
below, the first node static IP address (post boot) is configured
to ``192.168.200.100``.
Start and enable the Warewulf service
=====================================
.. code-block:: bash
# Start and enable the warewulfd service
sudo systemctl enable --now warewulfd
Configure system services automatically
=======================================
There are a number of services and configurations that Warewulf relies
on to operate. If you wish to configure all services, you can do so
individually (omitting the ``--all``) will print a help and usage
instructions.
.. note::
If the ``dhcpd`` service was not used before you will have to add
the interface on which the cluster network is running to the
``DHCP_INTERFACE`` in the file ``/etc/sysconfig/dhcpd``.
.. code-block:: bash
sudo wwctl configure --all
Pull and build the image
========================
This will pull a basic image from Docker Hub
and set it in the "default" node profile.
.. code-block:: bash
$ sudo wwctl image import docker://registry.opensuse.org/science/warewulf/leap-15.4/containers/kernel:latest leap15.4
$ sudo wwctl profile set default --image leap15.4
Set up the default node profile
===============================
The ``--setdefault`` arguments above will automatically set those
entries in the default profile, but if you wanted to set them by hand
to something different, you can do the following:
.. code-block:: bash
sudo wwctl profile set -y -C leap15.4
Next we set some default networking configurations for the first
ethernet device. On modern Linux distributions, the name of the device
is not critical, as it will be setup according to the HW
address. Because all nodes will share the netmask and gateway
configuration, we can set them in the default profile as follows:
.. code-block:: bash
sudo wwctl profile set -y default --netname default --netmask 255.255.255.0 --gateway 192.168.200.1
sudo wwctl profile list -a
Add a node
==========
Adding nodes can be done while setting configurations in one
command. Here we are setting the IP address of ``eth0`` and setting
this node to be discoverable, which will then automatically have the
HW address added to the configuration as the node boots.
Node names must be unique. If you have node groups and/or multiple
clusters, designate them using dot notation.
Note that the full node configuration comes from both cascading
profiles and node configurations which always supersede profile
configurations.
.. code-block:: bash
sudo wwctl node add n0000.cluster --netdev eth0 --ipaddr 192.168.200.100 --discoverable true
sudo wwctl node list -a n0000.cluster
Warewulf Overlays
=================
There are two types of overlays: system and runtime overlays.
System overlays are provisioned to the node before ``/sbin/init`` is
called. This enables us to prepopulate node configurations with
content that is node specific like networking and service
configurations.
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.
Overlays are generated from a template structure that is viewed using
the ``wwctl overlay`` commands. Files that end in the ``.ww`` suffix
are templates and abide by standard text/template rules. This supports
loops, arrays, variables, and functions making overlays extremely
flexible.
All overlays are compiled before being provisioned. This accelerates
the provisioning process because there is less to do when nodes are
being managed at scale.
Here are some of the common ``overlay`` commands:
.. code-block:: bash
sudo wwctl overlay list -l
sudo wwctl overlay list -ls
sudo wwctl overlay edit default /etc/hello_world.ww
sudo wwctl overlay build -a
Boot your compute node and watch it boot!