ip-algo: rename pod field to app; image from pod spec

The `pod` field hashed pod.Name, which differs per replica because of
the ReplicaSet pod-template-hash + 5-char random suffix. With
namespace,pod,image, all replicas of the same Deployment got distinct
hextets even though they were the same workload.

Replace `pod` with `app` — a stable workload identifier derived from
the controller chain:

  - Deployment → ReplicaSet → Pod: strip the pod-template-hash suffix
    from the RS name (`traefik-789df685f` → `traefik`).
  - StatefulSet/DaemonSet/Job → Pod: use controller name as-is.
  - Bare pod: pod name.

Image now comes from pod.Spec.Containers[0].Image (the spec'd
reference). 64-hex-char values are treated as sha256 digests and
parsed as before; everything else (image:tag, short SHA) is FNV-1a-64'd
as a string. This makes `traefik:v3.5` deterministic across replicas
without needing the runtime-resolved digest.

Net effect: namespace,app,image yields identical hextets across all
replicas of the same Deployment except the trailing random N nibble.

embed.Values.Pod → App; AllocRequest.Pod kept for log context only,
new App and Image fields drive the embed call. handlers.go computes
both via deriveAppName + podImageRef helpers.

Tests: 7 new TestDeriveAppName_* cases (Deploy/STS/DS/bare/RS-without-
hash/non-controller-owner) + TestPodImageRef. Existing fuzz seeds
updated for the new keyword.

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

pkg/embed/suffix.go

@@ -1,5 +1,5 @@
-// Package embed implements ip-algo: deterministic embedding of pod identity
-// (namespace, pod name, image digest) into the host portion of an IPv6
+// Package embed implements ip-algo: deterministic embedding of workload
+// identity (namespace, app name, image) into the host portion of an IPv6
 // address. The mapping is operator-friendly cosmetics — NOT a security
 // boundary. See dfritz-cni.md "IPv6 IID Embedding" for the full spec.
 package embed
@@ -17,18 +17,27 @@ type Field string
 
 const (
 	FieldNamespace Field = "namespace"
-	FieldPod       Field = "pod"
+	FieldApp       Field = "app"
 	FieldImage     Field = "image"
 )
 
-// Values carries the inputs for one embedding call. Image holds the SHA-256
-// manifest digest as 64 hex chars when known; otherwise pass the containerID
-// in ImageFallback and we'll FNV-1a-64 it.
+// Values carries the inputs for one embedding call.
+//
+// App is the stable workload identifier — typically the owning Deployment /
+// StatefulSet / DaemonSet name (callers strip the pod-template-hash from
+// ReplicaSet names before passing it in). Caller is responsible for picking
+// the right level of stability; this package just hashes whatever it gets.
+//
+// Image is whatever string the caller wants embedded for the image field;
+// the most common choice is pod.Spec.Containers[0].Image (the spec'd
+// reference). If the caller passes a 64-hex-char SHA-256 digest, the top
+// bits are taken as a hex value; otherwise it is FNV-1a-64'd as a plain
+// string. ImageFallback is used only when Image == "".
 type Values struct {
-	Namespace       string
-	Pod             string
-	Image           string // 64-char hex sha256 manifest digest, or empty
-	ImageFallback   string // typically containerID, used when Image=="".
+	Namespace     string
+	App           string
+	Image         string // sha256 hex (64 chars), or any string to FNV; empty → fallback
+	ImageFallback string // typically containerID, used when Image=="".
 }
 
 // MaxFieldNibbles is the largest single-field width supported by this
