add yes-not-preferred allocation decision

mhl-b · mhl-b · commit b40821ae8062 · 2025-08-20T12:11:30.000-07:00
diff --git a/server/src/main/java/org/elasticsearch/TransportVersions.java b/server/src/main/java/org/elasticsearch/TransportVersions.java
@@ -366,6 +366,7 @@ static TransportVersion def(int id) {
     public static final TransportVersion SIMULATE_INGEST_EFFECTIVE_MAPPING = def(9_140_0_00);
     public static final TransportVersion RESOLVE_INDEX_MODE_ADDED = def(9_141_0_00);
     public static final TransportVersion DATA_STREAM_WRITE_INDEX_ONLY_SETTINGS = def(9_142_0_00);
+    public static final TransportVersion ALLOCATION_DECISION_YES_NOT_PREFERRED = def(9_143_0_00);
 
     /*
      * STOP! READ THIS FIRST! No, really,
diff --git a/server/src/main/java/org/elasticsearch/cluster/routing/allocation/decider/AllocationDeciders.java b/server/src/main/java/org/elasticsearch/cluster/routing/allocation/decider/AllocationDeciders.java
@@ -205,27 +205,37 @@ private Decision withDeciders(
         BiFunction<String, Decision, String> logMessageCreator
     ) {
         if (debugMode == RoutingAllocation.DebugMode.OFF) {
-            Decision result = Decision.YES;
+            Decision finalDecision = Decision.YES;
+            Decision.Preferred preferred = Decision.Preferred.YES;
             for (AllocationDecider decider : deciders) {
                 var decision = deciderAction.apply(decider);
                 if (decision.type() == Decision.Type.NO) {
                     if (logger.isTraceEnabled()) {
                         logger.trace(() -> logMessageCreator.apply(decider.getClass().getSimpleName(), decision));
                     }
                     return decision;
-                } else if (result.type() == Decision.Type.YES && decision.type() == Decision.Type.THROTTLE) {
-                    result = decision;
+                } else if (finalDecision.type() == Decision.Type.YES && decision.type() == Decision.Type.THROTTLE) {
+                    finalDecision = decision;
+                } else if (decision.preferred() == Decision.Preferred.NO) {
+                    preferred = Decision.Preferred.NO;
                 }
             }
-            return result;
+            if (finalDecision.type() == Decision.Type.YES && preferred == Decision.Preferred.NO) {
+                return Decision.YES_NOT_PREFERRED;
+            } else {
+                return finalDecision;
+            }
         } else {
             var result = new Decision.Multi();
             for (AllocationDecider decider : deciders) {
                 var decision = deciderAction.apply(decider);
                 if (logger.isTraceEnabled() && decision.type() == Decision.Type.NO) {
                     logger.trace(() -> logMessageCreator.apply(decider.getClass().getSimpleName(), decision));
                 }
-                if (decision != Decision.ALWAYS && (debugMode == RoutingAllocation.DebugMode.ON || decision.type() != Decision.Type.YES)) {
+                if (decision != Decision.ALWAYS
+                    && (debugMode == RoutingAllocation.DebugMode.ON
+                        || decision.type() != Decision.Type.YES
+                        || decision.preferred() != Decision.Preferred.YES)) {
                     result.add(decision);
                 }
             }
diff --git a/server/src/main/java/org/elasticsearch/cluster/routing/allocation/decider/Decision.java b/server/src/main/java/org/elasticsearch/cluster/routing/allocation/decider/Decision.java
@@ -9,6 +9,7 @@
 
 package org.elasticsearch.cluster.routing.allocation.decider;
 
+import org.elasticsearch.TransportVersions;
 import org.elasticsearch.common.io.stream.StreamInput;
 import org.elasticsearch.common.io.stream.StreamOutput;
 import org.elasticsearch.common.io.stream.Writeable;
@@ -33,6 +34,7 @@ public sealed interface Decision extends ToXContent, Writeable permits Decision.
 
     Single ALWAYS = new Single(Type.YES);
     Single YES = new Single(Type.YES);
+    Single YES_NOT_PREFERRED = new Single(Type.YES, Preferred.NO);
     Single NO = new Single(Type.NO);
     Single THROTTLE = new Single(Type.THROTTLE);
 
@@ -48,6 +50,28 @@ static Decision single(Type type, @Nullable String label, @Nullable String expla
         return new Single(type, label, explanation, explanationParams);
     }
 
+    /**
+     * Creates YES/PREFERRED decision
+     * @param label label for the Decider that produced this decision
+     * @param explanation explanation of the decision
+     * @param explanationParams additional parameters for the decision
+     * @return new {@link Decision} instance
+     */
+    static Decision preferred(@Nullable String label, @Nullable String explanation, @Nullable Object... explanationParams) {
+        return new Single(Type.YES, Preferred.YES, label, explanation, explanationParams);
+    }
+
+    /**
+     * Creates YES/NOT-PREFERRED decision
+     * @param label label for the Decider that produced this decision
+     * @param explanation explanation of the decision
+     * @param explanationParams additional parameters for the decision
+     * @return new {@link Decision} instance
+     */
+    static Decision notPreferred(@Nullable String label, @Nullable String explanation, @Nullable Object... explanationParams) {
+        return new Single(Type.YES, Preferred.NO, label, explanation, explanationParams);
+    }
+
     static Decision readFrom(StreamInput in) throws IOException {
         // Determine whether to read a Single or Multi Decision
         if (in.readBoolean()) {
@@ -67,16 +91,20 @@ static Decision readFrom(StreamInput in) throws IOException {
 
     private static Single readSingleFrom(StreamInput in) throws IOException {
         final Type type = Type.readFrom(in);
+        Preferred preferred = type == Type.YES ?  Preferred.YES : Preferred.NO;
+        if (in.getTransportVersion().onOrAfter(TransportVersions.ALLOCATION_DECISION_YES_NOT_PREFERRED)) {
+            preferred = in.readEnum(Preferred.class);
+        }
         final String label = in.readOptionalString();
         final String explanation = in.readOptionalString();
         if (label == null && explanation == null) {
             return switch (type) {
-                case YES -> YES;
+                case YES -> preferred == Preferred.YES ? YES : YES_NOT_PREFERRED;
                 case THROTTLE -> THROTTLE;
                 case NO -> NO;
             };
         }
-        return new Single(type, label, explanation);
+        return new Single(type, preferred, label, explanation);
     }
 
     /**
@@ -85,6 +113,11 @@ private static Single readSingleFrom(StreamInput in) throws IOException {
      */
     Type type();
 
+    /**
+     * @return {@link Preferred}, a soft yes/no
+     */
+    Preferred preferred();
+
     /**
      * Get the description label for this decision.
      */
@@ -149,10 +182,22 @@ public static Type min(Type a, Type b) {
 
     }
 
+    /**
+     * Preferred indicates if allocation is favorable. It's a soft YES/NO, means allocation is still possible when not-preferred.
+     */
+    enum Preferred {
+        NO,
+        YES
+    }
+
     /**
      * Simple class representing a single decision
      */
-    record Single(Type type, String label, String explanationString) implements Decision, ToXContentObject {
+    record Single(Type type, Preferred preferred, String label, String explanationString) implements Decision, ToXContentObject {
+        public Single {
+            assert type == Type.YES || preferred == Preferred.NO : "only YES type can have preference";
+        }
+
         /**
          * Creates a new {@link Single} decision of a given type
          * @param type {@link Type} of the decision
@@ -161,6 +206,10 @@ private Single(Type type) {
             this(type, null, null, (Object[]) null);
         }
 
+        private Single(Type type, Preferred preferred) {
+            this(type, preferred, null, null, (Object[]) null);
+        }
+
         /**
          * Creates a new {@link Single} decision of a given type
          *
@@ -169,8 +218,27 @@ private Single(Type type) {
          * @param explanationParams A set of additional parameters
          */
         public Single(Type type, @Nullable String label, @Nullable String explanation, @Nullable Object... explanationParams) {
+            this(type, type == Type.YES ? Preferred.YES : Preferred.NO, label, explanation, explanationParams);
+        }
+
+        /**
+         * Creates a new {@link Single} decision of a given type
+         *
+         * @param type {@link Type} of the decision
+         * @param preferred {@link Preferred} soft yes/no
+         * @param explanation An explanation of this {@link Decision}
+         * @param explanationParams A set of additional parameters
+         */
+        public Single(
+            Type type,
+            Preferred preferred,
+            @Nullable String label,
+            @Nullable String explanation,
+            @Nullable Object... explanationParams
+        ) {
             this(
                 type,
+                preferred,
                 label,
                 explanationParams != null && explanationParams.length > 0
                     ? String.format(Locale.ROOT, explanation, explanationParams)
@@ -194,10 +262,11 @@ public String getExplanation() {
 
         @Override
         public String toString() {
+            var preference = type == Type.YES && preferred == Preferred.NO ? "_NOT_PREFERRED" : "";
             if (explanationString != null) {
-                return type + "(" + explanationString + ")";
+                return type + preference + "(" + explanationString + ")";
             }
-            return type + "()";
+            return type + preference + "()";
         }
 
         @Override
@@ -214,6 +283,9 @@ public XContentBuilder toXContent(XContentBuilder builder, Params params) throws
         public void writeTo(StreamOutput out) throws IOException {
             out.writeBoolean(false); // flag specifying its a single decision
             type.writeTo(out);
+            if (out.getTransportVersion().onOrAfter(TransportVersions.ALLOCATION_DECISION_YES_NOT_PREFERRED)) {
+                out.writeEnum(preferred);
+            }
             out.writeOptionalString(label);
             // Flatten explanation on serialization, so that explanationParams
             // do not need to be serialized
@@ -255,6 +327,16 @@ public Type type() {
             return ret;
         }
 
+        @Override
+        public Preferred preferred() {
+            for (var decision : decisions) {
+                if (decision.type() != Type.YES || decision.preferred() == Preferred.NO) {
+                    return Preferred.NO;
+                }
+            }
+            return Preferred.YES;
+        }
+
         @Override
         @Nullable
         public String label() {
diff --git a/server/src/main/java/org/elasticsearch/cluster/routing/allocation/decider/WriteLoadConstraintDecider.java b/server/src/main/java/org/elasticsearch/cluster/routing/allocation/decider/WriteLoadConstraintDecider.java
@@ -73,7 +73,7 @@ public Decision canAllocate(ShardRouting shardRouting, RoutingNode node, Routing
                 shardRouting.shardId()
             );
             logger.debug(explain);
-            return Decision.single(Decision.Type.NO, NAME, explain);
+            return Decision.notPreferred(NAME, explain);
         }
 
         if (calculateShardMovementChange(nodeWriteThreadPoolStats, shardWriteLoad) >= nodeWriteThreadPoolLoadThreshold) {
@@ -92,7 +92,7 @@ public Decision canAllocate(ShardRouting shardRouting, RoutingNode node, Routing
                 nodeWriteThreadPoolStats.totalThreadPoolThreads()
             );
             logger.debug(explain);
-            return Decision.single(Decision.Type.NO, NAME, explain);
+            return Decision.notPreferred(NAME, explain);
         }
 
         return Decision.YES;
@@ -101,12 +101,12 @@ public Decision canAllocate(ShardRouting shardRouting, RoutingNode node, Routing
     @Override
     public Decision canRemain(IndexMetadata indexMetadata, ShardRouting shardRouting, RoutingNode node, RoutingAllocation allocation) {
         if (writeLoadConstraintSettings.getWriteLoadConstraintEnabled().notFullyEnabled()) {
-            return Decision.single(Decision.Type.YES, NAME, "canRemain() is not enabled");
+            return Decision.preferred(NAME, "canRemain() is not enabled");
         }
 
         // TODO: implement
 
-        return Decision.single(Decision.Type.YES, NAME, "canRemain() is not yet implemented");
+        return Decision.preferred(NAME, "canRemain() is not yet implemented");
     }
 
     /**
diff --git a/server/src/test/java/org/elasticsearch/cluster/routing/allocation/decider/AllocationDecidersTests.java b/server/src/test/java/org/elasticsearch/cluster/routing/allocation/decider/AllocationDecidersTests.java
@@ -55,6 +55,17 @@ public void testCheckAllDecidersBeforeReturningYes() {
         verifyDecidersCall(debugMode, allDecisions, allDecisions.size(), expectedDecision);
     }
 
+    public void testCheckAllDecidersBeforeReturningYesNotPreferred() {
+        var debugMode = randomFrom(RoutingAllocation.DebugMode.values());
+        var allDecisions = generateDecisions(Decision.YES_NOT_PREFERRED, () -> Decision.YES);
+        var expectedDecision = switch (debugMode) {
+            case OFF -> Decision.YES_NOT_PREFERRED;
+            case EXCLUDE_YES_DECISIONS -> collectToMultiDecision(allDecisions, decision -> decision.preferred() != Decision.Preferred.YES);
+            case ON -> collectToMultiDecision(allDecisions);
+        };
+        verifyDecidersCall(debugMode, allDecisions, allDecisions.size(), expectedDecision);
+    }
+
     public void testCheckAllDecidersBeforeReturningThrottle() {
         var allDecisions = generateDecisions(Decision.THROTTLE, () -> Decision.YES);
         var debugMode = randomFrom(RoutingAllocation.DebugMode.values());
@@ -69,7 +80,10 @@ public void testCheckAllDecidersBeforeReturningThrottle() {
 
     public void testExitsAfterFirstNoDecision() {
         var expectedDecision = randomFrom(Decision.NO, Decision.single(Decision.Type.NO, "no with label", "explanation"));
-        var allDecisions = generateDecisions(expectedDecision, () -> randomFrom(Decision.YES, Decision.THROTTLE));
+        var allDecisions = generateDecisions(
+            expectedDecision,
+            () -> randomFrom(Decision.YES, Decision.YES_NOT_PREFERRED, Decision.THROTTLE)
+        );
         var expectedCalls = allDecisions.indexOf(expectedDecision) + 1;
 
         verifyDecidersCall(RoutingAllocation.DebugMode.OFF, allDecisions, expectedCalls, expectedDecision);
@@ -79,6 +93,7 @@ public void testCollectsAllDecisionsForDebugModeOn() {
         var allDecisions = generateDecisions(
             () -> randomFrom(
                 Decision.YES,
+                Decision.YES_NOT_PREFERRED,
                 Decision.THROTTLE,
                 Decision.single(Decision.Type.THROTTLE, "throttle with label", "explanation"),
                 Decision.NO,
@@ -94,13 +109,17 @@ public void testCollectsNoAndThrottleDecisionsForDebugModeExcludeYesDecisions()
         var allDecisions = generateDecisions(
             () -> randomFrom(
                 Decision.YES,
+                Decision.YES_NOT_PREFERRED,
                 Decision.THROTTLE,
                 Decision.single(Decision.Type.THROTTLE, "throttle with label", "explanation"),
                 Decision.NO,
                 Decision.single(Decision.Type.NO, "no with label", "explanation")
             )
         );
-        var expectedDecision = collectToMultiDecision(allDecisions, decision -> decision.type() != Decision.Type.YES);
+        var expectedDecision = collectToMultiDecision(
+            allDecisions,
+            decision -> decision.type() != Decision.Type.YES || decision.preferred() != Decision.Preferred.YES
+        );
 
         verifyDecidersCall(RoutingAllocation.DebugMode.EXCLUDE_YES_DECISIONS, allDecisions, allDecisions.size(), expectedDecision);
     }
diff --git a/server/src/test/java/org/elasticsearch/cluster/routing/allocation/decider/DecisionTests.java b/server/src/test/java/org/elasticsearch/cluster/routing/allocation/decider/DecisionTests.java
@@ -9,8 +9,13 @@
 
 package org.elasticsearch.cluster.routing.allocation.decider;
 
+import org.elasticsearch.TransportVersions;
 import org.elasticsearch.cluster.routing.allocation.decider.Decision.Type;
-import org.elasticsearch.test.ESTestCase;
+import org.elasticsearch.common.io.stream.Writeable;
+import org.elasticsearch.test.AbstractWireSerializingTestCase;
+import org.elasticsearch.test.TransportVersionUtils;
+
+import java.io.IOException;
 
 import static org.elasticsearch.cluster.routing.allocation.decider.Decision.Type.NO;
 import static org.elasticsearch.cluster.routing.allocation.decider.Decision.Type.THROTTLE;
@@ -19,7 +24,7 @@
 /**
  * A class for unit testing the {@link Decision} class.
  */
-public class DecisionTests extends ESTestCase {
+public class DecisionTests extends AbstractWireSerializingTestCase<Decision> {
 
     /**
      * Tests {@link Type#higherThan(Type)}
@@ -40,4 +45,41 @@ public void testHigherThan() {
         assertFalse(NO.higherThan(THROTTLE));
         assertFalse(NO.higherThan(YES));
     }
+
+    public void testNotPreferredSerializationBeforeVersion() throws IOException {
+        var inDecision = Decision.YES_NOT_PREFERRED;
+        var outDecision = copyInstance(
+            inDecision,
+            TransportVersionUtils.getPreviousVersion(TransportVersions.ALLOCATION_DECISION_YES_NOT_PREFERRED)
+        );
+        assertEquals("should fallback to always-preferred in prior versions", Decision.YES, outDecision);
+
+        inDecision = Decision.NO;
+        outDecision = copyInstance(
+            inDecision,
+            TransportVersionUtils.getPreviousVersion(TransportVersions.ALLOCATION_DECISION_YES_NOT_PREFERRED)
+        );
+        assertEquals(Decision.NO, outDecision);
+    }
+
+    public void testNotPreferredSerialization() throws IOException {
+        var inDecision = Decision.YES_NOT_PREFERRED;
+        var outDecision = copyInstance(inDecision, TransportVersions.ALLOCATION_DECISION_YES_NOT_PREFERRED);
+        assertEquals(inDecision, outDecision);
+    }
+
+    @Override
+    protected Writeable.Reader<Decision> instanceReader() {
+        return Decision::readFrom;
+    }
+
+    @Override
+    protected Decision createTestInstance() {
+        return Decision.single(YES, "label", "explanation", "param1", 2);
+    }
+
+    @Override
+    protected Decision mutateInstance(Decision instance) throws IOException {
+        return instance.type() == YES ? Decision.NO : Decision.YES;
+    }
 }
diff --git a/server/src/test/java/org/elasticsearch/cluster/routing/allocation/decider/WriteLoadConstraintDeciderTests.java b/server/src/test/java/org/elasticsearch/cluster/routing/allocation/decider/WriteLoadConstraintDeciderTests.java
diff --git a/x-pack/plugin/autoscaling/src/test/java/org/elasticsearch/xpack/autoscaling/storage/NodeDecisionTestUtils.java b/x-pack/plugin/autoscaling/src/test/java/org/elasticsearch/xpack/autoscaling/storage/NodeDecisionTestUtils.java
