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
81 lines
3.3 KiB
Markdown
81 lines
3.3 KiB
Markdown
# 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](https://git.unkin.net/unkin/encapi).
|
|
With bootapi, provisioning a new host is:
|
|
|
|
1. `terraform` the host into **NetBox** (device, interfaces/MACs, IP, platform,
|
|
role) and **encapi** (classification), then
|
|
2. 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](docs/endpoints.md).
|
|
|
|
## Documentation
|
|
|
|
- [docs/endpoints.md](docs/endpoints.md) — the PXE flow, every endpoint, error/fallback behavior, metrics.
|
|
- [docs/data-model.md](docs/data-model.md) — the exact template data model + NetBox custom fields + template selection.
|
|
- [docs/template-authoring.md](docs/template-authoring.md) — writing/overriding kickstart & iPXE templates.
|
|
- [docs/deployment.md](docs/deployment.md) — Kubernetes/argocd wiring, Vault secrets, and the DHCP cutover.
|
|
- [docs/security.md](docs/security.md) — what belongs in NetBox vs Vault; secrets in kickstarts.
|
|
|
|
## Configuration
|
|
|
|
Env-based (12-factor), see [`config.example.env`](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
|
|
|
|
```bash
|
|
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
|
|
```
|