SolrCloud
Overview
SolrCloud is a cluster of Solr servers that provides fault tolerance and high availability. It uses Apache ZooKeeper for cluster configuration and coordination. Number of nodes you need, usually depends on amount of data, number of queries, fault tolerance and high availability requirements.
There are two main SolrCloud deployment types: single Solr server with embedded ZooKeeper and multinode deployment with separate Solr and ZooKeeper clusters.
Single Solr Server with Embedded ZooKeeper
This is the simplest configuration of SolrCloud. A single instance of ZooKeeper and Solr server are running in the same JVM. This setup does not provide any fault tolerance or high availability, and could not be expanded. This configuration is recommended for development or testing and can be easily installed on a laptop or desktop.

Multinode Cluster
This configuration is recommended for production. It provides fault tolerance and high availability. Both ZooKeeper and Solr clusters can be expanded by adding more nodes.

Deployment Summary
Deployment type | Multinode cluster | Single Solr server with embedded ZooKeeper |
---|---|---|
Usage | Production / QA | Development / QA |
Scalability | Yes | No |
Fault tolerance and high availability | Yes | No |
Deployment options | On-prem or cloud: VMs, Kubernetes | Laptop or desktop: host, VM, docker |
High Availability Summary
Number of ZooKeeper nodes | Number of Solr nodes | Fault tolerance / High availability |
---|---|---|
1 | 1 | No |
1 | 2+ | ZooKeeper - No, Solr - Yes |
3 | 2+ | Yes |
Cores, Shards and Replicas
- A core is an instance of a Lucene index.
- A shard is a logical partition of the collection, containing a subset of documents from the collection. For example, if "registry" collection has 3,000 documents and 3 shards, then each shard has about 1,000 documents. Each shard has one or more replicas.
- A replica is a copy of a shard. Each replica exists within Solr as a core. For example, if "registry" collection has 3,000 documents, 3 shards and 2 replicas (per shard), then there are 6 cores (3 shards x 2 replicas) containing 1,000 documents each. There are 2 copies of each document.
- Every shard has a leader replica. Leaders are automatically elected. If a leader goes down, one of the other replicas is automatically elected as the new leader.
- When a document is sent to a Solr node for indexing, the system first determines which shard that document belongs to, and then which node is currently hosting the leader for that shard. The document is then forwarded to the current leader for indexing, and the leader forwards the update to all of the other replicas.
- By default, all replicas (cores) serve queries.
You can read more about shards and indexing data in SolrCloud at Solr web site.
Examples
Below are few example configurations for a collection with different number of shards and replicas in 3 node Solr cluster. The collection contains 3,000 documents.
1 Shard, 1 Replica

- Concurrent writes - 1 node
- Concurrent reads - 1 node
- Fault tolerant - No
1 Shard, 3 Replicas

- Concurrent writes - 1 node
- Concurrent reads - 3 nodes
- Fault tolerant - Yes (2 nodes could go down)
3 Shards, 2 Replicas

- Concurrent writes - 3 nodes
- Concurrent reads - 3 nodes (6 cores)
- Fault tolerant - Yes (1 node could go down)
Creating Collections
By default, when you create a collection in Solr, the number of shards and replicas is 1. The following example shows how to create registry collection with 3 shards and 2 replicas.
registry-manager create-registry -zkHost zk1.test.local -shards 3 -replicas 2
Cluster Expansion
Getting Information about Solr Collections
Before expanding the cluster you may need to get more information about your Solr collection(s). The following example shows how to call Solr API to get information about "registry" collection.
curl "http://solr1.test.local:8983/api/c/registry"
The response is a long JSON, similar to this
{ "responseHeader":{ "status":0, "QTime":26}, "cluster":{ "collections":{ "registry":{ "pullReplicas":"0", "replicationFactor":"1", "shards":{"shard1":{ "range":"80000000-7fffffff", "state":"active", "replicas":{"core_node2":{ "core":"registry_shard1_replica_n1", "base_url":"http://solr2.test.local:8983/solr", "node_name":"solr2.test.local:8983_solr", "state":"active", "type":"NRT", "force_set_state":"false", "leader":"true"}}}}, "router":{"name":"compositeId"}, "maxShardsPerNode":"1", "autoAddReplicas":"false", "nrtReplicas":"1", "tlogReplicas":"0", "znodeVersion":4, "configName":"registry"}}, "live_nodes":["solr2.test.local:8983_solr", "solr1.test.local:8983_solr"]}}
As you can see, collection "registry", has only one shard called "shard1". The shard has one replica called "core_node2" located on node "solr2.test.local:8983_solr".
Adding Replicas to a Shard
To add a replica to "shard1" of collection "registry" call one of the following Solr APIs.
# API v1 curl "http://localhost:8983/solr/admin/collections?action=ADDREPLICA&collection=registry&shard=shard1" # API v2 curl "http://solr1.test.local:8983/api/c/registry/shards" \ -XPOST -H 'Content-type:application/json' \ -d '{ add-replica: { shard: "shard1" } }'
Get "registry" collection info and check that new replica was created.
curl "http://solr1.test.local:8983/api/c/registry
In our example, "shard1" now has two replicas "core_node2" and "core_node4". Solr naming convention for replicas, shards and cores is strange. You can see some random numbers in names.
... "shards":{"shard1":{ ... "replicas":{ "core_node2":{ "core":"registry_shard1_replica_n1", "node_name":"solr2.test.local:8983_solr", ... "state":"active", "leader":"true"}, "core_node4":{ "core":"registry_shard1_replica_n3", "node_name":"solr1.test.local:8983_solr", ... "state":"active" }}}},
Note that Solr placed each replica on a different node. In some cases it might not work as expected. There is an API to move a replica from one node to another. In the following example, replica "core_node4" is moved from node "solr2.test.local:8983_solr" to "solr3.test.local:8983_solr". The whole command should be on a single line. We split it here to make it more readable.
curl "http://localhost:8983/solr/admin/collections?action=MOVEREPLICA &collection=registry &shard=shard1 &replica=core_node4 &sourceNode=solr2.test.local:8983_solr &targetNode=solr3.test.local:8983_solr"
You can learn more about replica management APIs at Solr website. Also see v2 API docs.
You can also view some information about collections and its replicas in Solr admin UI.
Increasing Number of Shards
There is a Solr API to split a shard into 2 or more pieces. In the following example, we will split "shard1" of "registry" collection into 2 new shards.
curl "http://localhost:8983/solr/admin/collections?action=SPLITSHARD&collection=registry&shard=shard1"
Old shard, "shard1", will be deactivated and two new shards, "shard1_0" and "shard1_1" will be created. "Shard1" had 2 replicas, so both new shards, "shard1_0" and "shard1_1", will have 2 replicas too.
For some reason, Solr placed both replicas of "shard1_1" on the same node, so I had to move one of the replicas to another node.
curl "http://localhost:8983/solr/admin/collections?action=MOVEREPLICA &collection=registry &shard=shard1_1 &replica=core_node10 &sourceNode=solr1.test.local:8983_solr &targetNode=solr2.test.local:8983_solr"
Now old shard can be deleted.
curl "http://localhost:8983/solr/admin/collections?action=DELETESHARD&collection=registry&shard=shard1"
You can learn more about shard management APIs at Solr website. Also see v2 API docs.