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

Improved template variables debug template and documentation

Browse Source 
- Closes #1097

Signed-off-by: Jonathon Anderson <janderson@ciq.com>
This commit is contained in:
Jonathon Anderson
2025-01-20 09:56:17 -07:00
parent 803e65e9c1
commit ef376e97de
3 changed files with 198 additions and 307 deletions
Download Patch File Download Diff File Expand all files Collapse all files

276
overlays/debug/internal/debug_test.go
View File

@@ -20,7 +20,7 @@ func Test_debugOverlay(t *testing.T) {
env := testenv.New(t)
defer env.RemoveAll()
env.ImportFile("etc/warewulf/nodes.conf", "nodes.conf")
env.ImportFile("var/lib/warewulf/overlays/debug/rootfs/warewulf/template-variables.md.ww", "../rootfs/warewulf/template-variables.md.ww")
env.ImportFile("var/lib/warewulf/overlays/debug/rootfs/tstruct.md.ww", "../rootfs/tstruct.md.ww")
tests := []struct {
name string
@@ -29,7 +29,7 @@ func Test_debugOverlay(t *testing.T) {
}{
{
name: "debug",
args: []string{"--render", "node1", "debug", "warewulf/template-variables.md.ww"},
args: []string{"--render", "node1", "debug", "tstruct.md.ww"},
log: debug,
},
}
@@ -55,80 +55,20 @@ func Test_debugOverlay(t *testing.T) {
const debug = `backupFile: true
writeFile: true
Filename: warewulf/template-variables.md
# Warewulf template variables
Filename: tstruct.md
# Warewulf template struct (tstruct)
This Warewulf template serves as a complete example of the variables
available to Warewulf templates. It may also be rendered against a
node to debug its apparent configuration.
wwctl overlay show --render $nodename debug /warewulf/template-variables.md.ww
wwctl overlay show --render $nodename debug tstruct.md.ww
The template data structure is defined in
internal/pkg/overlay/datastructure.go, though it also references
data from other structures.
## Node
- Id: node1
- Hostname: node1
- Comment:
- ClusterName:
- ImageName: rockylinux-9
- Ipxe: default
- RuntimeOverlay: hosts,ssh.authorized_keys,syncuser
- SystemOverlay: wwinit,wwclient,fstab,hostname,ssh.host_keys,issue,resolv,udev.netname,systemd.netname,ifcfg,NetworkManager,debian.interfaces,wicked,ignition
- Init: /sbin/init
- Root: initramfs
- AssetKey:
- Discoverable:
- Profiles: default
- Tags:
- Kernel:
- Version:
- Args: quiet crashkernel=no vga=791 net.naming-scheme=v238
- Ipmi:
- UserName: user
- Password: password
- Ipaddr: 192.168.4.21
- Netmask: 255.255.255.0
- Port:
- Gateway: 192.168.4.1
- Interface:
- Write: true
- Tags:
- NetDevs[default]:
- Type:
- OnBoot: true
- Device: wwnet0
- Hwaddr: e6:92:39:49:7b:03
- Ipaddr: 192.168.3.21
- Ipaddr6: <nil>
- Prefix: <nil>
- Netmask: 255.255.255.0
- Gateway: 192.168.3.1
- MTU:
- Primary: false
- Tags:
- NetDevs[secondary]:
- Type:
- OnBoot: true
- Device: wwnet1
- Hwaddr: 9a:77:29:73:14:f1
- Ipaddr: 192.168.3.22
- Ipaddr6: <nil>
- Prefix: <nil>
- Netmask: 255.255.255.0
- Gateway: 192.168.3.1
- MTU:
- Primary: false
- Tags: DNS1=8.8.8.8 DNS2=8.8.4.4
## Build variables
## Build
- BuildHost: %HOSTNAME%
- BuildTime: REMOVED_BY_TEST
@@ -136,8 +76,16 @@ data from other structures.
- BuildSource: REMOVED_BY_TEST
- Overlay: debug
## Warewulf server
## Network
- Port: 9873
- Secure: true
- UpdateInterval: 60
- AutobuildOverlays: true
- EnableHostOverlay: true
- Syslog: false
### Network
- Ipaddr:
- Ipaddr6:
@@ -146,9 +94,6 @@ data from other structures.
- NetworkCIDR:
- Ipv6: false
## Services
### DHCP
- Dhcp.Enabled: true
@@ -157,7 +102,6 @@ data from other structures.
- Dhcp.RangeEnd:
- Dhcp.SystemdName: dhcpd
### NFS
- Enabled: true
@@ -171,117 +115,91 @@ data from other structures.
- ed25519
- First key type: rsa
### Warewulf
## Node
- Port: 9873
- Secure: true
- UpdateInterval: 60
- AutobuildOverlays: true
- EnableHostOverlay: true
- Syslog: false
The current node may also be accessed as .ThisNode, which provides access to
node methods in addition to its fields.
- Id: node1
- Hostname: node1
- Comment:
- ClusterName:
- ImageName: rockylinux-9
- Ipxe: default
- RuntimeOverlay:
- hosts
- ssh.authorized_keys
- syncuser
- SystemOverlay:
- wwinit
- wwclient
- fstab
- hostname
- ssh.host_keys
- issue
- resolv
- udev.netname
- systemd.netname
- ifcfg
- NetworkManager
- debian.interfaces
- wicked
- ignition
- Init: /sbin/init
- Root: initramfs
- AssetKey:
- Discoverable:
- Profiles:
- default
- Tags:
- Kernel:
- Version:
- Args: quiet crashkernel=no vga=791 net.naming-scheme=v238
- Ipmi:
- UserName: user
- Password: password
- Ipaddr: 192.168.4.21
- Netmask: 255.255.255.0
- Port:
- Gateway: 192.168.4.1
- Interface:
- Write: true
- Tags:
- NetDevs[default]:
- Type:
- OnBoot: true
- Device: wwnet0
- Hwaddr: e6:92:39:49:7b:03
- Ipaddr: 192.168.3.21
- Ipaddr6: <nil>
- Prefix: <nil>
- Netmask: 255.255.255.0
- Gateway: 192.168.3.1
- MTU:
- Primary: false
- Tags:
- NetDevs[secondary]:
- Type:
- OnBoot: true
- Device: wwnet1
- Hwaddr: 9a:77:29:73:14:f1
- Ipaddr: 192.168.3.22
- Ipaddr6: <nil>
- Prefix: <nil>
- Netmask: 255.255.255.0
- Gateway: 192.168.3.1
- MTU:
- Primary: false
- Tags:
- DNS1=8.8.8.8
- DNS2=8.8.4.4
### Other nodes
## Other nodes
- AllNodes[0]:
- Id: node1
- Comment:
- ClusterName:
- ImageName: rockylinux-9
- Ipxe: default
- RuntimeOverlay: [hosts ssh.authorized_keys syncuser]
- SystemOverlay: [wwinit wwclient fstab hostname ssh.host_keys issue resolv udev.netname systemd.netname ifcfg NetworkManager debian.interfaces wicked ignition]
- Root: initramfs
- Discoverable:
- Init: /sbin/init
- AssetKey:
- Profiles: [default]
- Tags:
- Kernel
- Version:
- Args: quiet crashkernel=no vga=791 net.naming-scheme=v238
- Ipmi:
- Ipaddr: 192.168.4.21
- Netmask: 255.255.255.0
- Port:
- Gateway: 192.168.4.1
- UserName: user
- Password: password
- Interface:
- Write: true
- Tags:
- NetDevs[default]:
- Type:
- OnBoot: true
- Device: wwnet0
- Hwaddr: e6:92:39:49:7b:03
- Ipaddr: 192.168.3.21
- IpCIDR: 192.168.3.21/24
- Ipaddr6: <nil>
- Prefix: <nil>
- Netmask: 255.255.255.0
- Gateway: 192.168.3.1
- MTU:
- Primary: true
- Tags:
- NetDevs[secondary]:
- Type:
- OnBoot: true
- Device: wwnet1
- Hwaddr: 9a:77:29:73:14:f1
- Ipaddr: 192.168.3.22
- IpCIDR: 192.168.3.22/24
- Ipaddr6: <nil>
- Prefix: <nil>
- Netmask: 255.255.255.0
- Gateway: 192.168.3.1
- MTU:
- Primary: false
- Tags: DNS1=8.8.8.8 DNS2=8.8.4.4
- AllNodes[1]:
- Id: node2
- Comment:
- ClusterName:
- ImageName:
- Ipxe: default
- RuntimeOverlay: [hosts ssh.authorized_keys syncuser]
- SystemOverlay: [wwinit wwclient fstab hostname ssh.host_keys issue resolv udev.netname systemd.netname ifcfg NetworkManager debian.interfaces wicked ignition]
- Root: initramfs
- Discoverable:
- Init: /sbin/init
- AssetKey:
- Profiles: [default]
- Tags:
- Kernel
- Version:
- Args: quiet crashkernel=no vga=791 net.naming-scheme=v238
- Ipmi:
- Ipaddr: <nil>
- Netmask: <nil>
- Port:
- Gateway: <nil>
- UserName:
- Password:
- Interface:
- Write:
- Tags:
- NetDevs[default]:
- Type:
- OnBoot: true
- Device: wwnet0
- Hwaddr: e6:92:39:49:7b:04
- Ipaddr: 192.168.3.23
- IpCIDR: 192.168.3.23/24
- Ipaddr6: <nil>
- Prefix: <nil>
- Netmask: 255.255.255.0
- Gateway: 192.168.3.1
- MTU:
- Primary: true
- Tags:
All nodes in the registry are available to all templates in the .AllNodes
field. Each node provides access to all node fields, as shown above.
- AllNodes:
- node1
- node2
`

214
overlays/debug/rootfs/warewulf/template-variables.md.ww → overlays/debug/rootfs/tstruct.md.ww
View File

@@ -1,38 +1,103 @@
# Warewulf template variables
# Warewulf template struct (tstruct)
This Warewulf template serves as a complete example of the variables
available to Warewulf templates. It may also be rendered against a
node to debug its apparent configuration.
wwctl overlay show --render $nodename debug /warewulf/template-variables.md.ww
wwctl overlay show --render $nodename debug tstruct.md.ww
The template data structure is defined in
internal/pkg/overlay/datastructure.go, though it also references
data from other structures.
## Build
- BuildHost: {{ .BuildHost }}
- BuildTime: {{ .BuildTime }}
- BuildTimeUnix: {{ .BuildTimeUnix }}
- BuildSource: {{ .BuildSource }}
- Overlay: {{ .Overlay }}
## Warewulf server
- Port: {{ .Warewulf.Port }}
- Secure: {{ .Warewulf.Secure }}
- UpdateInterval: {{ .Warewulf.UpdateInterval }}
- AutobuildOverlays: {{ .Warewulf.AutobuildOverlays }}
- EnableHostOverlay: {{ .Warewulf.EnableHostOverlay }}
- Syslog: {{ .Warewulf.Syslog }}
### Network
- Ipaddr: {{ .Ipaddr }}
- Ipaddr6: {{ .Ipaddr6 }}
- Netmask: {{ .Netmask }}
- Network: {{ .Network }}
- NetworkCIDR: {{ .NetworkCIDR }}
- Ipv6: {{ .Ipv6 }}
### DHCP
- Dhcp.Enabled: {{ .Dhcp.Enabled }}
- Dhcp.Template: {{ .Dhcp.Template }}
- Dhcp.RangeStart: {{ .Dhcp.RangeStart }}
- Dhcp.RangeEnd: {{ .Dhcp.RangeEnd }}
- Dhcp.SystemdName: {{ .Dhcp.SystemdName }}
### NFS
- Enabled: {{ .Nfs.Enabled }}
- SystemdName: {{ .Nfs.SystemdName }}
{{- range $index, $export := .Nfs.ExportsExtended }}
- ExportsExtended[{{ $index }}]:
- Path: {{ $export.Path }}
- ExportOptions: {{ $export.ExportOptions }}
{{- end }}
### SSH
{{- if gt (len .Ssh.KeyTypes) 0 }}
- Key types:
{{- range $index, $keyType := .Ssh.KeyTypes }}
- {{ $keyType }}
{{- end }}
- First key type: {{ index .Ssh.KeyTypes 0 }}
{{- end }}
## Node
The current node may also be accessed as .ThisNode, which provides access to
node methods in addition to its fields.
- Id: {{ .Id }}
- Hostname: {{ .Hostname }}
- Comment: {{ .Comment }}
- ClusterName: {{ .ClusterName }}
- ImageName: {{ .ImageName }}
- Ipxe: {{ .Ipxe }}
- RuntimeOverlay: {{ range $index, $value := .RuntimeOverlay }}{{ if $index }},{{ end }}{{ $value }}{{ end }}
- SystemOverlay: {{ range $index, $value := .SystemOverlay }}{{ if $index }},{{ end }}{{ $value }}{{ end }}
- RuntimeOverlay:
{{- range $index, $value := .RuntimeOverlay }}
- {{ $value }}
{{- end }}
- SystemOverlay:
{{- range $index, $value := .SystemOverlay }}
- {{ $value }}
{{- end }}
- Init: {{ .Init }}
- Root: {{ .Root }}
- AssetKey: {{ .AssetKey }}
- Discoverable: {{ .Discoverable }}
- Profiles: {{ range $index, $value := .Profiles }}{{ if $index }},{{ end }}{{ $value }}{{ end }}
- Tags: {{ range $key, $value := .Tags }}{{ $key }}={{ $value }} {{ end }}
{{ if .Kernel }}
- Profiles:
{{- range $index, $value := .Profiles }}
- {{ $value }}
{{- end }}
- Tags:
{{- range $key, $value := .Tags }}
- {{ $key }}={{ $value }}
{{- end }}
- Kernel:
- Version: {{ .Kernel.Version }}
- Args: {{ .Kernel.Args }}
{{- end }}
{{ if .Ipmi }}
- Ipmi:
- UserName: {{ .Ipmi.UserName }}
- Password: {{ .Ipmi.Password }}
@@ -42,8 +107,10 @@ data from other structures.
- Gateway: {{ .Ipmi.Gateway }}
- Interface: {{ .Ipmi.Interface }}
- Write: {{ .Ipmi.Write }}
- Tags: {{ range $key, $value := .Ipmi.Tags }}{{ $key }}={{ $value }} {{ end }}
{{- end }}
- Tags:
{{- range $key, $value := .Ipmi.Tags }}
- {{ $key }}={{ $value }}
{{ end }}
{{- range $index, $netdev := .NetDevs }}
- NetDevs[{{ $index }}]:
- Type: {{ $netdev.Type }}
@@ -57,120 +124,21 @@ data from other structures.
- Gateway: {{ $netdev.Gateway }}
- MTU: {{ $netdev.MTU }}
- Primary: {{ $netdev.Primary }}
- Tags: {{ range $key, $value := $netdev.Tags }}{{ $key }}={{ $value }} {{ end }}
- Tags:
{{- range $key, $value := $netdev.Tags }}
- {{ $key }}={{ $value }}
{{- end }}
{{- end }}
{{- range $key, $value := .Resources }}
- Resource[{{$key}}]: {{ $value }}
{{- end }}
## Other nodes
## Build variables
All nodes in the registry are available to all templates in the .AllNodes
field. Each node provides access to all node fields, as shown above.
- BuildHost: {{ .BuildHost }}
- BuildTime: {{ .BuildTime }}
- BuildTimeUnix: {{ .BuildTimeUnix }}
- BuildSource: {{ .BuildSource }}
- Overlay: {{ .Overlay }}
## Network
- Ipaddr: {{ .Ipaddr }}
- Ipaddr6: {{ .Ipaddr6 }}
- Netmask: {{ .Netmask }}
- Network: {{ .Network }}
- NetworkCIDR: {{ .NetworkCIDR }}
- Ipv6: {{ .Ipv6 }}
## Services
### DHCP
- Dhcp.Enabled: {{ .Dhcp.Enabled }}
- Dhcp.Template: {{ .Dhcp.Template }}
- Dhcp.RangeStart: {{ .Dhcp.RangeStart }}
- Dhcp.RangeEnd: {{ .Dhcp.RangeEnd }}
- Dhcp.SystemdName: {{ .Dhcp.SystemdName }}
### NFS
- Enabled: {{ .Nfs.Enabled }}
- SystemdName: {{ .Nfs.SystemdName }}
{{- range $index, $export := .Nfs.ExportsExtended }}
- ExportsExtended[{{ $index }}]:
- Path: {{ $export.Path }}
- ExportOptions: {{ $export.ExportOptions }}
- MountOptions: {{ $export.MountOptions }}
- Mount: {{ $export.Mount }}
- AllNodes:
{{- range $index, $node := .AllNodes }}
- {{ $node.Id }}
{{- end }}
### SSH
{{- if gt (len .Ssh.KeyTypes) 0 }}
- Key types:
{{- range $index, $keyType := .Ssh.KeyTypes }}
- {{ $keyType }}
{{- end }}
- First key type: {{ index .Ssh.KeyTypes 0 }}
{{- end }}
### Warewulf
- Port: {{ .Warewulf.Port }}
- Secure: {{ .Warewulf.Secure }}
- UpdateInterval: {{ .Warewulf.UpdateInterval }}
- AutobuildOverlays: {{ .Warewulf.AutobuildOverlays }}
- EnableHostOverlay: {{ .Warewulf.EnableHostOverlay }}
- Syslog: {{ .Warewulf.Syslog }}
### Other nodes
{{ range $index, $node := .AllNodes -}}
- AllNodes[{{ $index }}]:
- Id: {{ $node.Id }}
- Comment: {{ $node.Comment }}
- ClusterName: {{ $node.ClusterName }}
- ImageName: {{ $node.ImageName }}
- Ipxe: {{ $node.Ipxe }}
- RuntimeOverlay: {{ $node.RuntimeOverlay }}
- SystemOverlay: {{ $node.SystemOverlay }}
- Root: {{ $node.Root }}
- Discoverable: {{ $node.Discoverable }}
- Init: {{ $node.Init }}
- AssetKey: {{ $node.AssetKey }}
- Profiles: {{ $node.Profiles }}
- Tags: {{ range $key, $value := $node.Tags }}{{ $key }}={{ $value }} {{ end }}
{{ if .Kernel }}
- Kernel
- Version: {{ $node.Kernel.Version }}
- Args: {{ $node.Kernel.Args }}
{{- end }}
{{ if .Ipmi }}
- Ipmi:
- Ipaddr: {{ $node.Ipmi.Ipaddr }}
- Netmask: {{ $node.Ipmi.Netmask }}
- Port: {{ $node.Ipmi.Port }}
- Gateway: {{ $node.Ipmi.Gateway }}
- UserName: {{ $node.Ipmi.UserName }}
- Password: {{ $node.Ipmi.Password }}
- Interface: {{ $node.Ipmi.Interface }}
- Write: {{ $node.Ipmi.Write }}
- Tags: {{ range $key, $value := $node.Ipmi.Tags }}{{ $key }}={{ $value }} {{ end }}
{{- end }}
{{- range $index, $netdev := $node.NetDevs }}
- NetDevs[{{ $index }}]:
- Type: {{ $netdev.Type }}
- OnBoot: {{ $netdev.OnBoot }}
- Device: {{ $netdev.Device }}
- Hwaddr: {{ $netdev.Hwaddr }}
- Ipaddr: {{ $netdev.Ipaddr }}
- IpCIDR: {{ $netdev.IpCIDR }}
- Ipaddr6: {{ $netdev.Ipaddr6 }}
- Prefix: {{ $netdev.Prefix }}
- Netmask: {{ $netdev.Netmask }}
- Gateway: {{ $netdev.Gateway }}
- MTU: {{ $netdev.MTU }}
- Primary: {{ $netdev.Primary }}
- Tags: {{ range $key, $value := $netdev.Tags }}{{ $key }}={{ $value }} {{ end }}
{{- end }}
{{ end }}

15
userdocs/contents/overlays.rst
View File

@@ -169,9 +169,13 @@ The **ignition** overlay defines partitions and file systems on local disks.
debug
-----
The **debug** overlay is not intended to be used in configuration, but can be
used as an example and applied with ``wwctl overlay show --render <nodename>
debug /warewulf/template-variables.md.ww``.
The **debug** overlay is not intended to be used in configuration, but is
provided as an example. In particular, the provided `tstruct.md.ww` demonstrates
the use of most available template metadata.
.. code-block:: console
# wwctl overlay show --render <nodename> debug tstruct.md.ww
host
----
@@ -220,8 +224,9 @@ downloaded for each node will be customized for that node. Templates
allow you to insert everything from variables, to including files from
the control node, as well as conditional content and loops.
Warewulf uses the ``text/template`` engine to facilitate implementing
dynamic content in a simple and standardized manner.
Warewulf uses the ``text/template`` engine to facilitate implementing dynamic
content in a simple and standardized manner. This template format is documented
at https://pkg.go.dev/text/template.
All template files will end with the suffix of ``.ww``. That tells
Warewulf that when building a file, that it should parse that file as