docs(upgrade) add 2.0.0rc1 upgrade path

UPGRADE.md

@@ -38,6 +38,114 @@ configuration, without dropping existing in-flight connections.
 
 
 
+## Upgrade to `2.0.0rc1`
+
+Kong adheres to [semantic versioning](https://semver.org/), which makes a
+distinction between "major", "minor" and "patch" versions. The upgrade path
+will be different on which previous version from which you are migrating.
+Upgrading into 2.0.x is a major version upgrade, so be aware of any
+breaking changes listed in the [CHANGELOG.md](https://github.com/Kong/kong/blob/2.0.0rc1/CHANGELOG.md) document.
+
+
+#### 1. Dependencies
+
+If you are using the provided binary packages, all necessary dependencies
+are bundled and you can skip this section.
+
+If you are building your dependencies by hand, there are changes since the
+previous release, so you will need to rebuild them with the latest patches.
+
+The required OpenResty version is
+[1.15.8.2](http://openresty.org/en/changelog-1015008.html), and the
+the set of [OpenResty
+patches](https://github.com/Kong/kong-build-tools/tree/master/openresty-build-tools/openresty-patches)
+included has changed, including the latest release of
+[lua-kong-nginx-module](https://github.com/Kong/lua-kong-nginx-module).
+Our [kong-build-tools](https://github.com/Kong/kong-build-tools)
+repository allows you to build OpenResty with the necessary patches
+and modules easily.
+
+For Go support, you also need the [Kong go-pluginserver](https://github.com/kong/go-pluginserver),
+which needs to be started up alongside Kong.
+
+
+#### 2. Breaking Changes
+
+Kong 2.0.0rc1 does include a few breaking changes over Kong 1.x, all of them
+related to the removal of service mesh:
+
+- **Removed Service Mesh support** - That has been deprecated in Kong 1.4
+  and made off-by-default already, and the code is now be gone in 2.0.
+  For Service Mesh, we now have [Kuma](https://kuma.io), which is something
+  designed for Mesh patterns from day one, so we feel at peace with removing
+  Kong's native Service Mesh functionality and focus on its core capabilities
+  as a gateway.
+- As part of service mesh removal, serviceless proxying was removed.
+  You can still set `service = null` when creating a route for use with
+  serverless plugins such as `aws-lambda`, or `request-termination`.
+- Removed the `origins` property.
+- Removed the `transparent` property.
+- Removed the Sidecar Injector plugin which was used for service mesh.
+
+
+#### 3. Suggested Upgrade Path
+
+##### Upgrade from `0.x` to `2.0.0rc1`
+
+The lowest version that Kong 2.0.0rc1 supports migrating from is 0.14.1. if you
+are migrating from a previous 0.x release, please migrate to 0.14.1 first.
+
+For upgrading from 0.14.1 to Kong 2.0.0rc1, the steps for upgrading are the same
+as upgrading from 0.14.1 to Kong 1.0. Please follow the steps described in the
+"Migration Steps from 0.14" in the [Suggested Upgrade Path for Kong
+1.0](#kong-1-0-upgrade-path).
+
+##### Upgrade from `1.0.x` - `1.4.x` to `2.0.0rc1`
+
+Kong 2.0.0rc1 supports a no-downtime migration model. This means that while the
+migration is ongoing, you will have two Kong clusters running, sharing the
+same database. (This is sometimes called the Blue/Green migration model.)
+
+The migrations are designed so that there is no need to fully copy
+the data, but this also means that they are designed in such a way so that
+the new version of Kong is able to use the data as it is migrated, and to do
+it in a way so that the old Kong cluster keeps working until it is finally
+time to decommission it. For this reason, the full migration is now split into
+two steps, which are performed via commands `kong migrations up` (which does
+only non-destructive operations) and `kong migrations finish` (which puts the
+database in the final expected state for Kong 2.0.0rc1).
+
+1. Download 2.0.0rc1, and configure it to point to the same datastore
+   as your old (1.0 to 1.4) cluster. Run `kong migrations up`.
+2. Once that finishes running, both the old and new (2.0.0rc1) clusters can now
+   run simultaneously on the same datastore. Start provisioning
+   2.0.0rc1 nodes, but do not use their Admin API yet. If you need to
+   perform Admin API requests, these should be made to the old cluster's nodes.
+   The reason is to prevent the new cluster from generating data
+   that is not understood by the old cluster.
+3. Gradually divert traffic away from your old nodes, and into
+   your 2.0.0rc1 cluster. Monitor your traffic to make sure everything
+   is going smoothly.
+4. When your traffic is fully migrated to the 2.0.0rc1 cluster,
+   decommission your old nodes.
+5. From your 2.0.0rc1 cluster, run: `kong migrations finish`.
+   From this point on, it will not be possible to start
+   nodes in the old cluster pointing to the same datastore anymore. Only run
+   this command when you are confident that your migration
+   was successful. From now on, you can safely make Admin API
+   requests to your 2.0.0rc1 nodes.
+
+##### Installing 2.0.0rc1 on a Fresh Datastore
+
+The following commands should be used to prepare a new 2.0.0rc1 cluster from a
+fresh datastore:
+
+```
+$ kong migrations bootstrap [-c config]
+$ kong start [-c config]
+```
+
+
 ## Upgrade to `1.4.0`
 
 Kong adheres to [semantic versioning](https://semver.org/), which makes a