From 5757162b764f2d2cd33f0a9c06bd01944ab969f8 Mon Sep 17 00:00:00 2001
From: griznog <griznog@gmail.com>
Date: Thu, 23 May 2024 16:35:27 -0700
Subject: [PATCH] Parallel overlay building examples.

---
 CHANGELOG.md                   |  1 +
 userdocs/contents/overlays.rst | 16 ++++++++++++++++
 2 files changed, 17 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index e682910c7..31ed00884 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,6 +8,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ### Added
 
+- Add examples for building overlays in parallel to documentation
 - Add the ability to boot nodes with `wwid=[interface]`, which replaces
   `interface` with the interface MAC address
 - Added https://github.com/Masterminds/sprig functions to templates #1030
diff --git a/userdocs/contents/overlays.rst b/userdocs/contents/overlays.rst
index fb3d10e2e..528e31728 100644
--- a/userdocs/contents/overlays.rst
+++ b/userdocs/contents/overlays.rst
@@ -162,6 +162,22 @@ built. Specific overlays can be selected with ``-O`` flag. For
 debugging purposes the templates can be written to a directory given
 via the ``-o`` flag.
 
+On clusters with large numbers of nodes a significant speedup can be achieved
+by building overlays in parallel. Adding parallel overlay building to `wwctl`
+is planned, see issue `#1087 <https://github.com/warewulf/warewulf/issues/1087>`_.
+Until parallel overlay building is implemented, builds can be easily done in 
+parallel with Gnu `parallel` or `xargs`, for example:
+
+.. code-block:: console
+
+  # Gnu parallel
+  wwctl node list | awk '{print $1}' | grep -v "NODE " | parallel -j 12 \
+    wwctl overlay build -N {}
+
+  # xargs
+  wwctl node list | awk '{print $1}' | grep -v "NODE " | xargs -n 1 -P 12 \
+    wwctl overlay build -N
+
 By default Warewulf will build/update and cache overlays as needed
 (configurable in the ``warewulf.conf``).