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/api/v1alpha1/nodeconfig_types.go

@@ -1,3 +1,8 @@
+// Package v1alpha1 contains the operator-facing API types for flock.
+//
+// Stability: alpha. The shape of these types may change in incompatible ways
+// between minor releases. CRDs are versioned and the agent reads only its
+// pinned version.
 package v1alpha1
 
 import metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
@@ -6,27 +11,78 @@ import metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 //
 // The agent reads this on startup and via informer for live updates. There is
 // no controller and no auto-allocation — purely declarative input.
+//
+// A NodeConfig's name MUST equal the Kubernetes node name it configures
+// (NodeConfigs are cluster-scoped). The agent ignores all NodeConfigs whose
+// name does not match its own node.
 type NodeConfigSpec struct {
 	// CIDR6 is the set of IPv6 CIDRs this node owns and advertises as BGP
-	// aggregates. Pod IPv6 addresses are allocated from these.
+	// aggregates. Pod IPv6 addresses are allocated from these. May be empty
+	// only if Defaults disables IPv6 for every pod on this node.
 	CIDR6 []string `json:"cidr6,omitempty"`
 
 	// CIDR4 is the set of IPv4 CIDRs this node owns and advertises as BGP
-	// aggregates. Pod IPv4 addresses are allocated from these.
+	// aggregates. Pod IPv4 addresses are allocated from these. May be empty
+	// when no pod on this node ever opts into IPv4.
 	CIDR4 []string `json:"cidr4,omitempty"`
 
 	// BGP configures the BGP sessions this node establishes upstream.
 	BGP BGPSpec `json:"bgp"`
+
+	// Defaults sets the per-node baseline for which address families a pod
+	// receives when its own annotations don't say. Pod-level
+	// `flock.fritzlab.net/ipv6` and `flock.fritzlab.net/ipv4` annotations
+	// always override these defaults.
+	//
+	// When a field is unset (nil), the agent falls back to its built-in
+	// baseline of IPv6=true, IPv4=false. When the whole Defaults block is
+	// nil, both built-in defaults apply.
+	//
+	// Typical uses:
+	//   - dual-stack node: Defaults: { ipv6: true, ipv4: true }
+	//   - IPv4-only node:  Defaults: { ipv6: false, ipv4: true }
+	//   - default (omit Defaults entirely): IPv6-only.
+	//
+	// Validation: at least one of IPv6 or IPv4 must end up true after merging
+	// (annotations + defaults + built-in baseline). The agent rejects pods
+	// that resolve to neither.
+	Defaults *FamilyDefaults `json:"defaults,omitempty"`
 }
 
+// FamilyDefaults is the per-node default for which address families a pod
+// receives when its annotations don't specify. Each field is a pointer so
+// "unset" is distinguishable from explicit "false".
+type FamilyDefaults struct {
+	// IPv6 is the default value for the `flock.fritzlab.net/ipv6` annotation.
+	// nil → fall back to the built-in baseline (true).
+	IPv6 *bool `json:"ipv6,omitempty"`
+
+	// IPv4 is the default value for the `flock.fritzlab.net/ipv4` annotation.
+	// nil → fall back to the built-in baseline (false).
+	IPv4 *bool `json:"ipv4,omitempty"`
+}
+
+// BGPSpec describes this node's BGP speaker configuration. Each upstream peer
+// becomes one BGP session in the rendered bird.conf.
 type BGPSpec struct {
-	ASN   uint32    `json:"asn"`
+	// ASN is this node's local autonomous system number. flock uses private
+	// ASNs in the 64512-65534 range by convention but accepts any value.
+	ASN uint32 `json:"asn"`
+
+	// Peers is the set of upstream BGP neighbors. At least one is required
+	// for BGP advertisement to function. Multiple peers of the same family
+	// are allowed (multi-homing).
 	Peers []BGPPeer `json:"peers"`
 }
 
+// BGPPeer is a single upstream BGP neighbor.
 type BGPPeer struct {
+	// Address is the peer's IP. May be IPv4 or IPv6. The agent picks an
+	// appropriate local source address on the same subnet.
 	Address string `json:"address"`
-	ASN     uint32 `json:"asn"`
+
+	// ASN is the peer's remote ASN.
+	ASN uint32 `json:"asn"`
 }
 
 // NodeConfig is the Schema for the nodeconfigs API. NodeConfigs are cluster-