How to Prepare an Elasticsearch Cluster for an Upgrade

Introduction

If you’re running an older version of Elasticsearch, you may be planning an upgrade in the near future. Upgrading your Elasticsearch cluster to the most current version is a smart move, allowing you to take advantage of new features, bug fixes and improved performance. It’s also possible to upgrade to even newer beta versions of the Elastic Stack, but these versions can be unstable and shouldn’t be tested in a production environment where there’s a risk of data loss or server downtime. In this article, we’ll provide a step-by-step guide to preparing your Elasticsearch cluster for an upgrade.

As of April 2019, the current, stable version of Elasticsearch is 7.x. For most versions of Elasticsearch, JDK 8 was the supported Java release; however, since v6.2 of Elasticsearch, Java 9 is supported as well.

Make sure to always consult the version of the Elasticsearch documentation that matches the version running on your server:

There is a dropdown menu on the right-hand side of Elastic’s website that allows you to change the documentation reference to match your specific version.

Back up data and create a snapshot

While there are a number of important actions to take when preparing for an upgrade, the most critical step before making any major changes to your Elasticsearch cluster is to back up all data, indices, and so forth. Any change or upgrade comes with a risk of data loss, and performing a backup will mitigate this risk.

If you want to keep the ability to downgrade, or revert your cluster and its indices to an earlier version, you’ll need to create a snapshot. An Elasticsearch ""_snapshot"" is essentially a backup of the cluster and its indices. You can back up the entire cluster or just a few indices, depending on your needs. You may not want to manage and deal with snapshots yourself– in that case, you can also use third-party libraries like curator to create backups and snapshots as well.

Creating a folder for your Elasticsearch snapshots

The next step in our upgrade preparation is to create a directory for the backup. We’ll use this folder’s path for the value of ""location"" when making the HTTP request to create a snapshot:

• Use the path that was returned by the pwd command

Keep in mind that while the snapshot tool can be very useful, it will not export data into other file formats (like JSON or CSV).

Exporting data outside of Elasticsearch

There are several ways to export Elasticsearch data, and there are tools to help you export the data to a CSV file format.

Make sure the indexes being exported are open:

If an Elasticsearch index is “closed” (meaning that the reading and writing of its data is disabled), it must first be opened using the Open Index API before it can be exported. Use the _cat/indices command to check if the index is open:

The status column of the returned output will tell you if it’s open or closed.

You can use a third-party plugin or application to export your Elasticsearch indices to a CSV or JSON file, if you don’t want to create a snapshot. One good option for exporting your data is Logstash, which is part of the Elastic Stack. To use Logstash to export Elasticsearch data to a CSV file, you’ll need two plugins: the Elasticsearch input plugin and the CSV output plugin.

Rolling Upgrades

Important: If your version of Elasticsearch is older than version 5.6, it’s recommended to first upgrade to version 5.6 before proceeding to upgrade to version 6.0 or beyond. The same holds true for those upgrading from 2.x to 5.x. See Elastic’s upgrade documentation for more details.

Aside from the exception of 5.6, rolling upgrades are usually no problem at all as long as the Elastic Stack stays within the major version– for example, upgrading from 6.2 to 6.7. If you’re upgrading from 5.6 you’ll need to perform a complete cluster restart.

If there are any indices that were created in Elasticsearch version of 2.x or older, then they must either be deleted, or re-indexed.

Understanding Upgrade Preparations

Best Practices for Upgrades

There are a few general rules to follow before migrating from one version to another version of Elasticsearch: Be sure to upgrade one node at a time when performing minor version migrations– for example, from 6.x to 6.y. Any major version upgrades require a full cluster restart. This is a key point to keep in mind if you’re planning to upgrade from 6.x to 7.

Deprecation Logging

Elasticsearch gives you the ability to enable logging of deprecated actions. This is an excellent way to stay on top of any feature or functionality that will soon lose its support. The default level of this logger is set to warn: `bash logger.deprecation.level = warn ` When you see various features and functionality being depreciated, it’s often a sign that it’s a good time to upgrade.

Back up Data — Snapshot

The easiest way to back up your indices is to create a “”snapshot”” of your Elasticsearch cluster. A snapshot is essentially a copy of all of the cluster’s indexes, placed into a repository on the same filesystem as the cluster.

Version Compatibility

Indices created in a specific major version number may not be compatible with other major versions of Elasticsearch. This means that a snapshot of an index created in version 5 can successfully be restored in an Elasticsearch cluster that’s been upgraded to 6, but an index created by a cluster running version 2.0 cannot. In addition, any indices that were created in version 1.x of Elasticsearch cannot be restored to version 5.x or 6.x.

If you need to restore an index from an older, incompatible version of Elasticsearch, you’ll need to rebuild the index in a different version of Elasticsearch—- one that the index is compatible with.

Repositories

Before you can create any snapshots or perform any restore operations, you must register a snapshot repository. It’s best to create a new snapshot repository for each major version of Elasticsearch.

The first step to perform before taking a snapshot or restoring an index is to register and give global access to the metadata of the repositories. This ensures that the cluster blocks are readable.

If a number of clusters are registered in the same repository, only one cluster should have write access to the repository. The other clusters registered to that repository would thus be set to readonly mode.

The ""fs"" type stands for the shared “”File System”” where your snapshots are stored. Other repository types, such as “”s3″” (S3 repository support), will require the use of a plugin.

You can use GET in a cURL request to retrieve the backup:

Elasticsearch will return a JSON object containing the backup and its location:

Conclusion

Upgrading your Elasticsearch cluster offers many benefits, such as bug fixes and new functionality; however, it’s a task that requires careful preparation to go smoothly. Any upgrade comes with a risk of data loss, so it’s important to take the proper steps to safeguard your data before moving forward with an upgrade. With the instructions outlined in this article, you’ll be ready to take all the steps needed to prepare for an Elasticsearch cluster upgrade.