solr/solr-ref-guide/src/cluster-node-management.adoc - lucene-solr - Git at Google

 = Cluster and Node Management Commands
 :toclevels: 1
 // Licensed to the Apache Software Foundation (ASF) under one
 // or more contributor license agreements.  See the NOTICE file
 // distributed with this work for additional information
 // regarding copyright ownership.  The ASF licenses this file
 // to you under the Apache License, Version 2.0 (the
 // "License"); you may not use this file except in compliance
 // with the License.  You may obtain a copy of the License at
 //
 //   http://www.apache.org/licenses/LICENSE-2.0
 //
 // Unless required by applicable law or agreed to in writing,
 // software distributed under the License is distributed on an
 // "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 // KIND, either express or implied.  See the License for the
 // specific language governing permissions and limitations
 // under the License.

 A cluster is a set of Solr nodes operating in coordination with each other.

 These API commands work with a SolrCloud cluster at the entire cluster level, or on individual nodes.

 [[clusterstatus]]
 == CLUSTERSTATUS: Cluster Status

 Fetch the cluster status including collections, shards, replicas, configuration name as well as collection aliases and cluster properties.

 `/admin/collections?action=CLUSTERSTATUS`

 Additionally, this command reports a `health` status of each collection and shard, in
 order to make it easier to monitor the operational state of the collections. The
 following health state values are defined, ordered from the best to worst, based on
 the percentage of active replicas (`active`):

 `GREEN`::
 `active == 100%`, all replicas are active and there's a shard leader.
 `YELLOW`::
 `100% > active > 50%`, AND there's a shard leader.
 `ORANGE`::
 `50% >= active > 0%`, AND there's a shard leader.
 `RED`::
 No active replicas *OR* there's no shard leader.

 The collection health state is reported as the worst state of any shard, e.g., for a
 collection with all shards GREEN except for one YELLOW the collection health will be
 reported as YELLOW.


 === CLUSTERSTATUS Parameters

 `collection`::
 The collection or alias name for which information is requested. If omitted, information on all collections in the cluster will be returned. If an alias is supplied, information on the collections in the alias will be returned.

 `shard`::
 The shard(s) for which information is requested. Multiple shard names can be specified as a comma-separated list.

 `\_route_`::
 This can be used if you need the details of the shard where a particular document belongs to and you don't know which shard it falls under.

 === CLUSTERSTATUS Response

 The response will include the status of the request and the status of the cluster.

 === Examples using CLUSTERSTATUS

 *Input*

 [source,text]
 ----
 http://localhost:8983/solr/admin/collections?action=CLUSTERSTATUS
 ----

 *Output*

 [source,json]
 ----
 {
   "responseHeader":{
     "status":0,
     "QTime":333},
   "cluster":{
     "collections":{
       "collection1":{
         "shards":{
           "shard1":{
             "range":"80000000-ffffffff",
             "state":"active",
             "health": "GREEN",
             "replicas":{
               "core_node1":{
                 "state":"active",
                 "core":"collection1",
                 "node_name":"127.0.1.1:8983_solr",
                 "base_url":"http://127.0.1.1:8983/solr",
                 "leader":"true"},
               "core_node3":{
                 "state":"active",
                 "core":"collection1",
                 "node_name":"127.0.1.1:8900_solr",
                 "base_url":"http://127.0.1.1:8900/solr"}}},
           "shard2":{
             "range":"0-7fffffff",
             "state":"active",
             "health": "GREEN",
             "replicas":{
               "core_node2":{
                 "state":"active",
                 "core":"collection1",
                 "node_name":"127.0.1.1:7574_solr",
                 "base_url":"http://127.0.1.1:7574/solr",
                 "leader":"true"},
               "core_node4":{
                 "state":"active",
                 "core":"collection1",
                 "node_name":"127.0.1.1:7500_solr",
                 "base_url":"http://127.0.1.1:7500/solr"}}}},
         "maxShardsPerNode":"1",
         "router":{"name":"compositeId"},
         "replicationFactor":"1",
         "znodeVersion": 11,
         "autoCreated":"true",
         "configName" : "my_config",
         "health": "GREEN",
         "aliases":["both_collections"]
       },
       "collection2":{
         "..."
       }
     },
     "aliases":{ "both_collections":"collection1,collection2" },
     "roles":{
       "overseer":[
         "127.0.1.1:8983_solr",
         "127.0.1.1:7574_solr"]
     },
     "live_nodes":[
       "127.0.1.1:7574_solr",
       "127.0.1.1:7500_solr",
       "127.0.1.1:8983_solr",
       "127.0.1.1:8900_solr"]
   }
 }
 ----

 [[clusterprop]]
 == CLUSTERPROP: Cluster Properties

 Add, edit or delete a cluster-wide property.

 `/admin/collections?action=CLUSTERPROP&name=_propertyName_&val=_propertyValue_`

 === CLUSTERPROP Parameters

 `name`::
 The name of the property. Supported properties names are `autoAddReplicas`, `legacyCloud`, `location`, `maxCoresPerNode`, `urlScheme`, and `defaultShardPreferences`.
 If the <<solr-tracing.adoc#,Jaeger tracing contrib>> has been enabled, the property `samplePercentage` is also available.
 +
 Other properties can be set (for example, if you need them for custom plugins) but they must begin with the prefix `ext.`.
 Unknown properties that don't begin with `ext.` will be rejected.

 `val`::
 The value of the property. If the value is empty or null, the property is unset.

 === CLUSTERPROP Response

 The response will include the status of the request and the properties that were updated or removed. If the status is anything other than "0", an error message will explain why the request failed.

 === Examples using CLUSTERPROP

 *Input*

 [source,text]
 ----
 http://localhost:8983/solr/admin/collections?action=CLUSTERPROP&name=urlScheme&val=https&wt=xml
 ----

 *Output*

 [source,xml]
 ----
 <response>
   <lst name="responseHeader">
     <int name="status">0</int>
     <int name="QTime">0</int>
   </lst>
 </response>
 ----

 === Setting Cluster-Wide Defaults

 It is possible to set cluster-wide default values for certain attributes of a collection, using the `defaults` parameter.

 *Set/update default values*
 [source,bash]
 ----
 curl -X POST -H 'Content-type:application/json' --data-binary '
 {
   "set-obj-property": {
     "defaults" : {
       "collection": {
         "numShards": 2,
         "nrtReplicas": 1,
         "tlogReplicas": 1,
         "pullReplicas": 1
       }
     }
   }
 }' http://localhost:8983/api/cluster
 ----

 *Unset the only value of `nrtReplicas`*
 [source,bash]
 ----
 curl -X POST -H 'Content-type:application/json' --data-binary '
 {
   "set-obj-property": {
     "defaults" : {
       "collection": {
         "nrtReplicas": null
       }
     }
   }
 }' http://localhost:8983/api/cluster
 ----

 *Unset all values in `defaults`*
 [source,bash]
 ----
 curl -X POST -H 'Content-type:application/json' --data-binary '
 { "set-obj-property" : {
     "defaults" : null
 }' http://localhost:8983/api/cluster
 ----

 NOTE: Until Solr 7.5, cluster properties supported a `collectionDefaults` key which is now deprecated and
 replaced with `defaults`. Using the `collectionDefaults` parameter in Solr 7.4 or 7.5 will continue to work
  but the format of the properties will automatically be converted to the new nested structure.
 Support for the "collectionDefaults" key will be removed in Solr 9.

 === Default Shard Preferences

 Using the `defaultShardPreferences` parameter, you can implement rack or availability zone awareness. First, make sure to "label" your nodes using a <<configuring-solrconfig-xml.adoc#jvm-system-properties,system property>> (e.g., `-Drack=rack1`). Then, set the value of `defaultShardPreferences` to `node.sysprop:sysprop.YOUR_PROPERTY_NAME` like this:

 [source,bash]
 ----
 curl -X POST -H 'Content-type:application/json' --data-binary '
 {
   "set-property" : {
     "name" : "defaultShardPreferences",
     "val" : "node.sysprop:sysprop.rack"
   }
 }' http://localhost:8983/api/cluster
 ----

 At this point, if you run a query on a node having e.g., `rack=rack1`, Solr will try to hit only replicas from `rack1`.

 [[balanceshardunique]]
 == BALANCESHARDUNIQUE: Balance a Property Across Nodes

 `/admin/collections?action=BALANCESHARDUNIQUE&collection=_collectionName_&property=_propertyName_`

 Insures that a particular property is distributed evenly amongst the physical nodes that make up a collection. If the property already exists on a replica, every effort is made to leave it there. If the property is *not* on any replica on a shard, one is chosen and the property is added.

 === BALANCESHARDUNIQUE Parameters

 `collection`::
 The name of the collection to balance the property in. This parameter is required.

 `property`::
 The property to balance. The literal `property.` is prepended to this property if not specified explicitly. This parameter is required.

 `onlyactivenodes`::
 Defaults to `true`. Normally, the property is instantiated on active nodes only. If this parameter is specified as `false`, then inactive nodes are also included for distribution.

 `shardUnique`::
 Something of a safety valve. There is one pre-defined property (`preferredLeader`) that defaults this value to `true`. For all other properties that are balanced, this must be set to `true` or an error message will be returned.

 === BALANCESHARDUNIQUE Response

 The response will include the status of the request. If the status is anything other than "0", an error message will explain why the request failed.

 === Examples using BALANCESHARDUNIQUE

 *Input*

 Either of these commands would put the "preferredLeader" property on one replica in every shard in the "collection1" collection.

 [source,text]
 ----
 http://localhost:8983/solr/admin/collections?action=BALANCESHARDUNIQUE&collection=collection1&property=preferredLeader&wt=xml

 http://localhost:8983/solr/admin/collections?action=BALANCESHARDUNIQUE&collection=collection1&property=property.preferredLeader&wt=xml
 ----

 *Output*

 [source,xml]
 ----
 <response>
   <lst name="responseHeader">
     <int name="status">0</int>
     <int name="QTime">9</int>
   </lst>
 </response>
 ----

 Examining the clusterstate after issuing this call should show exactly one replica in each shard that has this property.

 [[utilizenode]]
 == UTILIZENODE: Utilize a New Node

 [WARNING]
 .Autoscaling is deprecated
 ====
 The autoscaling framework in its current form is deprecated and will be removed in Solr 9.0.

 Some features relating to replica placement will be replaced in 9.0, but other features are not likely to be replaced.

 This command is part of the autoscaling framework and will be removed in 9.0 without a replacement.
 ====

 This command can be used to move some replicas from the existing nodes to either a new node or a less loaded node to reduce the load on the existing node.

 This uses your autoscaling policies and preferences to identify which replica needs to be moved. It tries to fix any policy violations first and then it tries to move some load off of the most loaded nodes according to the preferences.

 `/admin/collections?action=UTILIZENODE&node=nodeName`

 === UTILIZENODE Parameters

 `node`:: The name of the node that needs to be utilized. This parameter is required.

 [[replacenode]]
 == REPLACENODE: Move All Replicas in a Node to Another

 This command recreates replicas in one node (the source) to another node(s) (the target). After each replica is copied, the replicas in the source node are deleted.

 For source replicas that are also shard leaders the operation will wait for the number of seconds set with the `timeout` parameter to make sure there's an active replica that can become a leader (either an existing replica becoming a leader or the new replica completing recovery and becoming a leader).

 The API uses the Autoscaling framework to find nodes that can satisfy the disk requirements for the new replicas but only when an Autoscaling policy is configured. Refer to <<solrcloud-autoscaling-policy-preferences.adoc#,Autoscaling Policy and Preferences>> section for more details.

 `/admin/collections?action=REPLACENODE&sourceNode=_source-node_&targetNode=_target-node_`

 === REPLACENODE Parameters

 `sourceNode`::
 The source node from which the replicas need to be copied from. This parameter is required.

 `targetNode`::
 The target node where replicas will be copied. If this parameter is not provided, Solr will identify nodes automatically based on policies or number of cores in each node.

 `parallel`::
 If this flag is set to `true`, all replicas are created in separate threads. Keep in mind that this can lead to very high network and disk I/O if the replicas have very large indices. The default is `false`.

 `async`::
 Request ID to track this action which will be <<collections-api.adoc#asynchronous-calls,processed asynchronously>>.

 `timeout`::
 Time in seconds to wait until new replicas are created, and until leader replicas are fully recovered. The default is `300`, or 5 minutes.

 [IMPORTANT]
 ====
 This operation does not hold necessary locks on the replicas that belong to on the source node. So don't perform other collection operations in this period.
 ====

 [[deletenode]]
 == DELETENODE: Delete Replicas in a Node

 Deletes all replicas of all collections in that node. Please note that the node itself will remain as a live node after this operation.

 `/admin/collections?action=DELETENODE&node=nodeName`

 === DELETENODE Parameters

 `node`::
 The node to be removed. This parameter is required.

 `async`::
 Request ID to track this action which will be <<collections-api.adoc#asynchronous-calls,processed asynchronously>>.

 [[addrole]]
 == ADDROLE: Add a Role

 `/admin/collections?action=ADDROLE&role=_roleName_&node=_nodeName_`

 Assigns a role to a given node in the cluster. The only supported role is `overseer`.

 Use this command to dedicate a particular node as Overseer. Invoke it multiple times to add more nodes. This is useful in large clusters where an Overseer is likely to get overloaded. If available, one among the list of nodes which are assigned the 'overseer' role would become the overseer. The system would assign the role to any other node if none of the designated nodes are up and running.

 === ADDROLE Parameters

 `role`::
 The name of the role. The only supported role as of now is `overseer`. This parameter is required.

 `node`::
 The name of the node that will be assigned the role. It is possible to assign a role even before that node is started. This parameter is started.

 === ADDROLE Response

 The response will include the status of the request and the properties that were updated or removed. If the status is anything other than "0", an error message will explain why the request failed.

 === Examples using ADDROLE

 *Input*

 [source,text]
 ----
 http://localhost:8983/solr/admin/collections?action=ADDROLE&role=overseer&node=192.167.1.2:8983_solr&wt=xml
 ----

 *Output*

 [source,xml]
 ----
 <response>
   <lst name="responseHeader">
     <int name="status">0</int>
     <int name="QTime">0</int>
   </lst>
 </response>
 ----

 [[removerole]]
 == REMOVEROLE: Remove Role

 Remove an assigned role. This API is used to undo the roles assigned using ADDROLE operation

 `/admin/collections?action=REMOVEROLE&role=_roleName_&node=_nodeName_`

 === REMOVEROLE Parameters

 `role`::
 The name of the role. The only supported role as of now is `overseer`. This parameter is required.

 `node`::
 The name of the node where the role should be removed.


 === REMOVEROLE Response

 The response will include the status of the request and the properties that were updated or removed. If the status is anything other than "0", an error message will explain why the request failed.

 === Examples using REMOVEROLE

 *Input*

 [source,text]
 ----
 http://localhost:8983/solr/admin/collections?action=REMOVEROLE&role=overseer&node=192.167.1.2:8983_solr&wt=xml
 ----

 *Output*

 [source,xml]
 ----
 <response>
   <lst name="responseHeader">
     <int name="status">0</int>
     <int name="QTime">0</int>
   </lst>
 </response>
 ----

 [[overseerstatus]]
 == OVERSEERSTATUS: Overseer Status and Statistics

 Returns the current status of the overseer, performance statistics of various overseer APIs, and the last 10 failures per operation type.

 `/admin/collections?action=OVERSEERSTATUS`

 === Examples using OVERSEERSTATUS

 *Input:*

 [source,text]
 ----
 http://localhost:8983/solr/admin/collections?action=OVERSEERSTATUS
 ----

 [source,json]
 ----
 {
   "responseHeader":{
     "status":0,
     "QTime":33},
   "leader":"127.0.1.1:8983_solr",
   "overseer_queue_size":0,
   "overseer_work_queue_size":0,
   "overseer_collection_queue_size":2,
   "overseer_operations":[
     "createcollection",{
       "requests":2,
       "errors":0,
       "avgRequestsPerSecond":0.7467088842794136,
       "5minRateRequestsPerSecond":7.525069023276674,
       "15minRateRequestsPerSecond":10.271274280947182,
       "avgTimePerRequest":0.5050685,
       "medianRequestTime":0.5050685,
       "75thPcRequestTime":0.519016,
       "95thPcRequestTime":0.519016,
       "99thPcRequestTime":0.519016,
       "999thPcRequestTime":0.519016},
     "removeshard",{
       "..."
   }],
   "collection_operations":[
     "splitshard",{
       "requests":1,
       "errors":1,
       "recent_failures":[{
           "request":{
             "operation":"splitshard",
             "shard":"shard2",
             "collection":"example1"},
           "response":[
             "Operation splitshard caused exception:","org.apache.solr.common.SolrException:org.apache.solr.common.SolrException: No shard with the specified name exists: shard2",
             "exception",{
               "msg":"No shard with the specified name exists: shard2",
               "rspCode":400}]}],
       "avgRequestsPerSecond":0.8198143044809885,
       "5minRateRequestsPerSecond":8.043840552427673,
       "15minRateRequestsPerSecond":10.502079828515368,
       "avgTimePerRequest":2952.7164175,
       "medianRequestTime":2952.7164175000003,
       "75thPcRequestTime":5904.384052,
       "95thPcRequestTime":5904.384052,
       "99thPcRequestTime":5904.384052,
       "999thPcRequestTime":5904.384052},
     "..."
   ],
   "overseer_queue":[
     "..."
   ],
   "..."
  }
 ----

 [[migratestateformat]]
 == MIGRATESTATEFORMAT: Migrate Cluster State

 A expert level utility API to move a collection from shared `clusterstate.json` ZooKeeper node (created with `stateFormat=1`, the default in all Solr releases prior to 5.0) to the per-collection `state.json` stored in ZooKeeper (created with `stateFormat=2`, the current default) seamlessly without any application down-time.

 `/admin/collections?action=MIGRATESTATEFORMAT&collection=<collection_name>`

 === MIGRATESTATEFORMAT Parameters

 `collection`::
 The name of the collection to be migrated from `clusterstate.json` to its own `state.json` ZooKeeper node. This parameter is required.

 `async`::
 Request ID to track this action which will be <<collections-api.adoc#asynchronous-calls,processed asynchronously>>.

 This API is useful in migrating any collections created prior to Solr 5.0 to the more scalable cluster state format now used by default. If a collection was created in any Solr 5.x version or higher, then executing this command is not necessary.
	= Cluster and Node Management Commands
	:toclevels: 1
	// Licensed to the Apache Software Foundation (ASF) under one
	// or more contributor license agreements. See the NOTICE file
	// distributed with this work for additional information
	// regarding copyright ownership. The ASF licenses this file
	// to you under the Apache License, Version 2.0 (the
	// "License"); you may not use this file except in compliance
	// with the License. You may obtain a copy of the License at
	//
	// http://www.apache.org/licenses/LICENSE-2.0
	//
	// Unless required by applicable law or agreed to in writing,
	// software distributed under the License is distributed on an
	// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	// KIND, either express or implied. See the License for the
	// specific language governing permissions and limitations
	// under the License.

	A cluster is a set of Solr nodes operating in coordination with each other.

	These API commands work with a SolrCloud cluster at the entire cluster level, or on individual nodes.

	[[clusterstatus]]
	== CLUSTERSTATUS: Cluster Status

	Fetch the cluster status including collections, shards, replicas, configuration name as well as collection aliases and cluster properties.

	`/admin/collections?action=CLUSTERSTATUS`

	Additionally, this command reports a `health` status of each collection and shard, in
	order to make it easier to monitor the operational state of the collections. The
	following health state values are defined, ordered from the best to worst, based on
	the percentage of active replicas (`active`):

	`GREEN`::
	`active == 100%`, all replicas are active and there's a shard leader.
	`YELLOW`::
	`100% > active > 50%`, AND there's a shard leader.
	`ORANGE`::
	`50% >= active > 0%`, AND there's a shard leader.
	`RED`::
	No active replicas OR there's no shard leader.

	The collection health state is reported as the worst state of any shard, e.g., for a
	collection with all shards GREEN except for one YELLOW the collection health will be
	reported as YELLOW.


	=== CLUSTERSTATUS Parameters

	`collection`::
	The collection or alias name for which information is requested. If omitted, information on all collections in the cluster will be returned. If an alias is supplied, information on the collections in the alias will be returned.

	`shard`::
	The shard(s) for which information is requested. Multiple shard names can be specified as a comma-separated list.

	`\_route_`::
	This can be used if you need the details of the shard where a particular document belongs to and you don't know which shard it falls under.

	=== CLUSTERSTATUS Response

	The response will include the status of the request and the status of the cluster.

	=== Examples using CLUSTERSTATUS

	Input

	[source,text]
	----
	http://localhost:8983/solr/admin/collections?action=CLUSTERSTATUS
	----

	Output

	[source,json]
	----
	{
	"responseHeader":{
	"status":0,
	"QTime":333},
	"cluster":{
	"collections":{
	"collection1":{
	"shards":{
	"shard1":{
	"range":"80000000-ffffffff",
	"state":"active",
	"health": "GREEN",
	"replicas":{
	"core_node1":{
	"state":"active",
	"core":"collection1",
	"node_name":"127.0.1.1:8983_solr",
	"base_url":"http://127.0.1.1:8983/solr",
	"leader":"true"},
	"core_node3":{
	"state":"active",
	"core":"collection1",
	"node_name":"127.0.1.1:8900_solr",
	"base_url":"http://127.0.1.1:8900/solr"}}},
	"shard2":{
	"range":"0-7fffffff",
	"state":"active",
	"health": "GREEN",
	"replicas":{
	"core_node2":{
	"state":"active",
	"core":"collection1",
	"node_name":"127.0.1.1:7574_solr",
	"base_url":"http://127.0.1.1:7574/solr",
	"leader":"true"},
	"core_node4":{
	"state":"active",
	"core":"collection1",
	"node_name":"127.0.1.1:7500_solr",
	"base_url":"http://127.0.1.1:7500/solr"}}}},
	"maxShardsPerNode":"1",
	"router":{"name":"compositeId"},
	"replicationFactor":"1",
	"znodeVersion": 11,
	"autoCreated":"true",
	"configName" : "my_config",
	"health": "GREEN",
	"aliases":["both_collections"]
	},
	"collection2":{
	"..."
	}
	},
	"aliases":{ "both_collections":"collection1,collection2" },
	"roles":{
	"overseer":[
	"127.0.1.1:8983_solr",
	"127.0.1.1:7574_solr"]
	},
	"live_nodes":[
	"127.0.1.1:7574_solr",
	"127.0.1.1:7500_solr",
	"127.0.1.1:8983_solr",
	"127.0.1.1:8900_solr"]
	}
	}
	----

	[[clusterprop]]
	== CLUSTERPROP: Cluster Properties

	Add, edit or delete a cluster-wide property.

	`/admin/collections?action=CLUSTERPROP&name=_propertyName_&val=_propertyValue_`

	=== CLUSTERPROP Parameters

	`name`::
	The name of the property. Supported properties names are `autoAddReplicas`, `legacyCloud`, `location`, `maxCoresPerNode`, `urlScheme`, and `defaultShardPreferences`.
	If the <<solr-tracing.adoc#,Jaeger tracing contrib>> has been enabled, the property `samplePercentage` is also available.
	+
	Other properties can be set (for example, if you need them for custom plugins) but they must begin with the prefix `ext.`.
	Unknown properties that don't begin with `ext.` will be rejected.

	`val`::
	The value of the property. If the value is empty or null, the property is unset.

	=== CLUSTERPROP Response

	The response will include the status of the request and the properties that were updated or removed. If the status is anything other than "0", an error message will explain why the request failed.

	=== Examples using CLUSTERPROP

	Input

	[source,text]
	----
	http://localhost:8983/solr/admin/collections?action=CLUSTERPROP&name=urlScheme&val=https&wt=xml
	----

	Output

	[source,xml]
	----
	<response>
	<lst name="responseHeader">
	<int name="status">0</int>
	<int name="QTime">0</int>
	</lst>
	</response>
	----

	=== Setting Cluster-Wide Defaults

	It is possible to set cluster-wide default values for certain attributes of a collection, using the `defaults` parameter.

	Set/update default values
	[source,bash]
	----
	curl -X POST -H 'Content-type:application/json' --data-binary '
	{
	"set-obj-property": {
	"defaults" : {
	"collection": {
	"numShards": 2,
	"nrtReplicas": 1,
	"tlogReplicas": 1,
	"pullReplicas": 1
	}
	}
	}
	}' http://localhost:8983/api/cluster
	----

	Unset the only value of `nrtReplicas`
	[source,bash]
	----
	curl -X POST -H 'Content-type:application/json' --data-binary '
	{
	"set-obj-property": {
	"defaults" : {
	"collection": {
	"nrtReplicas": null
	}
	}
	}
	}' http://localhost:8983/api/cluster
	----

	Unset all values in `defaults`
	[source,bash]
	----
	curl -X POST -H 'Content-type:application/json' --data-binary '
	{ "set-obj-property" : {
	"defaults" : null
	}' http://localhost:8983/api/cluster
	----

	NOTE: Until Solr 7.5, cluster properties supported a `collectionDefaults` key which is now deprecated and
	replaced with `defaults`. Using the `collectionDefaults` parameter in Solr 7.4 or 7.5 will continue to work
	but the format of the properties will automatically be converted to the new nested structure.
	Support for the "collectionDefaults" key will be removed in Solr 9.

	=== Default Shard Preferences

	Using the `defaultShardPreferences` parameter, you can implement rack or availability zone awareness. First, make sure to "label" your nodes using a <<configuring-solrconfig-xml.adoc#jvm-system-properties,system property>> (e.g., `-Drack=rack1`). Then, set the value of `defaultShardPreferences` to `node.sysprop:sysprop.YOUR_PROPERTY_NAME` like this:

	[source,bash]
	----
	curl -X POST -H 'Content-type:application/json' --data-binary '
	{
	"set-property" : {
	"name" : "defaultShardPreferences",
	"val" : "node.sysprop:sysprop.rack"
	}
	}' http://localhost:8983/api/cluster
	----

	At this point, if you run a query on a node having e.g., `rack=rack1`, Solr will try to hit only replicas from `rack1`.

	[[balanceshardunique]]
	== BALANCESHARDUNIQUE: Balance a Property Across Nodes

	`/admin/collections?action=BALANCESHARDUNIQUE&collection=_collectionName_&property=_propertyName_`

	Insures that a particular property is distributed evenly amongst the physical nodes that make up a collection. If the property already exists on a replica, every effort is made to leave it there. If the property is not on any replica on a shard, one is chosen and the property is added.

	=== BALANCESHARDUNIQUE Parameters

	`collection`::
	The name of the collection to balance the property in. This parameter is required.

	`property`::
	The property to balance. The literal `property.` is prepended to this property if not specified explicitly. This parameter is required.

	`onlyactivenodes`::
	Defaults to `true`. Normally, the property is instantiated on active nodes only. If this parameter is specified as `false`, then inactive nodes are also included for distribution.

	`shardUnique`::
	Something of a safety valve. There is one pre-defined property (`preferredLeader`) that defaults this value to `true`. For all other properties that are balanced, this must be set to `true` or an error message will be returned.

	=== BALANCESHARDUNIQUE Response

	The response will include the status of the request. If the status is anything other than "0", an error message will explain why the request failed.

	=== Examples using BALANCESHARDUNIQUE

	Input

	Either of these commands would put the "preferredLeader" property on one replica in every shard in the "collection1" collection.

	[source,text]
	----
	http://localhost:8983/solr/admin/collections?action=BALANCESHARDUNIQUE&collection=collection1&property=preferredLeader&wt=xml

	http://localhost:8983/solr/admin/collections?action=BALANCESHARDUNIQUE&collection=collection1&property=property.preferredLeader&wt=xml
	----

	Output

	[source,xml]
	----
	<response>
	<lst name="responseHeader">
	<int name="status">0</int>
	<int name="QTime">9</int>
	</lst>
	</response>
	----

	Examining the clusterstate after issuing this call should show exactly one replica in each shard that has this property.

	[[utilizenode]]
	== UTILIZENODE: Utilize a New Node

	[WARNING]
	.Autoscaling is deprecated
	====
	The autoscaling framework in its current form is deprecated and will be removed in Solr 9.0.

	Some features relating to replica placement will be replaced in 9.0, but other features are not likely to be replaced.

	This command is part of the autoscaling framework and will be removed in 9.0 without a replacement.
	====

	This command can be used to move some replicas from the existing nodes to either a new node or a less loaded node to reduce the load on the existing node.

	This uses your autoscaling policies and preferences to identify which replica needs to be moved. It tries to fix any policy violations first and then it tries to move some load off of the most loaded nodes according to the preferences.

	`/admin/collections?action=UTILIZENODE&node=nodeName`

	=== UTILIZENODE Parameters

	`node`:: The name of the node that needs to be utilized. This parameter is required.

	[[replacenode]]
	== REPLACENODE: Move All Replicas in a Node to Another

	This command recreates replicas in one node (the source) to another node(s) (the target). After each replica is copied, the replicas in the source node are deleted.

	For source replicas that are also shard leaders the operation will wait for the number of seconds set with the `timeout` parameter to make sure there's an active replica that can become a leader (either an existing replica becoming a leader or the new replica completing recovery and becoming a leader).

	The API uses the Autoscaling framework to find nodes that can satisfy the disk requirements for the new replicas but only when an Autoscaling policy is configured. Refer to <<solrcloud-autoscaling-policy-preferences.adoc#,Autoscaling Policy and Preferences>> section for more details.

	`/admin/collections?action=REPLACENODE&sourceNode=_source-node_&targetNode=_target-node_`

	=== REPLACENODE Parameters

	`sourceNode`::
	The source node from which the replicas need to be copied from. This parameter is required.

	`targetNode`::
	The target node where replicas will be copied. If this parameter is not provided, Solr will identify nodes automatically based on policies or number of cores in each node.

	`parallel`::
	If this flag is set to `true`, all replicas are created in separate threads. Keep in mind that this can lead to very high network and disk I/O if the replicas have very large indices. The default is `false`.

	`async`::
	Request ID to track this action which will be <<collections-api.adoc#asynchronous-calls,processed asynchronously>>.

	`timeout`::
	Time in seconds to wait until new replicas are created, and until leader replicas are fully recovered. The default is `300`, or 5 minutes.

	[IMPORTANT]
	====
	This operation does not hold necessary locks on the replicas that belong to on the source node. So don't perform other collection operations in this period.
	====

	[[deletenode]]
	== DELETENODE: Delete Replicas in a Node

	Deletes all replicas of all collections in that node. Please note that the node itself will remain as a live node after this operation.

	`/admin/collections?action=DELETENODE&node=nodeName`

	=== DELETENODE Parameters

	`node`::
	The node to be removed. This parameter is required.

	`async`::
	Request ID to track this action which will be <<collections-api.adoc#asynchronous-calls,processed asynchronously>>.

	[[addrole]]
	== ADDROLE: Add a Role

	`/admin/collections?action=ADDROLE&role=_roleName_&node=_nodeName_`

	Assigns a role to a given node in the cluster. The only supported role is `overseer`.

	Use this command to dedicate a particular node as Overseer. Invoke it multiple times to add more nodes. This is useful in large clusters where an Overseer is likely to get overloaded. If available, one among the list of nodes which are assigned the 'overseer' role would become the overseer. The system would assign the role to any other node if none of the designated nodes are up and running.

	=== ADDROLE Parameters

	`role`::
	The name of the role. The only supported role as of now is `overseer`. This parameter is required.

	`node`::
	The name of the node that will be assigned the role. It is possible to assign a role even before that node is started. This parameter is started.

	=== ADDROLE Response

	The response will include the status of the request and the properties that were updated or removed. If the status is anything other than "0", an error message will explain why the request failed.

	=== Examples using ADDROLE

	Input

	[source,text]
	----
	http://localhost:8983/solr/admin/collections?action=ADDROLE&role=overseer&node=192.167.1.2:8983_solr&wt=xml
	----

	Output

	[source,xml]
	----
	<response>
	<lst name="responseHeader">
	<int name="status">0</int>
	<int name="QTime">0</int>
	</lst>
	</response>
	----

	[[removerole]]
	== REMOVEROLE: Remove Role

	Remove an assigned role. This API is used to undo the roles assigned using ADDROLE operation

	`/admin/collections?action=REMOVEROLE&role=_roleName_&node=_nodeName_`

	=== REMOVEROLE Parameters

	`role`::
	The name of the role. The only supported role as of now is `overseer`. This parameter is required.

	`node`::
	The name of the node where the role should be removed.


	=== REMOVEROLE Response

	The response will include the status of the request and the properties that were updated or removed. If the status is anything other than "0", an error message will explain why the request failed.

	=== Examples using REMOVEROLE

	Input

	[source,text]
	----
	http://localhost:8983/solr/admin/collections?action=REMOVEROLE&role=overseer&node=192.167.1.2:8983_solr&wt=xml
	----

	Output

	[source,xml]
	----
	<response>
	<lst name="responseHeader">
	<int name="status">0</int>
	<int name="QTime">0</int>
	</lst>
	</response>
	----

	[[overseerstatus]]
	== OVERSEERSTATUS: Overseer Status and Statistics

	Returns the current status of the overseer, performance statistics of various overseer APIs, and the last 10 failures per operation type.

	`/admin/collections?action=OVERSEERSTATUS`

	=== Examples using OVERSEERSTATUS

	Input:

	[source,text]
	----
	http://localhost:8983/solr/admin/collections?action=OVERSEERSTATUS
	----

	[source,json]
	----
	{
	"responseHeader":{
	"status":0,
	"QTime":33},
	"leader":"127.0.1.1:8983_solr",
	"overseer_queue_size":0,
	"overseer_work_queue_size":0,
	"overseer_collection_queue_size":2,
	"overseer_operations":[
	"createcollection",{
	"requests":2,
	"errors":0,
	"avgRequestsPerSecond":0.7467088842794136,
	"5minRateRequestsPerSecond":7.525069023276674,
	"15minRateRequestsPerSecond":10.271274280947182,
	"avgTimePerRequest":0.5050685,
	"medianRequestTime":0.5050685,
	"75thPcRequestTime":0.519016,
	"95thPcRequestTime":0.519016,
	"99thPcRequestTime":0.519016,
	"999thPcRequestTime":0.519016},
	"removeshard",{
	"..."
	}],
	"collection_operations":[
	"splitshard",{
	"requests":1,
	"errors":1,
	"recent_failures":[{
	"request":{
	"operation":"splitshard",
	"shard":"shard2",
	"collection":"example1"},
	"response":[
	"Operation splitshard caused exception:","org.apache.solr.common.SolrException:org.apache.solr.common.SolrException: No shard with the specified name exists: shard2",
	"exception",{
	"msg":"No shard with the specified name exists: shard2",
	"rspCode":400}]}],
	"avgRequestsPerSecond":0.8198143044809885,
	"5minRateRequestsPerSecond":8.043840552427673,
	"15minRateRequestsPerSecond":10.502079828515368,
	"avgTimePerRequest":2952.7164175,
	"medianRequestTime":2952.7164175000003,
	"75thPcRequestTime":5904.384052,
	"95thPcRequestTime":5904.384052,
	"99thPcRequestTime":5904.384052,
	"999thPcRequestTime":5904.384052},
	"..."
	],
	"overseer_queue":[
	"..."
	],
	"..."
	}
	----

	[[migratestateformat]]
	== MIGRATESTATEFORMAT: Migrate Cluster State

	A expert level utility API to move a collection from shared `clusterstate.json` ZooKeeper node (created with `stateFormat=1`, the default in all Solr releases prior to 5.0) to the per-collection `state.json` stored in ZooKeeper (created with `stateFormat=2`, the current default) seamlessly without any application down-time.

	`/admin/collections?action=MIGRATESTATEFORMAT&collection=<collection_name>`

	=== MIGRATESTATEFORMAT Parameters

	`collection`::
	The name of the collection to be migrated from `clusterstate.json` to its own `state.json` ZooKeeper node. This parameter is required.

	`async`::
	Request ID to track this action which will be <<collections-api.adoc#asynchronous-calls,processed asynchronously>>.

	This API is useful in migrating any collections created prior to Solr 5.0 to the more scalable cluster state format now used by default. If a collection was created in any Solr 5.x version or higher, then executing this command is not necessary.