SOLR-13169 Improve docs for MOVEREPLICA (#1699)
(cherry picked from commit b00d747eb6a94ab5775258b032e621f998ec44ba)
(cherry picked from commit 396490b65ca1af6ff1f1157a9896c9528c234eea)
diff --git a/solr/solr-ref-guide/src/replica-management.adoc b/solr/solr-ref-guide/src/replica-management.adoc
index cf508c3..bc461c7 100644
--- a/solr/solr-ref-guide/src/replica-management.adoc
+++ b/solr/solr-ref-guide/src/replica-management.adoc
@@ -24,8 +24,6 @@
Add one or more replicas to a shard in a collection. The node name can be specified if the replica is to be created in a specific node. Otherwise, a set of nodes can be specified and the most suitable ones among them will be chosen to create the replica(s).
-The API uses the Autoscaling framework to find nodes that can satisfy the disk requirements for the new replica(s) but only when an Autoscaling preferences or policy is configured. Refer to <<solrcloud-autoscaling-policy-preferences.adoc#solrcloud-autoscaling-policy-preferences,Autoscaling Policy and Preferences>> section for more details.
-
`/admin/collections?action=ADDREPLICA&collection=_collection_&shard=_shard_&node=_nodeName_`
=== ADDREPLICA Parameters
@@ -158,32 +156,100 @@
[[movereplica]]
== MOVEREPLICA: Move a Replica to a New Node
-This command moves a replica from one node to a new node. In case of shared filesystems the `dataDir` will be reused.
+This command moves a replica from one node to another node by executing ADDREPLICA on the destination and then DELETEREPLICA on the source. If this command is interrupted or times out before the ADDREPLICA operation produces a replica in an active state, the DELETEREPLICA will not occur. Timeouts do not cancel the ADDREPLICA, and will result in extra shards. In case of shared filesystems the `dataDir` will be reused.
-The API uses the Autoscaling framework to find nodes that can satisfy the disk requirements for the replica to be moved but only when an Autoscaling policy is configured. Refer to <<solrcloud-autoscaling-policy-preferences.adoc#solrcloud-autoscaling-policy-preferences,Autoscaling Policy and Preferences>> section for more details.
+If this command is used on a collection where more than one replica from the same shard exists on the same node, and the `shard` and `sourceNode` parameters match more than one replica, the replica selected is not deterministic (currently it's random).
-`/admin/collections?action=MOVEREPLICA&collection=collection&shard=shard&replica=replica&sourceNode=nodeName&targetNode=nodeName`
+WARNING: MOVERREPLICA does not check the maxShardsPerNode setting, and may produce a collection that is in violation of the maxShardsPerNode.
=== MOVEREPLICA Parameters
`collection`::
The name of the collection. This parameter is required.
-`shard`::
-The name of the shard that the replica belongs to. This parameter is required.
-
-`replica`::
-The name of the replica. This parameter is required.
-
-`sourceNode`::
-The name of the node that contains the replica. This parameter is required.
-
`targetNode`::
The name of the destination node. This parameter is required.
+`sourceNode`::
+The name of the node that contains the replica to move. This parameter is required unless `replica` is specified. If `replica` is specified this parameter is ignored.
+
+`shard`::
+The name of the shard for which a replica should be moved. This parameter is required unless `replica` is specified. If `replica` is specified, this parameter is ignored.
+
+`replica`::
+The name of the replica to move. This parameter is required unless `shard` and `sourceNode` are specified, however this parameter has precedence over those two parameters.
+
+`timeout`::
+The number of seconds to wait for the replica to be live in the new location before deleting the replica in the old location. Defaults to 600 seconds. Deletion will not occur and creation will not be rolled back in the event of a timeout, potentially leaving an extra replica. Presently, this parameter is ignored if the replica is an hdfs replica.
+
+`inPlaceMove`::
+For replicas that use shared filesystems allow 'in-place' move that reuses shared data. Defaults to true, but is ignored if the replica does not have the property `shared_storage` with a value of `true`
+
`async`::
Request ID to track this action which will be <<collections-api.adoc#asynchronous-calls,processed asynchronously>>.
+=== Examples using MOVEREPLICA
+
+[.dynamic-tabs]
+--
+
+[example.tab-pane#v2moveReplica]
+====
+[.tab-label]*V2 API*
+*Input*
+
+`POST /api/c/test`
+
+[source,json]
+----
+{
+ "move-replica":{
+ "replica":"core_node6",
+ "targetNode": "localhost:8983_solr"
+ }
+}
+----
+*Output*
+
+[source,json]
+----
+{
+ "responseHeader": {
+ "status": 0,
+ "QTime": 3668
+ },
+ "success": "MOVEREPLICA action completed successfully, moved replica=test_shard1_replica_n5 at node=localhost:8982_solr to replica=test_shard1_replica_n7 at node=localhost:8983_solr"
+}
+----
+====
+
+[example.tab-pane#v1createAlias]
+====
+[.tab-label]*V1 API*
+
+*Input*
+
+[source,text]
+----
+http://localhost:8983/solr/admin/collections?action=MOVEREPLICA&collection=test&targetNode=localhost:8983_solr&replica=core_node6
+----
+
+*Output*
+
+[source,json]
+----
+{
+ "responseHeader": {
+ "status": 0,
+ "QTime": 3668
+ },
+ "success": "MOVEREPLICA action completed successfully, moved replica=test_shard1_replica_n5 at node=localhost:8982_solr to replica=test_shard1_replica_n7 at node=localhost:8983_solr"
+}
+----
+====
+--
+
+
[[deletereplica]]
== DELETEREPLICA: Delete a Replica
diff --git a/solr/solrj/src/resources/apispec/collections.collection.Commands.json b/solr/solrj/src/resources/apispec/collections.collection.Commands.json
index a2694e1..b4545d3 100644
--- a/solr/solrj/src/resources/apispec/collections.collection.Commands.json
+++ b/solr/solrj/src/resources/apispec/collections.collection.Commands.json
@@ -24,15 +24,15 @@
"properties": {
"replica": {
"type": "string",
- "description": "The name of the replica"
+ "description": "The name of the replica to move. Either this parameter or shard + sourceNode is required, this parameter takes precedence."
},
"shard": {
"type": "string",
- "description": "The name of the shard"
+ "description": "The name of the shard for which a replica should be moved. Either this parameter or replica is required. If replica is specified, this parameter is ignored."
},
"sourceNode": {
"type": "string",
- "description": "The name of the node that contains the replica."
+ "description": "The name of the node that contains the replica. Either this parameter or replica is required. If replica is specified, this parameter is ignored."
},
"targetNode": {
"type": "string",
@@ -46,7 +46,7 @@
"timeout": {
"type": "integer",
"default": 600,
- "description": "Timeout to wait for replica to become active. For very large replicas this may need to be increased."
+ "description": "Number of seconds to wait for replica to become active before failing. For very large replicas this may need to be increased to ensure the old replica is deleted. Ignored for hdfs replicas."
},
"inPlaceMove": {
"type": "boolean",
