bootapi/docs/data-model.md

Template data model

Every kickstart and iPXE template is rendered with Go text/template against a single flat value. This is the exact, stable contract template authors code against. It is assembled in internal/render.dataFor from a NetBox device (internal/netbox) plus render-time config (env/Vault).

Kickstart templates (*.ks.tmpl)

Field	Type	Source	Notes
.Hostname	string	NetBox device name	short name, e.g. web01
.Domain	string	NetBox CF domain, else BOOTAPI_DOMAIN
.FQDN	string	derived	Hostname.Domain (or Hostname if no domain)
.Platform	string	NetBox platform slug	e.g. almalinux9 — primary template-selection key
.OSFamily	string	derived from platform	e.g. almalinux
.OSVersion	string	derived from platform	e.g. 9
.Arch	string	fixed x86_64 (today)
.Role	string	NetBox device role slug	e.g. kubernetes-worker
.Interfaces	[]Interface	NetBox interfaces + IPs	primary interface sorted first
.PrimaryInterface	*Interface	derived	the NIC carrying the primary IP (or first)
.PrimaryIP	string	NetBox device primary_ip	address only, no prefix
.Nameservers	[]string	NetBox CF nameservers, else BOOTAPI_NAMESERVERS
.RootPasswordHash	string	render-time (BOOTAPI_ROOT_PASSWORD_HASH[_FILE])	crypt(3) hash; empty ⇒ lock root. Never from NetBox — see security.md
.SSHAuthorizedKeys	[]string	render-time (BOOTAPI_SSH_AUTHORIZED_KEYS)
.PuppetServer	string	BOOTAPI_PUPPET_SERVER	default puppet.k8s.syd1.au.unkin.net
.PuppetCAServer	string	BOOTAPI_PUPPET_CA_SERVER	default puppetca.k8s.syd1.au.unkin.net
.PuppetCAURL	string	BOOTAPI_PUPPET_CA_URL	written to /etc/sysconfig/puppet-initial as PUPPETCA_URL
.BaseURL	string	BOOTAPI_BASE_URL	bootapi's own http URL
.KickstartURL	string	derived	BaseURL/ks/Hostname
.CallbackURL	string	derived	CallbackBaseURL/provisioned/Hostname
.ProvisionToken	string	render-time (BOOTAPI_PROVISION_TOKEN[_FILE])	bearer token the %post callback sends; empty ⇒ callback snippet omitted
.DistroVars	map[string]string	selected catalog entry's evaluated vars	e.g. .DistroVars.mirror (install-tree base); empty when no catalog entry matched
.BootBaseURL	string	BOOTAPI_BOOT_BASE_URL	legacy OS-tree base; empty when catalog-driven
.Custom	map[string]any	all NetBox custom fields, verbatim	escape hatch for site-specific knobs without a code change

Interface

Field	Type	Notes
.Name	string	NetBox interface name, e.g. eth0
.MAC	string	normalized lower-case colon form
.IP	string	address only (empty ⇒ no IP; skip in the network stanza)
.PrefixLen	int	CIDR length, e.g. 24
.Netmask	string	dotted-quad, e.g. 255.255.255.0
.Gateway	string	per-IP CF gateway, else device CF gateway, else empty
.VLAN	int	untagged VLAN id, or 0
.Primary	bool	true for the NIC with the primary IP

iPXE templates (*.ipxe.tmpl)

Rendered with everything above plus:

Field	Type	Notes
.KernelURL	string	from the selected catalog entry's kernel_url (else legacy BootBaseURL/images/pxeboot/vmlinuz)
.InitrdURL	string	catalog initrd_url (else legacy path)
.RepoURL	string	OS install-tree root (KernelURL minus images/pxeboot/vmlinuz); passed as inst.repo=
.KernelArgs	[]string	catalog entry's extra kernel args

The fallback templates (fallback-local, fallback-shell) are rendered with an empty value — they take no host data by design.

NetBox custom fields bootapi reads

Define these on the device (or, where noted, the IP address) in NetBox. All are optional; sensible fallbacks apply.

Custom field	On	Type	Effect
domain	device	text	DNS domain; overrides BOOTAPI_DOMAIN
gateway	device / IP address	text	default gateway (IP-level wins)
nameservers	device	text	comma-separated resolvers; overrides BOOTAPI_NAMESERVERS
provision_template	device	text	force a specific catalog entry / template name
pxe_enabled	device	boolean	gate network install (Cobbler's netboot_enabled). Unset ⇒ treated as enabled. Set false (or let the callback clear it) to boot local disk instead of re-installing.

Distro selection and the catalog

Host → distro is resolved through the distro catalog (catalog/*.yaml in the templates repo / embedded defaults). Each entry names a kickstart template, the kernel/initrd URL templates (artifactapi remotes) and extra kernel args. See template-authoring.md.

Selection precedence (both catalog Select and the kickstart-name fallback):

1. provision_template custom field — exact catalog entry / template name.
2. .Platform slug (e.g. almalinux9) matched against a catalog entry's match.platforms, else a template of that name.
3. .OSFamily (e.g. fedora) matched against match.family, else a template of that name.
4. BOOTAPI_DEFAULT_TEMPLATE (default almalinux9).

The version substituted into the catalog URLs is .OSVersion (the numeric suffix of the platform slug), falling back to the entry's version_default.