NodeConfig defaults + code-quality pass + fuzz tests + README

NodeConfig.Spec.Defaults adds per-node IPv6/IPv4 family defaults that pod
annotations can override; built-in baseline (v6=true, v4=false) still
applies when the field is omitted.

bird.Render now validates every operator-supplied value (peer addresses,
CIDRs, anycast IPs, source addresses) before templating — fuzz found a
peer address containing `}` produced unbalanced braces in bird.conf.
Failing input preserved as a regression seed.

Fuzz targets added for ParseAnnotations, ParseCNIArgs, HostIfaceName,
canonical, IPAM allocate sequences, embed.Embed, and bird.Render.
Hardened canonical/ipToU32 against nil and non-IPv4 inputs.

README rewritten for outside readers — quickstart, NodeConfig + annotation
reference with worked examples, anycast use cases, comparison vs Calico
and Cilium, requirements, limitations.

Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>

pkg/routing/bird/config.go

@@ -9,6 +9,7 @@ import (
 	"fmt"
 	"net"
 	"sort"
+	"strings"
 	"text/template"
 )
 
@@ -118,28 +119,150 @@ protocol bgp upstream4_{{$i}} {
 {{end}}{{end}}`
 
 // Render produces the bird.conf text.
+//
+// The output is deterministic: the same NodeBGP input always produces the
+// same string. CIDR lists, anycast lists, and peer lists are sorted before
+// templating so that the only way the rendered config changes is when
+// semantically meaningful inputs change. This stability matters because
+// BirdManager compares Render output against the last-written config to
+// avoid superfluous birdc reloads.
+//
+// Render validates every operator-supplied value that flows into the
+// templated output (peer addresses, CIDRs, anycast IPs, source addresses)
+// so a malformed NodeConfig or annotation cannot produce a malformed
+// bird.conf — even one that BIRD would later reject.
 func Render(in NodeBGP) (string, error) {
 	if in.RouterID == "" {
-		return "", fmt.Errorf("RouterID is required")
+		return "", fmt.Errorf("bird render: RouterID is required")
+	}
+	if net.ParseIP(in.RouterID) == nil {
+		return "", fmt.Errorf("bird render: RouterID %q is not a valid IP", in.RouterID)
 	}
 	if in.LocalASN == 0 {
-		return "", fmt.Errorf("LocalASN is required")
+		return "", fmt.Errorf("bird render: LocalASN is required")
 	}
-	// Stable order — important so config changes only when something real
-	// changes (avoids needless birdc reloads).
+	if err := validateLocalSource(in.LocalV6, "v6"); err != nil {
+		return "", err
+	}
+	if err := validateLocalSource(in.LocalV4, "v4"); err != nil {
+		return "", err
+	}
+	for i, p := range in.Peers {
+		if err := validatePeer(p); err != nil {
+			return "", fmt.Errorf("bird render: peer[%d]: %w", i, err)
+		}
+	}
+	if err := validateCIDRs(in.CIDR6, "v6"); err != nil {
+		return "", fmt.Errorf("bird render: cidr6: %w", err)
+	}
+	if err := validateCIDRs(in.CIDR4, "v4"); err != nil {
+		return "", fmt.Errorf("bird render: cidr4: %w", err)
+	}
+	if err := validateAnycastIPs(in.Anycast6, "v6"); err != nil {
+		return "", fmt.Errorf("bird render: anycast6: %w", err)
+	}
+	if err := validateAnycastIPs(in.Anycast4, "v4"); err != nil {
+		return "", fmt.Errorf("bird render: anycast4: %w", err)
+	}
+
 	in = normalize(in)
 
 	t, err := template.New("bird").Parse(tpl)
 	if err != nil {
-		return "", err
+		return "", fmt.Errorf("bird template parse: %w", err)
 	}
 	var buf bytes.Buffer
 	if err := t.Execute(&buf, in); err != nil {
-		return "", err
+		return "", fmt.Errorf("bird template execute: %w", err)
 	}
 	return buf.String(), nil
 }
 
+// validatePeer checks that a peer entry has a parseable IP whose family
+// matches its declared Family field, and a non-zero ASN.
+func validatePeer(p Peer) error {
+	if p.ASN == 0 {
+		return fmt.Errorf("ASN must be non-zero")
+	}
+	ip := net.ParseIP(p.Address)
+	if ip == nil {
+		return fmt.Errorf("address %q is not a valid IP", p.Address)
+	}
+	isV4 := ip.To4() != nil
+	switch p.Family {
+	case "v6":
+		if isV4 {
+			return fmt.Errorf("address %q is IPv4 but Family is v6", p.Address)
+		}
+	case "v4":
+		if !isV4 {
+			return fmt.Errorf("address %q is IPv6 but Family is v4", p.Address)
+		}
+	default:
+		return fmt.Errorf("Family %q must be v6 or v4", p.Family)
+	}
+	return nil
+}
+
+// validateCIDRs parses each entry as a CIDR and rejects family mismatches.
+// fam must be "v6" or "v4".
+func validateCIDRs(cidrs []string, fam string) error {
+	for _, c := range cidrs {
+		_, n, err := net.ParseCIDR(c)
+		if err != nil {
+			return fmt.Errorf("invalid CIDR %q: %w", c, err)
+		}
+		isV4 := n.IP.To4() != nil
+		if fam == "v6" && isV4 {
+			return fmt.Errorf("CIDR %q is IPv4, expected IPv6", c)
+		}
+		if fam == "v4" && !isV4 {
+			return fmt.Errorf("CIDR %q is IPv6, expected IPv4", c)
+		}
+	}
+	return nil
+}
+
+// validateAnycastIPs parses each entry as a literal IP (no prefix) and rejects
+// family mismatches.
+func validateAnycastIPs(ips []string, fam string) error {
+	for _, s := range ips {
+		ip := net.ParseIP(s)
+		if ip == nil {
+			return fmt.Errorf("invalid IP %q", s)
+		}
+		isV4 := ip.To4() != nil
+		if fam == "v6" && isV4 {
+			return fmt.Errorf("IP %q is IPv4, expected IPv6", s)
+		}
+		if fam == "v4" && !isV4 {
+			return fmt.Errorf("IP %q is IPv6, expected IPv4", s)
+		}
+	}
+	return nil
+}
+
+// validateLocalSource validates an optional LocalV6/LocalV4 source address.
+// Empty is allowed (BIRD picks its own); non-empty must be a parseable IP of
+// the matching family.
+func validateLocalSource(s, fam string) error {
+	if s == "" {
+		return nil
+	}
+	ip := net.ParseIP(s)
+	if ip == nil {
+		return fmt.Errorf("bird render: Local%s %q is not a valid IP", strings.ToUpper(fam), s)
+	}
+	isV4 := ip.To4() != nil
+	if fam == "v6" && isV4 {
+		return fmt.Errorf("bird render: LocalV6 %q is IPv4", s)
+	}
+	if fam == "v4" && !isV4 {
+		return fmt.Errorf("bird render: LocalV4 %q is IPv6", s)
+	}
+	return nil
+}
+
 func normalize(in NodeBGP) NodeBGP {
 	cp := in
 	cp.CIDR6 = sortedUnique(in.CIDR6)