diff --git a/overlays/debug/internal/debug_test.go b/overlays/debug/internal/debug_test.go index d87fa782..5c4d3da9 100644 --- a/overlays/debug/internal/debug_test.go +++ b/overlays/debug/internal/debug_test.go @@ -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: - - Prefix: - - 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: - - Prefix: - - 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: + - Prefix: + - 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: + - Prefix: + - 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: - - Prefix: - - 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: - - Prefix: - - 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: - - Netmask: - - Port: - - Gateway: - - 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: - - Prefix: - - 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 ` diff --git a/overlays/debug/rootfs/warewulf/template-variables.md.ww b/overlays/debug/rootfs/tstruct.md.ww similarity index 51% rename from overlays/debug/rootfs/warewulf/template-variables.md.ww rename to overlays/debug/rootfs/tstruct.md.ww index f3c39325..963fbdba 100644 --- a/overlays/debug/rootfs/warewulf/template-variables.md.ww +++ b/overlays/debug/rootfs/tstruct.md.ww @@ -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 }} diff --git a/userdocs/contents/overlays.rst b/userdocs/contents/overlays.rst index 90bfeb5b..44d3ef8d 100644 --- a/userdocs/contents/overlays.rst +++ b/userdocs/contents/overlays.rst @@ -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 -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 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