feat(cluster): profile-aware cluster-replica-validity-factor

Cache renders `cluster-replica-validity-factor 0`, disabling the
replica-validity gate so a replica failovers regardless of how stale its
last primary contact was (availability-first — avoids a stuck shard under a
partition/chaos window where node-timeout*factor elapses and no replica is
"valid"). Durable keeps Valkey's default gate (factor 10) so it never
promotes an arbitrarily-stale replica and silently loses acked writes. Old,
stable directive — no version gate. Overridable via spec.config.

Confirmed upstream (valkey-io/valkey-operator #216 / PR #222).

Author: melancholictheory

docs/valkey-compatibility.md

@@ -15,9 +15,14 @@ operator does not bundle Valkey.
   Probed on k3d. On **9.1+** the operator **uses Atomic Slot Migration**
   for all rebalance/reshard operations (version-gated `asmDetectSnippet`,
   `--cluster-use-atomic-slot-migration`; on <9.1 — classic key-by-key reshard;
-  see [adr/0001](adr/0001-atomic-slot-migration.md)). On 9.x it also renders
-  version-gated resilience directives: `cluster-allow-replica-migration no`,
-  `shutdown-on-sigterm failover` (≥9.0), `tls-auto-reload-interval` (TLS+≥9.1).
+  see [adr/0001](adr/0001-atomic-slot-migration.md)). The operator also renders
+  Cluster resilience directives. Version-agnostic (all versions):
+  `cluster-allow-replica-migration no`, and — for the **Cache** profile only —
+  `cluster-replica-validity-factor 0` (availability-first: a stale replica can
+  still win an election, avoiding a stuck shard; **Durable** keeps Valkey's
+  default gate so it never promotes a replica that would silently lose acked
+  writes). Version-gated: `shutdown-on-sigterm failover` (≥9.0) and
+  `tls-auto-reload-interval` (TLS+≥9.1).
 - **7.x** works (the cluster-specific features of 8/9 are not required), but is legacy.
 
 ## What to check when bumping the Valkey major

internal/controller/resources.go

@@ -382,6 +382,21 @@ func renderValkeyConf(vc *cachev1beta1.ValkeyCluster, password string) string {
 		// on all versions. Confirmed by upstream maintainer (valkey-operator #216).
 		// Overridable via spec.config.
 		fmt.Fprintf(&b, "cluster-allow-replica-migration no\n")
+		// Cache profile is availability-first: disable the replica-validity gate
+		// (factor 0) so a replica will failover regardless of how stale its last
+		// contact with the primary was — the same trade-off as
+		// cluster-require-full-coverage no. The default gate (factor 10) refuses to
+		// promote a replica once (now - last_primary_contact) exceeds
+		// cluster-node-timeout * factor + repl-ping-replica-period, which under a
+		// partition/chaos window can leave NO valid replica and a stuck shard with
+		// no election. Durable keeps the default gate: promoting an arbitrarily
+		// stale replica would silently lose acknowledged writes, violating the
+		// Durable contract. Old, stable directive (accepted on all versions, no
+		// gate). Overridable via spec.config. Confirmed upstream (valkey-operator
+		// #216 / PR #222).
+		if vc.Spec.Profile != cachev1beta1.ProfileDurable {
+			fmt.Fprintf(&b, "cluster-replica-validity-factor 0\n")
+		}
 		// Valkey 9.0+: on SIGTERM a cluster primary does a graceful manual failover
 		// to an up-to-date replica before shutting down — a node-local safety net
 		// for OUT-OF-BAND descheduling (node drain / eviction / preemption /

internal/controller/resources_test.go

@@ -1112,6 +1112,46 @@ func TestRenderValkeyConfVersionGatedDirectives(t *testing.T) {
 	}
 }
 
+func TestRenderValkeyConfReplicaValidityFactor(t *testing.T) {
+	mk := func(profile cachev1beta1.Profile, topo cachev1beta1.Topology, image string) *cachev1beta1.ValkeyCluster {
+		vc := minimalCR()
+		vc.Spec.Topology = topo
+		vc.Spec.Shards = ptr.To[int32](3)
+		vc.Spec.Profile = profile
+		if image != "" {
+			vc.Spec.Image = image
+		}
+		return vc
+	}
+
+	// Cache is availability-first: disable the replica-validity gate so a stale
+	// replica can still win an election (avoids a stuck shard). Any Valkey
+	// version — old, stable directive, no version gate.
+	for _, img := range []string{"valkey/valkey:8.0", "valkey/valkey:9.1"} {
+		if c := renderValkeyConf(mk(cachev1beta1.ProfileCache, cachev1beta1.TopologyCluster, img), ""); !strings.Contains(c, "cluster-replica-validity-factor 0") {
+			t.Errorf("%s Cache/Cluster must set cluster-replica-validity-factor 0\n%s", img, c)
+		}
+	}
+
+	// Durable keeps the default gate (nothing emitted): promoting an
+	// arbitrarily-stale replica would silently lose acknowledged writes.
+	if c := renderValkeyConf(mk(cachev1beta1.ProfileDurable, cachev1beta1.TopologyCluster, ""), ""); strings.Contains(c, "cluster-replica-validity-factor") {
+		t.Errorf("Durable/Cluster must NOT override the validity gate\n%s", c)
+	}
+
+	// Only Cluster topology gets the directive.
+	if c := renderValkeyConf(mk(cachev1beta1.ProfileCache, cachev1beta1.TopologyReplication, ""), ""); strings.Contains(c, "cluster-replica-validity-factor") {
+		t.Errorf("non-Cluster must not get cluster-replica-validity-factor\n%s", c)
+	}
+
+	// spec.config overrides the operator default (rendered last → wins).
+	over := mk(cachev1beta1.ProfileCache, cachev1beta1.TopologyCluster, "")
+	over.Spec.Config = map[string]string{"cluster-replica-validity-factor": "10"}
+	if c := renderValkeyConf(over, ""); !strings.Contains(c, "cluster-replica-validity-factor 10") {
+		t.Errorf("spec.config must be able to override the validity factor\n%s", c)
+	}
+}
+
 func TestReshardScriptsUseASMFlag(t *testing.T) {
 	mkVC := func(perShard bool) *cachev1beta1.ValkeyCluster {
 		vc := &cachev1beta1.ValkeyCluster{