From 8d3810df548e1edd88b7b8a68703362b590dca6a Mon Sep 17 00:00:00 2001
From: Noble Paul <noble@apache.org>
Date: Tue, 16 Oct 2018 17:38:51 +1100
Subject: [PATCH] SOLR-12740: migration docs

---
 .../src/migrate-to-policy-rule.adoc           | 170 ++++++++++++++++++
 1 file changed, 170 insertions(+)
 create mode 100644 solr/solr-ref-guide/src/migrate-to-policy-rule.adoc

diff --git a/solr/solr-ref-guide/src/migrate-to-policy-rule.adoc b/solr/solr-ref-guide/src/migrate-to-policy-rule.adoc
new file mode 100644
index 00000000000..c91e272f2a3
--- /dev/null
+++ b/solr/solr-ref-guide/src/migrate-to-policy-rule.adoc
@@ -0,0 +1,170 @@
+= Migrate to Policy Rules
+// 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.
+
+Replica placement rules (legacy) are deprecated in favor of the new policy and preferences syntax (new). This document helps you to migrate your existing replica placement rules to the new syntax.
+
+Every rule in the legacy framework can be expressed in the new syntax. Please refer to <<solrcloud-autoscaling-policy-preferences.adoc ,Autoscaling Policy & Preferences>> document for more details.
+
+
+The following is the legacy syntax for a rule that limits maximum one replica for each shard in any Solr node
+[source,text]
+----
+replica:<2,node:*,shard:**
+----
+The rules are specified along with a collection creation operation as the `rules` parameter
+
+The equivalent new syntax is
+[source,json]
+----
+{"replica":"<2","node":"#ANY","shard":"#EACH"}
+----
+
+The new policy rules have to be created separately using an API call  <<solrcloud-autoscaling-api.adoc#Create and Modify Cluster Policies, See examples>>
+
+
+=== Rule Operators
+
+All the following operators can be directly used in the new policy syntax and they mean the same.
+
+* *equals (no operator required)*: `tag:x` means tag value must be equal to ‘x’
+* *greater than (>)*: `tag:>x` means tag value greater than ‘x’. x must be a number
+* *less than (<)*: `tag:<x` means tag value less than ‘x’. x must be a number
+* *not equal (!)*: `tag:!x` means tag value MUST NOT be equal to ‘x’. The equals check is performed on String value
+
+=== Fuzzy Operator (~)
+There is no `~` operator in the new syntax. Please use the attribute `"strict":false` instead
+
+example:
+[source,json]
+----
+{"replica":"<2","node":"#ANY","shard":"#EACH", "strict": false}
+----
+
+
+== Tag names
+
+Tag values are provided by the framework and these tags mean the same the new syntax as well
+
+
+* *cores*: Number of cores in the node
+* *freedisk*: Disk space available in the node
+* *host*: host name of the node
+* *port*: port of the node
+* *node*: node name
+* *role*: The role of the node. The only supported role is 'overseer'
+* *ip_1, ip_2, ip_3, ip_4*: These are ip fragments for each node. For example, in a host with ip `192.168.1.2`, `ip_1 = 2`, `ip_2 =1`, `ip_3 = 168` and` ip_4 = 192`
+* *sysprop.\{PROPERTY_NAME}*: These are values available from system properties. `sysprop.key` means a value that is passed to the node as `-Dkey=keyValue` during the node startup. It is possible to use rules like `sysprop.key:expectedVal,shard:*`
+
+=== Snitches
+There is no equivalent for a snitch in the new policy framework
+
+== Porting existing Replica placement rules
+
+=== Keep less than 2 replicas (at most 1 replica) of this collection on any node
+
+For this rule, we define the `replica` condition with operators for "less than 2", and use a pre-defined tag named `node` to define nodes with any name.
+
+*legacy:*
+
+[source,text]
+----
+replica:<2,node:*
+----
+
+*new:*
+
+[source,json]
+----
+{"replica":"<2","node":"#ANY"}
+----
+=== For a given shard, keep less than 2 replicas on any node
+
+For this rule, we use the `shard` condition to define any shard, the `replica` condition with operators for "less than 2", and finally a pre-defined tag named `node` to define nodes with any name.
+
+*legacy:*
+
+[source,text]
+----
+shard:*,replica:<2,node:*
+----
+
+*new:*
+
+[source,json]
+----
+{"replica":"<2","shard":"#EACH", "node":"#ANY"}
+----
+=== Assign all replicas in shard1 to rack 730
+
+This rule limits the `shard` condition to 'shard1', but any number of replicas. We're also referencing a custom tag named `rack`. Before defining this rule, we will need to configure a custom Snitch which provides values for the tag `rack`.
+
+*legacy:*
+
+[source,text]
+----
+shard:shard1,replica:*,rack:730
+----
+
+*new:*
+
+[source,json]
+----
+{"replica":"#ALL", "shard":"shard1", "sysprop.rack":"730"}
+----
+
+Please note that all your nodes must be started with a system property `-Drack=<rack-number>`
+
+
+=== Create replicas in nodes with less than 5 cores only
+
+This rule uses the `replica` condition to define any number of replicas, but adds a pre-defined tag named `core` and uses operators for "less than 5".
+
+*legacy:*
+
+[source,text]
+----
+cores:<5
+----
+
+*new:*
+
+[source,json]
+----
+{"cores":"<5", "node":"#ANY"}
+----
+
+=== Do not create any replicas in host 192.45.67.3
+
+*legacy:*
+
+[source,text]
+----
+host:!192.45.67.3
+----
+
+*new:*
+
+[source,json]
+----
+{"replica": 0, "host":"192.45.67.3"}
+----
+
+
+== Defining Rules
+
+Rules are always defined in along with the collection in the legacy system. The new syntax allows you to specify rules globally as well as on a <<solrcloud-autoscaling-policy-preferences.adoc#Defining Collection-Specific Policies,per collection basis>>