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

feat(docs): New documentation

Browse Source 
Convert docs to mkdocs, move back into repo, publish to repo
This commit is contained in:
Brian Clemens
2022-09-15 21:00:17 +09:00
committed by GitHub
parent 8c0710e412
commit 04ee8cc967
34 changed files with 2482 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

127
userdocs/quickstart/el7.rst Normal file
View File

@@ -0,0 +1,127 @@
================================
EL7 Quickstart (CentOS and RHEL)
================================
Install Warewulf and dependencies
=================================
.. code-block:: bash
sudo yum install -y golang tftp-server dhcp nfs-utils
git clone https://github.com/hpcng/warewulf.git
cd warewulf
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 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
warewulf:
port: 9873
secure: false
update interval: 60
dhcp:
enabled: true
range start: 192.168.200.10
range end: 192.168.200.99
template: default
systemd name: dhcpd
tftp:
enabled: true
tftproot: /var/lib/tftpboot
systemd name: tftp
nfs:
systemd name: nfs-server
exports:
- /home
- /var/warewulf
.. 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 VNFS container and kernel
============================================
This will pull a basic VNFS container from Docker Hub and import the default running kernel from the controller node and set both in the "default" node profile.
.. code-block:: bash
sudo wwctl container import docker://warewulf/centos-7 centos-7 --setdefault
sudo wwctl kernel import $(uname -r) --setdefault
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 default -K $(uname -r) -C centos-7
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
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 --netname default -I 192.168.200.100 --discoverable
sudo wwctl node list -a n0000
Turn on your compute node and watch it boot!

151
userdocs/quickstart/el8.rst Normal file
View File

@@ -0,0 +1,151 @@
=====================================
EL8 Quickstart (Rocky Linux and RHEL)
=====================================
Install Warewulf and dependencies
=================================
.. code-block:: bash
sudo dnf groupinstall "Development Tools"
sudo dnf install epel-release
sudo dnf install golang tftp-server dhcp-server nfs-utils
git clone https://github.com/hpcng/warewulf.git
cd warewulf
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 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
warewulf:
port: 9873
secure: false
update interval: 60
dhcp:
enabled: true
range start: 192.168.200.10
range end: 192.168.200.99
template: default
systemd name: dhcpd
tftp:
enabled: true
tftproot: /var/lib/tftpboot
systemd name: tftp
nfs:
systemd name: nfs-server
exports:
- /home
- /var/warewulf
.. 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 VNFS container (including the kernel)
========================================================
This will pull a basic VNFS container from Docker Hub and import the default running
kernel from the controller node and set both in the "default" node profile.
.. code-block:: bash
sudo wwctl container import docker://warewulf/rocky:8 rocky-8
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 container we just imported above to the ``default`` node profile:
.. code-block:: bash
sudo wwctl profile set --yes --container rocky-8 "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
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
Turn on your compute node and watch it boot!

183
userdocs/quickstart/suse15.rst Normal file
View File

@@ -0,0 +1,183 @@
====================================
openSUSE Leap and SLES 15 Quickstart
====================================
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/hpcng/warewulf.git
cd warewulf
PREFIX=/usr SYSCONFDIR=/etc TFTPDIR=/srv/tftproot LOCALSTATEDIR=/var/lib make genconfig
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
warewulf:
port: 9873
secure: false
update interval: 60
autobuild overlays: true
host overlay: true
dhcp:
enabled: true
range start: 192.168.200.10
range end: 192.168.200.99
template: default
systemd name: dhcpd
tftp:
enabled: true
tftproot: /var/lib/tftpboot
systemd name: tftp
nfs:
enabled: true
export paths:
- path: /home
export options: rw,sync
mount options: defaults
mount: true
- path: /opt
export options: ro,sync,no_root_squash
mount options: defaults
mount: false
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.
.. 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 VNFS container and kernel
============================================
This will pull a basic VNFS container from Docker Hub and import the default running
kernel from the controller node and set both in the "default" node profile.
.. code-block:: bash
$ sudo wwctl container import docker://registry.opensuse.org/science/warewulf/leap-15.4/containers/kernel:latest leap15.4 --setdefault
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 -I 192.168.200.100 --discoverable
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 provisioned after the node has booted and 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!