diff --git a/solr/solr-ref-guide/build.gradle b/solr/solr-ref-guide/build.gradle index 1e455f29849..1d9c1a28f66 100644 --- a/solr/solr-ref-guide/build.gradle +++ b/solr/solr-ref-guide/build.gradle @@ -63,6 +63,7 @@ ext { antoraLunrExtensionVersion = "1.0.0-alpha.8" asciidoctorMathjaxVersion = "0.0.9" asciidoctorTabsVersion = "1.0.0-beta.6" + asciidoctorKrokiVersion = "0.18.1" linkCheckerVersion = "1.4.2" gulpCliVersion = "2.3.0" // Most recent commit as of 2022-06-24, this repo does not have tags @@ -243,10 +244,18 @@ task downloadAsciidoctorMathjaxExtension(type: NpmTask) { group = 'Build Dependency Download' args = ["install", "@djencks/asciidoctor-mathjax@${project.ext.asciidoctorMathjaxVersion}"] - inputs.property("asciidoctor-mathjax version", project.ext.asciidoctorMathjaxVersion) + inputs.property("Antora asciidoctor-mathjax version", project.ext.asciidoctorMathjaxVersion) outputs.dir("${project.ext.nodeProjectDir}/node_modules/@djencks/asciidoctor-mathjax") } +task downloadAsciiDoctorKrokiExtension(type: NpmTask) { + group = 'Build Dependency Download' + args = ["install", "asciidoctor-kroki"] + + inputs.property("asciidoctor-kroki version", project.ext.asciidoctorKrokiVersion) + outputs.dir("${project.ext.nodeProjectDir}/node_modules/asciidoctor-kroki") +} + task downloadAsciidoctorTabsExtension(type: NpmTask) { group = 'Build Dependency Download' args = ["install", "-D", "@asciidoctor/tabs@${project.ext.asciidoctorTabsVersion}"] @@ -262,6 +271,7 @@ task downloadAntora { dependsOn tasks.downloadAntoraCli dependsOn tasks.downloadAntoraSiteGenerator dependsOn tasks.downloadAntoraLunrExtension + dependsOn tasks.downloadAsciiDoctorKrokiExtension dependsOn tasks.downloadAsciidoctorMathjaxExtension dependsOn tasks.downloadAsciidoctorTabsExtension } diff --git a/solr/solr-ref-guide/modules/deployment-guide/deployment-nav.adoc b/solr/solr-ref-guide/modules/deployment-guide/deployment-nav.adoc index a41206030a7..754aa383202 100644 --- a/solr/solr-ref-guide/modules/deployment-guide/deployment-nav.adoc +++ b/solr/solr-ref-guide/modules/deployment-guide/deployment-nav.adoc @@ -18,7 +18,7 @@ .Deployment Guide * xref:solr-control-script-reference.adoc[] - +* xref:thinking-about-deployment-strategy.adoc[] * Installation & Deployment ** xref:system-requirements.adoc[] ** xref:installing-solr.adoc[] diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/installing-solr.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/installing-solr.adoc index 8dceba13dbe..529e90da3a9 100644 --- a/solr/solr-ref-guide/modules/deployment-guide/pages/installing-solr.adoc +++ b/solr/solr-ref-guide/modules/deployment-guide/pages/installing-solr.adoc @@ -59,7 +59,7 @@ A very good blog post that discusses the issues to consider is https://lucidwork One thing to note when planning your installation is that a hard limit exists in Lucene for the number of documents in a single index: approximately 2.14 billion documents (2,147,483,647 to be exact). In practice, it is highly unlikely that such a large number of documents would fit and perform well in a single index, and you will likely need to distribute your index across a cluster before you ever approach this number. -If you know you will exceed this number of documents in total before you've even started indexing, it's best to plan your installation with xref:cluster-types.adoc#solrcloud-mode[SolrCloud] as part of your design from the start. +Fortunantly, by default Solr is configured to be deployed in xref:cluster-types.adoc#solrcloud-mode[SolrCloud] mode to let you scale up. == Package Installation @@ -84,9 +84,7 @@ This directory includes several important scripts that will make using Solr easi solr and solr.cmd::: This is xref:solr-control-script-reference.adoc[Solr's Control Script], also known as `bin/solr` (*nix) / `bin/solr.cmd` (Windows). This script is the preferred tool to start and stop Solr. -You can also create collections or cores, configure authentication, and work with configuration files when running in SolrCloud mode. - -post::: The xref:indexing-guide:post-tool.adoc[], which provides a simple command line interface for POSTing content to Solr. +You can also create collections or cores, configure authentication, work with configuration files and even index documents into Solr. solr.in.sh and solr.in.cmd::: These are property files for *nix and Windows systems, respectively. @@ -198,8 +196,7 @@ For instance, to launch the "techproducts" example, you would do: bin/solr start --cloud -e techproducts ---- -Currently, the available examples you can run are: techproducts, schemaless, and cloud. -See the section xref:solr-control-script-reference.adoc#running-with-example-configurations[Running with Example Configurations] for details on each example. +See the section xref:solr-control-script-reference.adoc#running-with-example-configurations[Running with Example Configurations] for details on all the examples available. .Going deeper with SolrCloud NOTE: Running the `cloud` example demonstrates running multiple nodes of Solr using xref:cluster-types.adoc#solrcloud-mode[SolrCloud] mode. diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/taking-solr-to-production.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/taking-solr-to-production.adoc index 4adb5fd6b57..cfc2c8b3a66 100644 --- a/solr/solr-ref-guide/modules/deployment-guide/pages/taking-solr-to-production.adoc +++ b/solr/solr-ref-guide/modules/deployment-guide/pages/taking-solr-to-production.adoc @@ -247,10 +247,15 @@ You can also refer to xref:jvm-settings.adoc[] for tuning your memory and garbag The `bin/solr` script uses the `-XX:+CrashOnOutOfMemoryError` JVM option to crash Solr on `OutOfMemoryError` exceptions. This behavior is recommended. In SolrCloud mode ZooKeeper will be immediately notified that a node has experienced a non-recoverable error. -=== Going to Production with SolrCloud -To run Solr in SolrCloud mode, you need to set the `ZK_HOST` variable in the include file to point to your ZooKeeper ensemble. -Running the embedded ZooKeeper is not supported in production environments. +=== Going to Production with SolrCloud with Embedded ZooKeeper + +Solr runs by default in SolrCloud mode with an embedded ZooKeeper, no additional configuration required. + +=== Going to Production with SolrCloud with External ZooKeeper Ensemble + +To run Solr in SolrCloud mode with an external ZooKeeper ensemble, you need to set the `ZK_HOST` variable in the include file to point to your ZooKeeper ensemble. + For instance, if you have a ZooKeeper ensemble hosted on the following three hosts on the default client port 2181 (zk1, zk2, and zk3), then you would set: [source,bash] @@ -258,7 +263,9 @@ For instance, if you have a ZooKeeper ensemble hosted on the following three hos ZK_HOST=zk1,zk2,zk3 ---- -When the `ZK_HOST` variable is set, Solr will launch in "cloud" mode. +When the `ZK_HOST` variable is set, Solr will launch and connect to the defined ZooKeepers instead of starting an embedded ZooKeeper. + +See xref:zookeeper-ensemble[ZooKeeper Ensemble Configuration] for more on setting up ZooKeeper. ==== ZooKeeper chroot diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/thinking-about-deployment-strategy.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/thinking-about-deployment-strategy.adoc new file mode 100644 index 00000000000..97104cef8da --- /dev/null +++ b/solr/solr-ref-guide/modules/deployment-guide/pages/thinking-about-deployment-strategy.adoc @@ -0,0 +1,397 @@ += Thinking About Deployment Strategy +// 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. + +//// +This page has a number of graphs to help you visualize different Solr deployment strategies. + +The site https://magjac.com/graphviz-visual-editor/ allows you to play with those graphs in real time. +//// + +This section embodies the Solr community's thoughts on best practices for deploying Solr depending on your needs. + +NOTE: Soemthing about the various directions you can sacle... David Smiley had some good words. +Query load. Index Load. Number of Collections. Densitiy of Data (Vectors). + + +== Overview +There is a logical progression to scaling Solr. + +[graphviz] +.... +digraph { + node [style=rounded] + //layout=circo + overlap=false + //rankdir=LR; // Set the direction to left to right + node1 [label="1. Single \nNode"] + node2 [label="2. Nodes \nw/ Replication"] + node3 [label="2. Nodes \nw/ Embedded ZK"] + node5 [label="4. roles=data,zookeeper"] + node6 [label="5. External \nZK Ensemble"] + node7 [label="6. Solr Operator\n + Kubernetes"] + + node1 -> node2 + node2 -> node5 + node1 -> node3 + node3 -> node5 + node5 -> node6 + node6 -> node7 + +} +.... + + +== Solr from smallest to largest + +When we start up Solr on our computer, we're already starting Solr with the underpinnings required to let Solr scale in a smooth fashion, the coordination library ZooKeeper. +ZooKeeper is the unifying technology that supports maintaining state from a single node up to many 1000's of nodes. + +=== Simplest Setup + +If you only need a single Solr node, then it's perfectly reasonable to start Solr with `bin/solr start`. You will have a single Solr node running in SolrCloud mode, with all the lovely APIs and features that SolrCloud provides. + +[graphviz] +.... +digraph single_node { + node [style=rounded] + node1 [shape=box, fillcolor=yellow] + + node1 +} +.... + +Use this approach when: + +* You have minimal load +* You can restart Solr and reindex your data quickly +* You are just playing around +* You aren't worried about HA or Failover +* You want the simplest deployment approach. + + +=== Introducing Fail Over + +The next most common setup after a single node is having two seperate nodes running on seperate machines, with one as the xref:cluster-types.adoc#leaders[Leader] and the other as the Follower. + +There are two approaches that you can take, one that uses loosely coupled Solr nodes with embedded ZooKeepers, and one with a shared ZooKeeper. Both of these work just fine if you only need a single xref:cluster-types.adoc#shards[Shard] to store your data. If you need multiple Shards for your data volume, skip down below. + +==== Loosely coupled Solr Nodes + +The first is using replication to copy complete Lucene segments over from the Leader to the Followers. +This allows you to run two completely independent Solr nodes and copy the data over. +See the xref:user-managed-index-replication.adoc[User Managed Index Replication] page to learn more about setting this up. + +NOTE: Need to update user-managed-index-replication.adoc to talk about doing this when embedded zk is set up. + +NOTE: Reference https://github.com/apache/solr/pull/1875 + +[graphviz] +.... +digraph leader_follower_replication { + node [style=rounded] + leader [shape=box] + follower [fillcolor=yellow, style="rounded,filled"] + + leader -> follower +} +.... + +You can get even fancier with this, by introducing the concept of Repeater nodes. + +[graphviz] +.... +digraph leader_repeater_follower_replication { + node [style=rounded] + leader [shape=box] + repeater [fillcolor=yellow, style="rounded,filled"] + follower [shape=box] + + leader -> repeater -> follower +} +.... + +And even multiple followers: + +[graphviz] +.... +digraph leader_repeater_followers_replication { + node [style=rounded] + leader [shape=box] + repeater [shape=box] + follower1 [fillcolor=yellow, style="rounded,filled"] + follower2 [fillcolor=yellow, style="rounded,filled"] + follower3 [fillcolor=yellow, style="rounded,filled"] + + leader -> repeater + repeater -> follower1 + repeater -> follower2 + repeater -> follower3 +} +.... + +Use these approaches when: + +* You want each Solr node to be completely independent in state. No shared ZooKeeper for managing interactions. +* You don't need any kind of realtime/near real time updates. +* You potentially have a slow network boundary between your nodes, and want something robust between them. +* All your updates can go to the leader node. + +Some con's to this approach are: + +* This is pull based, so the segments are pulled by the bottom node from each node above them, which introduces latency and potential for slightly differnet views of the data in the Leader and the various Followers. +* You need to set up via various API calls all the interactions between the various nodes. + +==== Embedded ZooKeeper Ensemble Setup + +NOTE: This needs Jason's https://github.com/apache/solr/pull/2391 to get to done done! + +The second approach you can take is to use a simple ZooKeeper xref:solr-glossary.adoc#ensemble[Ensemble] setup. You can start a pair of Solr's and have their embedded ZooKeeper join each other to form an Ensemble. And yes, I hear you when you say "this isn't a odd number and ZK quorums should be an odd number to avoid split brain etc". + +NOTE: What is the difference between fail over and high availablity? + +[graphviz] +.... +graph simple_embedded_zk_ensemble { + node [style=rounded] + layout=neato + node1 [shape=box] + node2 [shape=box] + + node1 -- node2 + node2 -- node1 +} +.... + + +Use this approach when: + +* You have only two Solr nodes and they are close to each other in network terms. +* This approach is for when you want fail over, but you aren't worried about high availablity. You have a load balancer in front of the two Solr nodes and it notices one goes away and balances traffic to the other one for querying. +* You will deal with the fall out to indexing if one of the nodes goes away. + +You can then scale this up to multiple Solr's: + +[graphviz] +.... +graph simple_embedded_zk_ensemble { + node [style=rounded] + layout=neato + node1 [shape=box] + node2 [shape=box] + node3 [shape=box] + node4 [shape=box] + node5 [shape=box] + + node1 -- node2 + node2 -- node3 + node3 -- node4 + node4 -- node5 + node5 -- node1 +} +.... + +Use these approaches when: + +* You want to be able to split your logical Collection across multiple Shards. You want to be able to distribute Replicas around the cluster. +* You don't want to go through the effort of deploying a seperate ZK ensemble independently. And honestly, you don't need to either. + + +Some con's to this approach are: + +* Having five ZK's all updating each other is fine, but it starts to break down if you went to 9 or 11 ZooKeeper forming the Quorum. +* We currently don't have any flexible resizing of the quorum. You kind of just have to pick it. + +=== Moving Beyond the Basic Cluster + +NOTE: This isn't yet fleshed out as to how it works! + +Solr has a concept of node xref:deployment-guide:node-roles.adoc#ensemble[Roles] that could be leveraged to establish a set of Solr nodes that run embedded ZooKeeper, and then a larger set of Solr nodes that connect to those ZooKeepers. We currently have the concept of "data" nodes that hosts shards and replicas, we can introduce a "zookeeper" node that also runs the embedded ZooKeeper process. + +This will work well as you grow from six to 12 nodes in your cluster. + +[graphviz] +.... +graph simple_embedded_zk_ensemble { + node [style=rounded] + layout=circo + overlap=false + node1 [shape=box, label="data, zookeeper", fillcolor=yellow, style="rounded,filled"] + node2 [shape=box, label="data, zookeeper", fillcolor=yellow, style="rounded,filled"] + node3 [shape=box, label="data, zookeeper", fillcolor=yellow, style="rounded,filled"] + node4 [shape=box, label="data"] + node5 [shape=box, label="data"] + node6 [shape=box, label="data"] + node7 [shape=box, label="data"] + node8 [shape=box, label="data"] + node9 [shape=box, label="data"] + + + node1 -- node2 + node2 -- node3 + node3 -- node1 + node3 -- node4 + node4 -- node5 + node5 -- node6 + node6 -- node7 + node7 -- node8 + node8 -- node9 + node9 -- node1 +} +.... + +=== A dedicated ZooKeeper ensemble + +As your load in the cluster goes up, sharing ZooKeeper workloads with Solr workloads may become a bottleneck. + +NOTE: I wonder if this ever goes away by just having Solr nodes with the role `zookeeper` only? + +[graphviz] +.... +graph dedicate_zk_ensemble { + node [style=rounded] + layout=osage + overlap=false + node1 [shape=box, label=" zookeeper", fillcolor=yellow, style="rounded,filled"] + node2 [shape=box, label=" zookeeper", fillcolor=yellow, style="rounded,filled"] + node3 [shape=box, label=" zookeeper", fillcolor=yellow, style="rounded,filled"] + node4 [shape=box] + node5 [shape=box] + node6 [shape=box] + node7 [shape=box] + node8 [shape=box] + node9 [shape=box] + node10 [shape=box] + node11 [shape=box] + node12 [shape=box] + node13 [shape=box] + node14 [shape=box] + node15 [shape=box] + node16 [shape=box] + node17 [shape=box] + node18 [shape=box] + node19 [shape=box] + node20 [shape=box] + +} +.... + +Use this approach when: + +* You go beyond 12 Solr nodes up to 25 Solr nodes. +* You are leveraging all the features of SolrCloud to support multiple collections and different types of query and load characteritics, especially tuning shard and replica counts. +* You may need to move to five ZooKeepers. + +Some con's to this approach are: + +* You are responsible for configuring the external ZooKeeper ensemble. +* If you have any issues with the ZooKeeper ensemble then you need to define how you will handle failover/HA. + +=== Going massive means going Kubernetes + +NOTE: What would a diagram look like? How to show the operator? + +Beyond 25 nodes, you really need to think about more advanced tooling for managing all your nodes. + +[graphviz] +.... +graph kubernetes_setup { + fontname="Helvetica,Arial,sans-serif" + node [fontname="Helvetica,Arial,sans-serif"] + edge [fontname="Helvetica,Arial,sans-serif"] + layout=fdp + pack=1 + + Operator [fillcolor=aqua, style="filled"] + + zk1 [shape=box, label=" zookeeper", fillcolor=yellow, style="rounded,filled"] + zk2 [shape=box, label=" zookeeper", fillcolor=yellow, style="rounded,filled"] + zk3 [shape=box, label=" zookeeper", fillcolor=yellow, style="rounded,filled"] + + subgraph clusterKubernetes { + + Operator; + subgraph clusterSolr { + node1 + node2 + node3 + node4 + node5 + node6 + node7 + node8 + node9 + node10 + node11 + node12 + node13 + node14 + node15 + node16 + node17 + node18 + node19 + node20 + node21 + node22 + node23 + node24 + node25 + node26 + node27 + node28 + node29 + node30 + + } + subgraph clusterZK { + zk1 -- zk2; + zk2 -- zk3; + zk3 -- zk1; + } + } + + clusterSolr -- clusterZK +} +.... + +Use this approaches when: + +* You go beyond 24 Solr nodes. + +Some con's to this approach are: + +* Kubernetes is much like Oregon Trail, take a friend. + +== What about User Managed Solr? + +The User Managed mode is no longer recommended, and historically was mostly used because running embedded ZooKeeper was viewed as difficult. +These days, running embedded ZooKeeper is just fine, and that eliminates the main reason for User Managed. User Managed also doesn't support all the features and APIs that SolrCloud supports. + +== What about Embedding Solr in my Java Application? + +Yes, there is embedded Solr. YMMV. + +== What about Massive Multi-Tenant Use Cases? + +NOTE: Paging David Smiley...? + +Running thousands of collections, each representing it's own tenant? +Yeah, there are some things you need to do: + +* Item 1 +* Item 2 diff --git a/solr/solr-ref-guide/modules/deployment-guide/pages/zookeeper-ensemble.adoc b/solr/solr-ref-guide/modules/deployment-guide/pages/zookeeper-ensemble.adoc index 7bc232bb5ff..5990621f97d 100644 --- a/solr/solr-ref-guide/modules/deployment-guide/pages/zookeeper-ensemble.adoc +++ b/solr/solr-ref-guide/modules/deployment-guide/pages/zookeeper-ensemble.adoc @@ -17,12 +17,14 @@ // specific language governing permissions and limitations // under the License. -Although Solr comes bundled with http://zookeeper.apache.org[Apache ZooKeeper], you are strongly encouraged to use an external ZooKeeper setup in production. +Although Solr comes bundled with http://zookeeper.apache.org[Apache ZooKeeper], depending on your scaling needs you may need to use a external ZooKeeper setup in production. -While using Solr's embedded ZooKeeper instance is fine for getting started, you shouldn't use this in production because it does not provide any failover: if the Solr instance that hosts ZooKeeper shuts down, ZooKeeper is also shut down. +ERIC: this is editorial content that should be moved. +While using Solr's embedded ZooKeeper instance is fine for smaller setups, you shouldn't use this in production because it does not provide any failover: if the Solr instance that hosts ZooKeeper shuts down, ZooKeeper is also shut down. Any shards or Solr instances that rely on it will not be able to communicate with it or each other. The solution to this problem is to set up an external ZooKeeper _ensemble_, which is a number of servers running ZooKeeper that communicate with each other to coordinate the activities of the cluster. +ERIC: End editorial. == How Many ZooKeeper Nodes? diff --git a/solr/solr-ref-guide/playbook.template.yml b/solr/solr-ref-guide/playbook.template.yml index ad283d03392..8393fcd8add 100644 --- a/solr/solr-ref-guide/playbook.template.yml +++ b/solr/solr-ref-guide/playbook.template.yml @@ -47,9 +47,11 @@ output: asciidoc: attributes: stem: + kroki-fetch-diagram: true extensions: - '@djencks/asciidoctor-mathjax' - '@asciidoctor/tabs' + - asciidoctor-kroki runtime: fetch: true