Initial bootapi: NetBox-driven PXE/kickstart boot service
bootapi replaces Cobbler's PXE/kickstart side. It resolves a PXE-booting host
from NetBox (by MAC or hostname), renders an iPXE boot script and a kickstart
from Go text/templates, and serves them over HTTP. The ENC half already moved to
encapi; this covers the provisioning/boot half.
What's here:
- cmd/bootapi + internal/{config,model,netbox,render,server}; embedded default
templates under templates/ (AlmaLinux 9 + Fedora kickstarts, iPXE boot +
unknown-MAC fallbacks) ported from Cobbler's boot/bootstrap contract.
- NetBox client (v4.x API) behind a Resolver interface with a short-TTL cache;
tested against httptest fixtures using real NetBox JSON shapes.
- chi HTTP server: /ipxe/{mac}, /boot/ipxe?mac=, /ks/{ident}, healthz/readyz,
Prometheus /metrics. Unknown MAC -> safe fallback iPXE (200), unknown KS -> 404.
- Secrets (root pw hash, ssh keys) injected at render time from env/Vault, never
NetBox. Config is env-based per estate convention.
- Makefile (build/test/lint/docker + patch/minor/major), Dockerfile (distroless),
.woodpecker (pre-commit, golangci-lint v2 + go test -race, docker build on PR;
image push + Gitea binary release on v* tag), docs/ and example config.
go build/vet clean, go test -race green, golangci-lint v2 clean, pre-commit clean.
Claude-Session: https://claude.ai/code/session_015ur3i7D2azsMAWTSVABApv
This commit is contained in:
@@ -0,0 +1,423 @@
|
||||
// Package netbox resolves a PXE-booting machine (by MAC or hostname) into the
|
||||
// normalized model.Host that bootapi renders templates against. It talks to the
|
||||
// NetBox REST API (v4.x) behind the Resolver interface so the server can be
|
||||
// tested with an httptest fake.
|
||||
package netbox
|
||||
|
||||
import (
|
||||
"context"
|
||||
"crypto/tls"
|
||||
"encoding/json"
|
||||
"errors"
|
||||
"fmt"
|
||||
"net"
|
||||
"net/http"
|
||||
"net/url"
|
||||
"strings"
|
||||
"time"
|
||||
|
||||
"git.unkin.net/unkin/bootapi/internal/model"
|
||||
)
|
||||
|
||||
// ErrNotFound is returned when NetBox has no device matching the query. The
|
||||
// server maps it to an HTTP 404 (and, for iPXE, a safe fallback boot script).
|
||||
var ErrNotFound = errors.New("netbox: device not found")
|
||||
|
||||
// Resolver turns a MAC or hostname into a fully-resolved Host.
|
||||
type Resolver interface {
|
||||
HostByMAC(ctx context.Context, mac string) (*model.Host, error)
|
||||
HostByName(ctx context.Context, name string) (*model.Host, error)
|
||||
}
|
||||
|
||||
// Client is the HTTP-backed Resolver.
|
||||
type Client struct {
|
||||
baseURL string
|
||||
token string
|
||||
http *http.Client
|
||||
}
|
||||
|
||||
// Options configures a Client.
|
||||
type Options struct {
|
||||
BaseURL string
|
||||
Token string
|
||||
Timeout time.Duration
|
||||
Insecure bool
|
||||
// HTTPClient overrides the constructed client (used by tests).
|
||||
HTTPClient *http.Client
|
||||
}
|
||||
|
||||
// New builds a NetBox Client.
|
||||
func New(o Options) *Client {
|
||||
hc := o.HTTPClient
|
||||
if hc == nil {
|
||||
tr := &http.Transport{}
|
||||
if o.Insecure {
|
||||
tr.TLSClientConfig = &tls.Config{InsecureSkipVerify: true} //nolint:gosec // opt-in dev flag
|
||||
}
|
||||
timeout := o.Timeout
|
||||
if timeout == 0 {
|
||||
timeout = 5 * time.Second
|
||||
}
|
||||
hc = &http.Client{Timeout: timeout, Transport: tr}
|
||||
}
|
||||
return &Client{
|
||||
baseURL: strings.TrimRight(o.BaseURL, "/"),
|
||||
token: o.Token,
|
||||
http: hc,
|
||||
}
|
||||
}
|
||||
|
||||
// --- NetBox API JSON shapes (only the fields bootapi consumes) ---
|
||||
|
||||
type nbList[T any] struct {
|
||||
Count int `json:"count"`
|
||||
Results []T `json:"results"`
|
||||
}
|
||||
|
||||
type nbRef struct {
|
||||
ID int `json:"id"`
|
||||
Name string `json:"name"`
|
||||
Slug string `json:"slug"`
|
||||
}
|
||||
|
||||
type nbVLAN struct {
|
||||
VID int `json:"vid"`
|
||||
Name string `json:"name"`
|
||||
}
|
||||
|
||||
type nbMAC struct {
|
||||
MACAddress string `json:"mac_address"`
|
||||
}
|
||||
|
||||
type nbDevice struct {
|
||||
ID int `json:"id"`
|
||||
Name string `json:"name"`
|
||||
Platform *nbRef `json:"platform"`
|
||||
Role *nbRef `json:"role"`
|
||||
Site *nbRef `json:"site"`
|
||||
PrimaryIP *nbIPRef `json:"primary_ip"`
|
||||
CustomFields map[string]any `json:"custom_fields"`
|
||||
}
|
||||
|
||||
type nbIPRef struct {
|
||||
Address string `json:"address"`
|
||||
}
|
||||
|
||||
type nbInterface struct {
|
||||
ID int `json:"id"`
|
||||
Name string `json:"name"`
|
||||
MACAddress string `json:"mac_address"`
|
||||
PrimaryMACAddress *nbMAC `json:"primary_mac_address"`
|
||||
UntaggedVLAN *nbVLAN `json:"untagged_vlan"`
|
||||
Device *nbRef `json:"device"`
|
||||
}
|
||||
|
||||
func (i nbInterface) mac() string {
|
||||
if i.MACAddress != "" {
|
||||
return normalizeMAC(i.MACAddress)
|
||||
}
|
||||
if i.PrimaryMACAddress != nil {
|
||||
return normalizeMAC(i.PrimaryMACAddress.MACAddress)
|
||||
}
|
||||
return ""
|
||||
}
|
||||
|
||||
type nbIPAddress struct {
|
||||
Address string `json:"address"`
|
||||
AssignedObjectID int `json:"assigned_object_id"`
|
||||
CustomFields map[string]any `json:"custom_fields"`
|
||||
}
|
||||
|
||||
// --- Resolver implementation ---
|
||||
|
||||
// HostByMAC finds the device owning an interface with the given MAC and
|
||||
// resolves it to a Host.
|
||||
func (c *Client) HostByMAC(ctx context.Context, mac string) (*model.Host, error) {
|
||||
mac = normalizeMAC(mac)
|
||||
if mac == "" {
|
||||
return nil, fmt.Errorf("netbox: empty MAC")
|
||||
}
|
||||
var list nbList[nbInterface]
|
||||
if err := c.get(ctx, "/api/dcim/interfaces/", url.Values{"mac_address": {mac}}, &list); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
var dev *nbRef
|
||||
for _, i := range list.Results {
|
||||
if i.mac() == mac && i.Device != nil {
|
||||
dev = i.Device
|
||||
break
|
||||
}
|
||||
}
|
||||
if dev == nil {
|
||||
return nil, ErrNotFound
|
||||
}
|
||||
return c.resolveDevice(ctx, dev.ID)
|
||||
}
|
||||
|
||||
// HostByName finds a device by its NetBox name and resolves it to a Host.
|
||||
func (c *Client) HostByName(ctx context.Context, name string) (*model.Host, error) {
|
||||
// Strip any domain suffix: NetBox device names are short hostnames.
|
||||
short := name
|
||||
if i := strings.IndexByte(short, '.'); i >= 0 {
|
||||
short = short[:i]
|
||||
}
|
||||
var list nbList[nbDevice]
|
||||
if err := c.get(ctx, "/api/dcim/devices/", url.Values{"name": {short}}, &list); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
if len(list.Results) == 0 {
|
||||
return nil, ErrNotFound
|
||||
}
|
||||
return c.resolveDevice(ctx, list.Results[0].ID)
|
||||
}
|
||||
|
||||
// resolveDevice fetches the device, its interfaces and IP addresses, and
|
||||
// assembles a Host. It performs three bounded API calls.
|
||||
func (c *Client) resolveDevice(ctx context.Context, id int) (*model.Host, error) {
|
||||
var dev nbDevice
|
||||
if err := c.get(ctx, fmt.Sprintf("/api/dcim/devices/%d/", id), nil, &dev); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
|
||||
devID := url.Values{"device_id": {fmt.Sprint(id)}}
|
||||
var ifaces nbList[nbInterface]
|
||||
if err := c.get(ctx, "/api/dcim/interfaces/", devID, &ifaces); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
var ips nbList[nbIPAddress]
|
||||
if err := c.get(ctx, "/api/ipam/ip-addresses/", devID, &ips); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
|
||||
return buildHost(&dev, ifaces.Results, ips.Results), nil
|
||||
}
|
||||
|
||||
// buildHost assembles the normalized Host from raw NetBox objects. It is pure
|
||||
// (no I/O) so it can be unit-tested directly against fixture structs.
|
||||
func buildHost(dev *nbDevice, ifaces []nbInterface, ips []nbIPAddress) *model.Host {
|
||||
cf := dev.CustomFields
|
||||
domain := cfString(cf, "domain")
|
||||
|
||||
h := &model.Host{
|
||||
Hostname: dev.Name,
|
||||
Domain: domain,
|
||||
Custom: cf,
|
||||
Nameservers: cfStringList(cf, "nameservers"),
|
||||
TemplateOverride: cfString(cf, "provision_template"),
|
||||
Arch: "x86_64",
|
||||
}
|
||||
if dev.Platform != nil {
|
||||
h.Platform = dev.Platform.Slug
|
||||
h.OSFamily, h.OSVersion = splitPlatform(dev.Platform.Slug)
|
||||
}
|
||||
if dev.Role != nil {
|
||||
h.Role = dev.Role.Slug
|
||||
}
|
||||
|
||||
// Index IP addresses by the interface they are assigned to.
|
||||
ipByIface := map[int]nbIPAddress{}
|
||||
for _, ip := range ips {
|
||||
if _, seen := ipByIface[ip.AssignedObjectID]; !seen {
|
||||
ipByIface[ip.AssignedObjectID] = ip
|
||||
}
|
||||
}
|
||||
|
||||
primaryAddr := ""
|
||||
if dev.PrimaryIP != nil {
|
||||
primaryAddr = dev.PrimaryIP.Address
|
||||
h.PrimaryIP = addrOnly(primaryAddr)
|
||||
}
|
||||
|
||||
deviceGateway := cfString(cf, "gateway")
|
||||
|
||||
for _, in := range ifaces {
|
||||
iface := model.Interface{
|
||||
Name: in.Name,
|
||||
MAC: in.mac(),
|
||||
}
|
||||
if in.UntaggedVLAN != nil {
|
||||
iface.VLAN = in.UntaggedVLAN.VID
|
||||
}
|
||||
if ip, ok := ipByIface[in.ID]; ok {
|
||||
iface.IP = addrOnly(ip.Address)
|
||||
iface.PrefixLen = prefixLen(ip.Address)
|
||||
iface.Netmask = netmaskFor(iface.PrefixLen)
|
||||
if g := cfString(ip.CustomFields, "gateway"); g != "" {
|
||||
iface.Gateway = g
|
||||
}
|
||||
if iface.IP != "" && iface.IP == h.PrimaryIP {
|
||||
iface.Primary = true
|
||||
}
|
||||
}
|
||||
if iface.Gateway == "" {
|
||||
iface.Gateway = deviceGateway
|
||||
}
|
||||
h.Interfaces = append(h.Interfaces, iface)
|
||||
}
|
||||
|
||||
sortPrimaryFirst(h.Interfaces)
|
||||
|
||||
if h.Domain != "" {
|
||||
h.FQDN = h.Hostname + "." + h.Domain
|
||||
} else {
|
||||
h.FQDN = h.Hostname
|
||||
}
|
||||
return h
|
||||
}
|
||||
|
||||
// sortPrimaryFirst moves the primary interface to the front, preserving the
|
||||
// relative order of the rest.
|
||||
func sortPrimaryFirst(ifaces []model.Interface) {
|
||||
for i := range ifaces {
|
||||
if ifaces[i].Primary && i != 0 {
|
||||
p := ifaces[i]
|
||||
copy(ifaces[1:i+1], ifaces[0:i])
|
||||
ifaces[0] = p
|
||||
return
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// get performs a GET against the NetBox API and decodes the JSON body into out.
|
||||
func (c *Client) get(ctx context.Context, path string, q url.Values, out any) error {
|
||||
u := c.baseURL + path
|
||||
if len(q) > 0 {
|
||||
u += "?" + q.Encode()
|
||||
}
|
||||
req, err := http.NewRequestWithContext(ctx, http.MethodGet, u, nil)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
req.Header.Set("Accept", "application/json")
|
||||
if c.token != "" {
|
||||
req.Header.Set("Authorization", "Token "+c.token)
|
||||
}
|
||||
resp, err := c.http.Do(req)
|
||||
if err != nil {
|
||||
return fmt.Errorf("netbox request %s: %w", path, err)
|
||||
}
|
||||
defer func() { _ = resp.Body.Close() }()
|
||||
if resp.StatusCode == http.StatusNotFound {
|
||||
return ErrNotFound
|
||||
}
|
||||
if resp.StatusCode != http.StatusOK {
|
||||
return fmt.Errorf("netbox %s: HTTP %d", path, resp.StatusCode)
|
||||
}
|
||||
if err := json.NewDecoder(resp.Body).Decode(out); err != nil {
|
||||
return fmt.Errorf("netbox decode %s: %w", path, err)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// --- helpers ---
|
||||
|
||||
func normalizeMAC(s string) string {
|
||||
s = strings.TrimSpace(s)
|
||||
if s == "" {
|
||||
return ""
|
||||
}
|
||||
// Drop common separators then re-insert colons every 2 hex chars.
|
||||
var hex strings.Builder
|
||||
for _, r := range strings.ToLower(s) {
|
||||
if (r >= '0' && r <= '9') || (r >= 'a' && r <= 'f') {
|
||||
hex.WriteRune(r)
|
||||
}
|
||||
}
|
||||
h := hex.String()
|
||||
if len(h) != 12 {
|
||||
// Not a canonical 48-bit MAC; return lower-cased trimmed input.
|
||||
return strings.ToLower(s)
|
||||
}
|
||||
var b strings.Builder
|
||||
for i := 0; i < 12; i += 2 {
|
||||
if i > 0 {
|
||||
b.WriteByte(':')
|
||||
}
|
||||
b.WriteString(h[i : i+2])
|
||||
}
|
||||
return b.String()
|
||||
}
|
||||
|
||||
func addrOnly(cidr string) string {
|
||||
if i := strings.IndexByte(cidr, '/'); i >= 0 {
|
||||
return cidr[:i]
|
||||
}
|
||||
return cidr
|
||||
}
|
||||
|
||||
func prefixLen(cidr string) int {
|
||||
_, ipnet, err := net.ParseCIDR(cidr)
|
||||
if err != nil {
|
||||
return 0
|
||||
}
|
||||
ones, _ := ipnet.Mask.Size()
|
||||
return ones
|
||||
}
|
||||
|
||||
func netmaskFor(prefix int) string {
|
||||
if prefix <= 0 || prefix > 32 {
|
||||
return ""
|
||||
}
|
||||
mask := net.CIDRMask(prefix, 32)
|
||||
return fmt.Sprintf("%d.%d.%d.%d", mask[0], mask[1], mask[2], mask[3])
|
||||
}
|
||||
|
||||
// splitPlatform derives (family, majorVersion) from a NetBox platform slug such
|
||||
// as "almalinux9" -> ("almalinux","9") or "fedora42" -> ("fedora","42").
|
||||
func splitPlatform(slug string) (family, version string) {
|
||||
slug = strings.ToLower(slug)
|
||||
i := strings.IndexFunc(slug, func(r rune) bool { return r >= '0' && r <= '9' })
|
||||
if i < 0 {
|
||||
return slug, ""
|
||||
}
|
||||
family = strings.Trim(slug[:i], "-_")
|
||||
version = slug[i:]
|
||||
if d := strings.IndexByte(version, '.'); d >= 0 {
|
||||
version = version[:d]
|
||||
}
|
||||
return family, version
|
||||
}
|
||||
|
||||
func cfString(cf map[string]any, key string) string {
|
||||
if cf == nil {
|
||||
return ""
|
||||
}
|
||||
switch v := cf[key].(type) {
|
||||
case string:
|
||||
return v
|
||||
case map[string]any: // NetBox object custom fields serialize as {value,label}
|
||||
if s, ok := v["value"].(string); ok {
|
||||
return s
|
||||
}
|
||||
}
|
||||
return ""
|
||||
}
|
||||
|
||||
func cfStringList(cf map[string]any, key string) []string {
|
||||
if cf == nil {
|
||||
return nil
|
||||
}
|
||||
switch v := cf[key].(type) {
|
||||
case string:
|
||||
return splitComma(v)
|
||||
case []any:
|
||||
var out []string
|
||||
for _, e := range v {
|
||||
if s, ok := e.(string); ok && s != "" {
|
||||
out = append(out, s)
|
||||
}
|
||||
}
|
||||
return out
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func splitComma(v string) []string {
|
||||
var out []string
|
||||
for _, p := range strings.Split(v, ",") {
|
||||
if p = strings.TrimSpace(p); p != "" {
|
||||
out = append(out, p)
|
||||
}
|
||||
}
|
||||
return out
|
||||
}
|
||||
Reference in New Issue
Block a user