docs: More comprehensive upgrade docs for 5.0+

These changes include all three known upgrade scenarios:

1. New installation (K3 -> K5)
2. Standard upgrade (K4.2 -> K5)
3. Standard upgrade with reindex (K4.1 -> K5)

docs/setup.asciidoc

@@ -26,13 +26,20 @@ version of Node.js is not supported.
 == Elasticsearch version
 
 Kibana should be configured to run against an Elasticsearch node of the same
-version.
+version. This is the officially supported configuration.
 
 Running different major version releases of Kibana and Elasticsearch (e.g.
 Kibana 5.x and Elasticsearch 2.x) is not supported, nor is running a minor
 version of Kibana that is newer than the version of Elasticsearch (e.g. Kibana
 5.1 and Elasticsearch 5.0).
 
+Running a minor version of Elasticsearch that is higher than Kibana will
+generally work in order to faciliate an upgrade process where Elasticsearch
+is upgraded first (e.g. Kibana 5.0 and Elasticsearch 5.1). In this
+configuration, a warning will be logged on Kibana server startup, so it's only
+meant to be temporary until Kibana is upgraded to the same version as
+Elasticsearch.
+
 Running different patch version releases of Kibana and Elasticsearch (e.g.
 Kibana 5.0.0 and Elasticsearch 5.0.1) is generally supported, though we
 encourage users to run the same versions of Kibana and Elasticsearch down to

docs/setup/upgrade.asciidoc

@@ -1,27 +1,54 @@
 [[upgrade]]
 == Upgrading Kibana
 
-Your existing Kibana version is generally compatible with the next minor
-version release of Elasticsearch. This means you should upgrade your
-Elasticsearch cluster(s) before or at the same time as Kibana. We cannot
-guarantee compatibility between major version releases so in those cases both
-Elasticsearch and Kibana must be upgraded together.
+[IMPORTANT]
+===========================================
+Before upgrading Kibana:
 
-To upgrade Kibana:
+* Consult the <<breaking-changes,breaking changes>> docs.
+* Test upgrades in a dev environment before upgrading your production servers.
+* Backup your data using the Elasticsearch
+  {es-ref}modules-snapshots.html[snapshots] feature.
+  You **cannot roll back** to an earlier version unless you have a backup of
+  your data.
+* If you are using custom plugins, check that a compatible version is
+  available.
+===========================================
 
-. Create a {es-ref}modules-snapshots.html[snapshot]
-of the existing `.kibana` index.
-. Back up the `kibana.yml` configuration file.
-. Take note of the Kibana plugins that are installed:
- * `bin/kibana plugin --list` on 4.x versions of Kibana.
- * `bin/kibana-plugin list` on 5.x versions of Kibana.
-. To upgrade from an Archive File:
-.. Extract the new version of Kibana into a different directory.  See steps below.
-.. Migrate any custom configuration from your old kibana.yml to your new one
-.. Follow other steps below to complete the new installation.
-.. Once the new version is fully configured and working with required plugins, remove the previous version
-of Kibana
-. To upgrade using a Linux Package Manager:
-.. Uninstall the existing Kibana package: `apt-get remove kibana` or `yum remove kibana`
-.. Install the new Kibana package.   There have been some installer issues between various version of
-Kibana so the uninstall and install process is safer than an upgrade.
+Depending on which version of Kibana you're upgrading from, the upgrade process
+will vary. Please consult the following table to determine which process you
+should follow:
+
+[cols="1<m,1<m,3",options="header",]
+|=======================================================================
+|Upgrade From   |Upgrade To     |Supported Upgrade Type
+|3.x            |5.x            |<<upgrade-new-install,New installation>>
+|4.0 or 4.1     |5.x            |<<upgrade-standard-reindex,Standard upgrade & reindex>>
+|4.x >= 4.2     |5.x            |<<upgrade-standard,Standard upgrade>>
+|5.0.0 pre GA   |5.x            |<<upgrade-standard-reindex,Standard upgrade & reindex>>
+|5.x            |5.y            |<<upgrade-standard,Standard upgrade>> (where `y > x`)
+|=======================================================================
+
+[IMPORTANT]
+===========================================
+Reindex is required if you ever upgraded from Kibana 4.1 or 4.0
+
+Even if you're running Kibana version 4.2 or higher, if you have previously
+upgraded from Kibana 4.0 or 4.1, you will need to do a
+<<upgrade-standard-reindex,Standard upgrade & reindex>> when upgrading to 5.x.
+
+This is due to the Elasticsearch requirement that any index that was initially
+created before Elasticsearch 2.0 must be reindexed even if it's currently
+working in Elasticsearch 2.x.
+
+You only need to do this once when moving to 5.x.
+===========================================
+
+NOTE: Saved searches, visualizations, and dashboards created in Kibana 4.x are
+generally compatible with 5.x.
+
+include::upgrade/upgrade-standard.asciidoc[]
+
+include::upgrade/upgrade-standard-reindex.asciidoc[]
+
+include::upgrade/upgrade-new-install.asciidoc[]

