From 04372887f71c0d9127688a1dccced7754fcb701b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Mon, 28 Jul 2025 13:13:53 +0200 Subject: [PATCH 01/30] upgrade docs signifficant refinement --- deploy-manage/deploy/cloud-on-k8s.md | 2 +- deploy-manage/toc.yml | 12 +- deploy-manage/upgrade.md | 57 ++++++- .../upgrade/deployment-or-cluster.md | 28 +++- .../deployment-or-cluster/elasticsearch.md | 17 ++- .../upgrade/deployment-or-cluster/kibana.md | 16 +- .../deployment-or-cluster/upgrade-on-ece.md | 4 +- .../deployment-or-cluster/upgrade-on-eck.md | 12 +- deploy-manage/upgrade/ingest-components.md | 8 +- deploy-manage/upgrade/orchestrator.md | 2 +- deploy-manage/upgrade/prepare-to-upgrade.md | 144 ++++++++++++------ .../prepare-to-upgrade/upgrade-assistant.md | 8 +- docset.yml | 2 +- 13 files changed, 221 insertions(+), 91 deletions(-) diff --git a/deploy-manage/deploy/cloud-on-k8s.md b/deploy-manage/deploy/cloud-on-k8s.md index 5b14687c14..068f45acf3 100644 --- a/deploy-manage/deploy/cloud-on-k8s.md +++ b/deploy-manage/deploy/cloud-on-k8s.md @@ -78,7 +78,7 @@ ECK should work with all conformant **installers** listed in these [FAQs](https: Alpha, beta, and stable API versions follow the same [conventions used by Kubernetes](https://kubernetes.io/docs/concepts/overview/kubernetes-api/#api-versioning). -### {{stack}} compatibility +### {{stack}} compatibility [stack-compatibility] ECK is compatible with the following {{stack}} applications: diff --git a/deploy-manage/toc.yml b/deploy-manage/toc.yml index 2002ff21f8..94c7efc1cb 100644 --- a/deploy-manage/toc.yml +++ b/deploy-manage/toc.yml @@ -781,12 +781,6 @@ toc: - file: upgrade.md children: - file: upgrade/plan-upgrade.md - - file: upgrade/orchestrator.md - children: - - file: upgrade/orchestrator/upgrade-cloud-enterprise.md - children: - - file: upgrade/orchestrator/re-running-the-ece-upgrade.md - - file: upgrade/orchestrator/upgrade-cloud-on-k8s.md - file: upgrade/prepare-to-upgrade.md children: - file: upgrade/prepare-to-upgrade/upgrade-assistant.md @@ -807,6 +801,12 @@ toc: - file: upgrade/deployment-or-cluster/kibana-roll-back.md - file: upgrade/deployment-or-cluster/enterprise-search.md - file: upgrade/ingest-components.md + - file: upgrade/orchestrator.md + children: + - file: upgrade/orchestrator/upgrade-cloud-enterprise.md + children: + - file: upgrade/orchestrator/re-running-the-ece-upgrade.md + - file: upgrade/orchestrator/upgrade-cloud-on-k8s.md - file: uninstall.md children: - file: uninstall/uninstall-elastic-cloud-enterprise.md diff --git a/deploy-manage/upgrade.md b/deploy-manage/upgrade.md index 6d4b1e5ab3..c81d5c5ada 100644 --- a/deploy-manage/upgrade.md +++ b/deploy-manage/upgrade.md @@ -1,14 +1,61 @@ +--- +applies_to: + stack: + deployment: + eck: + ess: + ece: + self: +--- + # Upgrade -Upgrading to the latest version provides access to the newest Elastic features, enhancements, performance improvements, and bug fixes. These updates reduce costs, speed up threat response, and improve investigative and analytical data tools. +Upgrading to the latest version provides access to the newest Elastic features, security patches, performance improvements, and bug fixes. These updates reduce costs, speed up threat response, and improve investigative and analytical data tools. + +When Elastic releases new versions, older versions reach their end of life on a set schedule. To keep your deployment supported, stay up to date. For more information, refer to [Product End of Life Dates](https://www.elastic.co/support/eol). + +::::{note} +With [{{serverless-full}}](/deploy-manage/deploy/elastic-cloud/serverless.md), upgrades are fully managed by Elastic. Users automatically receive the latest features and improvements, with no need to plan or perform upgrade steps. +:::: + +The upgrade procedure depends on how your deployment is managed. If you're using {{ech}} or {{ece}}, upgrades can often be performed with a single click in the {{ecloud}} UI. For self-managed deployments, upgrades must be carried out manually using a rolling upgrade process, upgrading the nodes one by one to minimize downtime and ensure cluster stability. + +This section provides guidance to help you plan and safely perform upgrades of your Elastic Stack components, with a primary focus on {{es}} and {{kib}} as the core of the stack. It also covers upgrades for orchestration platforms like {{ece}} and {{eck}}, as well as related components such as APM, Beats, Elastic Agent, and Logstash. :::{important} In {{stack}} 9.0.0 and beyond, Enterprise Search is unavailable. For more information, refer to [Migrating to 9.x from Enterprise Search 8.x versions](https://www.elastic.co/guide/en/enterprise-search/8.18/upgrading-to-9-x.html). ::: -When Elastic releases new versions, older versions reach their end of life on a set schedule. To keep your deployment supported, stay up to date. For more information, refer to [Product End of Life Dates](https://www.elastic.co/support/eol). +## Upgrade overview -:::{note} -Upgrading from a release candidate build, such as 9.0.0-rc1, is unsupported. Use pre-releases only for testing in a temporary environment. -::: +Upgrading your Elastic cluster or deployment involves several stages, including planning, preparation, and execution. This section guides you through the full upgrade process: + +- [Plan your upgrade](./upgrade/plan-upgrade.md): Review compatibility, define your upgrade path and order, and understand important pre-upgrade considerations. + +- [Prepare to upgrade](./upgrade/prepare-to-upgrade.md): Follow detailed preparation steps for major, minor, and patch upgrades. Identify breaking changes, run the Upgrade Assistant (for major upgrades), and verify readiness. + +- [Upgrade your deployment or cluster](./upgrade/deployment-or-cluster.md): Step-by-step instructions for performing the upgrade, organized by deployment type: + + - [Upgrade deployments on {{ech}}](/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-ech.md) + - [Upgrade deployments on {{ece}}](/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-ece.md) + - [Upgrade deployments on {{eck}}](/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-eck.md) + - [Upgrade self-managed clusters](/deploy-manage/upgrade/deployment-or-cluster/self-managed.md) + +- [Upgrade ingest components](./upgrade/ingest-components.md): Covers supporting components such as Beats, Elastic Agent, Logstash, and APM Server. + +Additionally, if you're using a self-managed orchestration platform such as {{ece}} or {{eck}}, refer to [Upgrade your ECE or ECK orchestrator](/deploy-manage/upgrade/orchestrator.md) to keep the orchestrator up to date. + +## Upgrade paths [upgrade-paths] +% alternative title : Upgrade paths / Can I upgrade to any version? + +You can upgrade to a higher version if the target version was released *after* your current version. Upgrades to versions released *before* your current version are not supported, even if the version number is higher. Refer to [out-of-order releases](/deploy-manage/upgrade/deployment-or-cluster.md#out-of-order-releases) for more information. + +For example: +- ✅ Upgrade allowed: From 9.0.2 to 9.1.0 (9.1.0 released *after* 9.0.2) +- ❌ Not allowed: From 9.0.4 to 9.1.0 (9.1.0 released *before* 9.0.4) + +Refer to the [download past releases](https://www.elastic.co/downloads/past-releases#elasticsearch) page to check the release dates of different versions. +::::{note} +Major upgrades must be performed from the latest minor version of the previous major. For example, to upgrade to {{stack-version}}, you need to be on 8.19 first. +:::: \ No newline at end of file diff --git a/deploy-manage/upgrade/deployment-or-cluster.md b/deploy-manage/upgrade/deployment-or-cluster.md index 0fcb4103ce..2ba9af0f92 100644 --- a/deploy-manage/upgrade/deployment-or-cluster.md +++ b/deploy-manage/upgrade/deployment-or-cluster.md @@ -28,17 +28,35 @@ products: # Upgrade your deployment or cluster [upgrade-deployment-cluster] -When upgrading an existing cluster, you perform a minor or major upgrade. For example, a minor upgrade takes you from version 9.0.0 to 9.1.0, while a major upgrade takes you from version 8.0.0 to 9.0.0. +This section contains the actual upgrade instructions for {{es}} clusters and {{kib}} instances. Upgrade procedures depend on whether you installed Elastic components using Elastic-managed or self-managed infrastructure. -Upgrade procedures depend on whether you installed Elastic components using Elastic-managed or self-managed infrastructure. +## Prerequisites + +Before proceeding with the upgrade, review the [Plan your upgrade](/deploy-manage/upgrade/plan-upgrade.md) guidance to understand compatibility and timing considerations, and follow the steps in [Prepare to upgrade](/deploy-manage/upgrade/prepare-to-upgrade.md) to get your environment ready for the upgrade. + +## Out-of-order releases [out-of-order-releases] + +Elastic maintains several minor versions of Elasticsearch at once. This means releases do not always happen in order of their version numbers. You can only upgrade to {{stack-version}} if the version you are currently running meets both of these conditions: + +* Has an older version number than {{stack-version}} +* Has an earlier release date than {{stack-version}} + +If you are currently running a version with an older version number but a later release date than {{stack-version}}, wait for a newer release before upgrading. + +Additionally, upgrading from a release candidate build, such as 9.0.0-rc1, is unsupported. Use pre-releases only for testing in a temporary environment. + +## Upgrade methods If you’re using Elastic-managed infrastructure, use the following options: * [Upgrade on {{ech}}](/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-ech.md) -* Upgrade on [{{serverless-full}}](/deploy-manage/deploy/elastic-cloud/serverless.md), which is automatically performed by Elastic and requires no user management If you’re using self-managed infrastructure - either on-prem or public cloud - use the following options: * [Upgrade the {{stack}} on a self-managed cluster](/deploy-manage/upgrade/deployment-or-cluster/self-managed.md) -* [Upgrade on {{ece}} (ECE)](/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-ece.md) -* [Upgrade on {{eck}} (ECK)](/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-eck.md) +* [Upgrade your deployment on {{ece}} (ECE)](/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-ece.md) +* [Upgrade your deployment on {{eck}} (ECK)](/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-eck.md) + +::::{note} +With [{{serverless-full}}](/deploy-manage/deploy/elastic-cloud/serverless.md), upgrades are fully managed by Elastic. Users automatically receive the latest features and improvements, with no need to plan or perform upgrade steps. +:::: diff --git a/deploy-manage/upgrade/deployment-or-cluster/elasticsearch.md b/deploy-manage/upgrade/deployment-or-cluster/elasticsearch.md index 2d458b2a28..1ced7be968 100644 --- a/deploy-manage/upgrade/deployment-or-cluster/elasticsearch.md +++ b/deploy-manage/upgrade/deployment-or-cluster/elasticsearch.md @@ -9,7 +9,15 @@ applies_to: An {{es}} cluster can be upgraded one node at a time so upgrading does not interrupt service. Running multiple versions of {{es}} in the same cluster beyond the duration of an upgrade is not supported, as shards cannot be replicated from upgraded nodes to nodes running the older version. -Before you start, [take the upgrade preparation steps](/deploy-manage/upgrade/prepare-to-upgrade.md). When performing a [rolling upgrade](#rolling-upgrades): +:::{note} +Upgrading from a release candidate build, such as 9.0.0-rc1, is unsupported. Use pre-releases only for testing in a temporary environment. +::: + +Before you start, [take the upgrade preparation steps](/deploy-manage/upgrade/prepare-to-upgrade.md). + +## {{es}} nodes upgrade order + +When performing a [rolling upgrade](#rolling-upgrades): 1. Upgrade the data nodes first, tier-by-tier, starting with the frozen tier, then the cold tier, then the warm tier, then the hot tier, and finally any other data nodes which are not in a tier. Complete the upgrade for all nodes in each data tier before moving to the next. This ensures {{ilm-init}} can continue to move data through the tiers during the upgrade. You can get the list of nodes in a specific tier with a `GET /_nodes` request, for example: `GET /_nodes/data_frozen:true/_none`. 2. Upgrade all remaining nodes that are neither master-eligible nor data nodes. This includes dedicated ML nodes, dedicated ingest nodes, and dedicated coordinating nodes. @@ -17,6 +25,8 @@ Before you start, [take the upgrade preparation steps](/deploy-manage/upgrade/pr This order ensures that all nodes can join the cluster during the upgrade. Upgraded nodes can join a cluster with an older master, but older nodes cannot always join a cluster with a upgraded master. +## Upgrade process + To upgrade a cluster: 1. **Disable shard allocation**. @@ -45,10 +55,9 @@ To upgrade a cluster: It is possible to leave your {{ml}} jobs running during the upgrade, but it puts increased load on the cluster. When you shut down a {{ml}} node, its jobs automatically move to another node and restore the model states. ::::{note} - Any {{ml}} indices created before 8.x must be reindexed before upgrading, which you can initiate from the **Upgrade Assistant** in 8.18. For more information, refer to [Anomaly detection results migration] + Any {{ml}} indices created before 8.x must be reindexed before upgrading, which you can initiate from the **Upgrade Assistant** in 8.19. For more information, refer to [Anomaly detection results migration] :::: - * Temporarily halt the tasks associated with your {{ml}} jobs and {{dfeeds}} and prevent new jobs from opening by using the [set upgrade mode API](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-ml-set-upgrade-mode): ```console @@ -187,7 +196,7 @@ To upgrade a cluster: -## Rolling upgrades [rolling-upgrades] +## Rolling upgrades considerations [rolling-upgrades] During a rolling upgrade, the cluster continues to operate normally. However, any new functionality is disabled or operates in a backward compatible mode until all nodes in the cluster are upgraded. New functionality becomes operational once the upgrade is complete and all nodes are running the new version. Once that has happened, there’s no way to return to operating in a backward compatible mode. Nodes running the previous version will not be allowed to join the fully-updated cluster. diff --git a/deploy-manage/upgrade/deployment-or-cluster/kibana.md b/deploy-manage/upgrade/deployment-or-cluster/kibana.md index 12a05204cf..6df2bc68ba 100644 --- a/deploy-manage/upgrade/deployment-or-cluster/kibana.md +++ b/deploy-manage/upgrade/deployment-or-cluster/kibana.md @@ -1,8 +1,9 @@ --- applies_to: - stack: deployment: self: all +products: + - id: kibana --- # Upgrade {{kib}} [upgrade-kibana] @@ -53,21 +54,20 @@ To upgrade {{kib}}: 1. Shut down all {{kib}} instances. {{kib}} does not support rolling upgrades. **Upgrading while older {{kib}} instances are running can cause data loss or upgrade failures.** 2. To install the `deb` or `rpm` package: - - a. Use `rpm` or `dpkg`. This installs all files in their proper locations and will not overwrite the config files. - b. Upgrade any plugins by removing the existing plugin and reinstalling the appropriate version using the `kibana-plugin` script. For more information, refer to [{{kib}} plugins](kibana://reference/kibana-plugins.md). + 1. Use `rpm` or `dpkg`. This installs all files in their proper locations and will not overwrite the config files. + 2. Upgrade any plugins by removing the existing plugin and reinstalling the appropriate version using the `kibana-plugin` script. For more information, refer to [{{kib}} plugins](kibana://reference/kibana-plugins.md). 3. To install from a `zip` or `tar.gz` archive: - a. **Extract the archive to a new directory** to be sure that you don’t overwrite the `config` or `data` directories. - b. Copy the files from the `config` directory from your old installation to your new installation. - c. Copy the files from the `data` directory from your old installation to your new installation. + 1. **Extract the archive to a new directory** to be sure that you don’t overwrite the `config` or `data` directories. + 2. Copy the files from the `config` directory from your old installation to your new installation. + 3. Copy the files from the `data` directory from your old installation to your new installation. ::::{important} If you use {{monitor-features}}, you must re-use the data directory when you upgrade {{kib}}. Otherwise, the {{kib}} instance is assigned a new persistent UUID and becomes a new instance in the monitoring data. :::: - d. Install the appropriate versions of all your plugins for your new installation using the `kibana-plugin` script. For more information, refer to [{{kib}} plugins](kibana://reference/kibana-plugins.md). + 4. Install the appropriate versions of all your plugins for your new installation using the `kibana-plugin` script. For more information, refer to [{{kib}} plugins](kibana://reference/kibana-plugins.md). 4. Start {{kib}}. diff --git a/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-ece.md b/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-ece.md index fc91767ef2..39a695562a 100644 --- a/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-ece.md +++ b/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-ece.md @@ -12,10 +12,8 @@ A single click in the {{ecloud}} console can upgrade a deployment running on ECE Once you're [prepared to upgrade](/deploy-manage/upgrade/prepare-to-upgrade.md), do the following: -% Note: Add a link once confirmed where prepare to upgrade will reside in TOC. - 1. Ensure your current ECE and Docker or Podman versions are [compatible](https://www.elastic.co/support/matrix/#elastic-cloud-enterprise) with the {{stack}} version you're upgrading to. For example, if you're upgrading to 9.0.0, the minimum required version is ECE 4.0. If you don’t have a compatible version installed, [upgrade your orchestrator](/deploy-manage/upgrade/orchestrator/upgrade-cloud-enterprise.md). -2. Download the most recent [stack pack](/deploy-manage/deploy/cloud-enterprise/manage-elastic-stack-versions.md#ece_most_recent_elastic_stack_packs) for the version you’re upgrading to, then [add the stack pack](/deploy-manage/deploy/cloud-enterprise/manage-elastic-stack-versions.md#ece-manage-elastic-stack-add) to your installation using the Cloud UI. +2. Download the most recent [stack pack](/deploy-manage/deploy/cloud-enterprise/manage-elastic-stack-versions.md#ece_most_recent_elastic_stack_packs) for the version you’re upgrading to, then [add the stack pack](/deploy-manage/deploy/cloud-enterprise/manage-elastic-stack-versions.md#ece-manage-elastic-stack-add) to your ECE installation using the Cloud UI. 3. If not configured already, [assign a snapshots repository](/deploy-manage/tools/snapshot-and-restore/cloud-enterprise.md) to your deployment to enable snapshots and back up your data. Although this is optional, we recommend this step. ## Perform the upgrade diff --git a/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-eck.md b/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-eck.md index 7c543807a5..40458050d6 100644 --- a/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-eck.md +++ b/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-eck.md @@ -10,23 +10,23 @@ applies_to: The ECK orchestrator can safely perform upgrades to newer versions of the {{stack}}. -Once you're [prepared to upgrade](/deploy-manage/upgrade/prepare-to-upgrade.md), ensure the ECK version is [compatible](/deploy-manage/deploy/cloud-on-k8s.md) with the {{stack}} version you’re upgrading to. For example, if you're upgrading to 9.0.0, the minimum required ECK version is 3.0.0. If it's incompatible, [upgrade your orchestrator](/deploy-manage/upgrade/orchestrator/upgrade-cloud-on-k8s.md). +Once you're [prepared to upgrade](/deploy-manage/upgrade/prepare-to-upgrade.md), ensure the ECK version is [compatible](/deploy-manage/deploy/cloud-on-k8s.md#stack-compatibility) with the {{stack}} version you’re upgrading to. For example, if you're upgrading to {{stack-version}}, the minimum required ECK version is 3.0.0. If it's incompatible, [upgrade your orchestrator](/deploy-manage/upgrade/orchestrator/upgrade-cloud-on-k8s.md). ## Perform the upgrade 1. In the resource spec file, modify the `version` field for the desired {{stack}} version. 2. Save your changes. The orchestrator will start the upgrade process automatically. -In this example, we’re modifying the version to `9.0.0`. +In this example, we’re modifying the version to `{{stack-version}}`. -```yaml +```yaml subs=true apiVersion: elasticsearch.k8s.elastic.co/v1 kind: Elasticsearch metadata: name: elasticsearch-sample namespace: production spec: - version: 9.0.0 + version: {{stack-version}} monitoring: metrics: elasticsearchRefs: @@ -117,7 +117,7 @@ metadata: name: kibana-sample namespace: production spec: - version: 9.0.0 + version: {{stack-version}} monitoring: metrics: elasticsearchRefs: @@ -142,4 +142,4 @@ Check out [Nodes orchestration](/deploy-manage/deploy/cloud-on-k8s/nodes-orchest ## Next steps -Once you've successfully upgraded your deployment, [upgrade your ingest components](/deploy-manage/upgrade/ingest-components.md), such as {{ls}}, {{agents}}, or {{beats}}. +Once you've successfully upgraded your deployment, you can [upgrade your ingest components](/deploy-manage/upgrade/ingest-components.md), such as {{ls}}, {{agents}}, or {{beats}}. diff --git a/deploy-manage/upgrade/ingest-components.md b/deploy-manage/upgrade/ingest-components.md index 27375b753c..9bb9fda86b 100644 --- a/deploy-manage/upgrade/ingest-components.md +++ b/deploy-manage/upgrade/ingest-components.md @@ -12,6 +12,12 @@ applies_to: Once you've successfully [upgraded your deployment or cluster](/deploy-manage/upgrade/deployment-or-cluster.md), the final step is to update your ingest components and clients in the following order: 1. {{agent}}: [Upgrade instructions](../../reference/fleet/upgrade-elastic-agent.md) + + ::::{note} + If you plan to upgrade Fleet-managed {{agent}}s, start by upgrading the agent running as the {{fleet-server}}. + :::: + 2. {{beats}}: [Upgrade instructions](beats://reference/libbeat/upgrading.md) 3. {{ls}}: [Upgrade instructions](logstash://reference/upgrading-logstash.md) -4. Custom clients \ No newline at end of file +4. Custom clients + diff --git a/deploy-manage/upgrade/orchestrator.md b/deploy-manage/upgrade/orchestrator.md index 5cc71f3a22..a3a129a40b 100644 --- a/deploy-manage/upgrade/orchestrator.md +++ b/deploy-manage/upgrade/orchestrator.md @@ -14,7 +14,7 @@ The topics in this section apply to customers running the {{stack}} on {{ece}} ( Elastic provides customers with two major self-managed orchestrators to manage the {{stack}}. Before upgrading the products in the {{stack}}, ensure your orchestrator is running a compatible version. If your orchestrator is running an incompatible with the {{stack}} version you’re upgrading to, you must upgrade the orchestrator first. -If your orchestrator is up to date, you can skip this step and proceed with [Upgrading on ECE](/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-ece.md) or [Upgrading on ECK](/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-eck.md). +If your orchestrator is up to date, you can skip this step and proceed with [Upgrading your deployment on ECE](/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-ece.md) or [Upgrading your deployment on ECK](/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-eck.md). To learn how to upgrade your orchestrator, refer to one of these topics: diff --git a/deploy-manage/upgrade/prepare-to-upgrade.md b/deploy-manage/upgrade/prepare-to-upgrade.md index f9e547fac3..a7a53a293a 100644 --- a/deploy-manage/upgrade/prepare-to-upgrade.md +++ b/deploy-manage/upgrade/prepare-to-upgrade.md @@ -1,4 +1,5 @@ --- +navigation_title: Preparation steps applies_to: stack: deployment: @@ -9,54 +10,31 @@ applies_to: --- # Prepare to upgrade -Before you upgrade, review and complete the necessary preparation steps, which vary by version. +When upgrading an existing cluster, you perform a major, minor, or patch upgrade. A minor upgrade, for example, takes you from version 9.0.0 to 9.1.0; a major upgrade from 8.19.0 to 9.1.0; and a patch upgrade from 9.0.0 to 9.0.4. :::{important} Upgrading from a release candidate build, such as 9.0.0-rc1, is unsupported. Use pre-releases only for testing in a temporary environment. ::: -## Prepare to upgrade from 8.x [prepare-upgrade-from-8.x] +This document describes the preparation steps for upgrading {{es}}, which vary by version and type of upgrade. -To upgrade from 8.17.0 or earlier to 9.0.0, you must first upgrade to the latest 8.18 patch release. This allows you to use the [Upgrade Assistant](prepare-to-upgrade/upgrade-assistant.md) to identify and resolve issues, reindex indices created before 8.0.0, and perform a rolling upgrade. Upgrading to the latest 8.18 patch release is required even if you choose a full {{es}} cluster restart. If you're using 7.x and earlier, you may need to complete multiple upgrades or perform a full-cluster restart to reach the latest 8.18 patch release before upgrading to 9.0.0. +## Common preparation steps for all upgrades -If you are already running an 8.18.x version, it's also recommended to upgrade to the latest 8.18 patch release before upgrading to 9.x. This ensures that the latest version of the upgrade assistant is used, and any bug fixes that could have implications for the upgrade are applied. +The following steps are common to all types of upgrades, regardless if you are upgrading from 8.x (major upgrade), or if you are already running a 9.x version. -As an alternative to upgrading the cluster, you can create a new 9.0.0 deployment and reindex from the original cluster. For more information, refer to [Reindex to upgrade](#reindex-to-upgrade). +1. **Review breaking changes** -:::{note} -For flexible upgrade scheduling, 8.18.0 {{beats}} and {{ls}} are compatible with 9.x {{es}}. -By default, 8.x {{es}} clients are compatible with 9.x and use [REST API compatibility](elasticsearch://reference/elasticsearch/rest-apis/compatibility.md) to maintain compatibility with the 9.x {{es}} server. -::: - -Review the following best practices to upgrade your deployments. - -1. Run the [Upgrade Assistant](prepare-to-upgrade/upgrade-assistant.md), which identifies deprecated settings in your configuration and guides you through resolving issues that could prevent a successful upgrade. The Upgrade Assistant also helps resolve issues with older indices created before version 8.0.0, providing the option to reindex older indices or mark them as read-only. To prevent upgrade failures, we strongly recommend you **do not** skip this step. - - :::{note} - Depending on your setup, reindexing can change your indices, and you may need to update alerts, transforms, or other code targeting the old index. - ::: - -1. Before you change configurations or reindex, ensure you have a current [snapshot](/deploy-manage/tools/snapshot-and-restore/create-snapshots.md). + Although breaking changes typically affect [major upgrades](#prepare-upgrade-from-8.x), they can also occur in minor or patch releases. Review the [breaking changes](../../release-notes/index.md) for each product you use to learn more about potential impacts on your applications. Ensure you test with the new version before upgrading production deployments. - :::{tip} - Tip: In 8.3.0 and later, snapshots are generally available as simple archives. Use the [archive functionality](/deploy-manage/upgrade/deployment-or-cluster/reading-indices-from-older-elasticsearch-versions.md) to search snapshots from 5.0.0 and later without needing an old {{es}} cluster. This ensures that your {{es}} data remains accessible after upgrading, without requiring a reindex process. - ::: + If you are affected by a breaking change, you have to take action before upgrading. This can include updating your code, change configuration settings, or other steps. - To successfully upgrade, resolve all critical issues. If you make additional changes, create a snapshot to back up your data. +2. **Verify plugin compatibility** -1. To identify if your applications use unsupported features or behave differently in 9.x, review the deprecation logs in the Upgrade Assistant. + If you use [{{es}} plugins](elasticsearch://reference/elasticsearch/plugins.md), ensure each plugin is compatible with the {{es}} version you're upgrading to. -4. Major version upgrades can include breaking changes that require additional steps to ensure your applications function as expected. Review the [breaking changes](../../release-notes/index.md) for each product you use to learn more about potential impacts on your application. Ensure you test with the new version before upgrading existing deployments. +3. **Test in a non-production environment** -1. Make the recommended changes to ensure your clients continue operating as expected after the upgrade. - - :::{note} - As a temporary solution, use the 8.x syntax to submit requests to 9.x with REST API compatibility mode. While this allows you to submit requests using the old syntax, it doesn’t guarantee the same behavior. REST API compatibility should serve as a bridge during the upgrade, not a long-term solution. For more details on how to effectively use REST API compatibility during an upgrade, refer to [REST API compatibility](elasticsearch://reference/elasticsearch/rest-apis/compatibility.md). - ::: - -1. If you use {{es}} plugins, ensure each plugin is compatible with the {{es}} version you're upgrading. - -1. Before upgrading your production deployment, test the upgrade using an isolated environment. Ensure the test and production environments use the same settings. + Before upgrading your production deployment, test the upgrade using a non-production environment. Ensure the test and production environments use the same settings. :::{note} 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 behavior in your environment. @@ -75,37 +53,108 @@ Review the following best practices to upgrade your deployments. : Do all of your snapshot repositories work correctly and pass [repository analysis](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-snapshot-repository-analyze)? ::: -1. Create a snapshot of your production deployment before starting the upgrade. +4. **Create a snapshot for backup** + + Take a [snapshot](/deploy-manage/tools/snapshot-and-restore/create-snapshots.md) of your cluster before starting the upgrade. This provides a recovery point in case the upgrade needs to be rolled back. :::{important} After you start to upgrade your {{es}} cluster, you cannot downgrade any of its nodes. If you can't complete the upgrade process, you must [restore from a snapshot](/deploy-manage/tools/snapshot-and-restore/restore-snapshot.md) which was taken before starting the upgrade. ::: -1. If you use a separate [monitoring cluster](/deploy-manage/monitor/stack-monitoring/elasticsearch-monitoring-self-managed.md), upgrade the monitoring cluster before the production cluster. The monitoring cluster and the clusters being monitored should be running the same version of the {{stack}}. Monitoring clusters 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. +5. **Upgrade your monitoring cluster first** + + If you use a separate [monitoring cluster](/deploy-manage/monitor/stack-monitoring/elasticsearch-monitoring-self-managed.md), upgrade the monitoring cluster before the production cluster. The monitoring cluster and the clusters being monitored should be running the same version of the {{stack}}. Monitoring clusters 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. + +6. **Remote clusters** - :::{note} If you use {{ccs}}, versions 9.0.0 and later can search only remote clusters running the previous minor version, the same version, or a newer minor version in the same major version. For more information, refer to [{{ccs-cap}}](../../solutions/search/cross-cluster-search.md). - If you use {{ccr}}, a cluster that contains follower indices must run the same or newer (compatible) version as the remote cluster. For more information and to view the version compatibility matrix, refer to [{{ccr-cap}}](/deploy-manage/tools/cross-cluster-replication.md). To view your remote clusters in {{kib}}, go to **Stack Management > Remote Clusters**. + If you use {{ccr}}, a cluster that contains follower indices must run the same or newer (compatible) version as the remote cluster. For more information and to view the version compatibility matrix, refer to [{{ccr-cap}}](/deploy-manage/tools/cross-cluster-replication.md). + + To view your remote clusters in {{kib}}, go to **Stack Management > Remote Clusters**. + +7. (Optional) **Close {{ml}} jobs** + + To reduce overhead on the cluster during the upgrade, close {{ml}} jobs before starting the upgrade, and open them after the upgrade is complete. Although {{ml}} jobs can run during a rolling upgrade, doing so increases the cluster workload. + +## Additional preparation steps to upgrade from 8.x [prepare-upgrade-from-8.x] + +Major upgrades require additional planning and preparation, as they often introduce a significant number of breaking changes and require additional steps to ensure a smooth transition. The main challenges when preparing for a major version upgrade include: + +* Reindexing any indices created before 8.0.0, including those used by {{ml}} and transform jobs. +* Identifying and applying changes needed to accommodate breaking changes. + +To assist with this process, use the [Upgrade Assistant](prepare-to-upgrade/upgrade-assistant.md), which helps detect deprecated settings, highlights upgrade blockers, and guides you through the required actions. - In addition, if you have {{ccr-init}} data streams, refer to [Upgrade uni-directional {{ccr}} clusters with followed data streams](#upgrade-ccr-data-streams) for specific instructions on reindexing. +Follow these steps to prepare for a successful major upgrade from 8.x to 9.x: + +1. **Upgrade to the latest 8.19 patch release** + + To perform a major upgrade from 8.x to 9.x of {{es}}, you must first upgrade to 8.19.x. This allows you to use the [Upgrade Assistant](prepare-to-upgrade/upgrade-assistant.md) to identify and resolve issues, reindex indices created before 8.0.0, and prepare the cluster for the actual upgrade. Upgrading to 8.19 is required even if you choose a full {{es}} cluster restart to upgrade. + + ::::{note} + Because 8.18.0 and 9.0.0 were released at the same time, upgrading from 8.18.x to 9.0.x is also supported, as long it follows the supported [upgrade paths](../upgrade.md#upgrade-paths). However, upgrading to 9.1.0 or later requires starting from 8.19.x. + + As an example, these are valid upgrade paths to {{stack-version}}: + * Versions prior to 8.18 → 8.19.x → {{stack-version}} *(recommended)* + * Versions prior to 8.18 → 8.18.x → 9.0.x → {{stack-version}} :::: -1. To reduce overhead on the cluster during the upgrade, close {{ml}} jobs. Although {{ml}} jobs can run during a rolling upgrade, doing so increases the cluster workload. + If you are already running an 8.19.x version, it's also recommended to upgrade to the latest 8.19 patch release before upgrading to 9.x. This ensures that the latest version of the upgrade assistant is used, and any bug fixes that could have implications for the upgrade are applied. + + If you're using 7.x and earlier, you may need to complete multiple upgrades or perform a full-cluster restart to reach the latest 8.19 patch release before upgrading to 9.x. As an alternative method to upgrading the cluster, you can create a new 9.x deployment and reindex from the original cluster. For more information, refer to [Reindex to upgrade](#reindex-to-upgrade). + + :::{note} + For flexible upgrade scheduling, 8.19.x {{beats}} and {{ls}} are compatible with 9.x {{es}}. + By default, 8.x {{es}} clients are compatible with 9.x and use [REST API compatibility](elasticsearch://reference/elasticsearch/rest-apis/compatibility.md) to maintain compatibility with the 9.x {{es}} server. + ::: + +2. **Run the Upgrade Assistant** + + The [Upgrade Assistant](prepare-to-upgrade/upgrade-assistant.md) identifies deprecated settings in your configuration and guides you through resolving issues that could prevent a successful upgrade. The Upgrade Assistant also helps resolve issues with older indices created before version 8.0.0, providing the option to reindex older indices or mark them as read-only. To prevent upgrade failures, we strongly recommend you **do not** skip this step. + + :::{note} + Depending on your setup, reindexing can change your indices, and you may need to update alerts, transforms, or other code targeting the old index. + ::: -1. If you have `.ml-anomalies-*`anomaly detection result indices created in {{es}} 7.x, reindex them, mark them as read-only, or delete them before you upgrade to 9.x. For more information, refer to [Migrate anomaly detection results](#anomaly-migration). + Considerations when using the upgrade assistant: -1. If you have transform destination indices created in {{es}} 7.x, reset, reindex, or delete them before you upgrade to 9.x. For more information, refer to [Migrate transform destination indices](#transform-migration). + 1. Before you change configurations or reindex, ensure you have a current [snapshot](/deploy-manage/tools/snapshot-and-restore/create-snapshots.md). + :::{tip} + In 8.3.0 and later, snapshots are generally available as simple archives. You can use the [archive functionality](/deploy-manage/upgrade/deployment-or-cluster/reading-indices-from-older-elasticsearch-versions.md) to search snapshots from 5.0.0 and later without needing an old {{es}} cluster. This ensures that your {{es}} data remains accessible after upgrading, without requiring a reindex process. + ::: + + 2. For a successful upgrade, resolve all critical issues reported by the assistant. If you make additional changes, create a snapshot to back up your data. + + 3. To identify if your applications use unsupported features or behave differently in 9.x, review the deprecation logs in the Upgrade Assistant. + + 4. Make the recommended changes to ensure your clients continue operating as expected after the upgrade. + + :::{note} + As a temporary solution, use the 8.x syntax to submit requests to 9.x with REST API compatibility mode. While this allows you to submit requests using the old syntax, it doesn’t guarantee the same behavior. REST API compatibility should serve as a bridge during the upgrade, not a long-term solution. For more details on how to effectively use REST API compatibility during an upgrade, refer to [REST API compatibility](elasticsearch://reference/elasticsearch/rest-apis/compatibility.md). + ::: + +3. **{{ccr-cap}} (CCR)** + + If you have {{ccr-init}} data streams, and your indices require reindexing, refer to [Upgrade uni-directional {{ccr}} clusters with followed data streams](#upgrade-ccr-data-streams) for specific instructions. + +4. **Old {{ml}} indices** + + If you have `.ml-anomalies-*`anomaly detection result indices created in {{es}} 7.x, reindex them, mark them as read-only, or delete them before you upgrade to 9.x. For more information, refer to [Migrate anomaly detection results](#anomaly-migration). + +5. **Old transform indices** + + If you have transform destination indices created in {{es}} 7.x, reset, reindex, or delete them before you upgrade to 9.x. For more information, refer to [Migrate transform destination indices](#transform-migration). ## Reindex to upgrade [reindex-to-upgrade] -Optionally create a 9.0.0 deployment and reindex from remote: +If you are running a pre-8.x version, you might need to perform multiple upgrades before being able to upgrade to 9.x. As an alternative method to upgrading the cluster, you can create a new {{stack-version}} deployment and reindex from remote: -1. Provision an additional deployment running 9.0.0. -2. To reindex your data into the new {{es}} cluster, use the [reindex documents API](https://www.elastic.co/docs/api/doc/elasticsearch/v8/operation/operation-reindex) and temporarily send new index requests to both clusters. +1. Provision an additional deployment running the desired version, such as {{stack-version}}. +2. To reindex your data into the new {{es}} cluster, use the [reindex documents API](https://www.elastic.co/docs/api/doc/elasticsearch/v8/operation/operation-reindex) and temporarily send new indexing requests to both clusters. 3. Verify the new cluster performs as expected, fix any problems, and then permanently swap in the new cluster. -4. Delete the old deployment. On {{ecloud}}, you are billed only for the time the new deployment runs in parallel with your old deployment. Usage is billed on an hourly basis. +4. Delete the old deployment. On {{ecloud}}, you are billed for the time the new deployment runs in parallel with your old deployment. Usage is billed on an hourly basis. ## Upgrade uni-directional {{ccr}} clusters with followed data streams [upgrade-ccr-data-streams] @@ -134,9 +183,6 @@ If you need to write directly to non-write backing indices of data streams in a 3. Once the reindexing is complete and the leader cluster is upgraded, re-add the newly reindexed backing indexes as follower indices on the {{ccr-init}} follower. - - - ## Migrate anomaly detection results [anomaly-migration] Reindex, mark as read-only, or delete the `.ml-anomalies-*` {{anomaly-detect}} result indices created in {{es}} 7.x. diff --git a/deploy-manage/upgrade/prepare-to-upgrade/upgrade-assistant.md b/deploy-manage/upgrade/prepare-to-upgrade/upgrade-assistant.md index ba882da472..2572d6752e 100644 --- a/deploy-manage/upgrade/prepare-to-upgrade/upgrade-assistant.md +++ b/deploy-manage/upgrade/prepare-to-upgrade/upgrade-assistant.md @@ -10,11 +10,17 @@ applies_to: self: products: - id: kibana + - id: elasticsearch --- # Upgrade Assistant [upgrade-assistant] -The Upgrade Assistant helps you [prepare to upgrade](/deploy-manage/upgrade/prepare-to-upgrade.md) to the next version of the {{stack}}. To access the assistant, go to **{{stack-manage-app}} → Upgrade Assistant**. +The Upgrade Assistant helps you [prepare to upgrade](/deploy-manage/upgrade/prepare-to-upgrade.md) to the next major version of the {{stack}}. To access the assistant, go to **{{stack-manage-app}} → Upgrade Assistant**. + +::::{tip} +Upgrade assistant should be run from the latest minor release before a major upgrade. When upgrading to 9.x, ensure you run 8.19.latest, and run the assistant there. +Running the latest patched version of 8.19 will allow running the latest version of the upgrade assistant logic. +:::: The assistant identifies deprecated settings in your configuration, and if any of those settings are enabled, it guides you through resolving issues that could prevent a successful upgrade. The Upgrade Assistant also helps resolve issues with older indices created before version 8.0.0, providing options to reindex older indices or mark them as read-only. diff --git a/docset.yml b/docset.yml index e4996b3d48..6f09daaf39 100644 --- a/docset.yml +++ b/docset.yml @@ -278,7 +278,7 @@ subs: fleet-server-issue: "https://github.com/elastic/fleet-server/issues/" fleet-server-pull: "https://github.com/elastic/fleet-server/pull/" kib-pull: "https://github.com/elastic/kibana/pull/" - stack-version: "9.0.3" + stack-version: "9.1.0" ece_version: "4.0.1" eck_version: "3.0.0" eck_release_branch: "3.0" From 00bad2098a88eb9190dad7565fa5fa425019a199 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Mon, 28 Jul 2025 13:21:55 +0200 Subject: [PATCH 02/30] docset updated --- docset.yml | 3 --- 1 file changed, 3 deletions(-) diff --git a/docset.yml b/docset.yml index 39ad68d745..9ba23096d2 100644 --- a/docset.yml +++ b/docset.yml @@ -280,9 +280,6 @@ subs: fleet-server-pull: "https://github.com/elastic/fleet-server/pull/" kib-pull: "https://github.com/elastic/kibana/pull/" stack-version: "9.1.0" - ece_version: "4.0.1" - eck_version: "3.0.0" - eck_release_branch: "3.0" eck_helm_minimum_version: "3.2.0" eck_resources_list: "Elasticsearch, Kibana, APM Server, Beats, Elastic Agent, Elastic Maps Server, and Logstash" eck_resources_list_short: "APM Server, Beats, Elastic Agent, Elastic Maps Server, and Logstash" From aef71ef73d07e180dddbd7b587f4b73720fb9eb3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Mon, 28 Jul 2025 14:39:35 +0200 Subject: [PATCH 03/30] plan upgrade updated --- deploy-manage/upgrade.md | 4 ++ deploy-manage/upgrade/plan-upgrade.md | 94 ++++++++++++++++++++------- 2 files changed, 76 insertions(+), 22 deletions(-) diff --git a/deploy-manage/upgrade.md b/deploy-manage/upgrade.md index c81d5c5ada..6f411cce50 100644 --- a/deploy-manage/upgrade.md +++ b/deploy-manage/upgrade.md @@ -58,4 +58,8 @@ Refer to the [download past releases](https://www.elastic.co/downloads/past-rele ::::{note} Major upgrades must be performed from the latest minor version of the previous major. For example, to upgrade to {{stack-version}}, you need to be on 8.19 first. + +For flexible upgrade scheduling, 8.19 {{agent}}, {{beats}}, and {{ls}} are compatible with 9.x {{es}}. + +By default, 8.x {{es}} clients are compatible with 9.x and use [REST API compatibility](elasticsearch://reference/elasticsearch/rest-apis/compatibility.md) to maintain compatibility with the 9.x {{es}} cluster. :::: \ No newline at end of file diff --git a/deploy-manage/upgrade/plan-upgrade.md b/deploy-manage/upgrade/plan-upgrade.md index 86c9df0cba..c0f96a2291 100644 --- a/deploy-manage/upgrade/plan-upgrade.md +++ b/deploy-manage/upgrade/plan-upgrade.md @@ -1,30 +1,72 @@ +--- +applies_to: + stack: + deployment: + eck: + ess: + ece: + self: +--- # Plan your upgrade -There are several things you need to plan for before performing the actual upgrade, so create a test plan. Consider the following recommendations: +There are several important factors to consider before starting the upgrade process. Use the following recommendations to build a solid upgrade plan: -* 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 few weeks or more to complete. -* Consider opening a [support case](https://support.elastic.co/) with Elastic to alert our Elastic Support team of your system change. If you need additional assistance, [Elastic Consulting Services](https://www.elastic.co/consulting) provides the technical expertise and step-by-step approach for upgrading your Elastic deployment. +* Plan for an appropriate amount of time to complete the upgrade. Depending on your configuration and the size of your cluster, the process may take just a few minutes or several hours. In more complex environments, it could extend to a few weeks or more. +* Consider opening a [support case](https://support.elastic.co/) with Elastic to alert our Elastic Support team of your system change. If you need additional assistance, [Elastic Consulting Services](https://www.elastic.co/consulting) provides the technical expertise and step-by-step approach for upgrading your environment. * Schedule a system maintenance window within your organization. +* When possible, perform testing of the upgrade process in a non-production environment. -## Check system requirements [check-system-requirements] +The objective of this section is to facilitate the creation of an upgrade plan that addresses all the necessary steps and preparations needed for upgrading your deployment or cluster. -Ensure the version you’re upgrading to for {{es}}, {{kib}}, and any ingest components supports your current operating system. Refer to the [Product and Operating System support matrix](https://www.elastic.co/support/matrix#matrix_os). +## Compatibility checks + +Check if you can upgrade directly to the version you are aiming to upgrade to. If not, you need to find a valid upgrade path, and plan accordingly. + +* System requirements: Ensure the version you’re upgrading to for {{es}}, {{kib}}, and any ingest components supports your current operating system. Refer to the [Product and Operating System support matrix](https://www.elastic.co/support/matrix#matrix_os). + +* Compatibility with ingest components: Ensure your ingest components are compatible with the version you’re upgrading to for {{es}}. Refer to [conduct a component inventory](#conduct-a-component-inventory) for more details. + +* Orchestrator compatibility: If your orchestrator is not compatible with the {{stack}} version you’re upgrading to, you need to [upgrade the orchestrator](/deploy-manage/upgrade/orchestrator.md) before upgrading your cluster. Compatibility details are available in: + * [ECE - stack packs](/deploy-manage/deploy/cloud-enterprise/manage-elastic-stack-versions.md#ece_most_recent_elastic_stack_packs) + * [ECK - {{stack}} compatibility](/deploy-manage/deploy/cloud-on-k8s.md#stack-compatibility) + +* Developed clients compatibility: Check any client library you are using and ensure it is compatible with the version you’re upgrading to for {{es}}. Refer to [{{es}} clients](/reference/elasticsearch-clients/index.md) and [upgrade paths](../upgrade.md#upgrade-paths) for more information. + +* {{es}} version compatibility: Check [upgrade paths](../upgrade.md#upgrade-paths) description to ensure you can upgrade directly to the version you are aiming to upgrade to. + +Examples of situations where you need to adapt your upgrade path: + +* Some of your ingest components are not compatible with the version you are aiming to upgrade to, and they need to be upgraded first to a compatible version. +* Your orchestrator (ECE or ECK) or operating system is not compatible with the version you are aiming to upgrade to, and it needs to be upgraded first to a compatible version. +* Your running {{es}} version cannot be upgraded directly to the version you are aiming to upgrade to, and it needs to be upgraded first to an intermediate version. +* Due to some breaking changes, your developed clients are using {{es}} APIs that are not compatible with the version you are aiming to upgrade to, and they need to be adapted first. ### OpenJDK compatibility and FIPS compliance By default, {{es}} is built using Java and includes a bundled version of [OpenJDK](https://openjdk.java.net/) within each distribution. While we strongly recommend using the bundled Java Virtual Machine (JVM) in all installations of {{es}}, if you choose to use your own JVM, ensure it’s compatible by reviewing the [Product and JVM support matrix](https://www.elastic.co/support/matrix#matrix_jvm). -If you’re running {{es}} in FIPS 140-2 mode, we recommend using [Bouncy Castle](https://www.bouncycastle.org/java.html) as a Java security provider when running {{es}}. +If you’re running {{es}} in FIPS 140-2 mode, we recommend using [Bouncy Castle](https://www.bouncycastle.org/java.html) as a Java security provider when running {{es}}. + +### Rest API compatibility + +[REST API compatibility](elasticsearch://reference/elasticsearch/rest-apis/compatibility.md) is a per-request opt-in feature that can help REST clients mitigate non-compatible (breaking) changes to the REST API. ## Conduct a component inventory -It is very important to map all the components that are being used on the {{stack}}. When you upgrade your deployment, you also may need to upgrade all the other components. You should record whether any users use each component, and if so, also record the current version. While not comprehensive, here’s a list of components you should check: +When you plan to upgrade your deployment, it is very important to map all the components that are being used on the {{stack}}, and check if they are compatible with the {{es}} version you plan to upgrade to by reviewing the [Product compatibility support matrix](https://www.elastic.co/support/matrix#matrix_compatibility). + +::::{note} +If any of your ingest components does not support the {{es}} version you plan to upgrade to, you need to upgrade that component to a version that supports the desired {{es}} version before upgrading {{es}}. +:::: + +As part of the upgrade plan, you will also have to determine if you want to upgrade the ingest components to the same version as {{es}}, after the upgrade of {{es}} and {{kib}}. + +While not comprehensive, here’s a list of components you should check: * {{es}} * {{es}} Hadoop * {{es}} plugins * {{es}} clients -* {{kib}} * {{ls}} * {{ls}} plugins * {{beats}} @@ -41,9 +83,9 @@ It is very important to map all the components that are being used on the {{stac When you do your inventory, you can [enable audit logging](/deploy-manage/security/logging-configuration/enabling-audit-logs.md) to evaluate resources accessing your deployment. ::: -## Test your development environment +## Test in a non-production environment -We highly recommend testing and upgrading in your development environment before your production environment. Therefore, it is crucial to ensure that both your development and production environments have the same settings. Consider checking the following components beforehand: +We highly recommend testing the upgrade process in a non-production environment before applying changes to your production environment. To ensure meaningful results, your test and production environments should be configured as similarly as possible. Consider validating the following areas: * Enrichment information * Plugins @@ -60,23 +102,31 @@ We highly recommend testing and upgrading in your development environment before * Alerts * Authentication -## Choose your upgrade path [choose-upgrade-path] +## Upgrade order + +When upgrading the {{stack}}, the process begins with {{es}}, followed by {{kib}}, which must always be aligned in terms of versioning. Other components can remain on earlier versions as long as they are compatible with the target {{es}} version, though we recommend upgrading them as well to benefit from the latest features and fixes. + +If all components are compatible with the target version of {{es}}, we recommend upgrading them in the following order: -The procedures you follow to upgrade depend on your infrastructure and deployment method. You’ve installed Elastic components using either Elastic-managed infrastructure or self-managed infrastructure. +1. {{es}} +2. {{kib}} (must be kept aligned with the {{es}} version) +3. Fleet Server and APM Server (if used) +4. Ingest tools (Beats, Elastic Agent, Logstash, etc.) and {{es}} client libraries -### Elastic-managed infrastructure +::::{note} +If you use a separate [monitoring cluster](/deploy-manage/monitor/stack-monitoring/elasticsearch-monitoring-self-managed.md), upgrade the monitoring cluster before the production cluster. The monitoring cluster and the clusters being monitored should be running the same version of the {{stack}}. Monitoring clusters 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. +:::: -Elastic-managed infrastructure includes {{ecloud}} – the umbrella term for {{ech}} (ECH) and {{serverless-full}}. {{serverless-full}} (“Serverless”) is a fully managed cloud offering with three products: {{es-serverless}}, {{obs-serverless}}, and {{sec-serverless}}. All serverless products are built on top of the Search AI Lake. Customers on serverless receive the latest features automatically when updates are published and do not need to choose an upgrade path. +## Example of an upgrade plan -{{ech}} is Elastic’s cloud offering for managing {{stack}} deployments, built on top of {{es}}. A single click in the {{ecloud}} console can upgrade a deployment to a newer version. +Let's assume you are running all {{stack}} components in version 8.14 and your main goal is to upgrade {{es}} and {{kib}} to the latest {{stack-version}}, without requiring to upgrade the ingest components (Beats, Elastic Agent, and Logstash) except when required by the upgrade path. -### Self-managed infrastructure +The minimum steps your plan should include are: -Self-managed infrastructure – either on-prem or on public cloud, includes: -* {{stack}} -* {{ece}} (ECE) -* {{eck}} (ECK) +1. Upgrade {{es}} and {{kib}} to the latest 8.19 version, as a requirement for the major upgrade to {{stack-version}}. +2. Upgrade all ingest components to the latest 8.19 version, as otherwise they won't be compatible with {{es}} running {{stack-version}}. +3. Upgrade {{es}} and {{kib}} to {{stack-version}}. -For ECE and ECK, ensure the operator is running a version compatible with the {{stack}} version you’re upgrading to. If not, you need to upgrade that before [upgrading your cluster](/deploy-manage/upgrade/deployment-or-cluster.md). +## Next steps -If you’re running the {{stack}} on your own self-managed infrastructure, you must [upgrade each component individually](/deploy-manage/upgrade/deployment-or-cluster/self-managed.md). +Once you’ve planned your upgrade and defined a clear upgrade path for all the components, you can proceed to the [upgrade preparations](/deploy-manage/upgrade/prepare-to-upgrade.md). \ No newline at end of file From 19b49c0b88ac3535de74b0a47ead6d09849da56d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Mon, 28 Jul 2025 17:18:55 +0200 Subject: [PATCH 04/30] link fixed, and minor update --- deploy-manage/upgrade.md | 11 ++++++----- deploy-manage/upgrade/prepare-to-upgrade.md | 2 +- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/deploy-manage/upgrade.md b/deploy-manage/upgrade.md index 6f411cce50..e5063ffcb9 100644 --- a/deploy-manage/upgrade.md +++ b/deploy-manage/upgrade.md @@ -46,15 +46,16 @@ Upgrading your Elastic cluster or deployment involves several stages, including Additionally, if you're using a self-managed orchestration platform such as {{ece}} or {{eck}}, refer to [Upgrade your ECE or ECK orchestrator](/deploy-manage/upgrade/orchestrator.md) to keep the orchestrator up to date. ## Upgrade paths [upgrade-paths] -% alternative title : Upgrade paths / Can I upgrade to any version? You can upgrade to a higher version if the target version was released *after* your current version. Upgrades to versions released *before* your current version are not supported, even if the version number is higher. Refer to [out-of-order releases](/deploy-manage/upgrade/deployment-or-cluster.md#out-of-order-releases) for more information. +% Uncomment these examples when 9.1.1 and 9.0.5 are released. We currently don't have enough 9.x versions for meaningful examples. + ::::{note} Major upgrades must be performed from the latest minor version of the previous major. For example, to upgrade to {{stack-version}}, you need to be on 8.19 first. diff --git a/deploy-manage/upgrade/prepare-to-upgrade.md b/deploy-manage/upgrade/prepare-to-upgrade.md index a7a53a293a..6609ec3e79 100644 --- a/deploy-manage/upgrade/prepare-to-upgrade.md +++ b/deploy-manage/upgrade/prepare-to-upgrade.md @@ -30,7 +30,7 @@ The following steps are common to all types of upgrades, regardless if you are u 2. **Verify plugin compatibility** - If you use [{{es}} plugins](elasticsearch://reference/elasticsearch/plugins.md), ensure each plugin is compatible with the {{es}} version you're upgrading to. + If you use [{{es}} plugins](elasticsearch://reference/elasticsearch-plugins/index.md), ensure each plugin is compatible with the {{es}} version you're upgrading to. 3. **Test in a non-production environment** From cf7add68e13b8755a6f51257f26be4bdace5e7c6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Mon, 28 Jul 2025 18:27:40 +0200 Subject: [PATCH 05/30] compatibility checks updated --- deploy-manage/upgrade/plan-upgrade.md | 41 +++++++++------------ deploy-manage/upgrade/prepare-to-upgrade.md | 4 +- 2 files changed, 21 insertions(+), 24 deletions(-) diff --git a/deploy-manage/upgrade/plan-upgrade.md b/deploy-manage/upgrade/plan-upgrade.md index c0f96a2291..8d7d358a10 100644 --- a/deploy-manage/upgrade/plan-upgrade.md +++ b/deploy-manage/upgrade/plan-upgrade.md @@ -20,36 +20,29 @@ The objective of this section is to facilitate the creation of an upgrade plan t ## Compatibility checks -Check if you can upgrade directly to the version you are aiming to upgrade to. If not, you need to find a valid upgrade path, and plan accordingly. +Before upgrading, verify that your current environment supports the version you plan to upgrade to. If not, identify any required intermediate upgrades or component changes and include them in your upgrade plan. -* System requirements: Ensure the version you’re upgrading to for {{es}}, {{kib}}, and any ingest components supports your current operating system. Refer to the [Product and Operating System support matrix](https://www.elastic.co/support/matrix#matrix_os). +* **System requirements**: Ensure your current operating system is supported by the target versions of {{es}}, {{kib}}, and any ingest components. Refer to the [Product and Operating System support matrix](https://www.elastic.co/support/matrix#matrix_os). -* Compatibility with ingest components: Ensure your ingest components are compatible with the version you’re upgrading to for {{es}}. Refer to [conduct a component inventory](#conduct-a-component-inventory) for more details. +* **Ingest component compatibility**: Confirm that your ingest components, such as {{beats}}, {{ls}}, or {{agent}}, are compatible with the target {{es}} version. If they’re not, upgrade them first. Refer to [conduct a component inventory](#conduct-a-component-inventory) for guidance. -* Orchestrator compatibility: If your orchestrator is not compatible with the {{stack}} version you’re upgrading to, you need to [upgrade the orchestrator](/deploy-manage/upgrade/orchestrator.md) before upgrading your cluster. Compatibility details are available in: - * [ECE - stack packs](/deploy-manage/deploy/cloud-enterprise/manage-elastic-stack-versions.md#ece_most_recent_elastic_stack_packs) - * [ECK - {{stack}} compatibility](/deploy-manage/deploy/cloud-on-k8s.md#stack-compatibility) +* **Orchestrator compatibility**: If you’re using an orchestrator like {{ece}} or {{eck}}, verify that it supports the target {{stack}} version. If not, [upgrade the orchestrator](/deploy-manage/upgrade/orchestrator.md) before upgrading your cluster. Refer to: + * [ECE – Stack packs](/deploy-manage/deploy/cloud-enterprise/manage-elastic-stack-versions.md#ece_most_recent_elastic_stack_packs) + * [ECK – {{stack}} compatibility](/deploy-manage/deploy/cloud-on-k8s.md#stack-compatibility) -* Developed clients compatibility: Check any client library you are using and ensure it is compatible with the version you’re upgrading to for {{es}}. Refer to [{{es}} clients](/reference/elasticsearch-clients/index.md) and [upgrade paths](../upgrade.md#upgrade-paths) for more information. +* **Rest API compatibility**: If you use custom-developed applications or clients, ensure the [{{es}} client libraries](/reference/elasticsearch-clients/index.md) are compatible with the target version. If your applications use deprecated or removed APIs, you may need to update the client code first. -* {{es}} version compatibility: Check [upgrade paths](../upgrade.md#upgrade-paths) description to ensure you can upgrade directly to the version you are aiming to upgrade to. + ::::{note} + By default, 8.x {{es}} clients are compatible with 9.x and use [`REST API compatibility`](elasticsearch://reference/elasticsearch/rest-apis/compatibility.md) to maintain compatibility with the 9.x {{es}} cluster. -Examples of situations where you need to adapt your upgrade path: + `REST API compatibility` is a per-request opt-in feature that can help REST clients mitigate non-compatible (breaking) changes to the REST API. + :::: -* Some of your ingest components are not compatible with the version you are aiming to upgrade to, and they need to be upgraded first to a compatible version. -* Your orchestrator (ECE or ECK) or operating system is not compatible with the version you are aiming to upgrade to, and it needs to be upgraded first to a compatible version. -* Your running {{es}} version cannot be upgraded directly to the version you are aiming to upgrade to, and it needs to be upgraded first to an intermediate version. -* Due to some breaking changes, your developed clients are using {{es}} APIs that are not compatible with the version you are aiming to upgrade to, and they need to be adapted first. +* **{{es}} upgrade path**: Check the [upgrade paths](../upgrade.md#upgrade-paths) to determine whether you must upgrade through an intermediate version (such as 8.19.x before moving to 9.x), or if you can upgrade directly to the target version. -### OpenJDK compatibility and FIPS compliance +* **OpenJDK compatibility and FIPS compliance**: By default, {{es}} is built using Java and includes a bundled version of [OpenJDK](https://openjdk.java.net/) within each distribution. While we strongly recommend using the bundled Java Virtual Machine (JVM) in all installations of {{es}}, if you choose to use your own JVM, ensure it’s compatible by reviewing the [Product and JVM support matrix](https://www.elastic.co/support/matrix#matrix_jvm). -By default, {{es}} is built using Java and includes a bundled version of [OpenJDK](https://openjdk.java.net/) within each distribution. While we strongly recommend using the bundled Java Virtual Machine (JVM) in all installations of {{es}}, if you choose to use your own JVM, ensure it’s compatible by reviewing the [Product and JVM support matrix](https://www.elastic.co/support/matrix#matrix_jvm). - -If you’re running {{es}} in FIPS 140-2 mode, we recommend using [Bouncy Castle](https://www.bouncycastle.org/java.html) as a Java security provider when running {{es}}. - -### Rest API compatibility - -[REST API compatibility](elasticsearch://reference/elasticsearch/rest-apis/compatibility.md) is a per-request opt-in feature that can help REST clients mitigate non-compatible (breaking) changes to the REST API. + If you’re running {{es}} in FIPS 140-2 mode, we recommend using [Bouncy Castle](https://www.bouncycastle.org/java.html) as a Java security provider when running {{es}}. ## Conduct a component inventory @@ -114,12 +107,14 @@ If all components are compatible with the target version of {{es}}, we recommend 4. Ingest tools (Beats, Elastic Agent, Logstash, etc.) and {{es}} client libraries ::::{note} -If you use a separate [monitoring cluster](/deploy-manage/monitor/stack-monitoring/elasticsearch-monitoring-self-managed.md), upgrade the monitoring cluster before the production cluster. The monitoring cluster and the clusters being monitored should be running the same version of the {{stack}}. Monitoring clusters 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 [monitoring cluster](/deploy-manage/monitor/stack-monitoring/elasticsearch-monitoring-self-managed.md), upgrade the monitoring cluster before the production cluster. + +The monitoring cluster should be running the same version, or a newer one, than the clusters being monitored. It cannot monitor clusters running a newer version of the {{stack}}. If necessary, the monitoring cluster can monitor clusters running the latest release of the previous major version. :::: ## Example of an upgrade plan -Let's assume you are running all {{stack}} components in version 8.14 and your main goal is to upgrade {{es}} and {{kib}} to the latest {{stack-version}}, without requiring to upgrade the ingest components (Beats, Elastic Agent, and Logstash) except when required by the upgrade path. +Let's assume you are running all {{stack}} components in version 8.14 and your main goal is to upgrade {{es}} and {{kib}} to the latest {{stack-version}}, without requiring to upgrade the ingest components (Beats, Elastic Agent, and Logstash) except when required by the [upgrade paths](../upgrade.md#upgrade-paths). The minimum steps your plan should include are: diff --git a/deploy-manage/upgrade/prepare-to-upgrade.md b/deploy-manage/upgrade/prepare-to-upgrade.md index 6609ec3e79..13fdc7b7b1 100644 --- a/deploy-manage/upgrade/prepare-to-upgrade.md +++ b/deploy-manage/upgrade/prepare-to-upgrade.md @@ -63,7 +63,9 @@ The following steps are common to all types of upgrades, regardless if you are u 5. **Upgrade your monitoring cluster first** - If you use a separate [monitoring cluster](/deploy-manage/monitor/stack-monitoring/elasticsearch-monitoring-self-managed.md), upgrade the monitoring cluster before the production cluster. The monitoring cluster and the clusters being monitored should be running the same version of the {{stack}}. Monitoring clusters 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 [monitoring cluster](/deploy-manage/monitor/stack-monitoring/elasticsearch-monitoring-self-managed.md), upgrade the monitoring cluster before the production cluster. + + The monitoring cluster should be running the same version, or a newer one, than the clusters being monitored. It cannot monitor clusters running a newer version of the {{stack}}. If necessary, the monitoring cluster can monitor clusters running the latest release of the previous major version. 6. **Remote clusters** From a16512791b3a6f22a70c4bc04de33c07e7cf4395 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Mon, 28 Jul 2025 20:42:51 +0200 Subject: [PATCH 06/30] index compatibility and archive statemens improved --- deploy-manage/upgrade/plan-upgrade.md | 2 ++ deploy-manage/upgrade/prepare-to-upgrade.md | 26 ++++++++++++--------- 2 files changed, 17 insertions(+), 11 deletions(-) diff --git a/deploy-manage/upgrade/plan-upgrade.md b/deploy-manage/upgrade/plan-upgrade.md index 8d7d358a10..4bc9604b32 100644 --- a/deploy-manage/upgrade/plan-upgrade.md +++ b/deploy-manage/upgrade/plan-upgrade.md @@ -38,6 +38,8 @@ Before upgrading, verify that your current environment supports the version you `REST API compatibility` is a per-request opt-in feature that can help REST clients mitigate non-compatible (breaking) changes to the REST API. :::: +* **Index compatibility**: {{es}} provides full query and write support for indices created in the previous major version. If you have indices created in 7.x or earlier, you must reindex, delete, or [mark them as read-only](/deploy-manage/upgrade/deployment-or-cluster/reading-indices-from-older-elasticsearch-versions.md) before upgrading to 9.x. This topic is covered during the [upgrade preparations](prepare-to-upgrade.md#prepare-to-upgrade-from-8.x), with help from the Upgrade Assistant. + * **{{es}} upgrade path**: Check the [upgrade paths](../upgrade.md#upgrade-paths) to determine whether you must upgrade through an intermediate version (such as 8.19.x before moving to 9.x), or if you can upgrade directly to the target version. * **OpenJDK compatibility and FIPS compliance**: By default, {{es}} is built using Java and includes a bundled version of [OpenJDK](https://openjdk.java.net/) within each distribution. While we strongly recommend using the bundled Java Virtual Machine (JVM) in all installations of {{es}}, if you choose to use your own JVM, ensure it’s compatible by reviewing the [Product and JVM support matrix](https://www.elastic.co/support/matrix#matrix_jvm). diff --git a/deploy-manage/upgrade/prepare-to-upgrade.md b/deploy-manage/upgrade/prepare-to-upgrade.md index 13fdc7b7b1..ed9d2ab531 100644 --- a/deploy-manage/upgrade/prepare-to-upgrade.md +++ b/deploy-manage/upgrade/prepare-to-upgrade.md @@ -81,10 +81,7 @@ The following steps are common to all types of upgrades, regardless if you are u ## Additional preparation steps to upgrade from 8.x [prepare-upgrade-from-8.x] -Major upgrades require additional planning and preparation, as they often introduce a significant number of breaking changes and require additional steps to ensure a smooth transition. The main challenges when preparing for a major version upgrade include: - -* Reindexing any indices created before 8.0.0, including those used by {{ml}} and transform jobs. -* Identifying and applying changes needed to accommodate breaking changes. +Major upgrades require additional planning and preparation, as they often introduce a significant number of breaking changes and require additional steps to ensure a smooth transition. To assist with this process, use the [Upgrade Assistant](prepare-to-upgrade/upgrade-assistant.md), which helps detect deprecated settings, highlights upgrade blockers, and guides you through the required actions. @@ -108,6 +105,7 @@ Follow these steps to prepare for a successful major upgrade from 8.x to 9.x: :::{note} For flexible upgrade scheduling, 8.19.x {{beats}} and {{ls}} are compatible with 9.x {{es}}. + By default, 8.x {{es}} clients are compatible with 9.x and use [REST API compatibility](elasticsearch://reference/elasticsearch/rest-apis/compatibility.md) to maintain compatibility with the 9.x {{es}} server. ::: @@ -121,20 +119,26 @@ Follow these steps to prepare for a successful major upgrade from 8.x to 9.x: Considerations when using the upgrade assistant: - 1. Before you change configurations or reindex, ensure you have a current [snapshot](/deploy-manage/tools/snapshot-and-restore/create-snapshots.md). + 1. For a successful upgrade, **resolve all critical issues reported by the assistant**. - :::{tip} - In 8.3.0 and later, snapshots are generally available as simple archives. You can use the [archive functionality](/deploy-manage/upgrade/deployment-or-cluster/reading-indices-from-older-elasticsearch-versions.md) to search snapshots from 5.0.0 and later without needing an old {{es}} cluster. This ensures that your {{es}} data remains accessible after upgrading, without requiring a reindex process. - ::: + 2. Before you apply configuration changes or reindex, ensure you have a current [snapshot](/deploy-manage/tools/snapshot-and-restore/create-snapshots.md). + + 3. Indices created in 7.x or earlier must be reindexed or deleted before upgrading to 9.x. Alternatively, you can use the [archive functionality](/deploy-manage/upgrade/deployment-or-cluster/reading-indices-from-older-elasticsearch-versions.md) to enable read-only access to them in 9.x. Keep in mind that {{es}} nodes will fail to start if incompatible indices are present. + + ::::{tip} + In Elasticsearch 9.x, you can use the [archive functionality](/deploy-manage/upgrade/deployment-or-cluster/reading-indices-from-older-elasticsearch-versions.md) to access snapshots of 7.x or earlier indices, without needing to reindex or run an older cluster. This provides a convenient option to retain historical data in case you choose to delete those indices and keep them only in existing snapshots. + :::: - 2. For a successful upgrade, resolve all critical issues reported by the assistant. If you make additional changes, create a snapshot to back up your data. + 3. Review the deprecation logs from the Upgrade Assistant to determine if your applications are using features that are not supported or behave differently in 9.x. See the [breaking changes](/release-notes/breaking-changes.md) for more information about changes in 9.x that could affect your application. - 3. To identify if your applications use unsupported features or behave differently in 9.x, review the deprecation logs in the Upgrade Assistant. + ::::{note} + Make sure you check the breaking changes for each 9.x release up to your target release. + :::: 4. Make the recommended changes to ensure your clients continue operating as expected after the upgrade. :::{note} - As a temporary solution, use the 8.x syntax to submit requests to 9.x with REST API compatibility mode. While this allows you to submit requests using the old syntax, it doesn’t guarantee the same behavior. REST API compatibility should serve as a bridge during the upgrade, not a long-term solution. For more details on how to effectively use REST API compatibility during an upgrade, refer to [REST API compatibility](elasticsearch://reference/elasticsearch/rest-apis/compatibility.md). + As a temporary solution, use the 8.x syntax to submit requests to 9.x with REST API compatibility mode. While this allows you to submit requests using the old syntax, it doesn’t guarantee the same behavior. REST API compatibility should serve as a bridge during the upgrade, not a long-term solution. For more details on how to effectively use REST API compatibility during an upgrade, refer to [REST API compatibility](elasticsearch://reference/elasticsearch/rest-apis/compatibility.md). ::: 3. **{{ccr-cap}} (CCR)** From 3cdd2b90a467833fa3a37376a2fa12e4e86cbb20 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Mon, 28 Jul 2025 21:03:34 +0200 Subject: [PATCH 07/30] fixing links --- deploy-manage/upgrade/plan-upgrade.md | 2 +- deploy-manage/upgrade/prepare-to-upgrade.md | 4 +++- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/deploy-manage/upgrade/plan-upgrade.md b/deploy-manage/upgrade/plan-upgrade.md index 4bc9604b32..188ee7337a 100644 --- a/deploy-manage/upgrade/plan-upgrade.md +++ b/deploy-manage/upgrade/plan-upgrade.md @@ -38,7 +38,7 @@ Before upgrading, verify that your current environment supports the version you `REST API compatibility` is a per-request opt-in feature that can help REST clients mitigate non-compatible (breaking) changes to the REST API. :::: -* **Index compatibility**: {{es}} provides full query and write support for indices created in the previous major version. If you have indices created in 7.x or earlier, you must reindex, delete, or [mark them as read-only](/deploy-manage/upgrade/deployment-or-cluster/reading-indices-from-older-elasticsearch-versions.md) before upgrading to 9.x. This topic is covered during the [upgrade preparations](prepare-to-upgrade.md#prepare-to-upgrade-from-8.x), with help from the Upgrade Assistant. +* **Index compatibility**: {{es}} provides full query and write support for indices created in the previous major version. If you have indices created in 7.x or earlier, you must reindex, delete, or [mark them as read-only](/deploy-manage/upgrade/deployment-or-cluster/reading-indices-from-older-elasticsearch-versions.md) before upgrading to 9.x. This topic is covered during the [upgrade preparations](prepare-to-upgrade.md#prepare-upgrade-from-8.x), with help from the Upgrade Assistant. * **{{es}} upgrade path**: Check the [upgrade paths](../upgrade.md#upgrade-paths) to determine whether you must upgrade through an intermediate version (such as 8.19.x before moving to 9.x), or if you can upgrade directly to the target version. diff --git a/deploy-manage/upgrade/prepare-to-upgrade.md b/deploy-manage/upgrade/prepare-to-upgrade.md index ed9d2ab531..6f5bb7cf97 100644 --- a/deploy-manage/upgrade/prepare-to-upgrade.md +++ b/deploy-manage/upgrade/prepare-to-upgrade.md @@ -7,6 +7,8 @@ applies_to: ess: ece: self: +products: + - id: elasticsearch --- # Prepare to upgrade @@ -129,7 +131,7 @@ Follow these steps to prepare for a successful major upgrade from 8.x to 9.x: In Elasticsearch 9.x, you can use the [archive functionality](/deploy-manage/upgrade/deployment-or-cluster/reading-indices-from-older-elasticsearch-versions.md) to access snapshots of 7.x or earlier indices, without needing to reindex or run an older cluster. This provides a convenient option to retain historical data in case you choose to delete those indices and keep them only in existing snapshots. :::: - 3. Review the deprecation logs from the Upgrade Assistant to determine if your applications are using features that are not supported or behave differently in 9.x. See the [breaking changes](/release-notes/breaking-changes.md) for more information about changes in 9.x that could affect your application. + 3. Review the deprecation logs from the Upgrade Assistant to determine if your applications are using features that are not supported or behave differently in 9.x. See the [breaking changes](elasticsearch://release-notes/breaking-changes.md) for more information about changes in 9.x that could affect your application. ::::{note} Make sure you check the breaking changes for each 9.x release up to your target release. From 37eb35af4b93dc231101a345e16195eb44ce1832 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Mon, 28 Jul 2025 21:23:10 +0200 Subject: [PATCH 08/30] positioning prepare upgrade doc --- deploy-manage/upgrade/prepare-to-upgrade.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/deploy-manage/upgrade/prepare-to-upgrade.md b/deploy-manage/upgrade/prepare-to-upgrade.md index 6f5bb7cf97..6068565837 100644 --- a/deploy-manage/upgrade/prepare-to-upgrade.md +++ b/deploy-manage/upgrade/prepare-to-upgrade.md @@ -18,7 +18,7 @@ When upgrading an existing cluster, you perform a major, minor, or patch upgrade Upgrading from a release candidate build, such as 9.0.0-rc1, is unsupported. Use pre-releases only for testing in a temporary environment. ::: -This document describes the preparation steps for upgrading {{es}}, which vary by version and type of upgrade. +This document describes the preparation steps for upgrading {{es}}, which vary depending on the type of upgrade. These steps follow the [upgrade planning](./plan-upgrade.md) and should be completed before proceeding to [upgrade your deployment or cluster](./deployment-or-cluster.md). ## Common preparation steps for all upgrades @@ -813,3 +813,7 @@ If the destination index is no longer needed, it can be deleted with the transfo DELETE _transform/my-transform?delete_dest_index ``` ::: + +## Next steps + +After completing all the preparation steps, you're ready to [upgrade your deployment or cluster](./deployment-or-cluster.md). From 76261c94b3a6f89a46e0f2c3e1b670f0210f4cec Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Mon, 28 Jul 2025 21:46:47 +0200 Subject: [PATCH 09/30] upgrade order small update --- deploy-manage/upgrade/plan-upgrade.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/deploy-manage/upgrade/plan-upgrade.md b/deploy-manage/upgrade/plan-upgrade.md index 188ee7337a..22d96a10c2 100644 --- a/deploy-manage/upgrade/plan-upgrade.md +++ b/deploy-manage/upgrade/plan-upgrade.md @@ -101,13 +101,15 @@ We highly recommend testing the upgrade process in a non-production environment When upgrading the {{stack}}, the process begins with {{es}}, followed by {{kib}}, which must always be aligned in terms of versioning. Other components can remain on earlier versions as long as they are compatible with the target {{es}} version, though we recommend upgrading them as well to benefit from the latest features and fixes. -If all components are compatible with the target version of {{es}}, we recommend upgrading them in the following order: +In general, you should upgrade the components of your {{stack}} in the following order: 1. {{es}} 2. {{kib}} (must be kept aligned with the {{es}} version) 3. Fleet Server and APM Server (if used) 4. Ingest tools (Beats, Elastic Agent, Logstash, etc.) and {{es}} client libraries +If your deployment runs on {{ech}} or {{ece}}, the platform handles the upgrade and component order automatically in a single plan execution. You only need to upgrade any external ingest tools afterward. + ::::{note} If you use a separate [monitoring cluster](/deploy-manage/monitor/stack-monitoring/elasticsearch-monitoring-self-managed.md), upgrade the monitoring cluster before the production cluster. From d2f595400e2f18863a0ea19f419efa9dd492c9c1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Mon, 28 Jul 2025 21:56:28 +0200 Subject: [PATCH 10/30] next steps added in upgrade cluster --- deploy-manage/upgrade/deployment-or-cluster.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/deploy-manage/upgrade/deployment-or-cluster.md b/deploy-manage/upgrade/deployment-or-cluster.md index 2ba9af0f92..c9016134ea 100644 --- a/deploy-manage/upgrade/deployment-or-cluster.md +++ b/deploy-manage/upgrade/deployment-or-cluster.md @@ -60,3 +60,7 @@ If you’re using self-managed infrastructure - either on-prem or public cloud - ::::{note} With [{{serverless-full}}](/deploy-manage/deploy/elastic-cloud/serverless.md), upgrades are fully managed by Elastic. Users automatically receive the latest features and improvements, with no need to plan or perform upgrade steps. :::: + +## Next steps + +Once you've successfully upgraded your deployment, you can [upgrade your ingest components](./ingest-components.md), such as {{ls}}, {{agent}}, or {{beats}}. \ No newline at end of file From 57bea11380e2c5a3bfe41f1c3885696197770d2d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Mon, 28 Jul 2025 21:59:08 +0200 Subject: [PATCH 11/30] APM server updated to Elastic APM --- deploy-manage/upgrade/plan-upgrade.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/deploy-manage/upgrade/plan-upgrade.md b/deploy-manage/upgrade/plan-upgrade.md index 22d96a10c2..ef1dce008a 100644 --- a/deploy-manage/upgrade/plan-upgrade.md +++ b/deploy-manage/upgrade/plan-upgrade.md @@ -105,7 +105,7 @@ In general, you should upgrade the components of your {{stack}} in the following 1. {{es}} 2. {{kib}} (must be kept aligned with the {{es}} version) -3. Fleet Server and APM Server (if used) +3. Fleet Server and Elastic APM (if used) 4. Ingest tools (Beats, Elastic Agent, Logstash, etc.) and {{es}} client libraries If your deployment runs on {{ech}} or {{ece}}, the platform handles the upgrade and component order automatically in a single plan execution. You only need to upgrade any external ingest tools afterward. From 76a87238f81c1dc6c0c18484cb85a8942321169b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Mon, 28 Jul 2025 22:21:23 +0200 Subject: [PATCH 12/30] 8.18 statement updated --- deploy-manage/upgrade/prepare-to-upgrade.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/deploy-manage/upgrade/prepare-to-upgrade.md b/deploy-manage/upgrade/prepare-to-upgrade.md index 6068565837..64a3d3b3ac 100644 --- a/deploy-manage/upgrade/prepare-to-upgrade.md +++ b/deploy-manage/upgrade/prepare-to-upgrade.md @@ -94,7 +94,7 @@ Follow these steps to prepare for a successful major upgrade from 8.x to 9.x: To perform a major upgrade from 8.x to 9.x of {{es}}, you must first upgrade to 8.19.x. This allows you to use the [Upgrade Assistant](prepare-to-upgrade/upgrade-assistant.md) to identify and resolve issues, reindex indices created before 8.0.0, and prepare the cluster for the actual upgrade. Upgrading to 8.19 is required even if you choose a full {{es}} cluster restart to upgrade. ::::{note} - Because 8.18.0 and 9.0.0 were released at the same time, upgrading from 8.18.x to 9.0.x is also supported, as long it follows the supported [upgrade paths](../upgrade.md#upgrade-paths). However, upgrading to 9.1.0 or later requires starting from 8.19.x. + Because 8.18.0 and 9.0.0 were released simultaneously, upgrading from 8.18.x to 9.0.x is supported, as long as the versions comply with the supported [upgrade paths](../upgrade.md#upgrade-paths). However, upgrading to 9.1.0 or later requires starting from 8.19.x. As an example, these are valid upgrade paths to {{stack-version}}: * Versions prior to 8.18 → 8.19.x → {{stack-version}} *(recommended)* From 67b4fa11c8099e2f556fb3be2b014744ceb5887f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Tue, 29 Jul 2025 11:28:15 +0200 Subject: [PATCH 13/30] upgrade paths updated --- deploy-manage/upgrade.md | 26 ++++++++++++++++++++------ 1 file changed, 20 insertions(+), 6 deletions(-) diff --git a/deploy-manage/upgrade.md b/deploy-manage/upgrade.md index e5063ffcb9..2b77c10f0f 100644 --- a/deploy-manage/upgrade.md +++ b/deploy-manage/upgrade.md @@ -49,18 +49,32 @@ Additionally, if you're using a self-managed orchestration platform such as {{ec You can upgrade to a higher version if the target version was released *after* your current version. Upgrades to versions released *before* your current version are not supported, even if the version number is higher. Refer to [out-of-order releases](/deploy-manage/upgrade/deployment-or-cluster.md#out-of-order-releases) for more information. -% Uncomment these examples when 9.1.1 and 9.0.5 are released. We currently don't have enough 9.x versions for meaningful examples. - +### Upgrade paths from 8.x [upgrade-paths-8.x] + +To perform a major upgrade from 8.x, the required starting version depends on the target release: + +- To upgrade to the **9.0.x series**, you must be on **8.18.x**. +- To upgrade to **9.1.0 or later**, you must be on **8.19.x**, which is the latest minor release of the 8.x series. + ::::{note} -Major upgrades must be performed from the latest minor version of the previous major. For example, to upgrade to {{stack-version}}, you need to be on 8.19 first. +While 8.19 is the final minor release in the 8.x series, 8.18 was released at the same time as 9.0, enabling a supported upgrade path between the 8.18.x and 9.0.x series. This compatibility also applies to other features and clients. +:::: + +The following upgrade paths from 8.x are valid for reaching the latest {{stack-version}} release: + +* Versions prior to 8.18 → 8.19.x → {{stack-version}} *(recommended)* +* Versions prior to 8.18 → 8.18.x → 9.0.x → {{stack-version}} + +#### Ingest tools and clients considerations For flexible upgrade scheduling, 8.19 {{agent}}, {{beats}}, and {{ls}} are compatible with 9.x {{es}}. -By default, 8.x {{es}} clients are compatible with 9.x and use [REST API compatibility](elasticsearch://reference/elasticsearch/rest-apis/compatibility.md) to maintain compatibility with the 9.x {{es}} cluster. -:::: \ No newline at end of file +By default, 8.x {{es}} clients are compatible with 9.x and use [REST API compatibility](elasticsearch://reference/elasticsearch/rest-apis/compatibility.md) to maintain compatibility with the 9.x cluster. From b204fdc767994227c765a31dd22d5560ad788b10 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Tue, 29 Jul 2025 11:37:36 +0200 Subject: [PATCH 14/30] prepare upgrade minor change --- deploy-manage/upgrade/prepare-to-upgrade.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/deploy-manage/upgrade/prepare-to-upgrade.md b/deploy-manage/upgrade/prepare-to-upgrade.md index 64a3d3b3ac..ce17f9e023 100644 --- a/deploy-manage/upgrade/prepare-to-upgrade.md +++ b/deploy-manage/upgrade/prepare-to-upgrade.md @@ -91,7 +91,7 @@ Follow these steps to prepare for a successful major upgrade from 8.x to 9.x: 1. **Upgrade to the latest 8.19 patch release** - To perform a major upgrade from 8.x to 9.x of {{es}}, you must first upgrade to 8.19.x. This allows you to use the [Upgrade Assistant](prepare-to-upgrade/upgrade-assistant.md) to identify and resolve issues, reindex indices created before 8.0.0, and prepare the cluster for the actual upgrade. Upgrading to 8.19 is required even if you choose a full {{es}} cluster restart to upgrade. + To perform a major upgrade from 8.x to 9.x of {{es}}, you must first upgrade to 8.19.x. This allows you to use the [Upgrade Assistant](prepare-to-upgrade/upgrade-assistant.md) to identify and resolve issues, reindex indices created before 8.0.0, and prepare the cluster for the actual upgrade. Upgrading to 8.19 is required regardless of whether you perform a rolling upgrade or a full cluster restart to upgrade. ::::{note} Because 8.18.0 and 9.0.0 were released simultaneously, upgrading from 8.18.x to 9.0.x is supported, as long as the versions comply with the supported [upgrade paths](../upgrade.md#upgrade-paths). However, upgrading to 9.1.0 or later requires starting from 8.19.x. @@ -103,7 +103,7 @@ Follow these steps to prepare for a successful major upgrade from 8.x to 9.x: If you are already running an 8.19.x version, it's also recommended to upgrade to the latest 8.19 patch release before upgrading to 9.x. This ensures that the latest version of the upgrade assistant is used, and any bug fixes that could have implications for the upgrade are applied. - If you're using 7.x and earlier, you may need to complete multiple upgrades or perform a full-cluster restart to reach the latest 8.19 patch release before upgrading to 9.x. As an alternative method to upgrading the cluster, you can create a new 9.x deployment and reindex from the original cluster. For more information, refer to [Reindex to upgrade](#reindex-to-upgrade). + If you're using 7.x and earlier, you may need to complete multiple upgrades to reach the latest 8.19 patch release before upgrading to 9.x. As an alternative method to upgrading the cluster, you can create a new 9.x deployment and reindex from the original cluster. For more information, refer to [Reindex to upgrade](#reindex-to-upgrade). :::{note} For flexible upgrade scheduling, 8.19.x {{beats}} and {{ls}} are compatible with 9.x {{es}}. From 4860f91cb103c1f5fd2c5302f42587b32d54216c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Tue, 29 Jul 2025 11:52:40 +0200 Subject: [PATCH 15/30] version.stack used --- deploy-manage/upgrade.md | 6 +++--- deploy-manage/upgrade/deployment-or-cluster.md | 8 ++++---- .../upgrade/deployment-or-cluster/upgrade-on-eck.md | 8 ++++---- deploy-manage/upgrade/plan-upgrade.md | 8 ++++---- deploy-manage/upgrade/prepare-to-upgrade.md | 10 +++++----- docset.yml | 1 - 6 files changed, 20 insertions(+), 21 deletions(-) diff --git a/deploy-manage/upgrade.md b/deploy-manage/upgrade.md index 2b77c10f0f..57b8ff5658 100644 --- a/deploy-manage/upgrade.md +++ b/deploy-manage/upgrade.md @@ -68,10 +68,10 @@ To perform a major upgrade from 8.x, the required starting version depends on th While 8.19 is the final minor release in the 8.x series, 8.18 was released at the same time as 9.0, enabling a supported upgrade path between the 8.18.x and 9.0.x series. This compatibility also applies to other features and clients. :::: -The following upgrade paths from 8.x are valid for reaching the latest {{stack-version}} release: +The following upgrade paths from 8.x are valid for reaching the latest {{version.stack}} release: -* Versions prior to 8.18 → 8.19.x → {{stack-version}} *(recommended)* -* Versions prior to 8.18 → 8.18.x → 9.0.x → {{stack-version}} +* Versions prior to 8.18 → 8.19.x → {{version.stack}} *(recommended)* +* Versions prior to 8.18 → 8.18.x → 9.0.x → {{version.stack}} #### Ingest tools and clients considerations diff --git a/deploy-manage/upgrade/deployment-or-cluster.md b/deploy-manage/upgrade/deployment-or-cluster.md index c9016134ea..e9a92fba0c 100644 --- a/deploy-manage/upgrade/deployment-or-cluster.md +++ b/deploy-manage/upgrade/deployment-or-cluster.md @@ -36,12 +36,12 @@ Before proceeding with the upgrade, review the [Plan your upgrade](/deploy-manag ## Out-of-order releases [out-of-order-releases] -Elastic maintains several minor versions of Elasticsearch at once. This means releases do not always happen in order of their version numbers. You can only upgrade to {{stack-version}} if the version you are currently running meets both of these conditions: +Elastic maintains several minor versions of Elasticsearch at once. This means releases do not always happen in order of their version numbers. You can only upgrade to {{version.stack}} if the version you are currently running meets both of these conditions: -* Has an older version number than {{stack-version}} -* Has an earlier release date than {{stack-version}} +* Has an older version number than {{version.stack}} +* Has an earlier release date than {{version.stack}} -If you are currently running a version with an older version number but a later release date than {{stack-version}}, wait for a newer release before upgrading. +If you are currently running a version with an older version number but a later release date than {{version.stack}}, wait for a newer release before upgrading. Additionally, upgrading from a release candidate build, such as 9.0.0-rc1, is unsupported. Use pre-releases only for testing in a temporary environment. diff --git a/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-eck.md b/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-eck.md index 40458050d6..eaa13ed460 100644 --- a/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-eck.md +++ b/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-eck.md @@ -10,14 +10,14 @@ applies_to: The ECK orchestrator can safely perform upgrades to newer versions of the {{stack}}. -Once you're [prepared to upgrade](/deploy-manage/upgrade/prepare-to-upgrade.md), ensure the ECK version is [compatible](/deploy-manage/deploy/cloud-on-k8s.md#stack-compatibility) with the {{stack}} version you’re upgrading to. For example, if you're upgrading to {{stack-version}}, the minimum required ECK version is 3.0.0. If it's incompatible, [upgrade your orchestrator](/deploy-manage/upgrade/orchestrator/upgrade-cloud-on-k8s.md). +Once you're [prepared to upgrade](/deploy-manage/upgrade/prepare-to-upgrade.md), ensure the ECK version is [compatible](/deploy-manage/deploy/cloud-on-k8s.md#stack-compatibility) with the {{stack}} version you’re upgrading to. For example, if you're upgrading to {{version.stack}}, the minimum required ECK version is 3.0.0. If it's incompatible, [upgrade your orchestrator](/deploy-manage/upgrade/orchestrator/upgrade-cloud-on-k8s.md). ## Perform the upgrade 1. In the resource spec file, modify the `version` field for the desired {{stack}} version. 2. Save your changes. The orchestrator will start the upgrade process automatically. -In this example, we’re modifying the version to `{{stack-version}}`. +In this example, we’re modifying the version to `{{version.stack}}`. ```yaml subs=true apiVersion: elasticsearch.k8s.elastic.co/v1 @@ -26,7 +26,7 @@ metadata: name: elasticsearch-sample namespace: production spec: - version: {{stack-version}} + version: {{version.stack}} monitoring: metrics: elasticsearchRefs: @@ -117,7 +117,7 @@ metadata: name: kibana-sample namespace: production spec: - version: {{stack-version}} + version: {{version.stack}} monitoring: metrics: elasticsearchRefs: diff --git a/deploy-manage/upgrade/plan-upgrade.md b/deploy-manage/upgrade/plan-upgrade.md index ef1dce008a..9ce9f45342 100644 --- a/deploy-manage/upgrade/plan-upgrade.md +++ b/deploy-manage/upgrade/plan-upgrade.md @@ -118,13 +118,13 @@ The monitoring cluster should be running the same version, or a newer one, than ## Example of an upgrade plan -Let's assume you are running all {{stack}} components in version 8.14 and your main goal is to upgrade {{es}} and {{kib}} to the latest {{stack-version}}, without requiring to upgrade the ingest components (Beats, Elastic Agent, and Logstash) except when required by the [upgrade paths](../upgrade.md#upgrade-paths). +Let's assume you are running all {{stack}} components in version 8.14 and your main goal is to upgrade {{es}} and {{kib}} to the latest {{version.stack}}, without requiring to upgrade the ingest components (Beats, Elastic Agent, and Logstash) except when required by the [upgrade paths](../upgrade.md#upgrade-paths). The minimum steps your plan should include are: -1. Upgrade {{es}} and {{kib}} to the latest 8.19 version, as a requirement for the major upgrade to {{stack-version}}. -2. Upgrade all ingest components to the latest 8.19 version, as otherwise they won't be compatible with {{es}} running {{stack-version}}. -3. Upgrade {{es}} and {{kib}} to {{stack-version}}. +1. Upgrade {{es}} and {{kib}} to the latest 8.19 version, as a requirement for the major upgrade to {{version.stack}}. +2. Upgrade all ingest components to the latest 8.19 version, as otherwise they won't be compatible with {{es}} running {{version.stack}}. +3. Upgrade {{es}} and {{kib}} to {{version.stack}}. ## Next steps diff --git a/deploy-manage/upgrade/prepare-to-upgrade.md b/deploy-manage/upgrade/prepare-to-upgrade.md index ce17f9e023..e411e41b02 100644 --- a/deploy-manage/upgrade/prepare-to-upgrade.md +++ b/deploy-manage/upgrade/prepare-to-upgrade.md @@ -96,9 +96,9 @@ Follow these steps to prepare for a successful major upgrade from 8.x to 9.x: ::::{note} Because 8.18.0 and 9.0.0 were released simultaneously, upgrading from 8.18.x to 9.0.x is supported, as long as the versions comply with the supported [upgrade paths](../upgrade.md#upgrade-paths). However, upgrading to 9.1.0 or later requires starting from 8.19.x. - As an example, these are valid upgrade paths to {{stack-version}}: - * Versions prior to 8.18 → 8.19.x → {{stack-version}} *(recommended)* - * Versions prior to 8.18 → 8.18.x → 9.0.x → {{stack-version}} + As an example, these are valid upgrade paths to {{version.stack}}: + * Versions prior to 8.18 → 8.19.x → {{version.stack}} *(recommended)* + * Versions prior to 8.18 → 8.18.x → 9.0.x → {{version.stack}} :::: If you are already running an 8.19.x version, it's also recommended to upgrade to the latest 8.19 patch release before upgrading to 9.x. This ensures that the latest version of the upgrade assistant is used, and any bug fixes that could have implications for the upgrade are applied. @@ -157,9 +157,9 @@ Follow these steps to prepare for a successful major upgrade from 8.x to 9.x: ## Reindex to upgrade [reindex-to-upgrade] -If you are running a pre-8.x version, you might need to perform multiple upgrades before being able to upgrade to 9.x. As an alternative method to upgrading the cluster, you can create a new {{stack-version}} deployment and reindex from remote: +If you are running a pre-8.x version, you might need to perform multiple upgrades before being able to upgrade to 9.x. As an alternative method to upgrading the cluster, you can create a new {{version.stack}} deployment and reindex from remote: -1. Provision an additional deployment running the desired version, such as {{stack-version}}. +1. Provision an additional deployment running the desired version, such as {{version.stack}}. 2. To reindex your data into the new {{es}} cluster, use the [reindex documents API](https://www.elastic.co/docs/api/doc/elasticsearch/v8/operation/operation-reindex) and temporarily send new indexing requests to both clusters. 3. Verify the new cluster performs as expected, fix any problems, and then permanently swap in the new cluster. 4. Delete the old deployment. On {{ecloud}}, you are billed for the time the new deployment runs in parallel with your old deployment. Usage is billed on an hourly basis. diff --git a/docset.yml b/docset.yml index 9ba23096d2..6056ef226a 100644 --- a/docset.yml +++ b/docset.yml @@ -279,7 +279,6 @@ subs: fleet-server-issue: "https://github.com/elastic/fleet-server/issues/" fleet-server-pull: "https://github.com/elastic/fleet-server/pull/" kib-pull: "https://github.com/elastic/kibana/pull/" - stack-version: "9.1.0" eck_helm_minimum_version: "3.2.0" eck_resources_list: "Elasticsearch, Kibana, APM Server, Beats, Elastic Agent, Elastic Maps Server, and Logstash" eck_resources_list_short: "APM Server, Beats, Elastic Agent, Elastic Maps Server, and Logstash" From 9cdf06ed04e323f18298ab36af832025615ca0f5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Tue, 29 Jul 2025 12:28:36 +0200 Subject: [PATCH 16/30] frontmatters reviewed --- deploy-manage/upgrade.md | 6 ++++++ .../upgrade/deployment-or-cluster/archived-settings.md | 7 +++++++ .../upgrade/deployment-or-cluster/elasticsearch.md | 2 ++ .../upgrade/deployment-or-cluster/kibana-roll-back.md | 3 +++ .../reading-indices-from-older-elasticsearch-versions.md | 2 ++ .../upgrade/deployment-or-cluster/self-managed.md | 3 +++ .../upgrade/deployment-or-cluster/upgrade-on-ece.md | 4 ++++ .../upgrade/deployment-or-cluster/upgrade-on-ech.md | 2 ++ .../upgrade/deployment-or-cluster/upgrade-on-eck.md | 4 ++++ deploy-manage/upgrade/orchestrator.md | 3 +++ .../upgrade/orchestrator/re-running-the-ece-upgrade.md | 2 ++ deploy-manage/upgrade/plan-upgrade.md | 6 ++++++ deploy-manage/upgrade/prepare-to-upgrade.md | 4 ++++ .../upgrade/prepare-to-upgrade/upgrade-assistant.md | 3 +++ 14 files changed, 51 insertions(+) diff --git a/deploy-manage/upgrade.md b/deploy-manage/upgrade.md index 57b8ff5658..2f1c1ccb20 100644 --- a/deploy-manage/upgrade.md +++ b/deploy-manage/upgrade.md @@ -6,6 +6,12 @@ applies_to: ess: ece: self: +products: + - id: kibana + - id: cloud-enterprise + - id: cloud-hosted + - id: cloud-kubernetes + - id: elasticsearch --- # Upgrade diff --git a/deploy-manage/upgrade/deployment-or-cluster/archived-settings.md b/deploy-manage/upgrade/deployment-or-cluster/archived-settings.md index 693da00a27..12d49515f7 100644 --- a/deploy-manage/upgrade/deployment-or-cluster/archived-settings.md +++ b/deploy-manage/upgrade/deployment-or-cluster/archived-settings.md @@ -1,6 +1,13 @@ --- mapped_pages: - https://www.elastic.co/guide/en/elasticsearch/reference/current/archived-settings.html +applies_to: + stack: + deployment: + eck: + ess: + ece: + self: products: - id: elasticsearch --- diff --git a/deploy-manage/upgrade/deployment-or-cluster/elasticsearch.md b/deploy-manage/upgrade/deployment-or-cluster/elasticsearch.md index 1ced7be968..230570760e 100644 --- a/deploy-manage/upgrade/deployment-or-cluster/elasticsearch.md +++ b/deploy-manage/upgrade/deployment-or-cluster/elasticsearch.md @@ -3,6 +3,8 @@ applies_to: stack: deployment: self: all +products: + - id: elasticsearch --- # Upgrade {{es}} [upgrading-elasticsearch] diff --git a/deploy-manage/upgrade/deployment-or-cluster/kibana-roll-back.md b/deploy-manage/upgrade/deployment-or-cluster/kibana-roll-back.md index 42e25bf135..944559493d 100644 --- a/deploy-manage/upgrade/deployment-or-cluster/kibana-roll-back.md +++ b/deploy-manage/upgrade/deployment-or-cluster/kibana-roll-back.md @@ -2,6 +2,9 @@ navigation_title: Roll back to a previous version mapped_pages: - https://www.elastic.co/guide/en/kibana/current/upgrade-migrations-rolling-back.html +applies_to: + deployment: + self: all products: - id: kibana --- diff --git a/deploy-manage/upgrade/deployment-or-cluster/reading-indices-from-older-elasticsearch-versions.md b/deploy-manage/upgrade/deployment-or-cluster/reading-indices-from-older-elasticsearch-versions.md index ce92584833..afc9d495d2 100644 --- a/deploy-manage/upgrade/deployment-or-cluster/reading-indices-from-older-elasticsearch-versions.md +++ b/deploy-manage/upgrade/deployment-or-cluster/reading-indices-from-older-elasticsearch-versions.md @@ -6,6 +6,8 @@ applies_to: deployment: ess: self: + eck: + ece: products: - id: elasticsearch --- diff --git a/deploy-manage/upgrade/deployment-or-cluster/self-managed.md b/deploy-manage/upgrade/deployment-or-cluster/self-managed.md index f855f3219d..94d108095b 100644 --- a/deploy-manage/upgrade/deployment-or-cluster/self-managed.md +++ b/deploy-manage/upgrade/deployment-or-cluster/self-managed.md @@ -4,6 +4,9 @@ applies_to: stack: deployment: self: +products: + - id: elasticsearch + - id: kibana --- # Upgrade the {{stack}} on a self-managed cluster diff --git a/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-ece.md b/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-ece.md index 39a695562a..72bd3320bb 100644 --- a/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-ece.md +++ b/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-ece.md @@ -4,6 +4,10 @@ applies_to: stack: deployment: ece: +products: + - id: kibana + - id: cloud-enterprise + - id: elasticsearch --- # Upgrade your deployment on {{ece}} (ECE) diff --git a/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-ech.md b/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-ech.md index d19c5d75fd..dab63a9e07 100644 --- a/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-ech.md +++ b/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-ech.md @@ -10,6 +10,8 @@ applies_to: ess: products: - id: cloud-hosted + - id: elasticsearch + - id: kibana --- # Upgrade on {{ech}} (ECH) diff --git a/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-eck.md b/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-eck.md index eaa13ed460..eae9607190 100644 --- a/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-eck.md +++ b/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-eck.md @@ -4,6 +4,10 @@ applies_to: stack: deployment: eck: +products: + - id: kibana + - id: cloud-kubernetes + - id: elasticsearch --- # Upgrade your deployment on {{eck}} (ECK) diff --git a/deploy-manage/upgrade/orchestrator.md b/deploy-manage/upgrade/orchestrator.md index a3a129a40b..9f5b466442 100644 --- a/deploy-manage/upgrade/orchestrator.md +++ b/deploy-manage/upgrade/orchestrator.md @@ -4,6 +4,9 @@ applies_to: deployment: ece: eck: +products: + - id: cloud-enterprise + - id: cloud-kubernetes --- # Upgrade your orchestrator diff --git a/deploy-manage/upgrade/orchestrator/re-running-the-ece-upgrade.md b/deploy-manage/upgrade/orchestrator/re-running-the-ece-upgrade.md index 8ecf23fa17..416a8d0382 100644 --- a/deploy-manage/upgrade/orchestrator/re-running-the-ece-upgrade.md +++ b/deploy-manage/upgrade/orchestrator/re-running-the-ece-upgrade.md @@ -2,6 +2,8 @@ applies_to: deployment: ece: +products: + - id: cloud-enterprise --- # Re-running the ECE upgrade [re-running-ece-upgrade] diff --git a/deploy-manage/upgrade/plan-upgrade.md b/deploy-manage/upgrade/plan-upgrade.md index 9ce9f45342..e50017b054 100644 --- a/deploy-manage/upgrade/plan-upgrade.md +++ b/deploy-manage/upgrade/plan-upgrade.md @@ -6,6 +6,12 @@ applies_to: ess: ece: self: +products: + - id: kibana + - id: cloud-enterprise + - id: cloud-hosted + - id: cloud-kubernetes + - id: elasticsearch --- # Plan your upgrade diff --git a/deploy-manage/upgrade/prepare-to-upgrade.md b/deploy-manage/upgrade/prepare-to-upgrade.md index e411e41b02..a8ac4ff2a4 100644 --- a/deploy-manage/upgrade/prepare-to-upgrade.md +++ b/deploy-manage/upgrade/prepare-to-upgrade.md @@ -8,6 +8,10 @@ applies_to: ece: self: products: + - id: kibana + - id: cloud-enterprise + - id: cloud-hosted + - id: cloud-kubernetes - id: elasticsearch --- # Prepare to upgrade diff --git a/deploy-manage/upgrade/prepare-to-upgrade/upgrade-assistant.md b/deploy-manage/upgrade/prepare-to-upgrade/upgrade-assistant.md index 2572d6752e..ee92ac9bf4 100644 --- a/deploy-manage/upgrade/prepare-to-upgrade/upgrade-assistant.md +++ b/deploy-manage/upgrade/prepare-to-upgrade/upgrade-assistant.md @@ -10,6 +10,9 @@ applies_to: self: products: - id: kibana + - id: cloud-enterprise + - id: cloud-hosted + - id: cloud-kubernetes - id: elasticsearch --- From c93e12aa7558e7e49876019be9a58ec352316069 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Tue, 29 Jul 2025 12:31:21 +0200 Subject: [PATCH 17/30] archive wording change --- deploy-manage/upgrade/plan-upgrade.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/deploy-manage/upgrade/plan-upgrade.md b/deploy-manage/upgrade/plan-upgrade.md index e50017b054..a23e392584 100644 --- a/deploy-manage/upgrade/plan-upgrade.md +++ b/deploy-manage/upgrade/plan-upgrade.md @@ -44,7 +44,7 @@ Before upgrading, verify that your current environment supports the version you `REST API compatibility` is a per-request opt-in feature that can help REST clients mitigate non-compatible (breaking) changes to the REST API. :::: -* **Index compatibility**: {{es}} provides full query and write support for indices created in the previous major version. If you have indices created in 7.x or earlier, you must reindex, delete, or [mark them as read-only](/deploy-manage/upgrade/deployment-or-cluster/reading-indices-from-older-elasticsearch-versions.md) before upgrading to 9.x. This topic is covered during the [upgrade preparations](prepare-to-upgrade.md#prepare-upgrade-from-8.x), with help from the Upgrade Assistant. +* **Index compatibility**: {{es}} provides full query and write support for indices created in the previous major version. If you have indices created in 7.x or earlier, you must reindex, delete, or [archive](/deploy-manage/upgrade/deployment-or-cluster/reading-indices-from-older-elasticsearch-versions.md) them before upgrading to 9.x. This topic is covered during the [upgrade preparations](prepare-to-upgrade.md#prepare-upgrade-from-8.x), with help from the Upgrade Assistant. * **{{es}} upgrade path**: Check the [upgrade paths](../upgrade.md#upgrade-paths) to determine whether you must upgrade through an intermediate version (such as 8.19.x before moving to 9.x), or if you can upgrade directly to the target version. From 168f2d0e959e1fe4baf3726dba84e83288c2808c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Tue, 29 Jul 2025 20:29:05 +0200 Subject: [PATCH 18/30] Apply suggestions from code review Co-authored-by: David Kilfoyle <41695641+kilfoyle@users.noreply.github.com> --- deploy-manage/upgrade.md | 6 +++--- deploy-manage/upgrade/deployment-or-cluster.md | 6 +++--- deploy-manage/upgrade/ingest-components.md | 2 +- deploy-manage/upgrade/plan-upgrade.md | 14 +++++++------- 4 files changed, 14 insertions(+), 14 deletions(-) diff --git a/deploy-manage/upgrade.md b/deploy-manage/upgrade.md index 2f1c1ccb20..ef99875800 100644 --- a/deploy-manage/upgrade.md +++ b/deploy-manage/upgrade.md @@ -18,7 +18,7 @@ products: Upgrading to the latest version provides access to the newest Elastic features, security patches, performance improvements, and bug fixes. These updates reduce costs, speed up threat response, and improve investigative and analytical data tools. -When Elastic releases new versions, older versions reach their end of life on a set schedule. To keep your deployment supported, stay up to date. For more information, refer to [Product End of Life Dates](https://www.elastic.co/support/eol). +As Elastic releases new versions, older versions of Elastic products reach their end of life on a set schedule. To keep your deployment supported, stay up to date. For more information, refer to [Product End of Life Dates](https://www.elastic.co/support/eol). ::::{note} With [{{serverless-full}}](/deploy-manage/deploy/elastic-cloud/serverless.md), upgrades are fully managed by Elastic. Users automatically receive the latest features and improvements, with no need to plan or perform upgrade steps. @@ -26,7 +26,7 @@ With [{{serverless-full}}](/deploy-manage/deploy/elastic-cloud/serverless.md), u The upgrade procedure depends on how your deployment is managed. If you're using {{ech}} or {{ece}}, upgrades can often be performed with a single click in the {{ecloud}} UI. For self-managed deployments, upgrades must be carried out manually using a rolling upgrade process, upgrading the nodes one by one to minimize downtime and ensure cluster stability. -This section provides guidance to help you plan and safely perform upgrades of your Elastic Stack components, with a primary focus on {{es}} and {{kib}} as the core of the stack. It also covers upgrades for orchestration platforms like {{ece}} and {{eck}}, as well as related components such as APM, Beats, Elastic Agent, and Logstash. +This section provides guidance to help you plan and safely perform upgrades of your {{stack}} components, with a primary focus on {{es}} and {{kib}} as the core of the stack. It also covers upgrades for orchestration platforms like {{ece}} and {{eck}}, as well as related components such as APM, {{beats}}, {{agent}}, and {{ls}}. :::{important} In {{stack}} 9.0.0 and beyond, Enterprise Search is unavailable. For more information, refer to [Migrating to 9.x from Enterprise Search 8.x versions](https://www.elastic.co/guide/en/enterprise-search/8.18/upgrading-to-9-x.html). @@ -47,7 +47,7 @@ Upgrading your Elastic cluster or deployment involves several stages, including - [Upgrade deployments on {{eck}}](/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-eck.md) - [Upgrade self-managed clusters](/deploy-manage/upgrade/deployment-or-cluster/self-managed.md) -- [Upgrade ingest components](./upgrade/ingest-components.md): Covers supporting components such as Beats, Elastic Agent, Logstash, and APM Server. +- [Upgrade ingest components](./upgrade/ingest-components.md): Covers supporting components such as {{beats}}, {{agent}}, {{ls}}, and APM Server. Additionally, if you're using a self-managed orchestration platform such as {{ece}} or {{eck}}, refer to [Upgrade your ECE or ECK orchestrator](/deploy-manage/upgrade/orchestrator.md) to keep the orchestrator up to date. diff --git a/deploy-manage/upgrade/deployment-or-cluster.md b/deploy-manage/upgrade/deployment-or-cluster.md index e9a92fba0c..353016f11f 100644 --- a/deploy-manage/upgrade/deployment-or-cluster.md +++ b/deploy-manage/upgrade/deployment-or-cluster.md @@ -36,12 +36,12 @@ Before proceeding with the upgrade, review the [Plan your upgrade](/deploy-manag ## Out-of-order releases [out-of-order-releases] -Elastic maintains several minor versions of Elasticsearch at once. This means releases do not always happen in order of their version numbers. You can only upgrade to {{version.stack}} if the version you are currently running meets both of these conditions: +Elastic maintains several minor versions of {{es}} at the same time. This means releases do not always happen in order of their version numbers. You can only upgrade to {{version.stack}} if the version you are currently running meets both of these conditions: -* Has an older version number than {{version.stack}} +* Has a lower version number than {{version.stack}} * Has an earlier release date than {{version.stack}} -If you are currently running a version with an older version number but a later release date than {{version.stack}}, wait for a newer release before upgrading. +If you are currently running a version with a lower version number but a later release date than {{version.stack}}, wait for a newer release before upgrading. Additionally, upgrading from a release candidate build, such as 9.0.0-rc1, is unsupported. Use pre-releases only for testing in a temporary environment. diff --git a/deploy-manage/upgrade/ingest-components.md b/deploy-manage/upgrade/ingest-components.md index 9bb9fda86b..2a5efddd1e 100644 --- a/deploy-manage/upgrade/ingest-components.md +++ b/deploy-manage/upgrade/ingest-components.md @@ -14,7 +14,7 @@ Once you've successfully [upgraded your deployment or cluster](/deploy-manage/up 1. {{agent}}: [Upgrade instructions](../../reference/fleet/upgrade-elastic-agent.md) ::::{note} - If you plan to upgrade Fleet-managed {{agent}}s, start by upgrading the agent running as the {{fleet-server}}. + If you plan to upgrade {{fleet}}-managed {{agent}}s, start by upgrading the agent running as the {{fleet-server}}. :::: 2. {{beats}}: [Upgrade instructions](beats://reference/libbeat/upgrading.md) diff --git a/deploy-manage/upgrade/plan-upgrade.md b/deploy-manage/upgrade/plan-upgrade.md index a23e392584..dbcbdfdc86 100644 --- a/deploy-manage/upgrade/plan-upgrade.md +++ b/deploy-manage/upgrade/plan-upgrade.md @@ -48,13 +48,13 @@ Before upgrading, verify that your current environment supports the version you * **{{es}} upgrade path**: Check the [upgrade paths](../upgrade.md#upgrade-paths) to determine whether you must upgrade through an intermediate version (such as 8.19.x before moving to 9.x), or if you can upgrade directly to the target version. -* **OpenJDK compatibility and FIPS compliance**: By default, {{es}} is built using Java and includes a bundled version of [OpenJDK](https://openjdk.java.net/) within each distribution. While we strongly recommend using the bundled Java Virtual Machine (JVM) in all installations of {{es}}, if you choose to use your own JVM, ensure it’s compatible by reviewing the [Product and JVM support matrix](https://www.elastic.co/support/matrix#matrix_jvm). +* **OpenJDK compatibility and FIPS compliance**: By default, {{es}} is built using Java and includes a bundled version of [OpenJDK](https://openjdk.java.net/) in each distribution. While we strongly recommend using the bundled Java Virtual Machine (JVM) in all installations of {{es}}, if you choose to use your own JVM, ensure it’s compatible by reviewing the [Product and JVM support matrix](https://www.elastic.co/support/matrix#matrix_jvm). - If you’re running {{es}} in FIPS 140-2 mode, we recommend using [Bouncy Castle](https://www.bouncycastle.org/java.html) as a Java security provider when running {{es}}. + If you’re running {{es}} in FIPS 140-2 mode, we recommend using [Bouncy Castle](https://www.bouncycastle.org/java.html) as a Java security provider when running {{es}}. ## Conduct a component inventory -When you plan to upgrade your deployment, it is very important to map all the components that are being used on the {{stack}}, and check if they are compatible with the {{es}} version you plan to upgrade to by reviewing the [Product compatibility support matrix](https://www.elastic.co/support/matrix#matrix_compatibility). +When you plan to upgrade your deployment, it is very important to map all the components that are being used in the {{stack}}, and check if they are compatible with the {{es}} version you plan to upgrade to by reviewing the [Product compatibility support matrix](https://www.elastic.co/support/matrix#matrix_compatibility). ::::{note} If any of your ingest components does not support the {{es}} version you plan to upgrade to, you need to upgrade that component to a version that supports the desired {{es}} version before upgrading {{es}}. @@ -62,7 +62,7 @@ If any of your ingest components does not support the {{es}} version you plan to As part of the upgrade plan, you will also have to determine if you want to upgrade the ingest components to the same version as {{es}}, after the upgrade of {{es}} and {{kib}}. -While not comprehensive, here’s a list of components you should check: +While not comprehensive, here’s a list of the components you should check: * {{es}} * {{es}} Hadoop @@ -111,8 +111,8 @@ In general, you should upgrade the components of your {{stack}} in the following 1. {{es}} 2. {{kib}} (must be kept aligned with the {{es}} version) -3. Fleet Server and Elastic APM (if used) -4. Ingest tools (Beats, Elastic Agent, Logstash, etc.) and {{es}} client libraries +3. {{fleet-server}} and Elastic APM (if used) +4. Ingest tools ({{beats}}, {{agent}}, {{ls}}, etc.) and {{es}} client libraries If your deployment runs on {{ech}} or {{ece}}, the platform handles the upgrade and component order automatically in a single plan execution. You only need to upgrade any external ingest tools afterward. @@ -124,7 +124,7 @@ The monitoring cluster should be running the same version, or a newer one, than ## Example of an upgrade plan -Let's assume you are running all {{stack}} components in version 8.14 and your main goal is to upgrade {{es}} and {{kib}} to the latest {{version.stack}}, without requiring to upgrade the ingest components (Beats, Elastic Agent, and Logstash) except when required by the [upgrade paths](../upgrade.md#upgrade-paths). +Let's assume you are running all {{stack}} components in version 8.14 and your main goal is to upgrade {{es}} and {{kib}} to the latest {{version.stack}}, without requiring to upgrade the ingest components ({{beats}}, {{agent}}, and {{ls}}) except when required by the [upgrade paths](../upgrade.md#upgrade-paths). The minimum steps your plan should include are: From 254305f6db2de12c1b618ced334619c7c893cd66 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Tue, 29 Jul 2025 20:31:16 +0200 Subject: [PATCH 19/30] Update deploy-manage/upgrade/prepare-to-upgrade.md Co-authored-by: David Kilfoyle <41695641+kilfoyle@users.noreply.github.com> --- deploy-manage/upgrade/prepare-to-upgrade.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/deploy-manage/upgrade/prepare-to-upgrade.md b/deploy-manage/upgrade/prepare-to-upgrade.md index a8ac4ff2a4..9195921323 100644 --- a/deploy-manage/upgrade/prepare-to-upgrade.md +++ b/deploy-manage/upgrade/prepare-to-upgrade.md @@ -153,7 +153,7 @@ Follow these steps to prepare for a successful major upgrade from 8.x to 9.x: 4. **Old {{ml}} indices** - If you have `.ml-anomalies-*`anomaly detection result indices created in {{es}} 7.x, reindex them, mark them as read-only, or delete them before you upgrade to 9.x. For more information, refer to [Migrate anomaly detection results](#anomaly-migration). + If you have `.ml-anomalies-*` anomaly detection result indices created in {{es}} 7.x, reindex them, mark them as read-only, or delete them before you upgrade to 9.x. For more information, refer to [Migrate anomaly detection results](#anomaly-migration). 5. **Old transform indices** From 68acf6a7306798d97ea85807e9a8f3a6fc7318a9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Tue, 29 Jul 2025 20:46:43 +0200 Subject: [PATCH 20/30] applying dcturner suggestions --- deploy-manage/upgrade.md | 7 ++----- deploy-manage/upgrade/prepare-to-upgrade.md | 6 ++---- 2 files changed, 4 insertions(+), 9 deletions(-) diff --git a/deploy-manage/upgrade.md b/deploy-manage/upgrade.md index ef99875800..f581af2622 100644 --- a/deploy-manage/upgrade.md +++ b/deploy-manage/upgrade.md @@ -59,7 +59,7 @@ For example: - ✅ Upgrade allowed: From 9.0.4 to 9.1.0 (9.1.0 released *after* 9.0.4) - ❌ Not allowed: From 9.0.5 to 9.1.0 (9.1.0 released *before* 9.0.5) → wait for 9.1.1 to be released @@ -74,10 +74,7 @@ To perform a major upgrade from 8.x, the required starting version depends on th While 8.19 is the final minor release in the 8.x series, 8.18 was released at the same time as 9.0, enabling a supported upgrade path between the 8.18.x and 9.0.x series. This compatibility also applies to other features and clients. :::: -The following upgrade paths from 8.x are valid for reaching the latest {{version.stack}} release: - -* Versions prior to 8.18 → 8.19.x → {{version.stack}} *(recommended)* -* Versions prior to 8.18 → 8.18.x → 9.0.x → {{version.stack}} +If you're upgrading to the current {{version.stack}} release from an earlier 8.x version, first upgrade to the latest available 8.19 release. #### Ingest tools and clients considerations diff --git a/deploy-manage/upgrade/prepare-to-upgrade.md b/deploy-manage/upgrade/prepare-to-upgrade.md index 9195921323..5aa0c0a123 100644 --- a/deploy-manage/upgrade/prepare-to-upgrade.md +++ b/deploy-manage/upgrade/prepare-to-upgrade.md @@ -100,9 +100,7 @@ Follow these steps to prepare for a successful major upgrade from 8.x to 9.x: ::::{note} Because 8.18.0 and 9.0.0 were released simultaneously, upgrading from 8.18.x to 9.0.x is supported, as long as the versions comply with the supported [upgrade paths](../upgrade.md#upgrade-paths). However, upgrading to 9.1.0 or later requires starting from 8.19.x. - As an example, these are valid upgrade paths to {{version.stack}}: - * Versions prior to 8.18 → 8.19.x → {{version.stack}} *(recommended)* - * Versions prior to 8.18 → 8.18.x → 9.0.x → {{version.stack}} + If you're upgrading to the current {{version.stack}} release from an earlier 8.x version, first upgrade to the latest available 8.19 release. :::: If you are already running an 8.19.x version, it's also recommended to upgrade to the latest 8.19 patch release before upgrading to 9.x. This ensures that the latest version of the upgrade assistant is used, and any bug fixes that could have implications for the upgrade are applied. @@ -161,7 +159,7 @@ Follow these steps to prepare for a successful major upgrade from 8.x to 9.x: ## Reindex to upgrade [reindex-to-upgrade] -If you are running a pre-8.x version, you might need to perform multiple upgrades before being able to upgrade to 9.x. As an alternative method to upgrading the cluster, you can create a new {{version.stack}} deployment and reindex from remote: +If you are running a pre-8.x version, you might need to perform multiple upgrades before being able to upgrade to 9.x. As an alternative method to upgrading the cluster, you can create a new deployment in the target version and reindex from remote: 1. Provision an additional deployment running the desired version, such as {{version.stack}}. 2. To reindex your data into the new {{es}} cluster, use the [reindex documents API](https://www.elastic.co/docs/api/doc/elasticsearch/v8/operation/operation-reindex) and temporarily send new indexing requests to both clusters. From a91332e7f6df847abccf5b1725b9a123c255ed96 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Wed, 30 Jul 2025 13:27:46 +0200 Subject: [PATCH 21/30] Apply suggestions from code review Co-authored-by: shainaraskas <58563081+shainaraskas@users.noreply.github.com> --- deploy-manage/upgrade.md | 2 +- deploy-manage/upgrade/deployment-or-cluster.md | 2 +- .../upgrade/deployment-or-cluster/elasticsearch.md | 9 ++++++++- .../upgrade/deployment-or-cluster/upgrade-on-eck.md | 2 +- deploy-manage/upgrade/plan-upgrade.md | 12 ++++++------ .../upgrade/prepare-to-upgrade/upgrade-assistant.md | 2 +- 6 files changed, 18 insertions(+), 11 deletions(-) diff --git a/deploy-manage/upgrade.md b/deploy-manage/upgrade.md index f581af2622..a27093b309 100644 --- a/deploy-manage/upgrade.md +++ b/deploy-manage/upgrade.md @@ -29,7 +29,7 @@ The upgrade procedure depends on how your deployment is managed. If you're using This section provides guidance to help you plan and safely perform upgrades of your {{stack}} components, with a primary focus on {{es}} and {{kib}} as the core of the stack. It also covers upgrades for orchestration platforms like {{ece}} and {{eck}}, as well as related components such as APM, {{beats}}, {{agent}}, and {{ls}}. :::{important} -In {{stack}} 9.0.0 and beyond, Enterprise Search is unavailable. For more information, refer to [Migrating to 9.x from Enterprise Search 8.x versions](https://www.elastic.co/guide/en/enterprise-search/8.18/upgrading-to-9-x.html). +In {{stack}} 9.0.0 and beyond, Enterprise Search is unavailable. For more information, refer to [Migrating to 9.x from Enterprise Search 8.x versions](https://www.elastic.co/guide/en/enterprise-search/8.19/upgrading-to-9-x.html). ::: ## Upgrade overview diff --git a/deploy-manage/upgrade/deployment-or-cluster.md b/deploy-manage/upgrade/deployment-or-cluster.md index 353016f11f..56f76ac82b 100644 --- a/deploy-manage/upgrade/deployment-or-cluster.md +++ b/deploy-manage/upgrade/deployment-or-cluster.md @@ -28,7 +28,7 @@ products: # Upgrade your deployment or cluster [upgrade-deployment-cluster] -This section contains the actual upgrade instructions for {{es}} clusters and {{kib}} instances. Upgrade procedures depend on whether you installed Elastic components using Elastic-managed or self-managed infrastructure. +This section contains the upgrade instructions for {{es}} clusters and {{kib}} instances. Upgrade procedures depend on whether you installed Elastic components using Elastic-managed or self-managed infrastructure. ## Prerequisites diff --git a/deploy-manage/upgrade/deployment-or-cluster/elasticsearch.md b/deploy-manage/upgrade/deployment-or-cluster/elasticsearch.md index 230570760e..3c33b01401 100644 --- a/deploy-manage/upgrade/deployment-or-cluster/elasticsearch.md +++ b/deploy-manage/upgrade/deployment-or-cluster/elasticsearch.md @@ -21,7 +21,14 @@ Before you start, [take the upgrade preparation steps](/deploy-manage/upgrade/pr When performing a [rolling upgrade](#rolling-upgrades): -1. Upgrade the data nodes first, tier-by-tier, starting with the frozen tier, then the cold tier, then the warm tier, then the hot tier, and finally any other data nodes which are not in a tier. Complete the upgrade for all nodes in each data tier before moving to the next. This ensures {{ilm-init}} can continue to move data through the tiers during the upgrade. You can get the list of nodes in a specific tier with a `GET /_nodes` request, for example: `GET /_nodes/data_frozen:true/_none`. +1. Upgrade the data nodes first, tier-by-tier, in the following order: + 1. The frozen tier + 2. The cold tier + 3. The warm tier + 4. The hot tier + 5. Any other data nodes which are not in a tier. + + Complete the upgrade for all nodes in each data tier before moving to the next. This ensures {{ilm-init}} can continue to move data through the tiers during the upgrade. You can get the list of nodes in a specific tier with a `GET /_nodes` request, for example: `GET /_nodes/data_frozen:true/_none`. 2. Upgrade all remaining nodes that are neither master-eligible nor data nodes. This includes dedicated ML nodes, dedicated ingest nodes, and dedicated coordinating nodes. 3. Upgrade the master-eligible nodes last. You can retrieve a list of these nodes with `GET /_nodes/master:true/_none`. diff --git a/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-eck.md b/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-eck.md index eae9607190..d7c4ca77b6 100644 --- a/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-eck.md +++ b/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-eck.md @@ -21,7 +21,7 @@ Once you're [prepared to upgrade](/deploy-manage/upgrade/prepare-to-upgrade.md), 1. In the resource spec file, modify the `version` field for the desired {{stack}} version. 2. Save your changes. The orchestrator will start the upgrade process automatically. -In this example, we’re modifying the version to `{{version.stack}}`. +In this example, we’re modifying the version to {{version.stack}}. ```yaml subs=true apiVersion: elasticsearch.k8s.elastic.co/v1 diff --git a/deploy-manage/upgrade/plan-upgrade.md b/deploy-manage/upgrade/plan-upgrade.md index dbcbdfdc86..93ca1cf891 100644 --- a/deploy-manage/upgrade/plan-upgrade.md +++ b/deploy-manage/upgrade/plan-upgrade.md @@ -15,9 +15,9 @@ products: --- # Plan your upgrade -There are several important factors to consider before starting the upgrade process. Use the following recommendations to build a solid upgrade plan: +There are several important factors to consider before starting the upgrade process. Use the following recommendations to build your upgrade plan: -* Plan for an appropriate amount of time to complete the upgrade. Depending on your configuration and the size of your cluster, the process may take just a few minutes or several hours. In more complex environments, it could extend to a few weeks or more. +* Plan for an appropriate amount of time to complete the upgrade. Depending on your configuration and the size of your cluster, the process might take just a few minutes or several hours. In more complex environments, the process can take up to a few weeks or more to complete. * Consider opening a [support case](https://support.elastic.co/) with Elastic to alert our Elastic Support team of your system change. If you need additional assistance, [Elastic Consulting Services](https://www.elastic.co/consulting) provides the technical expertise and step-by-step approach for upgrading your environment. * Schedule a system maintenance window within your organization. * When possible, perform testing of the upgrade process in a non-production environment. @@ -36,12 +36,12 @@ Before upgrading, verify that your current environment supports the version you * [ECE – Stack packs](/deploy-manage/deploy/cloud-enterprise/manage-elastic-stack-versions.md#ece_most_recent_elastic_stack_packs) * [ECK – {{stack}} compatibility](/deploy-manage/deploy/cloud-on-k8s.md#stack-compatibility) -* **Rest API compatibility**: If you use custom-developed applications or clients, ensure the [{{es}} client libraries](/reference/elasticsearch-clients/index.md) are compatible with the target version. If your applications use deprecated or removed APIs, you may need to update the client code first. +* **Rest API compatibility**: If you use custom-developed applications or clients, ensure the [{{es}} client libraries](/reference/elasticsearch-clients/index.md) are compatible with the target version. If your applications use deprecated or removed APIs, then you might need to update the client code first. ::::{note} - By default, 8.x {{es}} clients are compatible with 9.x and use [`REST API compatibility`](elasticsearch://reference/elasticsearch/rest-apis/compatibility.md) to maintain compatibility with the 9.x {{es}} cluster. + By default, 8.x {{es}} clients are compatible with 9.x and use [REST API compatibility](elasticsearch://reference/elasticsearch/rest-apis/compatibility.md) to maintain compatibility with the 9.x {{es}} cluster. - `REST API compatibility` is a per-request opt-in feature that can help REST clients mitigate non-compatible (breaking) changes to the REST API. + REST API compatibility is a per-request opt-in feature that can help REST clients mitigate non-compatible (breaking) changes to the REST API. :::: * **Index compatibility**: {{es}} provides full query and write support for indices created in the previous major version. If you have indices created in 7.x or earlier, you must reindex, delete, or [archive](/deploy-manage/upgrade/deployment-or-cluster/reading-indices-from-older-elasticsearch-versions.md) them before upgrading to 9.x. This topic is covered during the [upgrade preparations](prepare-to-upgrade.md#prepare-upgrade-from-8.x), with help from the Upgrade Assistant. @@ -134,4 +134,4 @@ The minimum steps your plan should include are: ## Next steps -Once you’ve planned your upgrade and defined a clear upgrade path for all the components, you can proceed to the [upgrade preparations](/deploy-manage/upgrade/prepare-to-upgrade.md). \ No newline at end of file +After you’ve planned your upgrade and defined a clear upgrade path for all the components, you can proceed to the [upgrade preparations](/deploy-manage/upgrade/prepare-to-upgrade.md). \ No newline at end of file diff --git a/deploy-manage/upgrade/prepare-to-upgrade/upgrade-assistant.md b/deploy-manage/upgrade/prepare-to-upgrade/upgrade-assistant.md index ee92ac9bf4..33bedc4b00 100644 --- a/deploy-manage/upgrade/prepare-to-upgrade/upgrade-assistant.md +++ b/deploy-manage/upgrade/prepare-to-upgrade/upgrade-assistant.md @@ -22,7 +22,7 @@ The Upgrade Assistant helps you [prepare to upgrade](/deploy-manage/upgrade/prep ::::{tip} Upgrade assistant should be run from the latest minor release before a major upgrade. When upgrading to 9.x, ensure you run 8.19.latest, and run the assistant there. -Running the latest patched version of 8.19 will allow running the latest version of the upgrade assistant logic. +Running the latest patched version of 8.19 will apply latest version of the upgrade assistant logic. :::: The assistant identifies deprecated settings in your configuration, and if any of those settings are enabled, it guides you through resolving issues that could prevent a successful upgrade. The Upgrade Assistant also helps resolve issues with older indices created before version 8.0.0, providing options to reindex older indices or mark them as read-only. From 1575ed9fd6a6c2b378ee5b392ab3b3d5708a2a65 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Wed, 30 Jul 2025 14:58:06 +0200 Subject: [PATCH 22/30] applying Shaina's suggestions and small change in ECH upgrades --- deploy-manage/_snippets/serverless-upgrade.md | 5 +++++ deploy-manage/upgrade.md | 5 ++--- deploy-manage/upgrade/deployment-or-cluster.md | 5 ++--- deploy-manage/upgrade/deployment-or-cluster/elasticsearch.md | 2 +- .../upgrade/deployment-or-cluster/enterprise-search.md | 2 +- deploy-manage/upgrade/deployment-or-cluster/kibana.md | 1 + .../upgrade/deployment-or-cluster/upgrade-on-ech.md | 4 ++-- deploy-manage/upgrade/plan-upgrade.md | 2 +- 8 files changed, 15 insertions(+), 11 deletions(-) create mode 100644 deploy-manage/_snippets/serverless-upgrade.md diff --git a/deploy-manage/_snippets/serverless-upgrade.md b/deploy-manage/_snippets/serverless-upgrade.md new file mode 100644 index 0000000000..4551488cb6 --- /dev/null +++ b/deploy-manage/_snippets/serverless-upgrade.md @@ -0,0 +1,5 @@ +::::{note} +With [{{serverless-full}}](/deploy-manage/deploy/elastic-cloud/serverless.md), upgrades of the Elastic-managed infrastructure and project components are fully handled by Elastic. Users automatically receive the latest features and improvements, with no need to plan or perform project-level upgrades. + +Keep in mind that the [ingest components](/deploy-manage/upgrade/ingest-components.md) or clients you manage externally, such as {{agent}}, {{beats}}, {{ls}}, or custom applications, still need to be updated manually. +:::: \ No newline at end of file diff --git a/deploy-manage/upgrade.md b/deploy-manage/upgrade.md index a27093b309..abafe5d474 100644 --- a/deploy-manage/upgrade.md +++ b/deploy-manage/upgrade.md @@ -20,9 +20,8 @@ Upgrading to the latest version provides access to the newest Elastic features, As Elastic releases new versions, older versions of Elastic products reach their end of life on a set schedule. To keep your deployment supported, stay up to date. For more information, refer to [Product End of Life Dates](https://www.elastic.co/support/eol). -::::{note} -With [{{serverless-full}}](/deploy-manage/deploy/elastic-cloud/serverless.md), upgrades are fully managed by Elastic. Users automatically receive the latest features and improvements, with no need to plan or perform upgrade steps. -:::: +:::{include} /deploy-manage/_snippets/serverless-upgrade.md +::: The upgrade procedure depends on how your deployment is managed. If you're using {{ech}} or {{ece}}, upgrades can often be performed with a single click in the {{ecloud}} UI. For self-managed deployments, upgrades must be carried out manually using a rolling upgrade process, upgrading the nodes one by one to minimize downtime and ensure cluster stability. diff --git a/deploy-manage/upgrade/deployment-or-cluster.md b/deploy-manage/upgrade/deployment-or-cluster.md index 56f76ac82b..d53cfa2055 100644 --- a/deploy-manage/upgrade/deployment-or-cluster.md +++ b/deploy-manage/upgrade/deployment-or-cluster.md @@ -57,9 +57,8 @@ If you’re using self-managed infrastructure - either on-prem or public cloud - * [Upgrade your deployment on {{ece}} (ECE)](/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-ece.md) * [Upgrade your deployment on {{eck}} (ECK)](/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-eck.md) -::::{note} -With [{{serverless-full}}](/deploy-manage/deploy/elastic-cloud/serverless.md), upgrades are fully managed by Elastic. Users automatically receive the latest features and improvements, with no need to plan or perform upgrade steps. -:::: +:::{include} /deploy-manage/_snippets/serverless-upgrade.md +::: ## Next steps diff --git a/deploy-manage/upgrade/deployment-or-cluster/elasticsearch.md b/deploy-manage/upgrade/deployment-or-cluster/elasticsearch.md index 3c33b01401..d8adc4e5de 100644 --- a/deploy-manage/upgrade/deployment-or-cluster/elasticsearch.md +++ b/deploy-manage/upgrade/deployment-or-cluster/elasticsearch.md @@ -15,7 +15,7 @@ An {{es}} cluster can be upgraded one node at a time so upgrading does not inter Upgrading from a release candidate build, such as 9.0.0-rc1, is unsupported. Use pre-releases only for testing in a temporary environment. ::: -Before you start, [take the upgrade preparation steps](/deploy-manage/upgrade/prepare-to-upgrade.md). +Before you start the rolling upgrade procedure, [plan your upgrade](/deploy-manage/upgrade/plan-upgrade.md) and [take the upgrade preparation steps](/deploy-manage/upgrade/prepare-to-upgrade.md). ## {{es}} nodes upgrade order diff --git a/deploy-manage/upgrade/deployment-or-cluster/enterprise-search.md b/deploy-manage/upgrade/deployment-or-cluster/enterprise-search.md index 4d08480834..4733c70c49 100644 --- a/deploy-manage/upgrade/deployment-or-cluster/enterprise-search.md +++ b/deploy-manage/upgrade/deployment-or-cluster/enterprise-search.md @@ -12,4 +12,4 @@ applies_to: In {{stack}} 9.0.0 and beyond, Enterprise Search is unavailable. We recommend migrating to {{es}} for improved performance, scalability, and flexibility. For information about what {{es}} features you can use, check out this [blog post](https://www.elastic.co/blog/app-search-to-elasticsearch). -For complete information about resources and initiatives related to App Search migrations, future enhancements, and decommissioning, refer to [Migrating to 9.x from Enterprise Search 8.x versions](https://www.elastic.co/guide/en/enterprise-search/8.18/upgrading-to-9-x.html). \ No newline at end of file +For complete information about resources and initiatives related to App Search migrations, future enhancements, and decommissioning, refer to [Migrating to 9.x from Enterprise Search 8.x versions](https://www.elastic.co/guide/en/enterprise-search/8.19/upgrading-to-9-x.html). \ No newline at end of file diff --git a/deploy-manage/upgrade/deployment-or-cluster/kibana.md b/deploy-manage/upgrade/deployment-or-cluster/kibana.md index 6df2bc68ba..46c8bef3a2 100644 --- a/deploy-manage/upgrade/deployment-or-cluster/kibana.md +++ b/deploy-manage/upgrade/deployment-or-cluster/kibana.md @@ -1,5 +1,6 @@ --- applies_to: + stack: deployment: self: all products: diff --git a/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-ech.md b/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-ech.md index dab63a9e07..aee8cf5ea1 100644 --- a/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-ech.md +++ b/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-ech.md @@ -18,7 +18,7 @@ products: Once you are [prepared to upgrade](/deploy-manage/upgrade/prepare-to-upgrade.md), a single click in the {{ecloud}} console can upgrade a deployment 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}}, {{kib}}, Elastic APM, and all of your deployment components are upgraded simultaneously. -{{ecloud}} only supports upgrades to released versions. Release candidate builds and master snapshots are not supported. +{{ecloud}} only supports and enables upgrades to released versions that comply with the supported [upgrade paths](/deploy-manage/upgrade.md#upgrade-paths). Release candidate builds and master snapshots are not supported. ::::{important} Although it’s simple to upgrade an {{ecloud}} deployment, the new version might include breaking changes that affect your application. Ensure you review breaking changes and deprecation logs, make any necessary changes, and test against the new version before upgrading your production deployment. @@ -26,7 +26,7 @@ Although it’s simple to upgrade an {{ecloud}} deployment, the new version migh ## Availability during upgrades -For deployments with nodes in more than one availability zone, you can perform minor version upgrades, upgrades from 8.18 to 9.0.0, and cluster configuration changes with no downtime. Deployments with nodes in only one zone might experience downtime during these operations. +For deployments with nodes in more than one availability zone, you can perform upgrades and cluster configuration changes with no downtime. Deployments with nodes in only one zone might experience downtime during these operations. When {{kib}} instances are upgraded, all instances are shut down simultaneously, making {{kib}} temporarily inaccessible, even if it's deployed across multiple zones. diff --git a/deploy-manage/upgrade/plan-upgrade.md b/deploy-manage/upgrade/plan-upgrade.md index 93ca1cf891..761951f76d 100644 --- a/deploy-manage/upgrade/plan-upgrade.md +++ b/deploy-manage/upgrade/plan-upgrade.md @@ -46,7 +46,7 @@ Before upgrading, verify that your current environment supports the version you * **Index compatibility**: {{es}} provides full query and write support for indices created in the previous major version. If you have indices created in 7.x or earlier, you must reindex, delete, or [archive](/deploy-manage/upgrade/deployment-or-cluster/reading-indices-from-older-elasticsearch-versions.md) them before upgrading to 9.x. This topic is covered during the [upgrade preparations](prepare-to-upgrade.md#prepare-upgrade-from-8.x), with help from the Upgrade Assistant. -* **{{es}} upgrade path**: Check the [upgrade paths](../upgrade.md#upgrade-paths) to determine whether you must upgrade through an intermediate version (such as 8.19.x before moving to 9.x), or if you can upgrade directly to the target version. +* **{{es}} upgrade path**: Check the [upgrade paths](../upgrade.md#upgrade-paths) to determine whether you must upgrade through an intermediate version (such as 8.19.x before moving to 9.1+), or if you can upgrade directly to the target version. * **OpenJDK compatibility and FIPS compliance**: By default, {{es}} is built using Java and includes a bundled version of [OpenJDK](https://openjdk.java.net/) in each distribution. While we strongly recommend using the bundled Java Virtual Machine (JVM) in all installations of {{es}}, if you choose to use your own JVM, ensure it’s compatible by reviewing the [Product and JVM support matrix](https://www.elastic.co/support/matrix#matrix_jvm). From 36603e62c56eee095874cf7c326e088152abb516 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Wed, 30 Jul 2025 15:59:21 +0200 Subject: [PATCH 23/30] Update deploy-manage/upgrade/prepare-to-upgrade.md Co-authored-by: shainaraskas <58563081+shainaraskas@users.noreply.github.com> --- deploy-manage/upgrade/prepare-to-upgrade.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/deploy-manage/upgrade/prepare-to-upgrade.md b/deploy-manage/upgrade/prepare-to-upgrade.md index 5aa0c0a123..4695246369 100644 --- a/deploy-manage/upgrade/prepare-to-upgrade.md +++ b/deploy-manage/upgrade/prepare-to-upgrade.md @@ -22,7 +22,7 @@ When upgrading an existing cluster, you perform a major, minor, or patch upgrade Upgrading from a release candidate build, such as 9.0.0-rc1, is unsupported. Use pre-releases only for testing in a temporary environment. ::: -This document describes the preparation steps for upgrading {{es}}, which vary depending on the type of upgrade. These steps follow the [upgrade planning](./plan-upgrade.md) and should be completed before proceeding to [upgrade your deployment or cluster](./deployment-or-cluster.md). +This document describes the preparation steps for upgrading {{es}}, which vary depending on the type of upgrade. These steps follow the [upgrade planning](./plan-upgrade.md) phase, and should be completed before proceeding to [upgrade your deployment or cluster](./deployment-or-cluster.md). ## Common preparation steps for all upgrades From 53231fa582a1691eb4e4edbbbd59401f1898febc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Wed, 30 Jul 2025 17:05:47 +0200 Subject: [PATCH 24/30] applying suggestions --- .../deployment-or-cluster/upgrade-on-eck.md | 2 +- deploy-manage/upgrade/ingest-components.md | 2 +- deploy-manage/upgrade/prepare-to-upgrade.md | 26 +++++++++---------- 3 files changed, 15 insertions(+), 15 deletions(-) diff --git a/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-eck.md b/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-eck.md index d7c4ca77b6..16c0f1f560 100644 --- a/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-eck.md +++ b/deploy-manage/upgrade/deployment-or-cluster/upgrade-on-eck.md @@ -14,7 +14,7 @@ products: The ECK orchestrator can safely perform upgrades to newer versions of the {{stack}}. -Once you're [prepared to upgrade](/deploy-manage/upgrade/prepare-to-upgrade.md), ensure the ECK version is [compatible](/deploy-manage/deploy/cloud-on-k8s.md#stack-compatibility) with the {{stack}} version you’re upgrading to. For example, if you're upgrading to {{version.stack}}, the minimum required ECK version is 3.0.0. If it's incompatible, [upgrade your orchestrator](/deploy-manage/upgrade/orchestrator/upgrade-cloud-on-k8s.md). +Before you start the upgrade, [plan your upgrade](/deploy-manage/upgrade/plan-upgrade.md), [take the upgrade preparation steps](/deploy-manage/upgrade/prepare-to-upgrade.md), and ensure your ECK version is [compatible](/deploy-manage/deploy/cloud-on-k8s.md#stack-compatibility) with the {{stack}} version you’re upgrading to. If it's incompatible, [upgrade your orchestrator](/deploy-manage/upgrade/orchestrator/upgrade-cloud-on-k8s.md) first. ## Perform the upgrade diff --git a/deploy-manage/upgrade/ingest-components.md b/deploy-manage/upgrade/ingest-components.md index 2a5efddd1e..53072f74f3 100644 --- a/deploy-manage/upgrade/ingest-components.md +++ b/deploy-manage/upgrade/ingest-components.md @@ -6,6 +6,7 @@ applies_to: ess: ece: self: + serverless: --- # Upgrade your ingest components @@ -20,4 +21,3 @@ Once you've successfully [upgraded your deployment or cluster](/deploy-manage/up 2. {{beats}}: [Upgrade instructions](beats://reference/libbeat/upgrading.md) 3. {{ls}}: [Upgrade instructions](logstash://reference/upgrading-logstash.md) 4. Custom clients - diff --git a/deploy-manage/upgrade/prepare-to-upgrade.md b/deploy-manage/upgrade/prepare-to-upgrade.md index 4695246369..21d9ec46dc 100644 --- a/deploy-manage/upgrade/prepare-to-upgrade.md +++ b/deploy-manage/upgrade/prepare-to-upgrade.md @@ -40,7 +40,7 @@ The following steps are common to all types of upgrades, regardless if you are u 3. **Test in a non-production environment** - Before upgrading your production deployment, test the upgrade using a non-production environment. Ensure the test and production environments use the same settings. + Before upgrading your production deployment, test the upgrade using a non-production environment. Make sure the test environment mirrors production as closely as possible, including configuration and client interactions. :::{note} 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 behavior in your environment. @@ -145,27 +145,18 @@ Follow these steps to prepare for a successful major upgrade from 8.x to 9.x: As a temporary solution, use the 8.x syntax to submit requests to 9.x with REST API compatibility mode. While this allows you to submit requests using the old syntax, it doesn’t guarantee the same behavior. REST API compatibility should serve as a bridge during the upgrade, not a long-term solution. For more details on how to effectively use REST API compatibility during an upgrade, refer to [REST API compatibility](elasticsearch://reference/elasticsearch/rest-apis/compatibility.md). ::: -3. **{{ccr-cap}} (CCR)** +3. **Manage {{ccr-cap}} (CCR) follower data streams** If you have {{ccr-init}} data streams, and your indices require reindexing, refer to [Upgrade uni-directional {{ccr}} clusters with followed data streams](#upgrade-ccr-data-streams) for specific instructions. -4. **Old {{ml}} indices** +4. **Manage old {{ml}} indices** If you have `.ml-anomalies-*` anomaly detection result indices created in {{es}} 7.x, reindex them, mark them as read-only, or delete them before you upgrade to 9.x. For more information, refer to [Migrate anomaly detection results](#anomaly-migration). -5. **Old transform indices** +5. **Manage old transform indices** If you have transform destination indices created in {{es}} 7.x, reset, reindex, or delete them before you upgrade to 9.x. For more information, refer to [Migrate transform destination indices](#transform-migration). -## Reindex to upgrade [reindex-to-upgrade] - -If you are running a pre-8.x version, you might need to perform multiple upgrades before being able to upgrade to 9.x. As an alternative method to upgrading the cluster, you can create a new deployment in the target version and reindex from remote: - -1. Provision an additional deployment running the desired version, such as {{version.stack}}. -2. To reindex your data into the new {{es}} cluster, use the [reindex documents API](https://www.elastic.co/docs/api/doc/elasticsearch/v8/operation/operation-reindex) and temporarily send new indexing requests to both clusters. -3. Verify the new cluster performs as expected, fix any problems, and then permanently swap in the new cluster. -4. Delete the old deployment. On {{ecloud}}, you are billed for the time the new deployment runs in parallel with your old deployment. Usage is billed on an hourly basis. - ## Upgrade uni-directional {{ccr}} clusters with followed data streams [upgrade-ccr-data-streams] When moving to a new major version of {{es}}, you must perform specific actions to ensure that indices — including those that back a data stream — are compatible with the latest Lucene version. With a {{ccr-init}}-enabled cluster, consider whether you want to keep your older data writable or read-only to ensure you make changes to the cluster in the correct order. @@ -816,6 +807,15 @@ DELETE _transform/my-transform?delete_dest_index ``` ::: +## Reindex to upgrade [reindex-to-upgrade] + +If you are running a pre-8.x version, you might need to perform multiple upgrades before being able to upgrade to 9.x. As an alternative method to upgrading the cluster, you can create a new deployment in the target version and reindex from remote: + +1. Provision an additional deployment running the desired version, such as {{version.stack}}. +2. To reindex your data into the new {{es}} cluster, use the [reindex documents API](https://www.elastic.co/docs/api/doc/elasticsearch/v8/operation/operation-reindex) and temporarily send new indexing requests to both clusters. +3. Verify the new cluster performs as expected, fix any problems, and then permanently swap in the new cluster. +4. Delete the old deployment. On {{ecloud}}, you are billed for the time the new deployment runs in parallel with your old deployment. Usage is billed on an hourly basis. + ## Next steps After completing all the preparation steps, you're ready to [upgrade your deployment or cluster](./deployment-or-cluster.md). From 69172e9bafa04990dc4f1374c900bc5ee67356e5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Wed, 30 Jul 2025 17:34:17 +0200 Subject: [PATCH 25/30] flexible scheduling change --- deploy-manage/upgrade.md | 2 +- deploy-manage/upgrade/prepare-to-upgrade.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/deploy-manage/upgrade.md b/deploy-manage/upgrade.md index abafe5d474..6104393a49 100644 --- a/deploy-manage/upgrade.md +++ b/deploy-manage/upgrade.md @@ -77,6 +77,6 @@ If you're upgrading to the current {{version.stack}} release from an earlier 8.x #### Ingest tools and clients considerations -For flexible upgrade scheduling, 8.19 {{agent}}, {{beats}}, and {{ls}} are compatible with 9.x {{es}}. +For flexible upgrade scheduling, 8.19 {{agent}}, {{beats}}, and {{ls}} are compatible with all 9.x versions of {{es}}. By default, 8.x {{es}} clients are compatible with 9.x and use [REST API compatibility](elasticsearch://reference/elasticsearch/rest-apis/compatibility.md) to maintain compatibility with the 9.x cluster. diff --git a/deploy-manage/upgrade/prepare-to-upgrade.md b/deploy-manage/upgrade/prepare-to-upgrade.md index 21d9ec46dc..5195baa6ff 100644 --- a/deploy-manage/upgrade/prepare-to-upgrade.md +++ b/deploy-manage/upgrade/prepare-to-upgrade.md @@ -108,7 +108,7 @@ Follow these steps to prepare for a successful major upgrade from 8.x to 9.x: If you're using 7.x and earlier, you may need to complete multiple upgrades to reach the latest 8.19 patch release before upgrading to 9.x. As an alternative method to upgrading the cluster, you can create a new 9.x deployment and reindex from the original cluster. For more information, refer to [Reindex to upgrade](#reindex-to-upgrade). :::{note} - For flexible upgrade scheduling, 8.19.x {{beats}} and {{ls}} are compatible with 9.x {{es}}. + For flexible upgrade scheduling, 8.19.x {{agent}}, {{beats}} and {{ls}} are compatible with all 9.x versions of {{es}}. By default, 8.x {{es}} clients are compatible with 9.x and use [REST API compatibility](elasticsearch://reference/elasticsearch/rest-apis/compatibility.md) to maintain compatibility with the 9.x {{es}} server. ::: From 2f2f38138fe9b292bccb1f61cfbbc5076025e223 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Wed, 30 Jul 2025 18:04:32 +0200 Subject: [PATCH 26/30] preparation intro update --- deploy-manage/upgrade/prepare-to-upgrade.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/deploy-manage/upgrade/prepare-to-upgrade.md b/deploy-manage/upgrade/prepare-to-upgrade.md index 5195baa6ff..c81e9a11a5 100644 --- a/deploy-manage/upgrade/prepare-to-upgrade.md +++ b/deploy-manage/upgrade/prepare-to-upgrade.md @@ -16,14 +16,14 @@ products: --- # Prepare to upgrade -When upgrading an existing cluster, you perform a major, minor, or patch upgrade. A minor upgrade, for example, takes you from version 9.0.0 to 9.1.0; a major upgrade from 8.19.0 to 9.1.0; and a patch upgrade from 9.0.0 to 9.0.4. +This document describes the preparation steps for upgrading {{es}}, which vary depending on the type of upgrade. These steps follow the [upgrade planning](./plan-upgrade.md) phase, and should be completed before proceeding to [upgrade your deployment or cluster](./deployment-or-cluster.md). + +When upgrading an existing cluster, you perform a major, minor, or patch upgrade. A minor upgrade, for example, can take you from version 9.0.2 to 9.1.x; a major upgrade from 8.19.x to {{version.stack}}; and a patch upgrade from 9.0.1 to 9.0.4. :::{important} Upgrading from a release candidate build, such as 9.0.0-rc1, is unsupported. Use pre-releases only for testing in a temporary environment. ::: -This document describes the preparation steps for upgrading {{es}}, which vary depending on the type of upgrade. These steps follow the [upgrade planning](./plan-upgrade.md) phase, and should be completed before proceeding to [upgrade your deployment or cluster](./deployment-or-cluster.md). - ## Common preparation steps for all upgrades The following steps are common to all types of upgrades, regardless if you are upgrading from 8.x (major upgrade), or if you are already running a 9.x version. From 43033031905fbf66c8aac2461e2d7fb63f5fac95 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Wed, 30 Jul 2025 18:44:11 +0200 Subject: [PATCH 27/30] stepper included in preparations --- deploy-manage/upgrade/prepare-to-upgrade.md | 167 +++++++++++--------- 1 file changed, 91 insertions(+), 76 deletions(-) diff --git a/deploy-manage/upgrade/prepare-to-upgrade.md b/deploy-manage/upgrade/prepare-to-upgrade.md index c81e9a11a5..1ee1756244 100644 --- a/deploy-manage/upgrade/prepare-to-upgrade.md +++ b/deploy-manage/upgrade/prepare-to-upgrade.md @@ -26,64 +26,69 @@ Upgrading from a release candidate build, such as 9.0.0-rc1, is unsupported. Use ## Common preparation steps for all upgrades -The following steps are common to all types of upgrades, regardless if you are upgrading from 8.x (major upgrade), or if you are already running a 9.x version. +The following steps and recommendations are common to all types of upgrades, regardless if you are upgrading from 8.x (major upgrade), or if you are already running a 9.x version. -1. **Review breaking changes** +:::::{stepper} - Although breaking changes typically affect [major upgrades](#prepare-upgrade-from-8.x), they can also occur in minor or patch releases. Review the [breaking changes](../../release-notes/index.md) for each product you use to learn more about potential impacts on your applications. Ensure you test with the new version before upgrading production deployments. +::::{step} Review breaking changes +Although breaking changes typically affect [major upgrades](#prepare-upgrade-from-8.x), they can also occur in minor or patch releases. Review the [breaking changes](../../release-notes/index.md) for each product you use to learn more about potential impacts on your applications. Ensure you test with the new version before upgrading production deployments. - If you are affected by a breaking change, you have to take action before upgrading. This can include updating your code, change configuration settings, or other steps. +If you are affected by a breaking change, you have to take action before upgrading. This can include updating your code, change configuration settings, or other steps. +:::: -2. **Verify plugin compatibility** +::::{step} Verify plugin compatibility +If you use [{{es}} plugins](elasticsearch://reference/elasticsearch-plugins/index.md), ensure each plugin is compatible with the {{es}} version you're upgrading to. +:::: - If you use [{{es}} plugins](elasticsearch://reference/elasticsearch-plugins/index.md), ensure each plugin is compatible with the {{es}} version you're upgrading to. +::::{step} Create a snapshot for backup +Take a [snapshot](/deploy-manage/tools/snapshot-and-restore/create-snapshots.md) of your cluster before starting the upgrade. This provides a recovery point in case the upgrade needs to be rolled back. -3. **Test in a non-production environment** - - Before upgrading your production deployment, test the upgrade using a non-production environment. Make sure the test environment mirrors production as closely as possible, including configuration and client interactions. - - :::{note} - 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 behavior in your environment. - ::: - - :::{tip} - During your upgrade tests, pay particular attention to the following aspects: - - **Cluster stability** - : Does the new version of {{es}} form a stable healthy cluster? +:::{important} +After you start to upgrade your {{es}} cluster, you cannot downgrade any of its nodes. If you can't complete the upgrade process, you must [restore from a snapshot](/deploy-manage/tools/snapshot-and-restore/restore-snapshot.md) which was taken before starting the upgrade. +::: +:::: - **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? +::::{step} Test in a non-production environment +Before upgrading your production deployment, test the upgrade using a non-production environment. Make sure the test environment mirrors production as closely as possible, including configuration and client interactions. - **Snapshots** - : Do all of your snapshot repositories work correctly and pass [repository analysis](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-snapshot-repository-analyze)? - ::: +:::{note} +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 behavior in your environment. +::: -4. **Create a snapshot for backup** +:::{tip} +During your upgrade tests, pay particular attention to the following aspects: - Take a [snapshot](/deploy-manage/tools/snapshot-and-restore/create-snapshots.md) of your cluster before starting the upgrade. This provides a recovery point in case the upgrade needs to be rolled back. +**Cluster stability** +: Does the new version of {{es}} form a stable healthy cluster? - :::{important} - After you start to upgrade your {{es}} cluster, you cannot downgrade any of its nodes. If you can't complete the upgrade process, you must [restore from a snapshot](/deploy-manage/tools/snapshot-and-restore/restore-snapshot.md) which was taken before starting the upgrade. - ::: +**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? -5. **Upgrade your monitoring cluster first** +**Snapshots** +: Do all of your snapshot repositories work correctly and pass [repository analysis](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-snapshot-repository-analyze)? +::: - If you use a separate [monitoring cluster](/deploy-manage/monitor/stack-monitoring/elasticsearch-monitoring-self-managed.md), upgrade the monitoring cluster before the production cluster. +:::: - The monitoring cluster should be running the same version, or a newer one, than the clusters being monitored. It cannot monitor clusters running a newer version of the {{stack}}. If necessary, the monitoring cluster can monitor clusters running the latest release of the previous major version. +::::{step} Upgrade your monitoring cluster first +If you use a separate [monitoring cluster](/deploy-manage/monitor/stack-monitoring/elasticsearch-monitoring-self-managed.md), upgrade the monitoring cluster before the production cluster. -6. **Remote clusters** +The monitoring cluster should be running the same version, or a newer one, than the clusters being monitored. It cannot monitor clusters running a newer version of the {{stack}}. If necessary, the monitoring cluster can monitor clusters running the latest release of the previous major version. +:::: - If you use {{ccs}}, versions 9.0.0 and later can search only remote clusters running the previous minor version, the same version, or a newer minor version in the same major version. For more information, refer to [{{ccs-cap}}](../../solutions/search/cross-cluster-search.md). +::::{step} Upgrade remote clusters first +If you use {{ccs}}, versions 9.0.0 and later can search only remote clusters running the previous minor version, the same version, or a newer minor version in the same major version. For more information, refer to [{{ccs-cap}}](../../solutions/search/cross-cluster-search.md). - If you use {{ccr}}, a cluster that contains follower indices must run the same or newer (compatible) version as the remote cluster. For more information and to view the version compatibility matrix, refer to [{{ccr-cap}}](/deploy-manage/tools/cross-cluster-replication.md). +If you use {{ccr}}, a cluster that contains follower indices must run the same or newer (compatible) version as the remote cluster. For more information and to view the version compatibility matrix, refer to [{{ccr-cap}}](/deploy-manage/tools/cross-cluster-replication.md). - To view your remote clusters in {{kib}}, go to **Stack Management > Remote Clusters**. +To view your remote clusters in {{kib}}, go to **Stack Management > Remote Clusters**. +:::: -7. (Optional) **Close {{ml}} jobs** +::::{step} (Optional) Close machine learning jobs +To reduce overhead on the cluster during the upgrade, close {{ml}} jobs before starting the upgrade, and open them after the upgrade is complete. Although {{ml}} jobs can run during a rolling upgrade, doing so increases the cluster workload. +:::: - To reduce overhead on the cluster during the upgrade, close {{ml}} jobs before starting the upgrade, and open them after the upgrade is complete. Although {{ml}} jobs can run during a rolling upgrade, doing so increases the cluster workload. +::::: ## Additional preparation steps to upgrade from 8.x [prepare-upgrade-from-8.x] @@ -93,69 +98,79 @@ To assist with this process, use the [Upgrade Assistant](prepare-to-upgrade/upgr Follow these steps to prepare for a successful major upgrade from 8.x to 9.x: -1. **Upgrade to the latest 8.19 patch release** +:::::{stepper} - To perform a major upgrade from 8.x to 9.x of {{es}}, you must first upgrade to 8.19.x. This allows you to use the [Upgrade Assistant](prepare-to-upgrade/upgrade-assistant.md) to identify and resolve issues, reindex indices created before 8.0.0, and prepare the cluster for the actual upgrade. Upgrading to 8.19 is required regardless of whether you perform a rolling upgrade or a full cluster restart to upgrade. +::::{step} Upgrade to the latest 8.19 patch release - ::::{note} - Because 8.18.0 and 9.0.0 were released simultaneously, upgrading from 8.18.x to 9.0.x is supported, as long as the versions comply with the supported [upgrade paths](../upgrade.md#upgrade-paths). However, upgrading to 9.1.0 or later requires starting from 8.19.x. +To perform a major upgrade from 8.x to 9.x of {{es}}, you must first upgrade to 8.19.x. This allows you to use the [Upgrade Assistant](prepare-to-upgrade/upgrade-assistant.md) to identify and resolve issues, reindex indices created before 8.0.0, and prepare the cluster for the actual upgrade. Upgrading to 8.19 is required regardless of whether you perform a rolling upgrade or a full cluster restart to upgrade. - If you're upgrading to the current {{version.stack}} release from an earlier 8.x version, first upgrade to the latest available 8.19 release. - :::: +:::{note} +Because 8.18.0 and 9.0.0 were released simultaneously, upgrading from 8.18.x to 9.0.x is supported, as long as the versions comply with the supported [upgrade paths](../upgrade.md#upgrade-paths). However, upgrading to 9.1.0 or later requires starting from 8.19.x. - If you are already running an 8.19.x version, it's also recommended to upgrade to the latest 8.19 patch release before upgrading to 9.x. This ensures that the latest version of the upgrade assistant is used, and any bug fixes that could have implications for the upgrade are applied. +If you're upgrading to the current {{version.stack}} release from an earlier 8.x version, first upgrade to the latest available 8.19 release. +::: - If you're using 7.x and earlier, you may need to complete multiple upgrades to reach the latest 8.19 patch release before upgrading to 9.x. As an alternative method to upgrading the cluster, you can create a new 9.x deployment and reindex from the original cluster. For more information, refer to [Reindex to upgrade](#reindex-to-upgrade). +If you are already running an 8.19.x version, it's also recommended to upgrade to the latest 8.19 patch release before upgrading to 9.x. This ensures that the latest version of the upgrade assistant is used, and any bug fixes that could have implications for the upgrade are applied. - :::{note} - For flexible upgrade scheduling, 8.19.x {{agent}}, {{beats}} and {{ls}} are compatible with all 9.x versions of {{es}}. +If you're using 7.x and earlier, you may need to complete multiple upgrades to reach the latest 8.19 patch release before upgrading to 9.x. As an alternative method to upgrading the cluster, you can create a new 9.x deployment and reindex from the original cluster. For more information, refer to [Reindex to upgrade](#reindex-to-upgrade). - By default, 8.x {{es}} clients are compatible with 9.x and use [REST API compatibility](elasticsearch://reference/elasticsearch/rest-apis/compatibility.md) to maintain compatibility with the 9.x {{es}} server. - ::: +:::{note} +For flexible upgrade scheduling, 8.19.x {{agent}}, {{beats}} and {{ls}} are compatible with all 9.x versions of {{es}}. + +By default, 8.x {{es}} clients are compatible with 9.x and use [REST API compatibility](elasticsearch://reference/elasticsearch/rest-apis/compatibility.md) to maintain compatibility with the 9.x {{es}} server. +::: +:::: -2. **Run the Upgrade Assistant** +::::{step} Run the Upgrade Assistant + +The [Upgrade Assistant](prepare-to-upgrade/upgrade-assistant.md) identifies deprecated settings in your configuration and guides you through resolving issues that could prevent a successful upgrade. The Upgrade Assistant also helps resolve issues with older indices created before version 8.0.0, providing the option to reindex older indices or mark them as read-only. To prevent upgrade failures, we strongly recommend you **do not** skip this step. + +:::{note} + Depending on your setup, reindexing can change your indices, and you may need to update alerts, transforms, or other code targeting the old index. +::: - The [Upgrade Assistant](prepare-to-upgrade/upgrade-assistant.md) identifies deprecated settings in your configuration and guides you through resolving issues that could prevent a successful upgrade. The Upgrade Assistant also helps resolve issues with older indices created before version 8.0.0, providing the option to reindex older indices or mark them as read-only. To prevent upgrade failures, we strongly recommend you **do not** skip this step. +Considerations when using the upgrade assistant: - :::{note} - Depending on your setup, reindexing can change your indices, and you may need to update alerts, transforms, or other code targeting the old index. - ::: +* For a successful upgrade, **resolve all critical issues reported by the assistant**. {{es}} nodes will fail to start if incompatible indices are present. - Considerations when using the upgrade assistant: +* Before you apply configuration changes or reindex, ensure you have a current [snapshot](/deploy-manage/tools/snapshot-and-restore/create-snapshots.md). - 1. For a successful upgrade, **resolve all critical issues reported by the assistant**. +* Indices created in 7.x or earlier must be reindexed, deleted, or [archived](/deploy-manage/upgrade/deployment-or-cluster/reading-indices-from-older-elasticsearch-versions.md) (marked as read-only) before upgrading to 9.x. - 2. Before you apply configuration changes or reindex, ensure you have a current [snapshot](/deploy-manage/tools/snapshot-and-restore/create-snapshots.md). + :::{tip} + In Elasticsearch 9.x, you can also use the [archive functionality](/deploy-manage/upgrade/deployment-or-cluster/reading-indices-from-older-elasticsearch-versions.md) to access snapshots of 7.x or earlier indices, without needing to reindex or run an older cluster. This provides a convenient option to retain historical data in case you choose to delete those indices and keep them only in existing snapshots. + ::: - 3. Indices created in 7.x or earlier must be reindexed or deleted before upgrading to 9.x. Alternatively, you can use the [archive functionality](/deploy-manage/upgrade/deployment-or-cluster/reading-indices-from-older-elasticsearch-versions.md) to enable read-only access to them in 9.x. Keep in mind that {{es}} nodes will fail to start if incompatible indices are present. +* Review the deprecation logs from the Upgrade Assistant to determine if your applications are using features that are not supported or behave differently in 9.x. See the [breaking changes](elasticsearch://release-notes/breaking-changes.md) for more information about changes in 9.x that could affect your application. - ::::{tip} - In Elasticsearch 9.x, you can use the [archive functionality](/deploy-manage/upgrade/deployment-or-cluster/reading-indices-from-older-elasticsearch-versions.md) to access snapshots of 7.x or earlier indices, without needing to reindex or run an older cluster. This provides a convenient option to retain historical data in case you choose to delete those indices and keep them only in existing snapshots. - :::: + :::{note} + Make sure you check the breaking changes for each 9.x release up to your target release. + ::: - 3. Review the deprecation logs from the Upgrade Assistant to determine if your applications are using features that are not supported or behave differently in 9.x. See the [breaking changes](elasticsearch://release-notes/breaking-changes.md) for more information about changes in 9.x that could affect your application. +* Make the recommended changes to ensure your clients continue operating as expected after the upgrade. - ::::{note} - Make sure you check the breaking changes for each 9.x release up to your target release. - :::: + :::{note} + As a temporary solution, use the 8.x syntax to submit requests to 9.x with REST API compatibility mode. While this allows you to submit requests using the old syntax, it doesn’t guarantee the same behavior. REST API compatibility should serve as a bridge during the upgrade, not a long-term solution. For more details on how to effectively use REST API compatibility during an upgrade, refer to [REST API compatibility](elasticsearch://reference/elasticsearch/rest-apis/compatibility.md). + ::: +:::: - 4. Make the recommended changes to ensure your clients continue operating as expected after the upgrade. +::::{step} Manage CCR follower data streams +If you have {{ccr-cap}} (CCR) data streams, and your indices require reindexing, refer to [Upgrade uni-directional {{ccr}} clusters with followed data streams](#upgrade-ccr-data-streams) for specific instructions. +:::: - :::{note} - As a temporary solution, use the 8.x syntax to submit requests to 9.x with REST API compatibility mode. While this allows you to submit requests using the old syntax, it doesn’t guarantee the same behavior. REST API compatibility should serve as a bridge during the upgrade, not a long-term solution. For more details on how to effectively use REST API compatibility during an upgrade, refer to [REST API compatibility](elasticsearch://reference/elasticsearch/rest-apis/compatibility.md). - ::: +::::{step} Manage old machine learning indices +If you have `.ml-anomalies-*` anomaly detection result indices created in {{es}} 7.x, reindex them, mark them as read-only, or delete them before you upgrade to 9.x. For more information, refer to [Migrate anomaly detection results](#anomaly-migration). +:::: -3. **Manage {{ccr-cap}} (CCR) follower data streams** +::::{step} Manage old transform indices +If you have transform destination indices created in {{es}} 7.x, reset, reindex, or delete them before you upgrade to 9.x. For more information, refer to [Migrate transform destination indices](#transform-migration). +:::: - If you have {{ccr-init}} data streams, and your indices require reindexing, refer to [Upgrade uni-directional {{ccr}} clusters with followed data streams](#upgrade-ccr-data-streams) for specific instructions. +::::: -4. **Manage old {{ml}} indices** - If you have `.ml-anomalies-*` anomaly detection result indices created in {{es}} 7.x, reindex them, mark them as read-only, or delete them before you upgrade to 9.x. For more information, refer to [Migrate anomaly detection results](#anomaly-migration). -5. **Manage old transform indices** - If you have transform destination indices created in {{es}} 7.x, reset, reindex, or delete them before you upgrade to 9.x. For more information, refer to [Migrate transform destination indices](#transform-migration). ## Upgrade uni-directional {{ccr}} clusters with followed data streams [upgrade-ccr-data-streams] From b1d62f50a9c72da0c83d4b26497629dba96107a3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Thu, 31 Jul 2025 21:56:21 +0200 Subject: [PATCH 28/30] availability during upgrades and some final refinement --- deploy-manage/upgrade.md | 17 +++++++ .../upgrade/deployment-or-cluster/kibana.md | 7 ++- deploy-manage/upgrade/plan-upgrade.md | 46 +++++++++++++------ deploy-manage/upgrade/prepare-to-upgrade.md | 27 ++--------- 4 files changed, 58 insertions(+), 39 deletions(-) diff --git a/deploy-manage/upgrade.md b/deploy-manage/upgrade.md index 6104393a49..a227a8e6fb 100644 --- a/deploy-manage/upgrade.md +++ b/deploy-manage/upgrade.md @@ -50,6 +50,23 @@ Upgrading your Elastic cluster or deployment involves several stages, including Additionally, if you're using a self-managed orchestration platform such as {{ece}} or {{eck}}, refer to [Upgrade your ECE or ECK orchestrator](/deploy-manage/upgrade/orchestrator.md) to keep the orchestrator up to date. +## Availability during upgrades + +{{es}} supports rolling upgrades, where nodes are upgraded one at a time to minimize downtime and ensure cluster stability. If your deployment or cluster follows high availability best practices, such as using replicated indices and distributing nodes across multiple availability zones, it should remain available throughout the entire upgrade process. + +{{kib}} upgrades, however, require downtime. All running instances must be shut down before starting the upgrade. + +::::{important} +Ensure your deployment is properly sized and configured for high availability to reduce the risk of service interruption during upgrades. + +If you want to learn more about scaling, high availability, and performance, refer to: +* [Run {{es}} in production](/deploy-manage/production-guidance/elasticsearch-in-production-environments.md) +* [Run {{kib}} in production](/deploy-manage/production-guidance/kibana-in-production-environments.md) +* [{{ech}} > Plan for production](/deploy-manage/deploy/elastic-cloud/elastic-cloud-hosted-planning.md) +:::: + +You’ll find more information about availability considerations for specific deployment types in the related upgrade guides within this section. + ## Upgrade paths [upgrade-paths] You can upgrade to a higher version if the target version was released *after* your current version. Upgrades to versions released *before* your current version are not supported, even if the version number is higher. Refer to [out-of-order releases](/deploy-manage/upgrade/deployment-or-cluster.md#out-of-order-releases) for more information. diff --git a/deploy-manage/upgrade/deployment-or-cluster/kibana.md b/deploy-manage/upgrade/deployment-or-cluster/kibana.md index 46c8bef3a2..1f1c723b78 100644 --- a/deploy-manage/upgrade/deployment-or-cluster/kibana.md +++ b/deploy-manage/upgrade/deployment-or-cluster/kibana.md @@ -11,14 +11,14 @@ products: When you upgrade {{kib}}, you also upgrade the {{observability}} and {{elastic-sec}} solutions, which use {{kib}} as their main interface. +{{kib}} must always be upgraded after {{es}}, and to the same version. Version mismatches or upgrading in the wrong order can result in failures or unexpected behavior. + ::::{warning} {{kib}} automatically runs saved object migrations when required. To roll back to an earlier version in case of an upgrade failure, you **must** have a [backup snapshot](../../tools/snapshot-and-restore.md) that includes the `kibana` feature state. Snapshots include this feature state by default. For more information, refer to [Migrate saved objects](saved-object-migrations.md). - :::: - ## 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. @@ -29,8 +29,7 @@ For large deployments with more than 10 {{kib}} instances, and more than 10,000 ## Preparing for upgrading [preventing-migration-failures] -Before you start, ensure you [take the upgrade preparation steps](/deploy-manage/upgrade/prepare-to-upgrade.md). Then, take these extra steps to ensure you are ready to upgrade. - +Before you start, ensure that you’ve followed the [Plan your upgrade](/deploy-manage/upgrade/plan-upgrade.md) guidelines, completed the [upgrade preparation steps](/deploy-manage/upgrade/prepare-to-upgrade.md), and [upgraded the {{es}} cluster](./elasticsearch.md). ### Ensure your {{es}} cluster is healthy [_ensure_your_es_cluster_is_healthy] diff --git a/deploy-manage/upgrade/plan-upgrade.md b/deploy-manage/upgrade/plan-upgrade.md index 761951f76d..6ee41ef1cb 100644 --- a/deploy-manage/upgrade/plan-upgrade.md +++ b/deploy-manage/upgrade/plan-upgrade.md @@ -28,29 +28,38 @@ The objective of this section is to facilitate the creation of an upgrade plan t Before upgrading, verify that your current environment supports the version you plan to upgrade to. If not, identify any required intermediate upgrades or component changes and include them in your upgrade plan. -* **System requirements**: Ensure your current operating system is supported by the target versions of {{es}}, {{kib}}, and any ingest components. Refer to the [Product and Operating System support matrix](https://www.elastic.co/support/matrix#matrix_os). +**{{es}} upgrade path** +: Check the [upgrade paths](../upgrade.md#upgrade-paths) to determine whether you must upgrade through an intermediate version (such as 8.19.x before moving 9.1+), or if you can upgrade directly to the target version. -* **Ingest component compatibility**: Confirm that your ingest components, such as {{beats}}, {{ls}}, or {{agent}}, are compatible with the target {{es}} version. If they’re not, upgrade them first. Refer to [conduct a component inventory](#conduct-a-component-inventory) for guidance. +**System requirements** +: Ensure your current operating system is supported by the target versions of {{es}}, {{kib}}, and any ingest components. Refer to the [Product and Operating System support matrix](https://www.elastic.co/support/matrix#matrix_os). -* **Orchestrator compatibility**: If you’re using an orchestrator like {{ece}} or {{eck}}, verify that it supports the target {{stack}} version. If not, [upgrade the orchestrator](/deploy-manage/upgrade/orchestrator.md) before upgrading your cluster. Refer to: - * [ECE – Stack packs](/deploy-manage/deploy/cloud-enterprise/manage-elastic-stack-versions.md#ece_most_recent_elastic_stack_packs) - * [ECK – {{stack}} compatibility](/deploy-manage/deploy/cloud-on-k8s.md#stack-compatibility) +**OpenJDK compatibility and FIPS compliance** +: By default, {{es}} is built using Java and includes a bundled version of [OpenJDK](https://openjdk.java.net/) in each distribution. While we strongly recommend using the bundled Java Virtual Machine (JVM) in all installations of {{es}}, if you choose to use your own JVM, ensure it’s compatible by reviewing the [Product and JVM support matrix](https://www.elastic.co/support/matrix#matrix_jvm). -* **Rest API compatibility**: If you use custom-developed applications or clients, ensure the [{{es}} client libraries](/reference/elasticsearch-clients/index.md) are compatible with the target version. If your applications use deprecated or removed APIs, then you might need to update the client code first. + If you’re running {{es}} in FIPS 140-2 mode, we recommend using [Bouncy Castle](https://www.bouncycastle.org/java.html) as a Java security provider when running {{es}}. - ::::{note} - By default, 8.x {{es}} clients are compatible with 9.x and use [REST API compatibility](elasticsearch://reference/elasticsearch/rest-apis/compatibility.md) to maintain compatibility with the 9.x {{es}} cluster. +**Ingest component compatibility** +: Confirm that your ingest components, such as {{beats}}, {{ls}}, or {{agent}}, are compatible with the target {{es}} version. If they’re not, upgrade them first. Refer to [conduct a component inventory](#conduct-a-component-inventory) for guidance. + +**Rest API compatibility** +: If you use custom-developed applications or clients, ensure the [{{es}} client libraries](/reference/elasticsearch-clients/index.md) are compatible with the target version. If your applications use deprecated or removed APIs, then you might need to update the client code first. + :::{note} + By default, 8.x {{es}} clients are compatible with 9.x and use [REST API compatibility](elasticsearch://reference/elasticsearch/rest-apis/compatibility.md) to maintain compatibility with the 9.x {{es}} cluster. REST API compatibility is a per-request opt-in feature that can help REST clients mitigate non-compatible (breaking) changes to the REST API. - :::: + ::: -* **Index compatibility**: {{es}} provides full query and write support for indices created in the previous major version. If you have indices created in 7.x or earlier, you must reindex, delete, or [archive](/deploy-manage/upgrade/deployment-or-cluster/reading-indices-from-older-elasticsearch-versions.md) them before upgrading to 9.x. This topic is covered during the [upgrade preparations](prepare-to-upgrade.md#prepare-upgrade-from-8.x), with help from the Upgrade Assistant. +**Index compatibility** +: {{es}} provides full query and write support for indices created in the previous major version. If you have indices created in 7.x or earlier, you must reindex, delete, or [archive](/deploy-manage/upgrade/deployment-or-cluster/reading-indices-from-older-elasticsearch-versions.md) them before upgrading to 9.x. -* **{{es}} upgrade path**: Check the [upgrade paths](../upgrade.md#upgrade-paths) to determine whether you must upgrade through an intermediate version (such as 8.19.x before moving to 9.1+), or if you can upgrade directly to the target version. + This topic is covered during the [upgrade preparations](prepare-to-upgrade.md#prepare-upgrade-from-8.x), with help from the Upgrade Assistant. -* **OpenJDK compatibility and FIPS compliance**: By default, {{es}} is built using Java and includes a bundled version of [OpenJDK](https://openjdk.java.net/) in each distribution. While we strongly recommend using the bundled Java Virtual Machine (JVM) in all installations of {{es}}, if you choose to use your own JVM, ensure it’s compatible by reviewing the [Product and JVM support matrix](https://www.elastic.co/support/matrix#matrix_jvm). +**Orchestrator compatibility** +: If you’re using an orchestrator like {{ece}} or {{eck}}, verify that it supports the target {{stack}} version. If not, [upgrade the orchestrator](/deploy-manage/upgrade/orchestrator.md) before upgrading your cluster. Refer to: + * [ECE – Stack packs compatibility](/deploy-manage/deploy/cloud-enterprise/manage-elastic-stack-versions.md#ece_most_recent_elastic_stack_packs) + * [ECK – {{stack}} compatibility](/deploy-manage/deploy/cloud-on-k8s.md#stack-compatibility) - If you’re running {{es}} in FIPS 140-2 mode, we recommend using [Bouncy Castle](https://www.bouncycastle.org/java.html) as a Java security provider when running {{es}}. ## Conduct a component inventory @@ -103,6 +112,17 @@ We highly recommend testing the upgrade process in a non-production environment * Alerts * Authentication +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 [repository analysis](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-snapshot-repository-analyze)? + ## Upgrade order When upgrading the {{stack}}, the process begins with {{es}}, followed by {{kib}}, which must always be aligned in terms of versioning. Other components can remain on earlier versions as long as they are compatible with the target {{es}} version, though we recommend upgrading them as well to benefit from the latest features and fixes. diff --git a/deploy-manage/upgrade/prepare-to-upgrade.md b/deploy-manage/upgrade/prepare-to-upgrade.md index 1ee1756244..270f57c6f2 100644 --- a/deploy-manage/upgrade/prepare-to-upgrade.md +++ b/deploy-manage/upgrade/prepare-to-upgrade.md @@ -49,25 +49,12 @@ After you start to upgrade your {{es}} cluster, you cannot downgrade any of its :::: ::::{step} Test in a non-production environment -Before upgrading your production deployment, test the upgrade using a non-production environment. Make sure the test environment mirrors production as closely as possible, including configuration and client interactions. +Before upgrading your production deployment, test the upgrade using a non-production environment. Make sure the test environment mirrors production as closely as possible, including configuration and client interactions. Refer to [](./plan-upgrade.md#test-in-a-non-production-environment) for more details and recommendations. :::{note} 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 behavior in your environment. ::: -:::{tip} -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 [repository analysis](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-snapshot-repository-analyze)? -::: - :::: ::::{step} Upgrade your monitoring cluster first @@ -85,11 +72,13 @@ To view your remote clusters in {{kib}}, go to **Stack Management > Remote Clust :::: ::::{step} (Optional) Close machine learning jobs -To reduce overhead on the cluster during the upgrade, close {{ml}} jobs before starting the upgrade, and open them after the upgrade is complete. Although {{ml}} jobs can run during a rolling upgrade, doing so increases the cluster workload. +To reduce overhead on the cluster during the upgrade, close [{{ml}} jobs](/explore-analyze/machine-learning/anomaly-detection/ml-ad-run-jobs.md) before starting the upgrade, and open them after the upgrade is complete. Although {{ml}} jobs can run during a rolling upgrade, doing so increases the cluster workload. :::: ::::: +If you are preparing a minor or patch upgrade, you're ready to [upgrade your deployment or cluster](./deployment-or-cluster.md). If you are preparing a major upgrade, continue with the [preparations to upgrade from 8.x](#prepare-upgrade-from-8.x). + ## Additional preparation steps to upgrade from 8.x [prepare-upgrade-from-8.x] Major upgrades require additional planning and preparation, as they often introduce a significant number of breaking changes and require additional steps to ensure a smooth transition. @@ -168,9 +157,7 @@ If you have transform destination indices created in {{es}} 7.x, reset, reindex, ::::: - - - +After completing all the preparation steps, you're ready to [upgrade your deployment or cluster](./deployment-or-cluster.md). ## Upgrade uni-directional {{ccr}} clusters with followed data streams [upgrade-ccr-data-streams] @@ -830,7 +817,3 @@ If you are running a pre-8.x version, you might need to perform multiple upgrade 2. To reindex your data into the new {{es}} cluster, use the [reindex documents API](https://www.elastic.co/docs/api/doc/elasticsearch/v8/operation/operation-reindex) and temporarily send new indexing requests to both clusters. 3. Verify the new cluster performs as expected, fix any problems, and then permanently swap in the new cluster. 4. Delete the old deployment. On {{ecloud}}, you are billed for the time the new deployment runs in parallel with your old deployment. Usage is billed on an hourly basis. - -## Next steps - -After completing all the preparation steps, you're ready to [upgrade your deployment or cluster](./deployment-or-cluster.md). From db1e78cc1bbc406ad09a0a3965c06985cd9fcc4c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Fri, 1 Aug 2025 10:20:13 +0200 Subject: [PATCH 29/30] minor update on upgrade order --- deploy-manage/upgrade/plan-upgrade.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/deploy-manage/upgrade/plan-upgrade.md b/deploy-manage/upgrade/plan-upgrade.md index 6ee41ef1cb..86bb58087c 100644 --- a/deploy-manage/upgrade/plan-upgrade.md +++ b/deploy-manage/upgrade/plan-upgrade.md @@ -134,7 +134,7 @@ In general, you should upgrade the components of your {{stack}} in the following 3. {{fleet-server}} and Elastic APM (if used) 4. Ingest tools ({{beats}}, {{agent}}, {{ls}}, etc.) and {{es}} client libraries -If your deployment runs on {{ech}} or {{ece}}, the platform handles the upgrade and component order automatically in a single plan execution. You only need to upgrade any external ingest tools afterward. +If your deployment runs on {{ech}} or {{ece}}, the platform handles the upgrade and component order automatically in a single plan execution, including the {{fleet-server}} and APM as part of the Integrations Server. You only need to upgrade any external ingest tools afterward. ::::{note} If you use a separate [monitoring cluster](/deploy-manage/monitor/stack-monitoring/elasticsearch-monitoring-self-managed.md), upgrade the monitoring cluster before the production cluster. From 2aa6077e1766e816ad647fa369a578816522d5b7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Edu=20Gonz=C3=A1lez=20de=20la=20Herr=C3=A1n?= <25320357+eedugon@users.noreply.github.com> Date: Fri, 1 Aug 2025 10:28:39 +0200 Subject: [PATCH 30/30] minor update on plan example --- deploy-manage/upgrade/plan-upgrade.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/deploy-manage/upgrade/plan-upgrade.md b/deploy-manage/upgrade/plan-upgrade.md index 86bb58087c..b11645a945 100644 --- a/deploy-manage/upgrade/plan-upgrade.md +++ b/deploy-manage/upgrade/plan-upgrade.md @@ -150,7 +150,8 @@ The minimum steps your plan should include are: 1. Upgrade {{es}} and {{kib}} to the latest 8.19 version, as a requirement for the major upgrade to {{version.stack}}. 2. Upgrade all ingest components to the latest 8.19 version, as otherwise they won't be compatible with {{es}} running {{version.stack}}. -3. Upgrade {{es}} and {{kib}} to {{version.stack}}. +3. Follow all [preparation steps](./prepare-to-upgrade.md) and use the upgrade assistant to ensure the cluster is ready for a major upgrade. +4. {{es}} and {{kib}} to {{version.stack}}. ## Next steps