doc: deprecate _primary and _replica shard option (#26792)

Tells v6 users that we are going to remove these options in v7.

Relates #26335

Author: dnhatn

core/src/main/java/org/elasticsearch/cluster/routing/OperationRouting.java

@@ -199,12 +199,20 @@ private ShardIterator preferenceActiveShardIterator(IndexShardRoutingTable index
                 case LOCAL:
                     return indexShard.preferNodeActiveInitializingShardsIt(Collections.singleton(localNodeId));
                 case PRIMARY:
+                    deprecationLogger.deprecated("[_primary] has been deprecated in 6.1+, and will be removed in 7.0; " +
+                        "use [_only_nodes] or [_prefer_nodes]");
                     return indexShard.primaryActiveInitializingShardIt();
                 case REPLICA:
+                    deprecationLogger.deprecated("[_replica] has been deprecated in 6.1+, and will be removed in 7.0; " +
+                        "use [_only_nodes] or [_prefer_nodes]");
                     return indexShard.replicaActiveInitializingShardIt();
                 case PRIMARY_FIRST:
+                    deprecationLogger.deprecated("[_primary_first] has been deprecated in 6.1+, and will be removed in 7.0; " +
+                        "use [_only_nodes] or [_prefer_nodes]");
                     return indexShard.primaryFirstActiveInitializingShardsIt();
                 case REPLICA_FIRST:
+                    deprecationLogger.deprecated("[_replica_first] has been deprecated in 6.1+, and will be removed in 7.0; " +
+                        "use [_only_nodes] or [_prefer_nodes]");
                     return indexShard.replicaFirstActiveInitializingShardsIt();
                 case ONLY_LOCAL:
                     return indexShard.onlyNodeActiveInitializingShardsIt(localNodeId);

core/src/test/java/org/elasticsearch/cluster/structure/RoutingIteratorTests.java

@@ -444,6 +444,7 @@ public void testReplicaShardPreferenceIters() throws Exception {
 
         // When replicas haven't initialized, it comes back with the primary first, then initializing replicas
         GroupShardsIterator<ShardIterator> shardIterators = operationRouting.searchShards(clusterState, new String[]{"test"}, null, "_replica_first");
+        assertWarnings("[_replica_first] has been deprecated in 6.1+, and will be removed in 7.0; use [_only_nodes] or [_prefer_nodes]");
         assertThat(shardIterators.size(), equalTo(2)); // two potential shards
         ShardIterator iter = shardIterators.iterator().next();
         assertThat(iter.size(), equalTo(3)); // three potential candidates for the shard
@@ -463,10 +464,8 @@ public void testReplicaShardPreferenceIters() throws Exception {
 
         clusterState = strategy.applyStartedShards(clusterState, clusterState.getRoutingNodes().shardsWithState(INITIALIZING));
 
-        clusterState = strategy.applyStartedShards(clusterState, clusterState.getRoutingNodes().shardsWithState(INITIALIZING));
-
-
         shardIterators = operationRouting.searchShards(clusterState, new String[]{"test"}, null, "_replica");
+        assertWarnings("[_replica] has been deprecated in 6.1+, and will be removed in 7.0; use [_only_nodes] or [_prefer_nodes]");
         assertThat(shardIterators.size(), equalTo(2)); // two potential shards
         iter = shardIterators.iterator().next();
         assertThat(iter.size(), equalTo(2)); // two potential replicas for the shard
@@ -479,6 +478,7 @@ public void testReplicaShardPreferenceIters() throws Exception {
         assertFalse(routing.primary());
 
         shardIterators = operationRouting.searchShards(clusterState, new String[]{"test"}, null, "_replica_first");
+        assertWarnings("[_replica_first] has been deprecated in 6.1+, and will be removed in 7.0; use [_only_nodes] or [_prefer_nodes]");
         assertThat(shardIterators.size(), equalTo(2)); // two potential shards
         iter = shardIterators.iterator().next();
         assertThat(iter.size(), equalTo(3)); // three potential candidates for the shard
@@ -495,4 +495,45 @@ public void testReplicaShardPreferenceIters() throws Exception {
         assertTrue(routing.primary());
     }
 
+    public void testDeprecatedPreferences() throws Exception {
+        AllocationService strategy = createAllocationService(Settings.builder()
+            .put("cluster.routing.allocation.node_concurrent_recoveries", 10)
+            .build());
+
+        OperationRouting operationRouting = new OperationRouting(Settings.EMPTY, new ClusterSettings(Settings.EMPTY,
+            ClusterSettings.BUILT_IN_CLUSTER_SETTINGS));
+
+        MetaData metaData = MetaData.builder()
+            .put(IndexMetaData.builder("test").settings(settings(Version.CURRENT)).numberOfShards(2).numberOfReplicas(2))
+            .build();
+
+        RoutingTable routingTable = RoutingTable.builder()
+            .addAsNew(metaData.index("test"))
+            .build();
+
+        ClusterState clusterState = ClusterState.builder(ClusterName.CLUSTER_NAME_SETTING.getDefault(Settings.EMPTY))
+            .metaData(metaData)
+            .routingTable(routingTable)
+            .build();
+
+        clusterState = ClusterState.builder(clusterState).nodes(DiscoveryNodes.builder()
+            .add(newNode("node1"))
+            .add(newNode("node2"))
+            .localNodeId("node1")
+        ).build();
+
+        clusterState = strategy.applyStartedShards(clusterState, clusterState.getRoutingNodes().shardsWithState(INITIALIZING));
+
+        operationRouting.searchShards(clusterState, new String[]{"test"}, null, "_primary");
+        assertWarnings("[_primary] has been deprecated in 6.1+, and will be removed in 7.0; use [_only_nodes] or [_prefer_nodes]");
+
+        operationRouting.searchShards(clusterState, new String[]{"test"}, null, "_primary_first");
+        assertWarnings("[_primary_first] has been deprecated in 6.1+, and will be removed in 7.0; use [_only_nodes] or [_prefer_nodes]");
+
+        operationRouting.searchShards(clusterState, new String[]{"test"}, null, "_replica");
+        assertWarnings("[_replica] has been deprecated in 6.1+, and will be removed in 7.0; use [_only_nodes] or [_prefer_nodes]");
+
+        operationRouting.searchShards(clusterState, new String[]{"test"}, null, "_replica_first");
+        assertWarnings("[_replica_first] has been deprecated in 6.1+, and will be removed in 7.0; use [_only_nodes] or [_prefer_nodes]");
+    }
 }

docs/reference/search/request/preference.asciidoc

@@ -9,18 +9,21 @@ The `preference` is a query string parameter which can be set to:
 [horizontal]
 `_primary`:: 
 	The operation will go and be executed only on the primary
-	shards.
+	shards. deprecated[6.1.0, will be removed in 7.0, use `_only_nodes` or `_prefer_nodes`]
 
 `_primary_first`:: 
 	The operation will go and be executed on the primary
 	shard, and if not available (failover), will execute on other shards.
+	deprecated[6.1.0, will be removed in 7.0, use `_only_nodes` or `_prefer_nodes`]
 
 `_replica`::
   The operation will go and be executed only on a replica shard.
+  deprecated[6.1.0, will be removed in 7.0, use `_only_nodes` or `_prefer_nodes`]
 
 `_replica_first`::
   The operation will go and be executed only on a replica shard, and if
   not available (failover), will execute on other shards.
+  deprecated[6.1.0, will be removed in 7.0, use `_only_nodes` or `_prefer_nodes`]
 
 `_local`:: 
 	The operation will prefer to be executed on a local
@@ -33,7 +36,7 @@ The `preference` is a query string parameter which can be set to:
 `_shards:2,3`:: 
 	Restricts the operation to the specified shards. (`2`
 	and `3` in this case). This preference can be combined with other
-	preferences but it has to appear first: `_shards:2,3|_primary`
+	preferences but it has to appear first: `_shards:2,3|_local`
 
 `_only_nodes`::
     Restricts the operation to nodes specified in <<cluster,node specification>>

rest-api-spec/src/main/resources/rest-api-spec/test/bulk/20_list_of_strings.yml

@@ -1,5 +1,10 @@
 ---
 "List of strings":
+  - skip:
+      version: " - 6.0.99"
+      reason:  '[_primary] shard preference deprecated in 6.1+'
+      features: "warnings"
+
   - do:
       bulk:
         refresh: true
@@ -14,6 +19,9 @@
         # we count through the primary in case there is a replica that has not yet fully recovered
         preference: _primary
         index: test_index
+      warnings:
+        - "[_primary] has been deprecated in 6.1+, and will be removed in 7.0; use [_only_nodes] or [_prefer_nodes]"
+
 
   - match: {count: 2}