elastic · kilfoyle · Nov 30, 2021 · Nov 11, 2021 · Nov 15, 2021 · Nov 17, 2021
@@ -18,6 +18,10 @@ include::installing-stack.asciidoc[]
 
 include::upgrading-stack.asciidoc[]
 
+include::upgrading-stack-cloud.asciidoc[]
+
+include::upgrading-stack-on-prem.asciidoc[]
+
 include::highlights.asciidoc[]
 
 include::breaking.asciidoc[]

@@ -0,0 +1,95 @@
+[[upgrade-elastic-stack-for-elastic-cloud]]
+=== Upgrading on Elastic Cloud
+
+A single click in the Elastic Cloud console can upgrade a cluster to a newer
+version, add more processing capacity, change plugins, and enable or disable
+high availability, all at the same time. During the upgrade process,
+{es}, Kibana, {xpack} and the officially included plugins are
+upgraded simultaneously.
+
+Although upgrading your Elastic Cloud clusters is easy, you still need to
+address breaking changes that affect your application. Minor version upgrades,
+upgrades from 6.8 to {version}, and all other cluster configuration
+changes can be performed with no downtime.
+
+[float]
+=== Prepare for the upgrade
+
+To avoid downtime when a full cluster restart is required:
+
+. Provision an additional cluster with the new {es} version, reindex
+your data, and send index requests to both clusters temporarily.
+
+. Verify that the new cluster performs as expected, fix any problems, and then
+permanently swap in the new cluster.
+
+. Delete the old cluster to stop incurring additional costs. You are billed
+only for the time that the new cluster runs in parallel with your old cluster.
+Usage is billed on an hourly basis.
+
+//To learn more about the upgrade process on Elastic Cloud, see {cloud}/ec-upgrade-deployment.html[Upgrade versions].
+
+NOTE: Elastic Cloud only supports upgrades to released versions. Preview
+releases and master snapshots are not supported.
+
+TIP: You cannot downgrade after upgrading, so plan ahead to make sure that your applications still work after upgrading. For more information on changes that might affect your applications, see link:{ref}/breaking-changes.html[Breaking changes].
+
+The Upgrade Assistant::
+When you upgrade on Elastic Cloud, the deprecation API runs automatically to retrieve information about the cluster, node, and index-level settings that need to be removed or changed. If there are any deprecation issues that would prevent the upgraded deployment from successfully performing, the upgrade fails. To resolve the deprecation issues, use the {kibana-ref}/upgrade-assistant.html[Upgrade Assistant] in Kibana. If any indices in your Elasticsearch clusters need to be reindexed, the Upgrade Assistant will guide you through the steps.
++
+If your cluster does not include a Kibana instance yet, you can {cloud}/ec-enable-kibana.html[enable Kibana first], then use the Upgrade Assistant. After you resolve the deprecation issues, try the upgrade again.
+
+Snapshot behavior during upgrades::
+To keep your data safe, a snapshot is taken automatically before any changes are made to your cluster. After a major version upgrade is complete, and the first successful snapshot with the new major version is available, all snapshots taken with the previous version of Elasticsearch are removed.
++
+For example, before upgrading from Elasticsearch version 7.x to version 8.x, a snapshot is taken. After the upgrade to version 8.x is complete, and a snapshot is available, all snapshots taken with version 8.x are removed.
++ 
+On {ece}, you need to {ece-ref}/ece-manage-repositories.html[configure a snapshot repository] to enable snapshots.
+
+Review breaking changes::
+Major version upgrades can include changes that expose the upgrading process to possible risk. A breaking change is the result of a functional change between major Elasticsearch versions, and requires you to perform additional steps to ensure that you can use the new version as intended.
++
+Review the <<elastic-stack-breaking-changes>> and upgrade your code to work
+with {version}.
+
+Review known issues::
+The following known issues apply to the Elastic Stack 8.x releases:
++
+* There are deprecated APIs that are still available for use. If you see warnings in the {n} logs about the deprecated APIs, you can ignore them.
++
+* {n} does not support the ability to upgrade to or from release candidate builds, such as 8.0.0-rc1.
++
+* In {cloud} and {ece}, for Elasticsearch 7.8 and later the Index Lifecycle Managment (ILM) API is always enabled, even if the cluster is still using the deprecated index curation. If index curation and ILM are both configured to process the same indices the outcome can be unpredictable. As other stack products default to using ILM when it is available in Elasticsearch, we strongly encourage you to {cloud}/ec-migrate-index-management.html[Migrate to index lifecycle management]. ILM also has a superior feature set.
+
+Update the security realm settings::
+During the upgrade process, you are prompted to update the security realm settings when your `user_settings` include a `xpack.security.authc.realms` value. 
++
+There are two settings that prompt you to update:
++
+* If the security realm settings are located in `user_settings_override`, contact support to help you upgrade.
++
+* If the security realm settings are located in `user_settings`, you'll receive a message that allows you modify these settings. 
++
+To modify the `user_settings`:
++
+. On the *Update security realm settings* window, edit the settings.
++
+. Click *Update settings*.
+
+[float]
+=== Perform the upgrade
+
+Log in to your Cloud environment:
+
+//include::tab-widgets/code.asciidoc[]
+//include::tab-widgets/cloud-login-widget.asciidoc[]
+include::{docs-root}/shared/cloud/tab-widgets/code.asciidoc[]
+include::{docs-root}/shared/cloud/tab-widgets/cloud-login-widget.asciidoc[]
+
+Follow these steps to upgrade your stack version:
+
+. In the *Deployment version* section, click *Upgrade*.
+. Select a new version.
+. If you perform a major version upgrade and any incompatibilities are detected, the UI provides a link to the Upgrade Assistant in Kibana, which checks for deprecated settings in your cluster and indices and helps you to resolve them. After resolving any issues, return to the deployments page, select your deployment, click *Upgrade*, and select a version to restart the upgrade process. Any incompatibilities should now be resolved.
+. Click Upgrade. The new configuration takes a few minutes to create.
+. If you are upgrading to version 6.6 and earlier, major upgrades require a full cluster restart to complete the upgrade process.
@@ -0,0 +1,99 @@
+[[upgrading-elastic-stack-on-prem]]
+=== Upgrading on-prem
+
+Follow these steps to upgrade your Elastic Stack to version {version}.
+
+[discrete]
+=== Preparing to upgrade
+
+Before upgrading the Elastic Stack:
+
+. Check the {es} {ref}/logging.html#deprecation-logging[deprecation log]
+to see if you're using any deprecated features and update your code accordingly.
+By default, deprecation warnings are logged when the log level is set to `WARN`.
+
+. Review the <<elastic-stack-breaking-changes>> and upgrade your code to work
+with {version}.
+
+. Upgrade to last version of {prev-major-version} and use the
+{kibana-ref}/upgrade-assistant.html[{kib} Upgrade Assistant] to
+{ref}/docs-reindex.html[reindex] any indices that are not compatible with
+{version}.
+
+. Use the Upgrade Assistant to identify any changes you need to make to your
+cluster configuration.
+
+[discrete]
+[[upgrade-order-elastic-stack]]
+=== Upgrade process
+
+When you've made the necessary changes and are ready to upgrade from 6.8 to
+{version}:
+
+. Test the upgrade in a dev environment *before* upgrading your
+production cluster.
+
+. Back up your data. You **cannot roll back** to an earlier version unless
+you have a snapshot of your data. For information about creating snapshots, see
+{ref}/snapshot-restore.html[Snapshot and restore].
+
+. Consider closing {ml} jobs before you start the upgrade process. While {ml}
+jobs can continue to run during a rolling upgrade, it increases the overhead
+on the cluster during the upgrade process. For more information, see
+{ref}/rolling-upgrades.html[Rolling upgrades].
+
+. Upgrade the components of your Elastic Stack in the following order:
+
+.. {es} Hadoop: {hadoop-ref}/install.html[install instructions]
+.. {es}: {ref}/setup-upgrade.html[upgrade instructions]
+.. Kibana: {kibana-ref}/upgrade.html[upgrade instructions]
+.. Java API Client: {java-api-client}/installation.html#maven[dependency configuration]
+.. Logstash: {logstash-ref}/upgrading-logstash.html[upgrade instructions]
+.. Beats: {beats-ref}/upgrading.html[upgrade instructions]
+.. APM: {apm-guide-ref}/upgrade.html[upgrade instructions]
+.. {agent}: {fleet-guide}/upgrade-elastic-agent.html[upgrade instructions]
+
+
+[WARNING]
+====
+If using {agent} in 7.12 or lower, your {agent}s will automatically be unenrolled
+from {fleet} and will stop sending data when you upgrade to 7.13.
+You will need to uninstall your previous {agent}s before installing and enrolling
+{agent}s with {fleet-server}. To learn more, see {fleet-guide}/upgrade-elastic-agent.html[Upgrade {agent}].
+====
+
+[NOTE]
+====
+Logstash 6.8 and Beats 6.8 are compatible with all 7.x versions of
+{es}. This provides flexibility in when you schedule the upgrades
+for your Logstash instances and Beats agents, but we recommend upgrading as
+soon as possible to take advantage of performance improvements
+and other enhancements.
+
+The Java High Level REST Client can communicate with any {es} node running
+the same major version and greater or equal minor version.
+When you upgrade to the next major version, the client should be
+updated *after* all of the nodes in the cluster have been updated.
+====
+
+[discrete]
+[[oss-stack-upgrade]]
+=== Upgrading from 6.6 or earlier
+
+To upgrade directly to {es} {version} from versions 6.0-6.6, you must
+{ref}/reindex-upgrade.html[manually reindex] any 5.x indices you need to
+carry forward, and perform a {ref}/restart-upgrade.html[full cluster restart].
+This includes any internal indices created in 5.x, such as the `.kibana` and
+`.security*` indices.
+
+Make sure all 5.x indices have been deleted before upgrading to {version}. {es}
+{version} will fail to start if any 5.x indices are present.
+
+If you are running a version prior to 6.0,
+https://www.elastic.co/guide/en/elastic-stack/6.8/upgrading-elastic-stack.html[upgrade to 6.8]
+and reindex your old indices or bring up a new {version} cluster and
+{ref}/reindex-upgrade-remote.html[reindex from remote].
+
+The recommended path is to upgrade to 6.8 before upgrading to {version}. This
+makes it easier to identify the changes you need to make to upgrade and enables
+you to perform a rolling upgrade with no downtime.
@@ -14,130 +14,8 @@ remove or reindex them on your 7.x cluster before upgrading to {version}. The in
 Kibana and {xpack} indices and the default Beats and Logstash mapping templates
 also need to be updated to work with {version}.
 
