unkinben
274c480b09
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
bootapi
bootapi is a small Go service that replaces Cobbler's PXE/kickstart side. It
renders kickstart files and iPXE boot scripts from NetBox device data and
serves them over HTTP to PXE-booting hosts.
The ENC half of Cobbler already moved to encapi. With bootapi, provisioning a new host is:
terraformthe host into NetBox (device, interfaces/MACs, IP, platform, role) and encapi (classification), then- rack it and let it PXE-boot — DHCP points it at bootapi, which serves the iPXE script and the rendered kickstart; the kickstart hands off to the existing Puppet firstrun bootstrap.
How it works
DHCP next-server ─▶ iPXE ─▶ GET /ipxe/<mac> ─▶ boot kernel+initrd, inst.ks=<bootapi>/ks/<host>
└▶ GET /ks/<host> ─▶ rendered kickstart ─▶ puppet firstrun
bootapi identifies the booting host by the MAC it booted from (NetBox
interface lookup → device → primary IP, platform, role, interfaces), renders a
Go text/template selected from the host's platform/role/custom-field, and
serves it. Templates are embedded defaults, overridable from a directory
(ConfigMap in k8s).
Endpoints (summary)
| Path | Purpose |
|---|---|
GET /ipxe/{mac} · GET /boot/ipxe?mac= |
iPXE boot script |
GET /ks/{ident} |
rendered kickstart (MAC or hostname) |
GET /healthz · /readyz · /metrics |
health + Prometheus |
Unknown MAC → iPXE gets a safe fallback (local-disk boot, HTTP 200), never a 404. Unknown kickstart host → 404 (fail loud once installing). Full rationale in docs/endpoints.md.
Documentation
- docs/endpoints.md — the PXE flow, every endpoint, error/fallback behavior, metrics.
- docs/data-model.md — the exact template data model + NetBox custom fields + template selection.
- docs/template-authoring.md — writing/overriding kickstart & iPXE templates.
- docs/deployment.md — Kubernetes/argocd wiring, Vault secrets, and the DHCP cutover.
- docs/security.md — what belongs in NetBox vs Vault; secrets in kickstarts.
Configuration
Env-based (12-factor), see config.example.env. Key vars:
BOOTAPI_NETBOX_URL, BOOTAPI_NETBOX_TOKEN[_FILE], BOOTAPI_BASE_URL,
BOOTAPI_BOOT_BASE_URL, BOOTAPI_ROOT_PASSWORD_HASH[_FILE],
BOOTAPI_UNKNOWN_MAC_FALLBACK.
Development
make build # build ./bin/bootapi
make test-race # go test -race ./...
make lint # golangci-lint (v2) if installed, else go vet
make run # build + run
CI (Woodpecker): pre-commit, golangci-lint v2 + go test -race, and a
docker build on PRs; on a v* tag, a container image push and a Gitea binary
release. Cut a release with make patch|minor|major (tags + pushes).
Layout
cmd/bootapi/ main
internal/config/ env config
internal/model/ Host/Interface data model
internal/netbox/ NetBox client (+ TTL cache), behind a Resolver interface
internal/render/ text/template engine, selection, embedded-defaults loader
internal/server/ chi HTTP handlers + Prometheus metrics
templates/ embedded default kickstart + iPXE templates
docs/ see above