You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@lucene.apache.org by ct...@apache.org on 2017/07/31 18:20:13 UTC
lucene-solr:jira/solr-10821: SOLR-10821: standardize "autoscaling"
spelling & headings; other small copy edits
Repository: lucene-solr
Updated Branches:
refs/heads/jira/solr-10821 4644e2963 -> d77c47869
SOLR-10821: standardize "autoscaling" spelling & headings; other small copy edits
Project: http://git-wip-us.apache.org/repos/asf/lucene-solr/repo
Commit: http://git-wip-us.apache.org/repos/asf/lucene-solr/commit/d77c4786
Tree: http://git-wip-us.apache.org/repos/asf/lucene-solr/tree/d77c4786
Diff: http://git-wip-us.apache.org/repos/asf/lucene-solr/diff/d77c4786
Branch: refs/heads/jira/solr-10821
Commit: d77c4786909e406ba194ef7144e1abd38c8bce83
Parents: 4644e29
Author: Cassandra Targett <ct...@apache.org>
Authored: Mon Jul 31 13:19:30 2017 -0500
Committer: Cassandra Targett <ct...@apache.org>
Committed: Mon Jul 31 13:19:30 2017 -0500
----------------------------------------------------------------------
.../src/solrcloud-autoscaling-api.adoc | 78 +++++++++++---------
.../src/solrcloud-autoscaling-overview.adoc | 26 +++----
...olrcloud-autoscaling-policy-preferences.adoc | 2 +-
.../src/solrcloud-autoscaling.adoc | 14 ++--
solr/solr-ref-guide/src/solrcloud.adoc | 2 +-
5 files changed, 66 insertions(+), 56 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/d77c4786/solr/solr-ref-guide/src/solrcloud-autoscaling-api.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/solrcloud-autoscaling-api.adoc b/solr/solr-ref-guide/src/solrcloud-autoscaling-api.adoc
index 224def9..26e1290 100644
--- a/solr/solr-ref-guide/src/solrcloud-autoscaling-api.adoc
+++ b/solr/solr-ref-guide/src/solrcloud-autoscaling-api.adoc
@@ -1,4 +1,4 @@
-= SolrCloud AutoScaling API
+= SolrCloud Autoscaling API
:page-shortname: solrcloud-autoscaling-api
:page-permalink: solrcloud-autoscaling-api.html
:page-toclevels: 2
@@ -20,15 +20,15 @@
// specific language governing permissions and limitations
// under the License.
-The AutoScaling API can be used to read, set and remove cluster policy, preferences as well as for diagnostics on the state of the cluster.
+The Autoscaling API can be used to manage autoscaling policies and preferences, and to get diagnostics on the state of the cluster.
== Read API
-The AutoScaling read API is available at `/admin/autoscaling` as well as on `/v2/cluster/autoscaling` path. It returns information about the configured cluster preferences, cluster policy and collection specific policies.
+The autoscaling Read API is available at `/admin/autoscaling` or `/v2/cluster/autoscaling`. It returns information about the configured cluster preferences, cluster policy and collection-specific policies.
This API does not take any parameters.
-=== Read API response
+=== Read API Response
The output will contain cluster preferences, cluster policy and collection specific policies.
@@ -54,17 +54,17 @@ The output will contain cluster preferences, cluster policy and collection speci
}
----
-== Diagnostics
+== Diagnostics API
-The diagnostics API shows the violations, if any, of all conditions in the cluster or collection specific policy. It is available at the `/admin/autoscaling/diagnostics` path.
+The diagnostics API shows the violations, if any, of all conditions in the cluster or collection-specific policy. It is available at the `/admin/autoscaling/diagnostics` path.
This API does not take any parameters.
-=== Diagnostics API response
+=== Diagnostics API Response
The output will contain `sortedNodes` which is a list of nodes in the cluster sorted according to overall load in descending order (as determined by the preferences) and `violations` which is a list of nodes along with the conditions that they violate.
-=== Diagnostics API examples
+=== Examples Using Diagnostics API
Here is an example with no violations but in the `sortedNodes` section, we can see that the first node is most loaded (according to number of cores):
@@ -93,11 +93,14 @@ Here is an example with no violations but in the `sortedNodes` section, we can s
----
Suppose we added a condition to the cluster policy as follows:
+
[source,json]
----
-{ "replica": "<2", "shard": "#EACH", "node": "#ANY"}
+{"replica": "<2", "shard": "#EACH", "node": "#ANY"}
----
+
However, since the first node in the first example had more than 1 replica for a shard already, then the diagnostics API will return:
+
[source,json]
----
{
@@ -145,9 +148,9 @@ In the above example the node with port 8983 has two replicas for `shard1` in vi
The Write API is available at the same `/admin/autoscaling` and `/v2/cluster/autoscaling` endpoints as the read API but can only be used with the *POST* HTTP verb.
-The payload of the POST request is a JSON message having commands to set and remove components. Multiple commands can be specified together in the payload. The commands are executed in the order specified and the changes are atomic i.e. either all succeed or none.
+The payload of the POST request is a JSON message with commands to set and remove components. Multiple commands can be specified together in the payload. The commands are executed in the order specified and the changes are atomic, i.e., either all succeed or none.
-=== set-cluster-preferences: Create and modify cluster preferences
+=== set-cluster-preferences: Create and Modify Cluster Preferences
The cluster preferences are specified as a list of sort preferences. Multiple sorting preferences can be specified and they are applied in order.
@@ -157,19 +160,20 @@ Each preference is a JSON map having the following syntax:
You can see the __TODO__ section to know more about the allowed values for the `sort_order`, `sort_param` and `precision` parameters.
-*Input*:
+*Input*
+
[source,json]
----
{
- "set-cluster-preferences" : [
- { "minimize": "cores"}
+ "set-cluster-preferences" : [
+ {"minimize": "cores"}
]
}
----
-*Output*:
+*Output*
-The output has a key named `result` which either has `success` or `failure` as the value depending on whether the command succeeded or failed.
+The output has a key named `result` which will return either `success` or `failure` depending on whether the command succeeded or failed.
[source,json]
----
@@ -183,14 +187,14 @@ The output has a key named `result` which either has `success` or `failure` as t
}
----
-==== Example
+==== Example Setting Cluster Preferences
In this example we add cluster preferences that sort on three different parameters:
[source,json]
----
{
- "cluster-preferences": [
+ "set-cluster-preferences": [
{
"minimize": "cores",
"precision": 2
@@ -207,7 +211,7 @@ In this example we add cluster preferences that sort on three different paramete
}
----
-=== set-cluster-policy: Create and modify cluster preferences
+=== set-cluster-policy: Create and Modify Cluster Policies
You can see the __TODO__ section to know more about the allowed values for each condition in the policy.
@@ -215,8 +219,8 @@ You can see the __TODO__ section to know more about the allowed values for each
[source,json]
----
{
- "set-cluster-policy" : [
- { "replica": "<2", "shard": "#EACH", "node": "#ANY"}
+ "set-cluster-policy": [
+ {"replica": "<2", "shard": "#EACH", "node": "#ANY"}
]
}
----
@@ -234,25 +238,28 @@ Output:
}
----
-=== set-policy: Create and modify collection specific policy
+=== set-policy: Create and Modify Collection-Specific Policy
This command accepts a map of policy name to the list of conditions for that policy. Multiple named policies can be specified together. A named policy that does not exist already is created and if the named policy accepts already then it is replaced.
You can see the __TODO__ section to know more about the allowed values for each condition in the policy.
-*Input*:
+*Input*
+
[source,json]
----
{
- "set-policy" : {
- "policy1": [
- {"replica": "1", "shard": "#EACH", "port": "8983"}
- ]
- }
+ "set-policy": {
+ "policy1": [
+ {"replica": "1", "shard": "#EACH", "port": "8983"}
+ ]
+ }
}
----
-*Output*:
+*Output*
+
+[source,json]
----
{
"responseHeader": {
@@ -264,19 +271,18 @@ You can see the __TODO__ section to know more about the allowed values for each
}
----
-=== remove-policy: Remove a collection specific policy
+=== remove-policy: Remove a Collection-Specific Policy
This command accepts a policy name to be removed from Solr. The policy being removed must not be attached to any collection otherwise the command will fail.
-*Input*:
+*Input*
[source,json]
----
-{
- "remove-policy" : "policy1"
-}
+{"remove-policy": "policy1"}
----
-*Output*:
+*Output*
+[source,json]
----
{
"responseHeader": {
@@ -286,4 +292,4 @@ This command accepts a policy name to be removed from Solr. The policy being rem
"result": "success",
"WARNING": "This response format is experimental. It is likely to change in the future."
}
-----
\ No newline at end of file
+----
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/d77c4786/solr/solr-ref-guide/src/solrcloud-autoscaling-overview.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/solrcloud-autoscaling-overview.adoc b/solr/solr-ref-guide/src/solrcloud-autoscaling-overview.adoc
index d5eeccc..f0caf92 100644
--- a/solr/solr-ref-guide/src/solrcloud-autoscaling-overview.adoc
+++ b/solr/solr-ref-guide/src/solrcloud-autoscaling-overview.adoc
@@ -1,4 +1,4 @@
-= Overview of AutoScaling in SolrCloud
+= Overview of Autoscaling in SolrCloud
:page-shortname: solrcloud-autoscaling-overview
:page-permalink: solrcloud-autoscaling-overview.html
:page-toclevels: 1
@@ -20,40 +20,40 @@
// specific language governing permissions and limitations
// under the License.
-The goal of autoscaling feature is to make SolrCloud cluster management easier, automatic and intelligent. It aims to provide good defaults such that the cluster remains balanced and stable in the face of various events such as a node joining the cluster or leaving the cluster. This is achieved by satisfying a set of rules and sorting preferences that help Solr select the target of cluster management operations.
+Autoscaling in Solr aims to provide good defaults such that the cluster remains balanced and stable in the face of various events such as a node joining the cluster or leaving the cluster. This is achieved by satisfying a set of rules and sorting preferences that help Solr select the target of cluster management operations.
== Cluster Preferences
-The cluster preferences, as the name suggests, apply to all cluster management operations regardless of which collection they affect.
+Cluster preferences, as the name suggests, apply to all cluster management operations regardless of which collection they affect.
-A preference is a sort conditions that help Solr select nodes that either maximize or minimize given metrics e.g. a preference `{minimize : cores}` will help Solr select nodes such that the number of cores on each node is minimized. We write cluster preference in a way that reduces the overall load on the system. You can add more than one preferences to break ties.
+A preference is a set of conditions that help Solr select nodes that either maximize or minimize given metrics. For example, a preference `{minimize : cores}` will help Solr select nodes such that the number of cores on each node is minimized. We write cluster preference in a way that reduces the overall load on the system. You can add more than one preferences to break ties.
-The default cluster preferences consist of the above example which is to minimize the number of cores on all nodes.
+The default cluster preferences consist of the above example (`{minimize : cores}`) which is to minimize the number of cores on all nodes.
You can learn more about preferences in the __TODO__ section.
== Cluster Policy
-The cluster policy is a set of conditions that a node, shard or collection must satisfy before it can be chosen as the target of a cluster management operation. These conditions are applied across the cluster regardless of the collection being managed. For example, the condition `{"cores":"<10", "node":"#ANY"}` means that any node must have less than ten Solr cores in total regardless of which collection they belong to.
+A cluster policy is a set of conditions that a node, shard, or collection must satisfy before it can be chosen as the target of a cluster management operation. These conditions are applied across the cluster regardless of the collection being managed. For example, the condition `{"cores":"<10", "node":"#ANY"}` means that any node must have less than ten Solr cores in total regardless of which collection they belong to.
-There are many metrics on which the condition can be based e.g. system load average, heap usage, free disk space etc. The full list of supported metrics can be found at __TODO__ section.
+There are many metrics on which the condition can be based e.g., system load average, heap usage, free disk space etc. The full list of supported metrics can be found at __TODO__ section.
When a node, shard or collection does not satisfy the policy, we call it a *violation*. Solr ensures that cluster management operations minimize the number of violations. The cluster management operations are either invoked manually by us or automatically in response to *Triggers*.
-== Collection specific policies
+== Collection-Specific Policies
-Sometimes a collection may need conditions in addition to those specified in the cluster policy. In such cases, we can create named policies that can be used for specific collections. Firstly, we can use the `set-policy` API to create a new policy and then specify `policy=<policy_name>` parameter to the create collection API.
+Sometimes a collection may need conditions in addition to those specified in the cluster policy. In such cases, we can create named policies that can be used for specific collections. Firstly, we can use the `set-policy` API to create a new policy and then specify the `policy=<policy_name>` parameter to the CREATE command of the Collection API.
`/admin/collections?action=CREATE&name=coll1&numShards=1&replicationFactor=2&policy=policy1`
-The above create collection command will associate a policy named policy1 with the collection named coll1. Only a single policy may be associated with a collection.
+The above create collection command will associate a policy named `policy1` with the collection named `coll1`. Only a single policy may be associated with a collection.
-Note that the collection specific policy is applied *in addition* to the cluster policy i.e. it is not an override but an augmentation. Therefore the collection will follow all conditions laid out in the cluster preferences, cluster policy and the policy named `policy1`.
+Note that the collection-specific policy is applied *in addition* to the cluster policy, i.e., it is not an override but an augmentation. Therefore the collection will follow all conditions laid out in the cluster preferences, cluster policy, and the policy named `policy1`.
You can learn more about collection specific policies in the __TODO__ section.
-== AutoScaling APIs
+== Autoscaling APIs
The autoscaling APIs available at `/admin/autoscaling` can be used to read and modify each of the components discussed above.
-You can learn more about these APIs in the __TODO__ section.
\ No newline at end of file
+You can learn more about these APIs in the __TODO__ section.
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/d77c4786/solr/solr-ref-guide/src/solrcloud-autoscaling-policy-preferences.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/solrcloud-autoscaling-policy-preferences.adoc b/solr/solr-ref-guide/src/solrcloud-autoscaling-policy-preferences.adoc
index d12f5b8..ea47d17 100644
--- a/solr/solr-ref-guide/src/solrcloud-autoscaling-policy-preferences.adoc
+++ b/solr/solr-ref-guide/src/solrcloud-autoscaling-policy-preferences.adoc
@@ -1,4 +1,4 @@
-= SolrCloud AutoScaling Policy and Preferences
+= SolrCloud Autoscaling Policy and Preferences
:page-shortname: solrcloud-autoscaling-policy-preferences
:page-permalink: solrcloud-autoscaling-policy-preferences.html
// Licensed to the Apache Software Foundation (ASF) under one
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/d77c4786/solr/solr-ref-guide/src/solrcloud-autoscaling.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/solrcloud-autoscaling.adoc b/solr/solr-ref-guide/src/solrcloud-autoscaling.adoc
index 373818d..d9d2017 100644
--- a/solr/solr-ref-guide/src/solrcloud-autoscaling.adoc
+++ b/solr/solr-ref-guide/src/solrcloud-autoscaling.adoc
@@ -1,4 +1,4 @@
-= SolrCloud AutoScaling
+= SolrCloud Autoscaling
:page-shortname: solrcloud-autoscaling
:page-permalink: solrcloud-autoscaling.html
:page-children: solrcloud-autoscaling-overview, solrcloud-autoscaling-api, solrcloud-autoscaling-policy-preferences
@@ -19,8 +19,12 @@
// specific language governing permissions and limitations
// under the License.
-This section describes the autoscaling features of SolrCloud. It covers the following topics:
+The goal of autoscaling is to make SolrCloud cluster management easier by providing a way for changes to the cluster to be more automatic and more intelligent.
-* <<solrcloud-autoscaling-overview.adoc#solrcloud-autoscaling-overview,Overview of AutoScaling in SolrCloud>>
-* <<solrcloud-autoscaling-api.adoc#solrcloud-autoscaling-api,SolrCloud AutoScaling API>>
-* <<solrcloud-autoscaling-policy-preferences.adoc#solrcloud-autoscaling-policy-preferences,SolrCloud AutoScaling Policy and Preferences>>
\ No newline at end of file
+Autoscaling includes an API to manage cluster-wide and collection-specific policies and preferences and a rules syntax to define the guidelines for your cluster. Future Solr releases will include features to utilize the policies and preferences so they perform actions automatically when the rules are violated.
+
+The following sections describe the autoscaling features of SolrCloud:
+
+* <<solrcloud-autoscaling-overview.adoc#solrcloud-autoscaling-overview,Overview of Autoscaling in SolrCloud>>
+* <<solrcloud-autoscaling-api.adoc#solrcloud-autoscaling-api,SolrCloud Autoscaling API>>
+* <<solrcloud-autoscaling-policy-preferences.adoc#solrcloud-autoscaling-policy-preferences,SolrCloud Autoscaling Policy and Preferences>>
http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/d77c4786/solr/solr-ref-guide/src/solrcloud.adoc
----------------------------------------------------------------------
diff --git a/solr/solr-ref-guide/src/solrcloud.adoc b/solr/solr-ref-guide/src/solrcloud.adoc
index 36154a2..10b647f 100644
--- a/solr/solr-ref-guide/src/solrcloud.adoc
+++ b/solr/solr-ref-guide/src/solrcloud.adoc
@@ -45,4 +45,4 @@ In this section, we'll cover everything you need to know about using Solr in Sol
** <<configsets-api.adoc#configsets-api,ConfigSets API>>
* <<rule-based-replica-placement.adoc#rule-based-replica-placement,Rule-based Replica Placement>>
* <<cross-data-center-replication-cdcr.adoc#cross-data-center-replication-cdcr,Cross Data Center Replication (CDCR)>>
-*<<solrcloud-autoscaling.adoc#solrcloud-autoscaling,SolrCloud AutoScaling>>
+* <<solrcloud-autoscaling.adoc#solrcloud-autoscaling,SolrCloud Autoscaling>>