How to upgrade Elasticsearch versions

Introduction

Updating distributed systems, including Elasticsearch, can be a complex process due to the large volume of data, the number of nodes involved and the different configurations you may have in your cluster. In this article, we explain how to minimize risks when upgrading your Elasticsearch cluster.

There are two approaches to upgrading Elasticsearch service versions. The two options are full cluster restarts and rolling restarts. In the rest of the article we will discuss each in turn.

Always keep in mind that any changes to your system may result in data loss if you do not follow the instructions correctly. Always test and plan your upgrade carefully and take a backup of your data before performing any upgrades.

We’ll start with a review of important considerations, but you can jump to the instructions for full cluster restart upgrades and rolling restart upgrades anytime.

Elastic product EOL (End Of Life) dates

Each Elasticsearch version has its own end of life, and Elasticsearch explicitly mentions that each major version (release) of products is supported for 18 months after the release.

Read more

Note: In general it is recommended to always upgrade to the highest version possible, subject to compatibility / availability of any client libraries or plugins you are using. Also, please note that there are no EOL dates per minor version anymore. They just state that the 8.x release train will be maintained until “the later of 2026-06-10 or 6 months after the release date of 9.0.”

Compatibility matrix

Note: Elasticsearch version 7.17 is the last version that works with JDK 1.8 .

Master nodes or non-master nodes? Which should be upgraded first?

Before starting an upgrade, you need to divide your cluster into:

• Master-eligible nodes
• Master-ineligible nodes

The reason for this categorization is that higher version Elasticsearch master-ineligible nodes can always join a cluster with a lower version master node, but lower version master-ineligible nodes cannot join a higher version cluster.

This means that if you upgrade your master-eligible nodes before master-ineligible nodes, there is the possibility that some of the master-ineligible nodes leave the cluster and cannot rejoin. For this reason, it is necessary to first upgrade all master-ineligible nodes.

Preparing to upgrade Elasticsearch nodes

Elasticsearch nodes cannot be downgraded after upgrading. Before starting the upgrade process you should review the following:

Check the deprecation log

You should read and resolve any issues highlighted in the deprecation log. These logs are usually located in:

/var/log/elasticsearch/Your-Cluster-Name_deprecation.log

Upgrade Assistant in Kibana

In the last minor version of each major version, eg. 6.8.23 or 7.17.10, you will find an upgrade assistant to help you ensure that your cluster settings and configurations are compatible with the next version. Use the menu in Kibana to navigate to the assistant. You must clear all issues using the assistant before attempting to upgrade to the next major version.

Review the breaking changes

With each new version, breaking changes documentation is published to make you aware of any functionality which may change or disappear. You should always check this to ensure that none of these settings, configurations or mappings are being used in your setup. The main things that could be affected are:

• Node configuration (elasticsearch.yml)
• Index mappings and templates
• Cluster settings

Check the Elasticsearch plugins compatibility

If you are using any Elasticsearch plugins, you should check the availability and compatibility of the plugin with the new version.

Set up a test environment

You should test the upgrade process in a test or staging environment before upgrading your production cluster in order to check and resolve all issues before upgrading production.

Take a backup and snapshots from your data

Remember that it is not possible to downgrade an Elasticsearch node, and the only way to practically reverse a failed upgrade will be to create a new cluster with the old version and recover your data from snapshots. Therefore it is essential to take snapshots of all Elasticsearch indices before starting the upgrade process.

Full cluster restart upgrade (offline upgrade)

A full cluster restart upgrade consists of shutting down all the Elasticsearch nodes at once, upgrading all of them and then restarting each node. This type of upgrade will inevitably require your Elasticsearch cluster to be down for the duration of the upgrading process.

Offline upgrades are usually easier than online upgrades since you do not have to manage a cluster with different versions of nodes at the same time.

The steps are:

1. Disable shard allocation
2. Optionally stop non-essential indexing and perform a flush
3. Optionally stop the tasks associated with ML jobs and datafeeds
4. Stop all Elasticsearch nodes and upgrade them
5. Upgrade any plugins
6. Start the Elasticsearch cluster
7. Re-enable shard allocation
8. Upgrade client libraries to new version
9. Restart master-eligible nodes
10. Restart master-ineligible nodes
11. Optionally restart the tasks associated with ML jobs and datafeeds

Note that in a full cluster restart the master nodes must be started before the non-master nodes. This is to ensure that the master nodes can form the cluster in order to enable other nodes to join, and is contrary to a rolling upstart where the master-ineligible nodes should be upgraded before the master-eligible ones.

Rolling restart upgrade (online upgrade)

A rolling restart upgrade will upgrade a cluster without any downtime. In this case, each node is upgraded and restarted in turn without ever stopping the entire Elasticsearch cluster.

