Skip to content

Commit

Permalink
Update main docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@actions-user
actions-user committed Feb 17, 2024
1 parent 9602817 commit 61c57b2
Show file tree
Hide file tree
Showing 22 changed files with 268 additions and 290 deletions.
48 changes: 26 additions & 22 deletions static/docs/main/_sources/contents/configuration.rst.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
==========
Expand All @@ -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:
Expand Down
20 changes: 10 additions & 10 deletions static/docs/main/_sources/contents/containers.rst.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
===============
Expand Down
6 changes: 3 additions & 3 deletions static/docs/main/_sources/contents/initialization.rst.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.

Expand Down
60 changes: 29 additions & 31 deletions static/docs/main/_sources/contents/installation.rst.txt
View file
Original file line number Diff line number Diff line change
@@ -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
===========
Expand Down Expand Up @@ -49,50 +49,48 @@ 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
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
Expand Down
30 changes: 16 additions & 14 deletions static/docs/main/_sources/contents/kernel.rst.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -19,28 +19,26 @@ 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.).

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
Expand All @@ -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
----------------------------
Expand All @@ -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 changes: 11 additions & 14 deletions static/docs/main/_sources/contents/nodeconfig.rst.txt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.

Expand Down Expand Up @@ -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 -- --
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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 -- --
Expand Down Expand Up @@ -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.)
Expand Down
Loading

0 comments on commit 61c57b2

Please sign in to comment.