Upgrading from Elasticsearch 2.x to 5.0

Elasticsearch 5.o is still very new and most of you will want to wait a while and see how it’s doing before upgrading production clusters. However, the time for an upgrade will come eventually and here is my experience from the upgrade process.

Elasticsearch has a direct upgrade path only from version 2.x to 5.0. If you have a version older than 2.x you will have to upgrade to 2.0 before going on to 5.0.

Elasticsearch released a new migration plugin along with their new version. This plugin is supposed to check your system and determine if it is ready for upgrade.

The procedure described here was tested with an Elasticsearch 2.4 that was installed on Centos 6.8 using yum.

First of all, lets point our browser to port 9200 and see the current version:

  "name" : "Achilles",
  "cluster_name" : "elasticsearch",
  "cluster_uuid" : "H_lIQGVrQk627jsQTdVgnw",
  "version" : {
    "number" : "2.4.1",
    "build_hash" : "c67dc32e24162035d18d6fe1e952c4cbcbe79d16",
    "build_timestamp" : "2016-09-27T18:57:55Z",
    "build_snapshot" : false,
    "lucene_version" : "5.5.2"
  "tagline" : "You Know, for Search"

You can see the current version is 2.4.1.

Installing and running the migration helper plugin

export PATH=$PATH:/usr/share/elasticsearch/bin

[[email protected] elasticsearch]# plugin install https://github.com/elastic/elasticsearch-migration/releases/download/v2.0.2/elasticsearch-migration-2.0.2.zip
-> Installing from https://github.com/elastic/elasticsearch-migration/releases/download/v2.0.2/elasticsearch-migration-2.0.2.zip...
Trying https://github.com/elastic/elasticsearch-migration/releases/download/v2.0.2/elasticsearch-migration-2.0.2.zip ...
Downloading ...............................DONE
Verifying https://github.com/elastic/elasticsearch-migration/releases/download/v2.0.2/elasticsearch-migration-2.0.2.zip checksums if available ...
Downloading .DONE
Installed elasticsearch-migration into /usr/share/elasticsearch/plugins/elasticsearch-migration

Now point your browser to the plugin’s URL:

http://[server name]:9200/_plugin/elasticsearch-migration

You will be presented with a welcome screen that links you to the plugin’s Three sections: Cluster checkup, Reindex helper and Deprecation logging:

View full size image

Choosing cluster checkup leads to a short description and a color code list. From here you can run the checks:

At first run I had some faults like unsupported plugins and insufficient system resources:

If you click on the reindex helper you will see deprecated indexes that should be recreated (I did not have any):

And the deprecation log link can just toggle deprecation logging on or off. When it’s on Elasticsearch writes a new, different, log file with only deprecated actions and objects.

So, to comply with the cluster checkup I had to remove some old plogins like the license plugin which is now part of the X-Pack, and my beloved elastic-hq plugin.

After that my cluster passed the test and I could go on.

Upgrading Elasticsearch itself

Upgrading between major versions, as we perform here, require full cluster restart.

The whole process is described here.

First we disable shard allocation, so shutting down a node will not copy its shards to other nodes:

curl -XPUT '' -d'
"persistent": {
"cluster.routing.allocation.enable": "none"

"acknowledged" : true,
"persistent" : {
"cluster" : {
"routing" : {
"allocation" : {
"enable" : "none"
"transient" : { }

Then we perform a synced flash in order to speed up node recovery:

curl -XPOST ''

Now we should stop all running Elasticsearch services on all nodes and for each node execute:

Replace the old 2.x yum repository with the new 5.0 one:


rm -f /etc/yum.repos.d/elasticsearch.repo

echo "[elasticsearch-5.x]
name=Elasticsearch repository for 5.x packages
type=rpm-md" > /etc/yum.repos.d/elasticsearch.repo

Then clean yum metadata and run update:

yum --enablerepo=elasticsearch-5.x clean metadata

yum update elasticsearch

This is how it runs:

---> Running transaction check
---> Package elasticsearch.noarch 0:2.4.1-1 will be updated
---> Package elasticsearch.noarch 0:5.0.0-1 will be an update
---> Finished Dependency Resolution

Dependencies Resolved

Package Arch Version Repository Size
elasticsearch noarch 5.0.0-1 elasticsearch-5.x 31 M

Transaction Summary
Upgrade 1 Package(s)

Total download size: 31 M
Is this ok [y/N]: y
Downloading Packages:
elasticsearch-5.0.0.rpm | 31 MB 03:41
Running rpm_check_debug
Running Transaction Test
Transaction Test Succeeded
Running Transaction
Updating : elasticsearch-5.0.0-1.noarch 1/2
warning: /etc/elasticsearch/elasticsearch.yml created as /etc/elasticsearch/elasticsearch.yml.rpmnew
Cleanup : elasticsearch-2.4.1-1.noarch 2/2
Verifying : elasticsearch-5.0.0-1.noarch 1/2
Verifying : elasticsearch-2.4.1-1.noarch 2/2

elasticsearch.noarch 0:5.0.0-1


Note that the installation did not overwrite the old configuration file but created a new one, elasticsearch.yml.rpmnew.

Running diff on the new and old config file yields some minor differences in parameter names, like  “bootstrap.mlockall” that became “bootstrap.memory_lock” in the new version.

So you should use the new file and edit the appropriate parameters like network.host, http.port, discovery.zen.ping.unicast.hosts and node.name.

After that, it is a good idea to upgrade any plugins you have that support the new version (if they do not support it yet, like elastichq, you should just remove them for now).

Now start all nodes. When I tried to start, elasticsearch immediately stopped and a look at the log file revealed the reason:

java.lang.IllegalArgumentException: Property [elasticsearch.version] is missing for plugin [elasticsearch-migration]
at org.elasticsearch.plugins.PluginInfo.readFromProperties(PluginInfo.java:104) ~[elasticsearch-5.0.0.jar:5.0.0]
at org.elasticsearch.plugins.PluginsService.getPluginBundles(PluginsService.java:370) ~[elasticsearch-5.0.0.jar:5.0.0]
at org.elasticsearch.plugins.PluginsService.<init>(PluginsService.java:143) ~[elasticsearch-5.0.0.jar:5.0.0]
at org.elasticsearch.node.Node.<init>(Node.java:281) ~[elasticsearch-5.0.0.jar:5.0.0]
at org.elasticsearch.node.Node.<init>(Node.java:220) ~[elasticsearch-5.0.0.jar:5.0.0]

It turns out that the migration helper plugin we installed earlier isn’t compatible with version 5.0, so we will have to uninstall it first:

elasticsearch-plugin remove elasticsearch-migration

After that Elasticsearch started normally. At first the nodes status will be Red for a while, until they recover all primary shards, then they will turn Yellow. You can check the node status using this:

curl -XGET ''

Now we can re enable allocation of secondary shards:

curl -XPUT '' -d'
 "persistent": {
 "cluster.routing.allocation.enable": "all"

Now the secondary shards allocation will begin and when it is done, the status will turn Green. Now the cluster is upgraded and ready to use. You can see here that the version is now 5.0:

  "name" : "node-1",
  "cluster_name" : "guy",
  "cluster_uuid" : "4ai-opmGSKiVDkUPZobekw",
  "version" : {
    "number" : "5.0.0",
    "build_hash" : "253032b",
    "build_date" : "2016-10-26T04:37:51.531Z",
    "build_snapshot" : false,
    "lucene_version" : "6.2.0"
  "tagline" : "You Know, for Search"

You can look here if you want to see how to install the new X-Pack.


This entry was posted in ElasticSearch and tagged , , . Bookmark the permalink.

One Response to Upgrading from Elasticsearch 2.x to 5.0

  1. Aaron St. Clair says:

    I searched around for a while before finding your guide. I had previously installed my Elasticsearch 2.x using RPM instead of yum. Using your method allowed me to perform a seamless upgrade to 5.x without having to worry about which data files I need to retain.

Leave a Reply