It is NOT possible to carry out rolling restart upgrades involving a change in MAJOR versions, with the exception of the following:

• Upgrading Elasticsearch version 5.6.16 to version 6.x.x
• Upgrading Elasticsearch version 6.8.23 to version 7.x.x
• Upgrading Elasticsearch version 7.17.10 to version 8.x.x

For this reason, if you want to carry out a rolling restart upgrade between major versions, you should ALWAYS use the latest minor version as a stepping stone to upgrade to the next major version. For example, if you are using Elasticsearch 5.x.x you can upgrade to 5.6.16 and then to 6.8.23.

The correct order for upgrading nodes

1. Begin by upgrading nodes that are not master-eligible. To find these nodes, use either the GET /_nodes/_all,master:false/_none API call or locate nodes configured with node.master: false.
2. Proceed with the upgrade tier-by-tier, starting with the frozen tier. Complete the upgrade for all nodes in each data tier before moving to the next one. Upgrade the frozen tier first, followed by the cold, warm, and finally the hot tier. This ensures that the data can still flow through the tiers during the upgrade. To obtain a list of nodes in a specific tier, use the GET /_nodes request. For example, GET /_nodes/data_frozen:true/_none.
3. Finally, upgrade the master-eligible nodes. Retrieve a list of these nodes using GET /_nodes/master:true.

Following this order guarantees that all nodes can join the cluster during the upgrade process. Upgraded nodes can join a cluster with an older master, but older nodes may not be able to join a cluster with an upgraded master.

How to upgrade nodes in a rolling upgrade

The process for upgrading your nodes is as follows, upgrading all NON master-eligible nodes first.

1. Make sure your cluster is stable, green
   You need to make sure that all replicas are available in order to ensure that shutting down the node will not result in loss of data.
2. Disable unnecessary indexing
   Wherever it is practically feasible to do so, you should stop all indexing processes, since this will increase cluster stability.
3. Optionally stop the tasks associated with ML jobs and datafeeds
   Even though it is possible to leave your machine learning jobs running during the upgrade process, that will put an unnecessary pressure on the cluster.
4. Disable shard allocation
   It is important to stop shards rebalancing so that when you stop a node for upgrade the cluster does not reallocate shards to another node. (See command below).
5. Stop the Elasticsearch node
   Stop the Elasticsearch node before moving on to the next step
6. Upgrade Elasticsearch
   The method used to upgrade will depend upon the installation method used to install.
7. Upgrade plugins
   Elasticsearch will not start if the plugin is not of exactly the same version as Elasticsearch.
8. Start Elasticsearch
   Start Elasticsearch before moving on to the next step.
9. Re-enable shard allocation
   Using the command given below.
10. Check that the upgraded node has rejoined the cluster
    Using the command below, you can check how many nodes are in the cluster.
11. Wait for cluster status to turn green
    The command provided below will also show you the progress of the shard recovery process on the upgraded node, until the cluster reaches a green state.Do not be in a hurry to upgrade your nodes, wait for the cluster to fully recover before moving on. If the cluster does not go green, look in the logs to find any issues that may indicate problems with the upgrade or configuration.
12. Repeat
    Repeat the full process above for each node.
13. Optionally restart ML jobs and datafeeds

To disable shard allocation, run:

PUT _cluster/settings
{
 "persistent": {
   "cluster.routing.allocation.enable": "primaries"
 }
}

To re-enable shard allocation, run:

PUT _cluster/settings
{
 "persistent": {
   "cluster.routing.allocation.enable": null
 }
}

Get cluster status and see how many nodes are in the cluster using:

GET _cluster/health

Related content

IntegrationsHow To

June 5, 2025

Making sense of unstructured documents: Using Reducto parsing with Elasticsearch

Demonstrating how Reducto's document processing can be integrated with Elasticsearch for semantic search.

AW

By: Adel Wu

Generative AIHow To

June 2, 2025

AI-powered case deflection: build & deploy in minutes

Exploring the AI Assistant Knowledge Base capabilities combined with Playground to create a self-service case deflection platform.

TM

By: Tomás Murúa

IntegrationsHow To

May 21, 2025

Get set, build: Red Hat OpenShift AI applications powered by Elasticsearch vector database

The Elasticsearch vector database is now supported by the ‘AI Generation with LLM and RAG’ Validated Pattern. This blog walks you through how to get started.

TP

By: Tom Potoma

Developer ExperienceJavascript+1

May 19, 2025

Elasticsearch in JavaScript the proper way, part II

Reviewing production best practices and explaining how to run the Elasticsearch Node.js client in Serverless environments.

JR

By: Jeffrey Rengifo

Developer ExperienceJavascript+1

May 15, 2025

Elasticsearch in JavaScript the proper way, part I

Explaining how to create a production-ready Elasticsearch backend in JavaScript.

JR

By: Jeffrey Rengifo