Address PR review: PXE gate + callback, git-sync templates, distro catalog, k8s targets, http+https

Implements the six review comments on PR #1:

- Per-host PXE-enable gate: read NetBox pxe_enabled custom field; a known host
  with it false gets the safe local-boot script (Cobbler netboot_enabled). Add a
  token-guarded POST /provisioned/{ident} callback that clears pxe_enabled in
  NetBox, plus a %post snippet in the default kickstarts that calls it.
- Templates from a git repo: bootapi clones a templates repo and re-pulls every
  BOOTAPI_TEMPLATE_GIT_INTERVAL (default 3m), atomically swapping the template
  set (last-good kept on parse failure; embedded defaults are the startup
  fallback). Metrics for syncs/failures/generation.
- Distro catalog (catalog/*.yaml): NetBox host -> boot images/kickstart, so
  adding an OS is a YAML + template change. Ships almalinux + fedora entries
  (artifactapi remotes); debian/talos path documented.
- Boot images from the artifactapi almalinux/fedora remotes via the catalog.
- Bind resolvers, puppet server/CA and PUPPETCA_URL env file now target the k8s
  services (198.18.200.7; puppet(ca).k8s.syd1.au.unkin.net).
- Boot path served over plain HTTP (installers lack CA trust) with an optional
  parallel HTTPS listener; docs say do not 301 the boot endpoints.

New packages: internal/catalog, internal/gitsync. NetBox client gains a
pxe_enabled write (token needs that scope - noted in docs). `bootapi validate`
subcommand validates a template/catalog set for the templates-repo CI.

go build/vet clean, go test -race green, golangci-lint v2 clean, pre-commit clean.

Claude-Session: https://claude.ai/code/session_015ur3i7D2azsMAWTSVABApv

internal/netbox/cache.go

@@ -15,7 +15,7 @@ import (
 // while keeping the data fresh enough that a re-provisioned host picks up
 // changes on its next boot.
 type Cache struct {
-	inner Resolver
+	inner API
 	ttl   time.Duration
 	now   func() time.Time // injectable for tests
 
@@ -38,7 +38,7 @@ type cacheEntry struct {
 }
 
 // NewCache wraps inner with a TTL cache. A non-positive ttl disables caching.
-func NewCache(inner Resolver, ttl time.Duration) *Cache {
+func NewCache(inner API, ttl time.Duration) *Cache {
 	return &Cache{
 		inner:   inner,
 		ttl:     ttl,
@@ -47,6 +47,19 @@ func NewCache(inner Resolver, ttl time.Duration) *Cache {
 	}
 }
 
+// SetPXEEnabled writes through to NetBox and drops the whole cache, so the next
+// /ipxe lookup reflects the flipped gate immediately rather than serving a
+// stale "enabled" host for up to the TTL.
+func (c *Cache) SetPXEEnabled(ctx context.Context, deviceID int, enabled bool) error {
+	if err := c.inner.SetPXEEnabled(ctx, deviceID, enabled); err != nil {
+		return err
+	}
+	c.mu.Lock()
+	clear(c.entries)
+	c.mu.Unlock()
+	return nil
+}
+
 // HostByMAC returns a cached host or resolves and caches one.
 func (c *Cache) HostByMAC(ctx context.Context, mac string) (*model.Host, error) {
 	return c.lookup(ctx, "mac:"+normalizeMAC(mac), func() (*model.Host, error) {

internal/netbox/cache_test.go

@@ -12,10 +12,11 @@ import (
 
 // countingResolver records how many times the underlying resolver is hit.
 type countingResolver struct {
-	mu    sync.Mutex
-	calls int
-	host  *model.Host
-	err   error
+	mu     sync.Mutex
+	calls  int
+	writes int
+	host   *model.Host
+	err    error
 }
 
 func (c *countingResolver) HostByMAC(context.Context, string) (*model.Host, error) {
@@ -27,6 +28,12 @@ func (c *countingResolver) HostByMAC(context.Context, string) (*model.Host, erro
 func (c *countingResolver) HostByName(context.Context, string) (*model.Host, error) {
 	return c.HostByMAC(context.Background(), "")
 }
+func (c *countingResolver) SetPXEEnabled(context.Context, int, bool) error {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	c.writes++
+	return c.err
+}
 
 func TestCacheHitAndExpiry(t *testing.T) {
 	inner := &countingResolver{host: &model.Host{Hostname: "web01"}}
@@ -60,6 +67,29 @@ func TestCacheHitAndExpiry(t *testing.T) {
 	}
 }
 
+func TestCacheInvalidatedOnWrite(t *testing.T) {
+	inner := &countingResolver{host: &model.Host{Hostname: "web01"}}
+	cache := NewCache(inner, time.Minute)
+
+	// Warm the cache.
+	if _, err := cache.HostByMAC(context.Background(), "aa:bb:cc:00:11:22"); err != nil {
+		t.Fatal(err)
+	}
+	// A write must drop the cache so the next read re-resolves.
+	if err := cache.SetPXEEnabled(context.Background(), 12, false); err != nil {
+		t.Fatal(err)
+	}
+	if inner.writes != 1 {
+		t.Fatalf("inner writes = %d, want 1", inner.writes)
+	}
+	if _, err := cache.HostByMAC(context.Background(), "aa:bb:cc:00:11:22"); err != nil {
+		t.Fatal(err)
+	}
+	if inner.calls != 2 {
+		t.Fatalf("inner calls = %d, want 2 (cache dropped by write)", inner.calls)
+	}
+}
+
 func TestCacheDisabled(t *testing.T) {
 	inner := &countingResolver{host: &model.Host{Hostname: "web01"}}
 	cache := NewCache(inner, 0) // ttl <= 0 disables caching

internal/netbox/netbox.go

@@ -5,6 +5,7 @@
 package netbox
 
 import (
+	"bytes"
 	"context"
 	"crypto/tls"
 	"encoding/json"
@@ -29,6 +30,19 @@ type Resolver interface {
 	HostByName(ctx context.Context, name string) (*model.Host, error)
 }
 
+// Writer mutates NetBox. Today it only flips the pxe_enabled gate (the
+// end-of-kickstart callback). Kept separate from Resolver so read-only callers
+// need not depend on write scope.
+type Writer interface {
+	SetPXEEnabled(ctx context.Context, deviceID int, enabled bool) error
+}
+
+// API is the full NetBox surface bootapi uses (reads + the pxe_enabled write).
+type API interface {
+	Resolver
+	Writer
+}
+
 // Client is the HTTP-backed Resolver.
 type Client struct {
 	baseURL string
@@ -199,11 +213,13 @@ func buildHost(dev *nbDevice, ifaces []nbInterface, ips []nbIPAddress) *model.Ho
 	domain := cfString(cf, "domain")
 
 	h := &model.Host{
+		DeviceID:         dev.ID,
 		Hostname:         dev.Name,
 		Domain:           domain,
 		Custom:           cf,
 		Nameservers:      cfStringList(cf, "nameservers"),
 		TemplateOverride: cfString(cf, "provision_template"),
+		PXEEnabled:       cfBool(cf, "pxe_enabled"),
 		Arch:             "x86_64",
 	}
 	if dev.Platform != nil {
@@ -278,6 +294,39 @@ func sortPrimaryFirst(ifaces []model.Interface) {
 	}
 }
 
+// SetPXEEnabled PATCHes the device's pxe_enabled custom field. This is the only
+// write bootapi performs; the NetBox token therefore needs write scope on the
+// device custom field (see docs/security.md).
+func (c *Client) SetPXEEnabled(ctx context.Context, deviceID int, enabled bool) error {
+	body := map[string]any{"custom_fields": map[string]any{"pxe_enabled": enabled}}
+	b, err := json.Marshal(body)
+	if err != nil {
+		return err
+	}
+	path := fmt.Sprintf("/api/dcim/devices/%d/", deviceID)
+	req, err := http.NewRequestWithContext(ctx, http.MethodPatch, c.baseURL+path, bytes.NewReader(b))
+	if err != nil {
+		return err
+	}
+	req.Header.Set("Content-Type", "application/json")
+	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 patch device %d: %w", deviceID, err)
+	}
+	defer func() { _ = resp.Body.Close() }()
+	if resp.StatusCode == http.StatusNotFound {
+		return ErrNotFound
+	}
+	if resp.StatusCode != http.StatusOK {
+		return fmt.Errorf("netbox patch device %d: HTTP %d", deviceID, resp.StatusCode)
+	}
+	return nil
+}
+
 // 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
@@ -393,6 +442,28 @@ func cfString(cf map[string]any, key string) string {
 	return ""
 }
 
+// cfBool reads a boolean custom field. Returns nil when the field is absent or
+// null so callers can distinguish "unset" from "false".
+func cfBool(cf map[string]any, key string) *bool {
+	if cf == nil {
+		return nil
+	}
+	switch v := cf[key].(type) {
+	case bool:
+		return &v
+	case string: // tolerate "true"/"false" string encodings
+		switch strings.ToLower(v) {
+		case "true", "1", "yes":
+			b := true
+			return &b
+		case "false", "0", "no":
+			b := false
+			return &b
+		}
+	}
+	return nil
+}
+
 func cfStringList(cf map[string]any, key string) []string {
 	if cf == nil {
 		return nil

internal/netbox/netbox_test.go

@@ -6,9 +6,13 @@ import (
 	"net/http"
 	"net/http/httptest"
 	"strings"
+	"sync/atomic"
 	"testing"
 )
 
+// patchedDevice records whether the fake NetBox saw a PATCH on device 12.
+var patchedDevice atomic.Bool
+
 // fakeNetBox serves canned NetBox v4.x JSON for the endpoints bootapi calls.
 // The payloads are trimmed but structurally faithful to real API responses.
 func fakeNetBox(t *testing.T) *httptest.Server {
@@ -38,8 +42,13 @@ func fakeNetBox(t *testing.T) *httptest.Server {
 		}
 	})
 
-	// Device detail.
+	// Device detail (GET) + pxe_enabled write (PATCH).
 	mux.HandleFunc("/api/dcim/devices/", func(w http.ResponseWriter, r *http.Request) {
+		if r.Method == http.MethodPatch && strings.HasSuffix(r.URL.Path, "/12/") {
+			patchedDevice.Store(true)
+			writeJSON(w, `{"id":12,"name":"web01"}`)
+			return
+		}
 		if strings.HasSuffix(r.URL.Path, "/12/") {
 			writeJSON(w, `{
 				"id":12,"name":"web01",
@@ -47,7 +56,7 @@ func fakeNetBox(t *testing.T) *httptest.Server {
 				"role":{"id":2,"name":"K8s Worker","slug":"kubernetes-worker"},
 				"site":{"slug":"syd1"},
 				"primary_ip":{"address":"10.0.1.20/24"},
-				"custom_fields":{"domain":"syd1.au.unkin.net","gateway":"10.0.1.254","nameservers":"10.0.0.1,10.0.0.2","provision_template":null}}`)
+				"custom_fields":{"domain":"syd1.au.unkin.net","gateway":"10.0.1.254","nameservers":"10.0.0.1,10.0.0.2","provision_template":null,"pxe_enabled":true}}`)
 			return
 		}
 		// name= query (HostByName)
@@ -102,6 +111,12 @@ func TestHostByMAC(t *testing.T) {
 	if h.PrimaryIP != "10.0.1.20" {
 		t.Errorf("primaryIP = %q", h.PrimaryIP)
 	}
+	if h.DeviceID != 12 {
+		t.Errorf("deviceID = %d, want 12", h.DeviceID)
+	}
+	if h.PXEEnabled == nil || !*h.PXEEnabled || !h.ShouldPXEInstall() {
+		t.Errorf("pxe_enabled = %v, want true", h.PXEEnabled)
+	}
 	if len(h.Nameservers) != 2 || h.Nameservers[0] != "10.0.0.1" {
 		t.Errorf("nameservers = %v", h.Nameservers)
 	}
@@ -181,6 +196,44 @@ func TestAuthTokenRequired(t *testing.T) {
 	}
 }
 
+func TestSetPXEEnabled(t *testing.T) {
+	srv := fakeNetBox(t)
+	defer srv.Close()
+	patchedDevice.Store(false)
+	c := newTestClient(t, srv.URL)
+
+	if err := c.SetPXEEnabled(context.Background(), 12, false); err != nil {
+		t.Fatalf("SetPXEEnabled: %v", err)
+	}
+	if !patchedDevice.Load() {
+		t.Error("expected a PATCH to device 12, got none")
+	}
+}
+
+func TestCfBool(t *testing.T) {
+	tr := true
+	cases := []struct {
+		cf   map[string]any
+		want *bool
+	}{
+		{map[string]any{"pxe_enabled": true}, &tr},
+		{map[string]any{"pxe_enabled": "false"}, boolp(false)},
+		{map[string]any{"pxe_enabled": nil}, nil},
+		{map[string]any{}, nil},
+	}
+	for _, c := range cases {
+		got := cfBool(c.cf, "pxe_enabled")
+		switch {
+		case got == nil && c.want == nil:
+		case got != nil && c.want != nil && *got == *c.want:
+		default:
+			t.Errorf("cfBool(%v) = %v, want %v", c.cf, got, c.want)
+		}
+	}
+}
+
+func boolp(b bool) *bool { return &b }
+
 func TestNormalizeMAC(t *testing.T) {
 	cases := map[string]string{
 		"AA:BB:CC:00:11:22": "aa:bb:cc:00:11:22",