-[discrete]
-=== Preparing to upgrade
+Refer to the upgrade instructions for your environment:
 
-Before upgrading the Elastic Stack to {version}:
+* <<upgrade-elastic-stack-for-elastic-cloud,Upgrading on Elastic Cloud>>
+* <<upgrading-elastic-stack-on-prem,Upgrading on-prem>>
 
-. Check the {es} {ref}/logging.html#deprecation-logging[deprecation log]
-to see if you're using any deprecated features and update your code accordingly.
-By default, deprecation warnings are logged when the log level is set to `WARN`.
-
-. Review the <<elastic-stack-breaking-changes>> and upgrade your code to work
-with {version}.
-
-. Upgrade to last version of {prev-major-version} and use the
-{kibana-ref}/upgrade-assistant.html[{kib} Upgrade Assistant] to
-{ref}/docs-reindex.html[reindex] any indices that are not compatible with
-{version}.
-
-. Use the Upgrade Assistant to identify any changes you need to make to your
-cluster configuration.
-
-[discrete]
-[[upgrade-order-elastic-stack]]
-=== Upgrade process
-
-When you've made the necessary changes and are ready to upgrade from 6.8 to
-{version}:
-
-. Test the upgrade in a dev environment *before* upgrading your
-production cluster.
-
-. Back up your data. You **cannot roll back** to an earlier version unless
-you have a snapshot of your data. For information about creating snapshots, see
-{ref}/snapshot-restore.html[Snapshot and restore].
-
-. Consider closing {ml} jobs before you start the upgrade process. While {ml}
-jobs can continue to run during a rolling upgrade, it increases the overhead
-on the cluster during the upgrade process. For more information, see
-{ref}/rolling-upgrades.html[Rolling upgrades].
-
-. Upgrade the components of your Elastic Stack in the following order:
-
-.. {es} Hadoop: {hadoop-ref}/install.html[install instructions]
-.. {es}: {ref}/setup-upgrade.html[upgrade instructions]
-.. Kibana: {kibana-ref}/upgrade.html[upgrade instructions]
-.. Java API Client: {java-api-client}/installation.html#maven[dependency configuration]
-.. Logstash: {logstash-ref}/upgrading-logstash.html[upgrade instructions]
-.. Beats: {beats-ref}/upgrading.html[upgrade instructions]
-.. APM: {apm-guide-ref}/upgrade.html[upgrade instructions]
-.. {agent}: {fleet-guide}/upgrade-elastic-agent.html[upgrade instructions]
-
-
-[WARNING]
-====
-If using {agent} in 7.12 or lower, your {agent}s will automatically be unenrolled
-from {fleet} and will stop sending data when you upgrade to 7.13.
-You will need to uninstall your previous {agent}s before installing and enrolling
-{agent}s with {fleet-server}. To learn more, see {fleet-guide}/upgrade-elastic-agent.html[Upgrade {agent}].
-====
-
-[NOTE]
-====
-Logstash 6.8 and Beats 6.8 are compatible with all 7.x versions of
-{es}. This provides flexibility in when you schedule the upgrades
-for your Logstash instances and Beats agents, but we recommend upgrading as
-soon as possible to take advantage of performance improvements
-and other enhancements.
-
-The Java High Level REST Client can communicate with any {es} node running
-the same major version and greater or equal minor version.
-When you upgrade to the next major version, the client should be
-updated *after* all of the nodes in the cluster have been updated.
-====
-
-[discrete]
-[[oss-stack-upgrade]]
-=== Upgrading from 6.6 or earlier
-
-To upgrade directly to {es} {version} from versions 6.0-6.6, you must
-{ref}/reindex-upgrade.html[manually reindex] any 5.x indices you need to
-carry forward, and perform a {ref}/restart-upgrade.html[full cluster restart].
-This includes any internal indices created in 5.x, such as the `.kibana` and
-`.security*` indices.
-
-Make sure all 5.x indices have been deleted before upgrading to {version}. {es}
-{version} will fail to start if any 5.x indices are present.
-
-If you are running a version prior to 6.0,
-https://www.elastic.co/guide/en/elastic-stack/6.8/upgrading-elastic-stack.html[upgrade to 6.8]
-and reindex your old indices or bring up a new {version} cluster and
-{ref}/reindex-upgrade-remote.html[reindex from remote].
-
-The recommended path is to upgrade to 6.8 before upgrading to {version}. This
-makes it easier to identify the changes you need to make to upgrade and enables
-you to perform a rolling upgrade with no downtime.
-
-[discrete]
-[[upgrade-elastic-stack-for-elastic-cloud]]
-=== Upgrading on Elastic Cloud
-
-A single click in the Elastic Cloud console can upgrade a cluster to a newer
-version, add more processing capacity, change plugins, and enable or disable
-high availability, all at the same time. During the upgrade process,
-{es}, Kibana, {xpack} and the officially included plugins are
-upgraded simultaneously.
-
-Although upgrading your Elastic Cloud clusters is easy, you still need to
-address breaking changes that affect your application. Minor version upgrades,
-upgrades from 6.8 to {version}, and all other cluster configuration
-changes can be performed with no downtime.
-
-To avoid downtime when a full cluster restart is required:
-
-. Provision an additional cluster with the new {es} version, reindex
-your data, and send index requests to both clusters temporarily.
-
-. Verify that the new cluster performs as expected, fix any problems, and then
-permanently swap in the new cluster.
-
-. Delete the old cluster to stop incurring additional costs. You are billed
-only for the time that the new cluster runs in parallel with your old cluster.
-Usage is billed on an hourly basis.
-
-To learn more about the upgrade process on Elastic Cloud, see
-{cloud}/ec-upgrade-deployment.html[Upgrade versions].
-
-NOTE: Elastic Cloud only supports upgrades to released versions. Preview
-releases and master snapshots are not supported.