From 0f1233e201a693bde762ba5103db65e94a7dfa02 Mon Sep 17 00:00:00 2001 From: David Turner Date: Fri, 28 Mar 2025 07:32:51 +0000 Subject: [PATCH 1/3] Expand guidance on testing an upgrade Call out specifically to look for cluster stability, performance, and snapshot repository bugs. --- .../install-upgrade/upgrading-stack.asciidoc | 37 ++++++++++++++++--- 1 file changed, 32 insertions(+), 5 deletions(-) diff --git a/docs/en/install-upgrade/upgrading-stack.asciidoc b/docs/en/install-upgrade/upgrading-stack.asciidoc index 8b6dcfd8c..8efe8a95a 100644 --- a/docs/en/install-upgrade/upgrading-stack.asciidoc +++ b/docs/en/install-upgrade/upgrading-stack.asciidoc @@ -52,15 +52,42 @@ endif::[] compatible with {es} version {version}. . Test the upgrade in an isolated environment before upgrading your production -cluster. + cluster. ++ +[IMPORTANT] +---- +The upgraded version of {es} may interact with its environment in different +ways from the version you are currently running. It is possible that your +environment behaves incorrectly in a way that does not matter to the version of +{es} that you are currently running, but which does matter to the upgraded +version. In this case, the upgraded version will not work correctly until you +address the incorrect behaviour in your environment. + +During your upgrade tests, pay particular attention to the following aspects: + +Cluster stability:: Does the new version of {es} form a stable healthy cluster? + +Indexing and search performance:: Does the new version of {es} perform the same +(or better) than the current one on your specific workload and data? + +Snapshots:: Do all of your snapshot repositories work correctly and pass +{ref}/repo-analysis-api.html[repository analysis]? +---- . Make sure you have a current snapshot before you start the upgrade. + -IMPORTANT: You cannot downgrade {es} nodes after upgrading. -If you cannot complete the upgrade process, -you will need to restore from the snapshot. +IMPORTANT: You cannot downgrade {es} nodes after starting to upgrade your +cluster. If you cannot complete the upgrade process, build a new cluster and +restore a snapshot taken before starting the upgrade. -. If you use a separate {ref}/monitoring-production.html[monitoring cluster], you should upgrade the monitoring cluster before the production cluster. In general, the monitoring cluster and the clusters being monitored should be running the same version of the stack. A monitoring cluster cannot monitor production clusters running newer versions of the stack. If necessary, the monitoring cluster can monitor production clusters running the latest release of the previous major version. +. If you use a separate {ref}/monitoring-production.html[monitoring cluster], + upgrade the monitoring cluster before the production cluster. ++ +In general, the monitoring cluster and the clusters being monitored should be +running the same version of the stack. A monitoring cluster cannot monitor +production clusters running newer versions of the stack. If necessary, the +monitoring cluster can monitor production clusters running the latest release +of the previous major version. // end::generic-upgrade-steps[] //// From 9772adac697c1610f5428da72d167f159f8eb9e4 Mon Sep 17 00:00:00 2001 From: David Turner Date: Fri, 28 Mar 2025 08:11:54 +0000 Subject: [PATCH 2/3] ---- is special --- docs/en/install-upgrade/upgrading-stack.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/en/install-upgrade/upgrading-stack.asciidoc b/docs/en/install-upgrade/upgrading-stack.asciidoc index 8efe8a95a..9b10484fe 100644 --- a/docs/en/install-upgrade/upgrading-stack.asciidoc +++ b/docs/en/install-upgrade/upgrading-stack.asciidoc @@ -55,7 +55,7 @@ compatible with {es} version {version}. cluster. + [IMPORTANT] ----- +-- The upgraded version of {es} may interact with its environment in different ways from the version you are currently running. It is possible that your environment behaves incorrectly in a way that does not matter to the version of @@ -72,7 +72,7 @@ Indexing and search performance:: Does the new version of {es} perform the same Snapshots:: Do all of your snapshot repositories work correctly and pass {ref}/repo-analysis-api.html[repository analysis]? ----- +-- . Make sure you have a current snapshot before you start the upgrade. + From 8531f1201ea9d9133951b4f9c6f90f5859085aa7 Mon Sep 17 00:00:00 2001 From: David Turner Date: Fri, 28 Mar 2025 08:37:59 +0000 Subject: [PATCH 3/3] Delimiter pedantry ;) Co-authored-by: Liam Thompson <32779855+leemthompo@users.noreply.github.com> --- docs/en/install-upgrade/upgrading-stack.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/en/install-upgrade/upgrading-stack.asciidoc b/docs/en/install-upgrade/upgrading-stack.asciidoc index 9b10484fe..ea154d21b 100644 --- a/docs/en/install-upgrade/upgrading-stack.asciidoc +++ b/docs/en/install-upgrade/upgrading-stack.asciidoc @@ -55,7 +55,7 @@ compatible with {es} version {version}. cluster. + [IMPORTANT] --- +==== The upgraded version of {es} may interact with its environment in different ways from the version you are currently running. It is possible that your environment behaves incorrectly in a way that does not matter to the version of @@ -72,7 +72,7 @@ Indexing and search performance:: Does the new version of {es} perform the same Snapshots:: Do all of your snapshot repositories work correctly and pass {ref}/repo-analysis-api.html[repository analysis]? --- +==== . Make sure you have a current snapshot before you start the upgrade. +