[DOCS] Added tables and fixes to upgrade.asciidoc, fixed version in R…

…EADME.textile

Author: Sean Gallagher
Date: 10 Apr 2014 15:23 EDT

README.textile

@@ -208,7 +208,7 @@ running the Elasticsearch test suite.
 
 h3. Upgrading to Elasticsearch 1.x?
 
-In order to ensure a smooth upgrade process from earlier versions of Elasticsearch (< 0.90.x), it is recommended to perform a full cluster restart. Please see the "Upgrading" section of the "setup reference":http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/setup.html.
+In order to ensure a smooth upgrade process from earlier versions of Elasticsearch (< 1.0.0), it is recommended to perform a full cluster restart. Please see the "Upgrading" section of the "setup reference":http://www.elasticsearch.org/guide/en/elasticsearch/reference/current/setup.html.
 
 h1. License
 

docs/reference/setup/upgrade.asciidoc

@@ -1,7 +1,21 @@
 [[setup-upgrade]]
 == Upgrading
 
-Elasticsearch can usually be upgraded using a rolling upgrade process, resulting in no interruption of service.  This section details how to perform both rolling and restart upgrades.
+Elasticsearch can usually be upgraded using a rolling upgrade process, resulting in no interruption of service.  This section details how to perform both rolling and restart upgrades.  To determine whether a rolling upgrade is supported for your release, please consult this table:
+
+[cols="1,2,3",options="header",]
+|=======================================================================
+|Upgrade From |Upgrade To |Supported Upgrade Type
+|0.90.x |1.x |Restart Upgrade
+
+|< 0.90.7 |0.90.x |Restart Upgrade
+
+|>= 0.90.7 |0.90.x |Rolling Upgrade
+
+|1.x |1.x |Rolling Upgrade
+|=======================================================================
+
+Before upgrading from 0.90.x or any earlier version to 1.x or later, it is a good idea to consult the <<breaking-changes,breaking changes>> docs.
 
 [float]
 [[backup]]
@@ -58,9 +72,24 @@ To back up a running 1.0 or later system, it is simplest to use the snapshot fea
 
 [float]
 [[rolling-upgrades]]
-=== Rolling Upgrades
+=== Rolling upgrade process
 
-Within major releases after release 1.0, rolling upgrades are supported.  To perform a rolling upgrade:
+A rolling upgrade allows the ES cluster to be upgraded one node at a time, with no observable downtime for end users.  Running multiple versions of Elasticsearch in the same cluster for any length of time beyond that required for an upgrade is not supported, as shard replication from the more recent version to the previous versions will not work.
+
+Within minor or maintenance releases after release 1.0, rolling upgrades are supported.  To perform a rolling upgrade:
+
+* Disable shard reallocation (optional).  This is done to allow for a faster startup after cluster shutdown.  If this step is not performed, the nodes will immediately start trying to replicate shards to each other on startup and will spend a lot of time on wasted I/O.  With shard reallocation disabled, the nodes will join the cluster with their indices intact, without attempting to rebalance.  After startup is complete, reallocation will be turned back on.
+
+This syntax applies to Elasticsearch 1.0 and later:
+
+[source,sh]
+--------------------------------------------------
+        curl -XPUT localhost:9200/_cluster/settings -d '{
+                "transient" : {
+                    "cluster.routing.allocation.enable" : "none"
+                }
+        }'
+--------------------------------------------------
 
 * Shut down a single node within the cluster.
 
@@ -73,22 +102,35 @@ curl -XPOST 'http://localhost:9200/_cluster/nodes/_local/_shutdown'
 
 * Upgrade the stopped node.  To upgrade using a zip or compressed tarball from elasticsearch.org:
 ** Extract the zip or tarball to a new directory, usually in the same volume as the current Elasticsearch installation.  Do not overwrite the existing installation, as the downloaded archive will contain a default elasticsearch.yml file and will overwrite your existing configuration.
-** Copy the configuration files from the old Elasticsearch installation's config directory to the new Elasticsearch installation's config directory.  Copy data files if necessary.  If data files are not located within the tarball's extraction directory, they will not have to be moved.
+** Copy the configuration files from the old Elasticsearch installation's config directory to the new Elasticsearch installation's config directory.  Move data files from the old Elasticsesarch installation's data directory if necessary.  If data files are not located within the tarball's extraction directory, they will not have to be moved.
 ** The simplest solution for moving from one version to another is to have a symbolic link for 'elasticsearch' that points to the currently running version.  This link can be easily updated and will provide a stable access point to the most recent version.  Update this symbolic link if it is being used.
 
 *To upgrade using a .deb or .rpm package:
 
 ** Use rpm or deb to install the new package.  All files should be placed in their proper locations, and config files should not be overwritten.
 
-** Start the now upgraded node.  Observe that all shards are properly allocated back to the node and that it joins the cluster smoothly.
+* Start the now upgraded node.  Confirm that it joins the cluster.
+
+* Repeat this process for all remaining nodes.
+
+* When the process is complete on all nodes, you can re-enable shard reallocation:
+
+[source,sh]
+--------------------------------------------------
+        curl -XPUT localhost:9200/_cluster/settings -d '{
+                "transient" : {
+                    "cluster.routing.allocation.enable" : "all"
+                }
+        }'
+--------------------------------------------------
 
-Repeat this process for all remaining nodes.
+* Observe that all shards are properly allocated on all nodes.  Balancing may take some time.
 
 It may be possible to perform the upgrade by installing the new software while the service is running.  This would reduce downtime by ensuring the service was ready to run on the new version as soon as it is stopped on the node being upgraded.  This can be done by installing the new version in its own directory and using the symbolic link method outlined above.  It is important to test this procedure first to be sure that site-specific configuration data and production indices will not be overwritten during the upgrade process.
 
 [float]
 [[restart-upgrade]]
-=== Upgrading from 0.90.x or earlier to 1.0 or later
+=== Cluster restart upgrade process
 
 Elasticsearch releases prior to 1.0 and releases after 1.0 are not compatible with each other, so a rolling upgrade is not possible.  In order to upgrade a pre-1.0 system to 1.0 or later, a full cluster stop and start is required.  In order to perform this upgrade:
 
@@ -115,9 +157,9 @@ This syntax is from versions prior to 1.0:
 
 * After upgrading Elasticsearch on all nodes is complete, the cluster can be started by starting each node individually.
 ** Start master-eligible nodes first, one at a time.  Verify that a quorum has been reached and a master has been elected before proceeding.
-** Start data and client nodes one at a time, verifying that they successfully join the cluster.
+** Start data nodes and then client nodes one at a time, verifying that they successfully join the cluster.
 
-* When the cluster is up and running, shard reallocation can be enabled.
+* When the cluster is running and reaches a yellow state, shard reallocation can be enabled.
 
 This syntax is from release 1.0 and later:
 [source,sh]