Add link to allocation explain setting conflict message

docs/reference/cluster/allocation-explain.asciidoc

@@ -81,6 +81,7 @@ you might expect otherwise.
 
 ===== Unassigned primary shard
 
+[[allocation-explain-setting-conflict]]
 ====== Conflicting settings
 The following request gets an allocation explanation for an unassigned primary
 shard.

server/src/internalClusterTest/java/org/elasticsearch/action/admin/cluster/allocation/ClusterAllocationExplainIT.java

@@ -28,6 +28,7 @@
 import org.elasticsearch.cluster.routing.allocation.NodeAllocationResult;
 import org.elasticsearch.cluster.routing.allocation.decider.Decision;
 import org.elasticsearch.common.Priority;
+import org.elasticsearch.common.ReferenceDocs;
 import org.elasticsearch.common.Strings;
 import org.elasticsearch.common.settings.Settings;
 import org.elasticsearch.common.util.set.Sets;
@@ -359,8 +360,8 @@ public void testUnassignedReplicaWithPriorCopy() throws Exception {
                     assertEquals(Decision.Type.NO, d.type());
                     assertEquals(Strings.format("""
                         node does not match index setting [index.routing.allocation.include] \
-                        filters [_name:"%s"]\
-                        """, primaryNodeName), d.getExplanation());
+                        filters [_name:"%s"]; for more information, see [%s]\
+                        """, primaryNodeName, ReferenceDocs.ALLOCATION_EXPLAIN_SETTING_CONFLICT), d.getExplanation());
                 } else {
                     assertEquals(Decision.Type.YES, d.type());
                     assertNotNull(d.getExplanation());
@@ -460,10 +461,10 @@ public void testAllocationFilteringOnIndexCreation() throws Exception {
             for (Decision d : result.getCanAllocateDecision().getDecisions()) {
                 if (d.label().equals("filter")) {
                     assertEquals(Decision.Type.NO, d.type());
-                    assertEquals(
-                        "node does not match index setting [index.routing.allocation.include] filters [_name:\"non_existent_node\"]",
-                        d.getExplanation()
-                    );
+                    assertEquals(Strings.format("""
+                        node does not match index setting [index.routing.allocation.include] \
+                        filters [_name:\"non_existent_node\"]; for more information, see [%s]\
+                        """, ReferenceDocs.ALLOCATION_EXPLAIN_SETTING_CONFLICT), d.getExplanation());
                 }
             }
         }
