Revises 8.x-8.x upgrade guide (#5830)

* Revises 8.x-8.x upgrade guide * Address editorial feedback * Applies feedback to 7.17 guide * Updates section name
elastic · Oct 24, 2024 · 1c62f2d · 1c62f2d
1 parent 360e4c7
commit 1c62f2d
Show file tree

Hide file tree

Showing 2 changed files with 78 additions and 43 deletions.
diff --git a/docs/upgrade/upgrade-7.17-8.x.asciidoc b/docs/upgrade/upgrade-7.17-8.x.asciidoc
@@ -82,7 +82,7 @@ NOTE: If you're using Elastic Cloud Hosted or {ece}, this is already included in
 ... Ensure that the index and search rate are close to what they were before upgrading. Go to **Stack Monitoring** -> **{es}** -> **Overview**.
 +
 TIP: You can also check the index document count using the {ref}/cat-indices.html[cat index API].
-... Verify that SLM is taking snapshots by {ref}/snapshots-take-snapshot.html#check-slm-history[checking the SLM history]. 
+... Verify that {slm} SLM is taking snapshots by {ref}/snapshots-take-snapshot.html#check-slm-history[checking the SLM history]. 
 ... If you use {ml}, ensure that it is up and running. 
 .. For {kib}: 
 ... Ensure that you and your users can successfully log in to {kib} and access desired pages.
@@ -92,11 +92,11 @@ TIP: You can also check the index document count using the {ref}/cat-indices.htm
 
 . Upgrade your ingest components (such as {ls}, {fleet} and {agent}, {beats}, etc.). For details, refer to the {stack-ref}/upgrading-elastic-stack.html[Elastic Stack upgrade docs].
 
-. Validate that Ingest is operating correctly.
+. Validate that ingest is operating correctly.
 .. Open *Discover*, go through data views for each of your expected ingest data streams, and ensure that data is being ingested in the expected format and volume. 
 
 . Validate that {elastic-sec} is operating correctly.
-.. Re-enable your desired SIEM detection rules (rule management), and ensure that enabled rules are running without errors or warnings (rule monitoring).
+.. On the **Rules** page, re-enable your desired SIEM detection rules (**Rule Management** tab), and ensure that enabled rules are running without errors or warnings (**Rule Monitoring** tab).
 .. Ensure that any SOAR workflows that consume alerts are working.
 .. Verify that any custom dashboards your team has created are working properly, especially if they operate on alert documents.
 

diff --git a/docs/upgrade/upgrade-security.asciidoc b/docs/upgrade/upgrade-security.asciidoc
@@ -2,9 +2,9 @@
 
 = Upgrade {elastic-sec} to {version}
 
-Before you upgrade {elastic-sec}, take the necessary <<preventing-migration-failures, preparation steps>>, which will vary depending on what version you are upgrading to:
+Before you upgrade {elastic-sec}, take the necessary preparation steps, which will vary depending on what version you are upgrading to:
 
-* <<upgrade-8.x, Upgrade from an earlier 8.x version>>
+* <<upgrade-8x-8x, Upgrade from an 8.x to an 8.x version>>
 * <<upgrade-7.17-8x, Upgrade from 7.17 to an 8.x version>>
 * <<upgrade-7.16-8.x, Upgrade from 7.16 or earlier to an 8.x version>>
 
@@ -21,7 +21,7 @@ state. By default, snapshots include the `kibana` feature state.
 ====
 
 [float]
-=== Upgrading multiple {kib} instances
+== Upgrading multiple {kib} instances
 When upgrading several {kib} instances connected to the same {es} cluster,
 ensure that all outdated instances are shut down before starting the upgrade.
 
@@ -37,69 +37,104 @@ but upgrading from a pre-release to the Generally Available version is unsupport
 You should use pre-release versions only for testing in a temporary environment.
 
 [float]
-=== Support for Elastic prebuilt detection rule automatic updates
+=== Ensure that all {kib} instances are the same
+When you perform an upgrade migration of different {kib} versions, the migration can fail.
+Ensure that all {kib} instances are running the same version, configuration, and plugins.
+
+[float]
+== Support for Elastic prebuilt detection rule automatic updates
 <<update-prebuilt-rules,Automatic updates of Elastic prebuilt detection rules>> are supported for the current {elastic-sec} version and the latest three previous minor releases. For example, if you’re upgrading to {elastic-sec} 8.10, you’ll be able to use the Rules UI to update your prebuilt rules until {elastic-sec} 8.14 is released. After that point, you can still manually download and install updated prebuilt rules, but you must upgrade to the latest {elastic-sec} version to receive automatic updates.
 
 [float]
-[[preventing-migration-failures]]
-=== Preparing for migration
+[[upgrade-8x-8x]]
+== Upgrade from an 8.x to an 8.x version
 
-Take these extra steps to ensure you are ready for migration.
+Follow this guide to upgrade from an earlier 8.x version to a later 8.x version.
 
 [float]
-==== Ensure your {es} cluster is healthy
-Problems with your {es} cluster can prevent {kib} upgrades from succeeding.
+=== Plan for your upgrade
 
-During the upgrade process, {kib} creates new indices into which updated documents are written. If a cluster is approaching the low watermark, there's a high risk of {kib} not being able to create these. Reading, transforming, and writing updated documents can be memory intensive, using more available heap than during routine operation. You must ensure that enough heap is available to prevent requests from timing out or throwing errors from circuit breaker exceptions. You should also ensure that all shards are replicated and assigned.
+Before upgrading from an earlier 8.x version, consider the following recommendations:
 
-A healthy cluster has:
+* Plan for an appropriate amount of time to complete the upgrade. Depending on your configuration and the size of your cluster, the process can take up to a week to complete.
 
- * Enough free disk space, at least twice the amount of storage taken up by the `.kibana` and `.kibana_task_manager` indices
- * Sufficient heap size
- * A "green" cluster status
+* Open a https://support.elastic.co[support case] with Elastic to alert our Elastic Support team of your system change. If you need additional assistance, https://www.elastic.co/consulting[Elastic Consulting Services] provides the technical expertise and step-by-step approach for upgrading your Elastic deployment.
 
-[float]
-==== Ensure that all {kib} instances are the same
-When you perform an upgrade migration of different {kib} versions, the migration can fail.
-Ensure that all {kib} instances are running the same version, configuration, and plugins.
+* Choose a version to upgrade to. We recommend the latest minor and patch version. Be sure to upgrade your development or non-production deployment to the same version as your production deployment. 
+
+* Ensure that you have {kibana-ref}/xpack-monitoring.html[stack monitoring] enabled in {kib}. Take note of your current index and search rate. 
+
+* Review your selected version's features, Elastic connectors, integrations, and detection rules to determine if you can replace any customized content with out-of-the-box functionality. This can help reduce your workload and the complexity of your upgrade.
+
+* Review release notes, deprecations, and breaking changes for {security-guide}/release-notes.html[{elastic-sec}], {ref}/es-release-notes.html[{es}], {kibana-ref}/release-notes.html[{kib}], and, if applicable, {fleet-guide}/release-notes.html[{fleet} and {agent}], {beats-ref}/release-notes.html[{beats}], and {logstash-ref}/releasenotes.html[{ls}]. Identify any issues that might affect your deployment. Work with your Elastic team on any questions you may have. Start with breaking changes for your solution and platform components, such as {es} and {kib}. 
+
+* Schedule a system maintenance window within your organization.
 
 [float]
-==== Back up your data
+=== Pre-upgrade steps
 
-Be sure to have a {ref}/snapshot-restore.html[snapshot] of all your data before migrating, so that if something goes wrong during migration, you can restore from the snapshot and try again.
+To prepare for the upgrade process, follow these steps before you start:
 
-Review the {kibana-ref}/resolve-migrations-failures.html[common causes of {kib} upgrade failures] and how to prevent them.
+. Do a software version inventory across your entire Elastic deployment, including {es}, {kib}, {agent}, {beats}, and {ls}. 
 
+. If you're not using {ref}/snapshots-take-snapshot.html#automate-snapshots-slm[{slm} (SLM)], you must set up and configure a policy, then run the policy to create at least one {ref}/snapshot-restore.html[snapshot]—a backup of indices taken from a running cluster. If you need to roll back during the upgrade process, use a recent snapshot to avoid data loss. Snapshots are {ref}/snapshot-restore.html#how-snapshots-work[incremental]—depending on the cluster size and the input/output rate, the initial snapshot may take several hours to complete. If you're using SLM, {ref}/snapshots-take-snapshot.html#check-slm-history[check the SLM history] to ensure that snapshots are completing successfully.
 
 [float]
-[[upgrade-8.x]]
-== Upgrade from an earlier 8.x version 
+=== Perform an 8.x to 8.x upgrade on a deployment
 
-. Review the breaking changes for each product you use and make the necessary changes so your code is compatible with {version}.
+IMPORTANT: We strongly recommend performing the following steps on a non-production deployment first to address any potential issues before upgrading your production deployments. If you're using a cross-cluster search environment, upgrade your remote deployments first.
 
-** {apm-guide-ref}/apm-breaking.html[APM {version} breaking changes]
-** {beats-ref}/breaking-changes.html[Beats {version} breaking changes]
-** {ref}/breaking-changes.html[{es} {version} breaking changes]
-** {security-guide}/release-notes.html[{elastic-sec} {version} breaking changes]
-** {kibana-ref}/release-notes.html[{kib} {version} breaking changes]
-** {logstash-ref}/breaking-changes.html[{ls} {version} breaking changes]
-+
-. If you use any {es} plugins, ensure each plugin has a version compatible with {es} version {version}.
+. If you haven't already done so, back up your cluster data to a {ref}/snapshots-take-snapshot.html[snapshot].
 
-. Test the upgrade in an isolated environment before upgrading your production
-cluster.
+. We recommend you <<rules-api-export, export all your custom detection rules>> in case there are issues with the detection engine after the upgrade.
 
-. Ensure you have a current snapshot before you start the upgrade.
+. Upgrade {es}.  
+** If you're using {ecloud}, we recommend upgrades with no downtime. Refer to {cloud}/ec-upgrade-deployment.html[these instructions].  
+** If you're using {ece} (ECE), refer to {ece-ref}/ece-upgrade-deployment.html[these instructions].  
+** If you're using {eck} (ECK), refer to {eck-ref}/k8s-upgrading-stack.html[these instructions]. 
+** If you're upgrading a self-orchestrated deployment, refer to {stack-ref}/upgrading-elasticsearch.html[these instructions] and upgrade the data nodes tier by tier in this order:
+... Frozen tier
+... Cold tier 
+... Warm tier
+... Hot tier 
+... Any other nodes not in a tier
+... All remaining nodes that are neither master-eligible nor data nodes
+... Master-eligible nodes
+
+. Upgrade {kib}. Refer to {stack-ref}/upgrading-kibana.html[these instructions].
 +
-IMPORTANT: You cannot downgrade {es} nodes after upgrading. 
-If you cannot complete the upgrade process, 
-you will need to restore from the snapshot.
+NOTE: If you're using Elastic Cloud Hosted or {ece}, this is already included in the {es} upgrade.
+
+. Validate that {es} and {kib} are operating as expected by completing the following checks: 
+.. For {es}:
+... Check the status of your clusters and ensure that they're green by running a `GET _cat/health` API request. For more information, refer to the {ref}/cat-health.html[cat health API documentation].
+... Ensure that the index and search rate are close to what they were before upgrading. Go to **Stack Monitoring** -> **{es}** -> **Overview**.
++
+TIP: You can also check the index document count using the {ref}/cat-indices.html[cat index API].
+... Verify that {slm} (SLM) is taking snapshots by {ref}/snapshots-take-snapshot.html#check-slm-history[checking the SLM history]. 
+... If you use {ml}, ensure that it is up and running. 
+.. For {kib}: 
+... Ensure that you and your users can successfully log in to {kib} and access desired pages.
+... Check {kibana-ref}/discover.html[Discover] and verify that the index patterns you typically use are available.
+... Verify that your commonly used {kibana-ref}/dashboard.html[dashboards] are available and working properly.
+... If you use any Watcher-based {kib} scheduled {kibana-ref}/reporting-getting-started.html[reporting], ensure that it's working properly.
+
+. Upgrade your ingest components (such as {ls}, {fleet} and {agent}, {beats}, etc.). For details, refer to the {stack-ref}/upgrading-elastic-stack.html[Elastic Stack upgrade docs].
+
+. Validate that ingest is operating correctly.
+.. Open *Discover*, go through data views for each of your expected ingest data streams, and ensure that data is being ingested in the expected format and volume. 
+
+. Validate that {elastic-sec} is operating correctly.
+.. On the **Rules** page, re-enable your desired SIEM detection rules (**Rule Management** tab), and ensure that enabled rules are running without errors or warnings (**Rule Monitoring** tab).
+.. Ensure that any SOAR workflows that consume alerts are working.
+.. Verify that any custom dashboards your team has created are working properly, especially if they operate on alert documents.
 
-. If you use a separate {ref}/monitoring-production.html[monitoring cluster], you should upgrade the monitoring cluster before the production cluster. Generally, the monitoring cluster and the clusters being monitored should be running the same {stack} version. A monitoring cluster cannot monitor production clusters running newer stack versions. If necessary, the monitoring cluster can monitor production clusters running the latest release of the previous major version.
+. If you performed these steps on a non-production deployment, repeat these same steps on your production environment. If you're using a cross-cluster search environment and performed these steps on your remote clusters, repeat these same steps on your other deployments. 
+. Confirm with your appropriate stakeholders that the upgrade process has been successful.
 
 [float]
 [[upgrade-notes-8.8]]
-=== Considerations when upgrading to 8.8
+=== Considerations when upgrading to 8.8 or later
 
 After you upgrade to 8.8 or later, frequency settings for <<rule-notifications,rule actions>> created in 8.7 or earlier are automatically moved from the rule level to the action level. The action schedules remain the same and will continue to run on their previously specified frequency (`On each rule execution`, `Hourly`, `Daily`, or `Weekly`).