@@ -127,13 +136,22 @@ func fieldValue(f Field, v Values, bits int) (uint64, error) {
 	switch f {
 	case FieldNamespace:
 		return topBitsFNV(v.Namespace, bits), nil
-	case FieldPod:
-		return topBitsFNV(v.Pod, bits), nil
+	case FieldApp:
+		return topBitsFNV(v.App, bits), nil
 	case FieldImage:
-		if v.Image != "" {
+		if v.Image == "" {
+			return topBitsFNV(v.ImageFallback, bits), nil
+		}
+		// SHA-256 manifest digests are exactly 64 hex chars (with optional
+		// "sha256:" prefix). Anything else — image:tag references like
+		// "traefik:v3", or short SHAs — gets FNV-1a-64'd as a string. This
+		// preserves the original digest behaviour while letting callers
+		// pass pod.Spec.Containers[0].Image directly.
+		s := strings.TrimPrefix(v.Image, "sha256:")
+		if len(s) == 64 && isHex(s) {
 			return topBitsHex(v.Image, bits)
 		}
-		return topBitsFNV(v.ImageFallback, bits), nil
+		return topBitsFNV(v.Image, bits), nil
 	default:
 		return 0, fmt.Errorf("unknown field %q", f)
 	}
@@ -163,6 +181,21 @@ func topBitsHex(s string, bits int) (uint64, error) {
 	return v >> uint(64-bits), nil
 }
 
+// isHex reports whether every byte in s is a valid hex digit.
+func isHex(s string) bool {
+	for i := 0; i < len(s); i++ {
+		c := s[i]
+		switch {
+		case c >= '0' && c <= '9':
+		case c >= 'a' && c <= 'f':
+		case c >= 'A' && c <= 'F':
+		default:
+			return false
+		}
+	}
+	return true
+}
+
 // writeNibble sets the (nibIdx)-th nibble of addr (0 = highest nibble of byte 0).
 func writeNibble(addr net.IP, nibIdx int, nb byte) {
 	bytePos := nibIdx / 2

pkg/embed/suffix_fuzz_test.go

@@ -11,29 +11,30 @@ func FuzzEmbed(f *testing.F) {
 	type seed struct {
 		prefix    string
 		fields    string // comma-separated, mapped below to []Field
-		ns, pod   string
+		ns, app   string
 		image     string
 		fallback  string
 		nNibble   byte
 	}
 	for _, s := range []seed{
-		{"2602:817:3000:f001::/64", "namespace,pod,image", "mail", "stalwart-0", "", "ctr", 0xe},
-		{"2001:db8::/64", "namespace", "ns", "p", "", "", 0},
-		{"2001:db8::/96", "pod", "", "podname", "", "ctr", 0xf},
-		{"2001:db8::/48", "namespace,pod", "ns", "p", "", "ctr", 0x1},
-		{"2001:db8::/120", "namespace", "n", "p", "", "ctr", 0x0},   // 8 host nibbles
-		{"2001:db8::/124", "namespace", "n", "p", "", "ctr", 0x0},   // 4 host nibbles
-		{"2001:db8::/127", "namespace", "n", "p", "", "ctr", 0x0},   // not nibble-aligned
-		{"2001:db8::/63", "namespace", "n", "p", "", "ctr", 0x0},    // not nibble-aligned
-		{"2001:db8::/64", "namespace,pod,image", "", "", "sha256:abcdef0123456789aabbccddeeff00112233445566778899aabbccddeeff0011", "", 0xa},
-		{"2001:db8::/64", "namespace,pod,image", "", "", "", "ctr", 0xa},
+		{"2602:817:3000:f001::/64", "namespace,app,image", "mail", "stalwart", "", "ctr", 0xe},
+		{"2001:db8::/64", "namespace", "ns", "a", "", "", 0},
+		{"2001:db8::/96", "app", "", "appname", "", "ctr", 0xf},
+		{"2001:db8::/48", "namespace,app", "ns", "a", "", "ctr", 0x1},
+		{"2001:db8::/120", "namespace", "n", "a", "", "ctr", 0x0},   // 8 host nibbles
+		{"2001:db8::/124", "namespace", "n", "a", "", "ctr", 0x0},   // 4 host nibbles
+		{"2001:db8::/127", "namespace", "n", "a", "", "ctr", 0x0},   // not nibble-aligned
+		{"2001:db8::/63", "namespace", "n", "a", "", "ctr", 0x0},    // not nibble-aligned
+		{"2001:db8::/64", "namespace,app,image", "", "", "sha256:abcdef0123456789aabbccddeeff00112233445566778899aabbccddeeff0011", "", 0xa},
+		{"2001:db8::/64", "namespace,app,image", "", "", "traefik:v3.5", "ctr", 0xa},
+		{"2001:db8::/64", "namespace,app,image", "", "", "", "ctr", 0xa},
 		{"2001:db8::/64", "namespace", "🦆", "🐧", "", "", 0},
-		{"2001:db8::/64", "namespace", "ns\x00\x00", "p", "", "", 0},
+		{"2001:db8::/64", "namespace", "ns\x00\x00", "a", "", "", 0},
 	} {
-		f.Add(s.prefix, s.fields, s.ns, s.pod, s.image, s.fallback, s.nNibble)
+		f.Add(s.prefix, s.fields, s.ns, s.app, s.image, s.fallback, s.nNibble)
 	}
 
-	f.Fuzz(func(t *testing.T, prefix, fieldsStr, ns, pod, image, fallback string, nNibble byte) {
+	f.Fuzz(func(t *testing.T, prefix, fieldsStr, ns, app, image, fallback string, nNibble byte) {
 		_, network, err := net.ParseCIDR(prefix)
 		if err != nil {
 			return
@@ -44,7 +45,7 @@ func FuzzEmbed(f *testing.F) {
 		}
 		got, err := Embed(network, fields, Values{
 			Namespace:     ns,
-			Pod:           pod,
+			App:           app,
 			Image:         image,
 			ImageFallback: fallback,
 		}, nNibble)
@@ -74,8 +75,8 @@ func decodeFields(s string) ([]Field, bool) {
 		switch string(cur) {
 		case string(FieldNamespace):
 			out = append(out, FieldNamespace)
-		case string(FieldPod):
-			out = append(out, FieldPod)
+		case string(FieldApp):
+			out = append(out, FieldApp)
 		case string(FieldImage):
 			out = append(out, FieldImage)
 		default:

pkg/embed/suffix_test.go

@@ -70,8 +70,8 @@ func TestEmbed_Slash64Deterministic(t *testing.T) {
 	// /64 with 3 fields: 5+5+5+1 nibbles = 64-bit IID.
 	net64 := mustCIDR(t, "2602:817:3000:f001::/64")
 	addr, err := Embed(net64,
-		[]Field{FieldNamespace, FieldPod, FieldImage},
-		Values{Namespace: "mail", Pod: "stalwart-0", ImageFallback: "container-abc"},
+		[]Field{FieldNamespace, FieldApp, FieldImage},
+		Values{Namespace: "mail", App: "stalwart", ImageFallback: "container-abc"},
 		0xe,
 	)
 	if err != nil {
@@ -79,8 +79,8 @@ func TestEmbed_Slash64Deterministic(t *testing.T) {
 	}
 	// Property: same inputs → same output (twice).
 	addr2, err := Embed(net64,
-		[]Field{FieldNamespace, FieldPod, FieldImage},
-		Values{Namespace: "mail", Pod: "stalwart-0", ImageFallback: "container-abc"},
+		[]Field{FieldNamespace, FieldApp, FieldImage},
+		Values{Namespace: "mail", App: "stalwart", ImageFallback: "container-abc"},
 		0xe,
 	)
 	if err != nil {
@@ -101,8 +101,8 @@ func TestEmbed_Slash64Deterministic(t *testing.T) {
 
 func TestEmbed_DifferentInputsDifferentOutputs(t *testing.T) {
 	net64 := mustCIDR(t, "2602:817:3000:f001::/64")
-	a, _ := Embed(net64, []Field{FieldNamespace, FieldPod}, Values{Namespace: "ns1", Pod: "p1"}, 0)
-	b, _ := Embed(net64, []Field{FieldNamespace, FieldPod}, Values{Namespace: "ns2", Pod: "p1"}, 0)
+	a, _ := Embed(net64, []Field{FieldNamespace, FieldApp}, Values{Namespace: "ns1", App: "p1"}, 0)
+	b, _ := Embed(net64, []Field{FieldNamespace, FieldApp}, Values{Namespace: "ns2", App: "p1"}, 0)
 	if a.Equal(b) {
 		t.Fatalf("different namespace produced identical IID: %s", a)
 	}