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

Merge pull request #862 from anderbubble/userdocs-fact-check

Browse Source 
Userdocs fact check and audit
This commit is contained in:
Jonathon Anderson
2024-02-17 02:41:45 -07:00
committed by GitHub
parent 7db1f5da0f 7fbc5a16cf
commit c828356b53
13 changed files with 126 additions and 137 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
etc/warewulf.conf
View File

@@ -1,7 +1,7 @@
WW_INTERNAL: 45
ipaddr: 192.168.200.1
netmask: 255.255.255.0
network: 192.168.200.0
ipaddr: 10.0.0.1
netmask: 255.255.252.0
network: 10.0.0.0
warewulf:
port: 9873
secure: false
@@ -11,8 +11,8 @@ warewulf:
syslog: false
dhcp:
enabled: true
range start: 192.168.200.50
range end: 192.168.200.99
range start: 10.0.1.1
range end: 10.0.1.255
systemd name: dhcpd
tftp:
enabled: true

2
go.mod
View File

@@ -11,7 +11,6 @@ require (
github.com/creasty/defaults v1.7.0
github.com/fatih/color v1.15.0
github.com/golang/glog v1.0.0
github.com/golang/protobuf v1.5.2
github.com/google/uuid v1.3.0
github.com/grpc-ecosystem/grpc-gateway/v2 v2.15.2
github.com/manifoldco/promptui v0.9.0
@@ -57,6 +56,7 @@ require (
github.com/docker/go-units v0.4.0 // indirect
github.com/ghodss/yaml v1.0.0 // indirect
github.com/gogo/protobuf v1.3.2 // indirect
github.com/golang/protobuf v1.5.2 // indirect
github.com/golang/snappy v0.0.3 // indirect
github.com/gorilla/mux v1.7.4 // indirect
github.com/inconshreveable/mousetrap v1.0.1 // indirect

48
userdocs/contents/configuration.rst
View File

@@ -10,14 +10,14 @@ warewulf.conf
=============
The Warewulf configuration exists as follows in the current version of
Warewulf (4.3.0):
Warewulf (4.4.0):
.. code-block:: yaml
WW_INTERNAL: 43
ipaddr: 192.168.200.1
netmask: 255.255.255.0
network: 192.168.200.0
ipaddr: 10.0.0.1
netmask: 255.255.252.0
network: 10.0.0.0
warewulf:
port: 9873
secure: false
@@ -27,8 +27,8 @@ Warewulf (4.3.0):
syslog: false
dhcp:
enabled: true
range start: 192.168.200.50
range end: 192.168.200.99
range start: 10.0.1.1
range end: 10.0.1.255
systemd name: dhcpd
tftp:
enabled: true
@@ -45,6 +45,10 @@ Warewulf (4.3.0):
mount options: defaults
mount: false
systemd name: nfs-server
container mounts:
- source: /etc/resolv.conf
dest: /etc/resolv.conf
readonly: true
Generally you can leave this file as is, as long as you set the
appropriate networking information. Specifically the following
@@ -64,16 +68,12 @@ configurations:
network, failures will occur. This specifies the range of addresses
you want DHCP to use.
.. note::
The network configuration listed above assumes the network layout
in the [Background](background.md) portion of the documentation.
The other configuration options are usually not touched, but they are
explained as follows:
* ``*:enabled``: This disables Warewulf's control of an external
service. This is useful if you want to manage that service directly.
* ``*:enabled``: This can be used to disable Warewulf's control of a
system service. This is useful if you want to manage that service
directly.
* ``*:systemd name``: This is so Warewulf can control some of the
host's services. For the distributions that we've built and tested
@@ -111,8 +111,12 @@ explained as follows:
to syslog or are written directly to a log file. (e.g.,
``/var/log/warewulfd.log``)
* ``nfs:export paths``: Warewulf will automatically set up the NFS
exports if you wish for it to do this.
* ``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
them to operate in the host environment prior to deployment.
nodes.conf
==========
@@ -130,18 +134,18 @@ command.
.. note::
This configuration is not written at install time, but the
first time you attempt to run ``wwctl``, this file will be generated
if it does not exist already.
This configuration is not written at install time; but, the first
time you attempt to run ``wwctl``, this file will be generated if
it does not exist already.
defaults.conf
=============
The ``defaults.conf`` file configures default values used when none
are specified. For example: if a node does not have 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.
are specified in ``nodes.conf``. For example: if a node does not have
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:

20
userdocs/contents/containers.rst
View File

@@ -11,21 +11,21 @@ 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
a lot of tooling and standards around defining, building,
distributing, securing, and managing containers, so Warewulf (as of
v4.0) now integrates directly within the container ecosystem to
facilitate the process of VNFS image management.
distributing, securing, and managing containers, so Warewulf v4 now
integrates directly within the container ecosystem to facilitate the
process of VNFS 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
Warewulf as you always have.
Warewulf as before.
It is important to understand that Warewulf is not running a container
runtime on the nodes. While that is absolutely possible to run
containers from the booted hosts, Warewulf is provisioning the
container image to the bare metal and booting it. This container will
be used as the base operating system and by default it will run
stateless in memory. This means when you reboot the node, the node
persists no information about Warewulf or how it booted.
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
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
===============

6
userdocs/contents/initialization.rst
View File

@@ -42,8 +42,8 @@ Warewulf Service
================
The Warewulf installation attempts to register the Warewulf service
with Systemd, so it should be as easy to start/stop/check as any other
Systemd service:
with systemd, so it should be as easy to start/stop/check as any other
systemd service:
.. code-block:: console
@@ -58,7 +58,7 @@ command line program as follows:
.. note::
If the Warewulf service is running via Systemd, restarting
If the Warewulf service is running via systemd, restarting
stopping, and starting it from the ``wwctl`` command may result in
unexpected results.

60
userdocs/contents/installation.rst
View File

@@ -1,9 +1,9 @@
#####################
=====================
Warewulf Installation
#####################
=====================
There are multiple methods to install Warewulf, this page describes
the installation process of multiple methods:
There are multiple methods to install Warewulf. This page describes
the installation process for some of those methods.
Binary RPMs
===========
@@ -49,10 +49,9 @@ source code as follows:
Release Tarball
---------------
When the Warewulf project releases stable versions, they are available
via source form here:
`https://github.com/warewulf/warewulf/tags <https://github.com/warewulf/warewulf/tags/>`_
The Warewulf project releases source distributions alongside its
binary RPMs. You can obtain them from the `GitHub releases
<https://github.com/hpcng/warewulf/releases>`_ page.
Select the version you wish to install and download the tarball to any
location on the server, then follow these directions making the
@@ -60,39 +59,38 @@ appropriate substitutions:
.. code-block:: bash
# EDIT HERE
VERSION=4.2.0
DOWNLOAD=/tmp/warewulf-${4.2.0}.tar.gz
# COPY/PASTE THIS
mkdir ~/src
cd ~/src
tar xvf ${DOWNLOAD}
VERSION=4.4.0
curl -LO https://github.com/hpcng/warewulf/releases/download/v${VERSION}/warewulf-${VERSION}.tar.gz
tar -xf warewulf-${VERSION}.tar.gz
cd warewulf-${VERSION}
make all && sudo make install
Git
---
Warewulf is developed in "Git", a source code management platform that
allows collaborative development and revision control. From the Git
repository, you can download different versions of the project either
from tags or branches. By default, when you go to the GitHub page, you
will find the default branch entitled ``main``. The ``main`` branch is
where most of the active development occurs, so if you want to obtain
the latest and greatest version of Warewulf, this is where to go. But
be forewarned, using a snapshot from ``main`` is not guaranteed to be
stable or generally supported for production. If you are building for
production, it is best to download a release tarball from the main
site, the GitHub releases page, or from a Git tag.
Warewulf is developed in GitHub, a source code management platform
that allows collaborative development and revision control. From the
Git repository, you can download different versions of the project
either from tags or branches. By default, when you go to the GitHub
page, you will find the default branch entitled ``development``. The
``development`` branch is where most of the active development occurs,
so if you want to obtain the latest and greatest version of Warewulf,
this is where to go. But be forewarned, using a snapshot from
``development`` is not guaranteed to be stable or generally supported
for production.
Alternatively, the ``main`` branch is more stable and is used as a
staging area for pending releases.
If you are building for production, it is best to download a release
tarball from the main site, the GitHub releases page, or from a Git
tag.
.. code-block:: bash
mkdir ~/git
cd ~/git
git clone https://github.com/warewulf/warewulf.git
git clone https://github.com/hpcng/warewulf.git
cd warewulf
git checkout main # or switch to a tag like '4.2.0'
git checkout development # or switch to a tag like 'v4.4.0'
make all && sudo make install
Runtime Dependencies

30
userdocs/contents/kernel.rst
View File

@@ -6,8 +6,8 @@ Node Kernels
============
Warewulf nodes require a Linux kernel to boot. There are multiple ways
to do this, but the default, and easiest way is to install the kernel
you wish to use for a particular container, into the container.
to do this, but the default and easiest way is to install the kernel
you wish to use for a particular container into the container.
Warewulf will locate the kernel automatically within the container and
by default use that kernel for any node configured to use that
@@ -19,15 +19,14 @@ You can see what kernel is included in a container by using the
.. code-block:: console
# wwctl container list
CONTAINER NAME NODES KERNEL VERSION
alpine 0
rocky 0 4.18.0-348.12.2.el8_5.x86_64
rocky_updated 1 4.18.0-348.23.1.el8_5.x86_64
CONTAINER NAME NODES KERNEL VERSION CREATION TIME MODIFICATION TIME SIZE
alpine 0 05 Jun 23 20:02 MDT 05 Jun 23 20:02 MDT 17.9 MiB
rocky-8 1 4.18.0-372.13.1.el8_6.x86_64 17 Jan 23 23:48 MST 06 Apr 23 09:40 MDT 2.4 GiB
Here you will notice the alpine contianer that was imported has no
kernel within it, and each of the rocky containers include a kernel.
kernel within it, and the rocky container includes a kernel.
This model was introduced in Warewulf 4.3.0. Previously, Warewulf
This model was introduced in Warewulf v4.3. Previously, Warewulf
managed the kernel and the container separately, which made it hard to
build and distribute containers that have custom drivers and/or
configurations included (e.g. OFED, GPUs, etc.).
@@ -35,12 +34,11 @@ configurations included (e.g. OFED, GPUs, etc.).
Kernel Overrides
================
It is still possible to specify a kernel to a container if it doesn't
It is still possible to specify a kernel for a container if it doesn't
include it's own kernel, or if you wish to override the default kernel
by using the ``kernel override`` capability.
You can specify this option either within the ``nodes.conf`` directly
or via the command line with the ``--kerneloverride`` option to
You can specify this option with the ``--kerneloverride`` option to
``wwctl node set`` or ``wwctl profile set`` commands.
In this case you will also need to import a kernel specifically into
@@ -53,7 +51,7 @@ follows:
4.18.0-305.3.1.el8_4.x86_64: Done
This process will import not only the kernel image itself, but also
all of the kernel modules and firmware associated to this kernel.
all of the kernel modules and firmware associated with this kernel.
Listing All Imported Kernels
----------------------------
@@ -67,5 +65,9 @@ following command:
VNFS NAME NODES
4.18.0-305.3.1.el8_4.x86_64 0
Once a kernel has been imported and showing up in this list you can
configure it to boot compute nodes.
# wwctl kernel list
KERNEL NAME KERNEL VERSION NODES
4.18.0-305.3.1.el8_4.x86_64 0
Once a kernel has been imported you can configure it to boot compute
nodes.

25
userdocs/contents/nodeconfig.rst
View File

@@ -22,7 +22,7 @@ Creating a new node is as simple as running the following command:
.. code-block:: console
# wwctl node add n001 -I 172.16.1.11
# wwctl node add n001 -I 10.0.2.1
Added node: n001
Adding several nodes
@@ -33,18 +33,17 @@ given. An additional IP address will incremented. So the command
.. code-block:: console
# wwctl node add n00[2-4] -I 172.16.1.12
# wwctl node add n00[2-4] -I 10.0.2.2
Added node: n002
Added node: n003
Added node: n004
# wwctl node list -n n00[1-4]
NODE NAME NAME HWADDR IPADDR GATEWAY DEVICE
==========================================================================================
n001 default -- 172.16.1.11 -- (eth0)
n002 default -- 172.16.1.12 -- (eth0)
n003 default -- 172.16.1.13 -- (eth0)
n004 default -- 172.16.1.14 -- (eth0)
n001 default -- 10.0.2.1 -- (eth0)
n002 default -- 10.0.2.2 -- (eth0)
n003 default -- 10.0.2.3 -- (eth0)
n004 default -- 10.0.2.4 -- (eth0)
has added 4 nodes with the incremented IP addresses.
@@ -74,17 +73,15 @@ their attributes as follows:
# wwctl node list
NODE NAME PROFILES NETWORK
================================================================================
n001 default
n001 default
You can also see the node's full attribute list by specifying the
``-a`` option (all):
.. code-block:: bash
.. code-block:: console
# wwctl node list -a n001
NODE FIELD PROFILE VALUE
=====================================================================================
n001 Id -- n001
n001 comment default This profile is automatically included for each node
n001 cluster -- --
@@ -155,7 +152,7 @@ And you can check that the container name is set for ``n001``:
Configuring the Node's Kernel
-----------------------------
While the recommended method for assigning a kernel in 4.3 and beyond
While the recommended method for assigning a kernel in v4.3 and beyond
is to include it in the container / node image, a kernel can still be
specified as an override at the node or profile. To illustrate this,
we import the most recent kernel from a openSUSE Tumbleweed release.
@@ -190,7 +187,7 @@ container, kernel, and network:
.. code-block:: console
# wwctl node list -a n001
=====================================================================================
NODE FIELD PROFILE VALUE
n001 Id -- n001
n001 comment default This profile is automatically included for each node
n001 cluster -- --
@@ -264,7 +261,7 @@ Node Discovery
--------------
The hwaddr of a node can be automatically discovered by setting
`--discoverable` on a node. If a node attempts to provision against
``--discoverable`` on a node. If a node attempts to provision against
Warewulf using an interface that is unknown to Warewulf, that address
is associated with the first discoverable node. (Multiple discoverable
nodes are sorted lexically, first by cluster, then by ID.)

44
userdocs/contents/profiles.rst
View File

@@ -28,7 +28,6 @@ follows:
# wwctl profile list
PROFILE NAME COMMENT/DESCRIPTION
================================================================================
default This profile is automatically included for each node
And with the ``-a`` flag:
@@ -36,25 +35,24 @@ And with the ``-a`` flag:
.. code-block:: console
# wwctl profile list -a
################################################################################
PROFILE NAME FIELD VALUE
default Id default
default Comment This profile is automatically included for each node
default Cluster --
default Container --
default Kernel --
default KernelArgs --
default Init --
default Root --
default RuntimeOverlay --
default SystemOverlay --
default Ipxe --
default IpmiIpaddr --
default IpmiNetmask --
default IpmiPort --
default IpmiGateway --
default IpmiUserName --
default IpmiInterface --
PROFILE FIELD PROFILE VALUE
default Id -- default
default Comment -- This profile is automatically included for each node
default Cluster -- --
default Container -- --
default Kernel -- --
default KernelArgs -- --
default Init -- --
default Root -- --
default RuntimeOverlay -- --
default SystemOverlay -- --
default Ipxe -- --
default IpmiIpaddr -- --
default IpmiNetmask -- --
default IpmiPort -- --
default IpmiGateway -- --
default IpmiUserName -- --
default IpmiInterface -- --
As you can see here, there is only one attribute set by default in
this profile, and that is the "Comment" field. That Comment is
@@ -65,7 +63,6 @@ configuration attribute there:
.. code-block:: console
# wwctl node list -a | head -n 5
################################################################################
NODE FIELD PROFILE VALUE
n0000 Id -- n0000
n0000 Comment default This profile is automatically included for each node
@@ -88,7 +85,6 @@ demonstrate how to use this second profile.
# wwctl profile add test_profile
# wwctl profile list
PROFILE NAME COMMENT/DESCRIPTION
================================================================================
default This profile is automatically included for each node
test_profile --
@@ -115,7 +111,6 @@ And you can now verify that the node has both profile configurations:
.. code-block:: console
# wwctl node list -a | head -n 6
################################################################################
NODE FIELD PROFILE VALUE
n0000 Id -- n0000
n0000 Comment default This profile is automatically included for each node
@@ -134,7 +129,6 @@ configurations. We can also overwrite configurations as follows:
Are you sure you want to modify 1 profile(s): y
# wwctl node list -a | head -n 6
################################################################################
NODE FIELD PROFILE VALUE
n0000 Id -- n0000
n0000 Comment test_profile test comment
@@ -150,7 +144,6 @@ And if we delete the superseded profile attribute from
Are you sure you want to modify 1 profile(s): y
# wwctl node list -a | head -n 6
################################################################################
NODE FIELD PROFILE VALUE
n0000 Id -- n0000
n0000 Comment default This profile is automatically included for each node
@@ -175,7 +168,6 @@ as can be seen here:
Are you sure you want to modify 1 nodes(s): y
# wwctl node list -a | head -n 6
################################################################################
NODE FIELD PROFILE VALUE
n0000 Id -- n0000
n0000 Comment SUPERSEDED This value takes precedent

2
userdocs/contents/setup.rst
View File

@@ -60,7 +60,7 @@ 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
* ``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:

11
userdocs/contents/stateless.rst
View File

@@ -14,9 +14,9 @@ of scale became apparent. Of course in HPC, there are many scalability
factors which needed to be overcome as we continued to scale up
clusters. Pretty early on was the "administrative scaling" which is
the factor that full time systems administrators could only maintain
so many servers. While homogenous configurations were able to help
so many servers. While homogeneous configurations were able to help
that, we still had the problem that every installed server became a
point of administration, version creep, and debugging. The larger the
point of administration, version drift, and debugging. The larger the
cluster, the harder this problem was to solve.
Warewulf was created to help with exactly this.
@@ -40,8 +40,7 @@ management of these systems completely changed the paradigm.
There were several cluster provision and management toolkits already
available when Warewulf was created and while these tools absolutely
helped, there was even more optimization to be had. Stateless
computing.
helped, there was even more optimization to be had.
Why Stateless Provisioning
==========================
@@ -55,8 +54,8 @@ This is Warewulf.
Stateless provisioning is realizing 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 individually is a point of
system administration, but rather the entire cluster, inclusively is
administrated as a single unit.
system administration, but rather the entire cluster is administrated
as a single unit.
If all cluster nodes are booting the same OS image (or set of OS
images), then any individual nodes that have problems is

2
userdocs/contents/wwctl.rst
View File

@@ -6,7 +6,7 @@ Warewulf's command-line interface is based primarily around the
``wwctl`` command. This command has sub-commands for each major
component of Warewulf's functionality.
* ``configure`` configures external services that Warewulf depends on
* ``configure`` configures system services that Warewulf depends on
* ``container`` configures containers (node images)
* ``kernel`` configures override kernels
* ``node`` manages nodes in the cluster

3
userdocs/index.rst
View File

@@ -57,6 +57,3 @@ Welcome to the Warewulf User Guide!
:glob:
reference/*