@@ -551,7 +552,12 @@ public void testAllocationFilteringPreventsShardMove() throws Exception {
             if (d.label().equals("filter")) {
                 assertEquals(Decision.Type.NO, d.type());
                 assertEquals(
-                    "node does not match index setting [index.routing.allocation.include] filters [_name:\"non_existent_node\"]",
+                    Strings.format(
+                        """
+                            node does not match index setting [index.routing.allocation.include] \
+                            filters [_name:\"non_existent_node\"]; for more information, see [%s]""",
+                        ReferenceDocs.ALLOCATION_EXPLAIN_SETTING_CONFLICT
+                    ),
                     d.getExplanation()
                 );
             } else {
@@ -574,7 +580,12 @@ public void testAllocationFilteringPreventsShardMove() throws Exception {
             if (d.label().equals("filter")) {
                 assertEquals(Decision.Type.NO, d.type());
                 assertEquals(
-                    "node does not match index setting [index.routing.allocation.include] filters [_name:\"non_existent_node\"]",
+                    Strings.format(
+                        """
+                            node does not match index setting [index.routing.allocation.include] \
+                            filters [_name:\"non_existent_node\"]; for more information, see [%s]""",
+                        ReferenceDocs.ALLOCATION_EXPLAIN_SETTING_CONFLICT
+                    ),
                     d.getExplanation()
                 );
             } else {
@@ -883,9 +894,16 @@ public void testBetterBalanceButCannotAllocate() throws Exception {
         for (Decision d : result.getCanAllocateDecision().getDecisions()) {
             if (d.label().equals("filter")) {
                 assertEquals(Decision.Type.NO, d.type());
-                assertEquals(Strings.format("""
-                    node does not match index setting [index.routing.allocation.include] filters [_name:"%s"]\
-                    """, primaryNodeName), d.getExplanation());
+                assertEquals(
+                    Strings.format(
+                        """
+                            node does not match index setting [index.routing.allocation.include] \
+                            filters [_name:"%s"]; for more information, see [%s]""",
+                        primaryNodeName,
+                        ReferenceDocs.ALLOCATION_EXPLAIN_SETTING_CONFLICT
+                    ),
+                    d.getExplanation()
+                );
             } else {
                 assertEquals(Decision.Type.YES, d.type());
                 assertNotNull(d.getExplanation());

server/src/main/java/org/elasticsearch/cluster/routing/allocation/decider/FilterAllocationDecider.java

@@ -16,6 +16,7 @@
 import org.elasticsearch.cluster.routing.RoutingNode;
 import org.elasticsearch.cluster.routing.ShardRouting;
 import org.elasticsearch.cluster.routing.allocation.RoutingAllocation;
+import org.elasticsearch.common.ReferenceDocs;
 import org.elasticsearch.common.settings.ClusterSettings;
 import org.elasticsearch.common.settings.Setting;
 import org.elasticsearch.common.settings.Setting.Property;
@@ -150,9 +151,10 @@ private static Decision shouldIndexFilter(IndexMetadata indexMd, DiscoveryNode n
                 return allocation.decision(
                     Decision.NO,
                     NAME,
-                    "node does not match index setting [%s] filters [%s]",
+                    "node does not match index setting [%s] filters [%s]; for more information, see [%s]",
                     IndexMetadata.INDEX_ROUTING_REQUIRE_GROUP_PREFIX,
-                    indexRequireFilters
+                    indexRequireFilters,
+                    ReferenceDocs.ALLOCATION_EXPLAIN_SETTING_CONFLICT
                 );
             }
         }
@@ -161,9 +163,10 @@ private static Decision shouldIndexFilter(IndexMetadata indexMd, DiscoveryNode n
                 return allocation.decision(
                     Decision.NO,
                     NAME,
-                    "node does not match index setting [%s] filters [%s]",
+                    "node does not match index setting [%s] filters [%s]; for more information, see [%s]",
                     IndexMetadata.INDEX_ROUTING_INCLUDE_GROUP_PREFIX,
-                    indexIncludeFilters
+                    indexIncludeFilters,
+                    ReferenceDocs.ALLOCATION_EXPLAIN_SETTING_CONFLICT
                 );
             }
         }

server/src/main/java/org/elasticsearch/common/ReferenceDocs.java

@@ -83,6 +83,7 @@ public enum ReferenceDocs {
     ALLOCATION_EXPLAIN_NO_COPIES,
     ALLOCATION_EXPLAIN_MAX_RETRY,
     SECURE_SETTINGS,
+    ALLOCATION_EXPLAIN_SETTING_CONFLICT,
     // this comment keeps the ';' on the next line so every entry above has a trailing ',' which makes the diff for adding new links cleaner
     ;
 

server/src/main/resources/org/elasticsearch/common/reference-docs-links.txt

@@ -45,3 +45,4 @@ CIRCUIT_BREAKER_ERRORS                                          circuit-breaker-
 ALLOCATION_EXPLAIN_NO_COPIES                                    cluster-allocation-explain.html#no-valid-shard-copy
 ALLOCATION_EXPLAIN_MAX_RETRY                                    cluster-allocation-explain.html#maximum-number-of-retries-exceeded
 SECURE_SETTINGS                                                 secure-settings.html
+ALLOCATION_EXPLAIN_SETTING_CONFLICT                             cluster-allocation-explain.html#allocation-explain-setting-conflict