docs/setup/upgrade/upgrade-new-install.asciidoc

@@ -0,0 +1,10 @@
+[[upgrade-new-install]]
+=== New Installation
+
+Kibana 4.0 introduced a major architectural overhaul. As a result, the
+underlying `.kibana` schema changed so significantly that upgrading from Kibana
+3.x requires recreating all visualizations, dashboards, etc.
+
+If you're upgrading from 3.x, please follow the
+<<install,installation instructions>> to install Kibana from scratch, and then
+manually recreate your searches, visualizations, and dashboards.

docs/setup/upgrade/upgrade-standard-reindex.asciidoc

@@ -0,0 +1,25 @@
+[[upgrade-standard-reindex]]
+=== Standard Upgrade with Reindex
+
+You must perform a reindex in Elasticsearch whenever you're upgrading Kibana
+that has an existing `.kibana` index created prior to Elasticsearch 2.0.
+
+This is the case if you're upgrading directly from Kibana 4.1 or 4.0 as well as
+when your existing install of Kibana 4.2+ was previously upgraded from 4.1 or
+4.0.
+
+Reindexing is the process of creating a new index with updated syntax and
+mappings directly from an existing index. While it is possible to do this
+manually, we recommend using the Elasticsearch Migration Plugin as described
+in the Elasticsearch
+{es-ref}reindex-upgrade.html#reindex-upgrade[Reindex to upgrade] guide.
+
+NOTE: The Elasticsearch Migration Plugin creates a versioned `.kibana` index
+as well as an {es-ref}indices-aliases.html[index alias] that points to it.
+Kibana 5.0 supports this index alias, but if you want to run Kibana 4.x while
+this Elastic stack upgrade is underway, you'll need to configure your Kibana
+4.x install to point to the versioned index using the `kibana.index`
+configuration in your `kibana.yml` file.
+
+Once your reindex is complete, you can follow the
+<<upgrade-standard, Standard Upgrade>> instructions.

docs/setup/upgrade/upgrade-standard.asciidoc

@@ -0,0 +1,55 @@
+[[upgrade-standard]]
+=== Standard Upgrade
+
+A standard upgrade is the most straightforward way to upgrade Kibana, and it's
+possible when you're upgrading from Kibana version 4.2 or higher.
+
+If you haven't already, consult this <<upgrade,table>> to verify that standard
+upgrade is supported for your version of Kinana.
+
+NOTE: If you've saved and/or exported objects in Kibana that rely on the
+<<search,Elasticsearch Query DSL>>, make sure to check the Elasticsearch
+{es-ref}breaking-changes.html[breaking changes] documentation and take the
+necessary remediation steps as per those instructions.
+
+[float]
+==== Upgrading using a `deb` or `rpm` package
+
+. Stop the existing Kibana process using the appropriate command for your
+  system.
+. Use `rpm` or `dpkg` to install the new package. All files should be placed in
+  their proper locations and config files should not be overwritten.
++
+[NOTE]
+--
+Kibana 4.x used a different config location than 5.0+, so if you're upgrading
+from 4.x, you will need to copy the configurations from your old config
+(`/opt/kibana/config/kibana.yml`) to your new config
+(`/etc/kibana/kibana.yml`).
+
+Make sure you remove or update any configurations
+that are indicated in the <<breaking-changes,breaking changes>> documentation
+otherwise Kibana will fail to start.
+--
+. Upgrade any plugins by removing the existing plugin and reinstalling the
+  appropriate version using the `kibana-plugin` script. Check out the
+  <<kibana-plugins,plugins>> documentation for more information.
+. Start the new Kibana process using the appropriate command for your system.
+
+[float]
+==== Upgrading using a `zip` or `tar.gz` archive
+
+. Extract the `zip` or `tar.gz` archive to a new directory to be sure that you
+  don't overwrite the `config` or `data` directories.
+. Copy the files from the `config` directory from your old installation to your
+  new installation. Make sure you remove or update any configurations that are
+  indicated in the <<breaking-changes,breaking changes>> documentation
+  otherwise Kibana will fail to start.
+. Copy the files from the `data` directory from your old installation to your
+  new installation.
+. Install the appropriate versions of all your plugins for your new
+  installation using the `kibana-plugin` script. Check out the
+  <<kibana-plugins,plugins>> documentation for more information.
+. Stop the old Kibana process.
+. Start the new Kibana process.
+