Documentation reorg for v4.6.0

Signed-off-by: Jonathon Anderson <janderson@ciq.com>
2025-02-18 16:26:05 -07:00
parent 98695cbbff
commit 9e41378e1c
65 changed files with 3493 additions and 4654 deletions
--- a/userdocs/overlays/templates.rst
+++ b/userdocs/overlays/templates.rst
@@ -0,0 +1,207 @@
+.. _templates:
+
+=========
+Templates
+=========
+
+Templates (denoted in overlays with a ``.ww`` suffix) allow you to create
+dynamic configuration specifically for the node that it is applied to. Templates
+have access to all metadata from the node registry (``nodes.conf``) and much of
+the server configuration (``warewulf.conf``), and can also reference and import
+files from the server file system.
+
+Warewulf uses the ``text/template`` engine to facilitate implementing dynamic
+content. This template format is documented at `pkg.go.dev/text/template.
+<https://pkg.go.dev/text/template>`_
+
+.. note::
+
+   When the template is rendered within a built overlay image, the ``.ww`` will
+   be dropped, so ``/etc/hosts.ww`` will end up being ``/etc/hosts``.
+
+Non-Overlay Templates
+=====================
+
+Most Warewulf templates are included in overlays, but there are a few
+non-overlay templates as well.
+
+* ``/etc/warewulf/ipxe/``: includes iPXE script templates to direct iPXE during
+  the network boot process.
+* ``/etc/warewulf/grub/``: includes GRUB script templates to direct GRUB during
+  the network boot process.
+* ``/usr/share/warewulf/bmc/``: includes templates to generate BMC control
+  commands for the ``wwctl power``, ``wwctl sensor``, and ``wwctl console``
+  commands.
+
+Template functions
+==================
+
+Warewulf templates have access to a number of functions that assist in creating
+more dynamic and expressive templates.
+
+Default functions
+-----------------
+
+``text/template`` includes a number of `default functions
+<https://pkg.go.dev/text/template#hdr-Functions>`_ that are available during
+Warewulf template processing.
+
+Sprig
+-----
+
+Supplementing the default functions, Warewulf templates also have access to
+`Sprig functions.`_
+
+.. _Sprig functions.: https://masterminds.github.io/sprig/
+
+Include
+-------
+
+Reads content from the given file into the template. If the file does not begin
+with ``/`` it is considered relative to ``Paths.Sysconfdir``.
+
+.. code-block::
+
+   {{ Include "/root/.ssh/authorized_keys" }}
+
+IncludeFrom
+-----------
+
+Reads content from the given file from the given image into the template.
+
+.. code-block::
+
+   {{ IncludeFrom $.ImageName "/etc/passwd" }}
+
+IncludeBlock
+------------
+
+Reads content from the given file into the template, stopping when the provided
+abort string is found.
+
+.. code-block::
+  
+   {{ IncludeBlock "/etc/hosts" "# Do not edit after this line" }}
+
+ImportLink
+----------
+
+Causes the processed template file to become a symlink to the same target as the
+referenced symlink.
+
+.. code-block::
+
+   {{ ImportLink "/etc/localtime" }}
+
+basename
+--------
+
+Returns the base name of the given path.
+
+.. code-block::
+
+   {{- range $type, $name := $.Tftp.IpxeBinaries }}
+    if option architecture-type = {{ $type }} {
+        filename "/warewulf/{{ basename $name }}";
+    }
+   {{- end }}
+
+file
+----
+
+Write the content from the template to the specified file name. May be specified
+more than once in a template to write content to multiple files.
+
+.. code-block::
+
+   {{- range $devname, $netdev := .NetDevs }}
+   {{- $filename := print "ifcfg-" $devname ".conf" }}
+   {{ file $filename }}
+   {{/* content here */}}
+   {{- end }}
+
+softlink
+--------
+
+Causes the processed template file to become a symlink to the referenced target.
+
+.. code-block::
+  
+   {{ printf "%s/%s" "/usr/share/zoneinfo" .Tags.localtime | softlink }}
+
+readlink
+--------
+
+Equivalent to ``filepath.EvalSymlinks``. Returns the target path of a named
+symlink.
+
+.. code-block::
+
+   {{ readlink /etc/localtime }}
+
+IgnitionJson
+------------
+
+Generates JSON suitable for use by Ignition to create 
+
+abort
+-----
+
+Immediately aborts processing the template and does not write a file.
+
+.. code-block::
+  
+   {{ abort }}
+
+nobackup
+--------
+
+   Disables the creation of a backup file when replacing files with the current
+   template.
+
+.. code-block::
+
+   {{ nobackup }}
+
+UniqueField
+-----------
+
+UniqueField returns a filtered version of a multi-line input string. input is
+expected to be a field-separated format with one record per line (terminated by
+`\n`). Order of lines is preserved, with the first matching line taking
+precedence.
+
+For example, the following template snippet has been used in the ``syncuser`` overlay
+to generate a combined ``/etc/passwd``.
+
+.. code-block::
+
+   {{
+       printf "%s\n%s" 
+           (IncludeFrom $.ImageName "/etc/passwd" | trim)
+           (Include (printf "%s/%s" .Paths.Sysconfdir "passwd") | trim)
+       | UniqueField ":" 0 | trim
+   }}
+
+Examples
+========
+
+Many example templates are included in the distribution overlays. The ``debug``
+template also includes a ``tstruct.ww`` template that includes much of the
+available metadata.
+
+.. code-block:: shell
+
+   wwctl overlay show debug tstruct.ww
+   wwctl overlay show debug tstruct.ww --render=n1
+
+Node-Specific Files
+-------------------
+
+Sometimes there is the need to have specific files for each cluster node which
+can't be generated by a template (e.g., a per-node Kerberos keytab). You can
+include these files with following template:
+
+.. code-block::
+
+   {{ Include (printf "/srv/%s/%s" .Id "payload") }}