defaults: built-in baseline is dual-stack (IPv6 + IPv4), not IPv6-only

BuiltinFamilyDefaults() now returns {WantV6: true, WantV4: true}. Pods
that want a single family explicitly opt out via the
flock.fritzlab.net/ipv4 (or ipv6) annotation, or the operator narrows
the default at the node level via NodeConfig.Spec.Defaults.

Annotation precedence is unchanged: pod annotation > NodeConfig defaults
> built-in baseline. Tests updated to reflect the new baseline; the
"opt out of v4" path now has explicit coverage.

Docs updated:
  - NodeConfig.Spec.Defaults Go doc + CRD descriptions reflect the new
    baseline and its overrides
  - README opening framing softened from "IPv6-first" to "dual-stack,
    IPv6-friendly"; example pods + spec.defaults table flipped to
    treat dual-stack as the default and v6/v4-only as overrides
  - README NetworkPolicy line in the comparison table flipped to
    "yes (nftables)" since v1 enforcement shipped
  - Limitations note about IPv4-only destinations rewritten — every
    pod has v4 by default now, so the question is whether your IPv4
    pool is routable beyond your network

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

pkg/agent/annotations.go

@@ -26,7 +26,7 @@ const (
 // FamilyDefaults is the per-call baseline for whether a pod receives an IPv6
 // and/or IPv4 address. It is the merge of:
 //
-//  1. flock's built-in baseline (IPv6=true, IPv4=false), then
+//  1. flock's built-in baseline (IPv6=true, IPv4=true — dual-stack), then
 //  2. any NodeConfig.Spec.Defaults override the operator has applied to
 //     the local node.
 //
@@ -43,13 +43,17 @@ type FamilyDefaults struct {
 	WantV4 bool
 }
 
-// BuiltinFamilyDefaults returns flock's hard-coded fallback: IPv6 only.
-// This is the policy applied when no NodeConfig override is in effect.
+// BuiltinFamilyDefaults returns flock's hard-coded fallback: dual-stack
+// (IPv6 + IPv4). This is the policy applied when no NodeConfig override is
+// in effect. Pods that want a single family explicitly opt out via the
+// `flock.fritzlab.net/ipv6` or `flock.fritzlab.net/ipv4` annotation, or
+// the operator narrows the fallback at the node level via
+// NodeConfig.Spec.Defaults.
 //
 // We define it as a function rather than a var so callers can't mutate the
 // shared baseline at runtime.
 func BuiltinFamilyDefaults() FamilyDefaults {
-	return FamilyDefaults{WantV6: true, WantV4: false}
+	return FamilyDefaults{WantV6: true, WantV4: true}
 }
 
 // FamilyDefaultsFromNodeConfig resolves the effective per-node defaults,

pkg/agent/annotations_test.go

@@ -13,8 +13,8 @@ func boolPtr(b bool) *bool { return &b }
 
 func TestBuiltinFamilyDefaults(t *testing.T) {
 	d := BuiltinFamilyDefaults()
-	if !d.WantV6 || d.WantV4 {
-		t.Fatalf("built-in defaults wrong: v6=%v v4=%v (want true/false)", d.WantV6, d.WantV4)
+	if !d.WantV6 || !d.WantV4 {
+		t.Fatalf("built-in defaults wrong: v6=%v v4=%v (want dual-stack true/true)", d.WantV6, d.WantV4)
 	}
 }
 
@@ -37,14 +37,16 @@ func TestFamilyDefaultsFromNodeConfig_PartialOverride(t *testing.T) {
 	nc := &flockv1alpha1.NodeConfig{
 		Spec: flockv1alpha1.NodeConfigSpec{
 			Defaults: &flockv1alpha1.FamilyDefaults{
-				IPv4: boolPtr(true),
+				IPv4: boolPtr(false),
 			},
 		},
 	}
 	d := FamilyDefaultsFromNodeConfig(nc)
-	// IPv6 was unset → keeps built-in true; IPv4 was set → flipped on.
-	if !d.WantV6 || !d.WantV4 {
-		t.Fatalf("partial override wrong: %+v (want v6=true, v4=true)", d)
+	// IPv6 unset → keeps built-in true; IPv4 explicitly set to false →
+	// node opts the family off. Validates that an explicit false beats
+	// the dual-stack baseline rather than being silently overridden.
+	if !d.WantV6 || d.WantV4 {
+		t.Fatalf("partial override wrong: %+v (want v6=true, v4=false)", d)
 	}
 }
 
@@ -64,12 +66,27 @@ func TestFamilyDefaultsFromNodeConfig_FullOverride(t *testing.T) {
 }
 
 func TestParseAnnotations_BuiltinDefaults(t *testing.T) {
+	// Built-in baseline is dual-stack — no annotation needed.
 	a, err := ParseAnnotations(nil, BuiltinFamilyDefaults())
 	if err != nil {
 		t.Fatal(err)
 	}
+	if !a.WantV6 || !a.WantV4 {
+		t.Fatalf("expected dual-stack default, got v6=%v v4=%v", a.WantV6, a.WantV4)
+	}
+}
+
+// TestParseAnnotations_OptOutV4 — pods that want IPv6 only must opt out
+// explicitly via the ipv4 annotation now that the built-in is dual-stack.
+func TestParseAnnotations_OptOutV4(t *testing.T) {
+	a, err := ParseAnnotations(map[string]string{
+		annotationPrefix + "ipv4": "false",
+	}, BuiltinFamilyDefaults())
+	if err != nil {
+		t.Fatal(err)
+	}
 	if !a.WantV6 || a.WantV4 {
-		t.Fatalf("defaults wrong: v6=%v v4=%v", a.WantV6, a.WantV4)
+		t.Fatalf("ipv4=false override failed: v6=%v v4=%v", a.WantV6, a.WantV4)
 	}
 }
 
@@ -100,6 +117,8 @@ func TestParseAnnotations_AnnotationOverridesNodeDefault(t *testing.T) {
 }
 
 func TestParseAnnotations_DualStackViaAnnotation(t *testing.T) {
+	// Same as built-in default; explicit ipv4=true is a no-op now but must
+	// still parse cleanly.
 	a, err := ParseAnnotations(map[string]string{
 		annotationPrefix + "ipv4": "true",
 	}, BuiltinFamilyDefaults())
@@ -112,10 +131,12 @@ func TestParseAnnotations_DualStackViaAnnotation(t *testing.T) {
 }
 
 func TestParseAnnotations_NoFamily(t *testing.T) {
+	// Pod opts out of both families → must be rejected.
 	if _, err := ParseAnnotations(map[string]string{
 		annotationPrefix + "ipv6": "false",
+		annotationPrefix + "ipv4": "false",
 	}, BuiltinFamilyDefaults()); err == nil {
-		t.Fatalf("expected error: ipv6=false ipv4=false")
+		t.Fatalf("expected error when pod opts out of both families")
 	}
 }
 

pkg/agent/ipam.go

@@ -69,8 +69,9 @@ type AllocRequest struct {
 	Namespace   string
 	Pod         string
 	// WantV6 / WantV4 are the post-merge address family selection (pod
-	// annotation > NodeConfig.Spec.Defaults > built-in baseline). At least
-	// one MUST be true; Allocate rejects the request otherwise.
+	// annotation > NodeConfig.Spec.Defaults > built-in baseline of
+	// dual-stack). At least one MUST be true; Allocate rejects the request
+	// otherwise.
 	WantV6 bool
 	WantV4 bool
 	// AnnCIDR6 / AnnCIDR4 come from the cidr6 / cidr4 annotations. Empty

pkg/api/v1alpha1/nodeconfig_types.go

@@ -35,13 +35,13 @@ type NodeConfigSpec struct {
 	// 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.
+	// baseline of IPv6=true, IPv4=true (dual-stack). 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.
+	//   - dual-stack node (built-in default): omit Defaults entirely.
+	//   - IPv6-only node:  Defaults: { ipv6: true,  ipv4: false }
+	//   - IPv4-only node:  Defaults: { ipv6: false, ipv4: true  }
 	//
 	// Validation: at least one of IPv6 or IPv4 must end up true after merging
 	// (annotations + defaults + built-in baseline). The agent rejects pods
@@ -58,7 +58,7 @@ type FamilyDefaults struct {
 	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).
+	// nil → fall back to the built-in baseline (true).
 	IPv4 *bool `json:"ipv4,omitempty"`
 }