There are three different approaches to upgrading from Elasticsearch to OpenSearch.
- Full-cluster restart upgrade (in-place)
- Rolling restart upgrade (in-place)
- Restore snapshot (new cluster)
The recommended upgrade process for most of the Graylog community is the full-cluster restart upgrade (in-place). Therefore, this method will be the primary focus of our upgrade guide. You can, however, find a high-level overview of each method in the following sections to help you choose the right method for your needs and environment.
In-Place Upgrades
In-place upgrade methods repurpose your existing Elasticsearch nodes and are more like a software upgrade than a software migration. You will not need to create and restore a snapshot of your Elasticsearch data with an in-place upgrade.
The two types of in-place upgrades are a full-cluster restart and a rolling restart.
There are several differences between the two methods, most importantly, varying levels of complexity, risk for error, and downtime. The full-cluster restart process shuts down the entire Elasticsearch cluster while the rolling restart method only shuts down and upgrades one Elasticsearch node at a time until all nodes in the cluster are running OpenSearch.
Full-Cluster Restart
The full-cluster restart upgrade is generally considered the simpler of the two in-place upgrade methods. This method consists of shutting down the entire Elasticsearch cluster, installing and configuring the OpenSearch software, copying data from Elasticsearch data.dir file systems to OpenSearch data.dir file systems, and then starting up the OpenSearch cluster. This method requires your Graylog nodes to have sufficient available disk space to store all incoming messages in the journal while OpenSearch is installed and configured.
Before you install OpenSearch, find the PATH assigned to the data.dir of your Elasticsearch nodes. You can find this parameter and its assigned value within the elasticearch.yml files. This assigned value defines the file system location of your Elasticsearch indices and other data. It is important to note this location so you do not overwrite it during the installation or configuration of OpenSearch. If you plan to reuse the same file system location of your former Elasticsearch nodes, then there is no concern for overwriting your Elasticsearch indices.
After the OpenSearch software is installed and configured on each node of the Elasticsearch cluster, copy the data within the Elasticsearch nodes data.dir to the OpenSearch nodes data.dir. This enables you to reuse your existing data in the new OpenSearch cluster while offering a potential method to revert. It is technically possible to configure OpenSearch to use the same data.dir as the former Elasticsearch nodes; however, doing so prevents you from being able to revert to the previous working state.
Once the Elasticsearch data has been copied into the OpenSearch data.dir file system locations, all of the nodes of the OpenSearch cluster can be started. When the OpenSearch cluster reaches a "green" state, you will then need to restart all of your Graylog nodes to complete the upgrade process.
As the entire Elasticsearch cluster is offline in this method, no changes can be made to its data; therefore, no time is spent waiting on replication between shards, unlike with the rolling restart upgrade.
Rolling Restart
A rolling restart upgrade is defined here as keeping your Elasticsearch cluster online throughout the process of upgrading it to OpenSearch. This method is more complex, slower, and prone to error than a full-cluster restart, and it requires replicas for every index of every Graylog index set; however, it allows for the indexing of incoming messages and search queries to be serviced by Graylog throughout the upgrade process.
Steps involved with the rolling restart method span, but are not limited to, disabling and re-enabling shard allocation when you upgrade an Elasticsearch node to OpenSearch to waiting for the cluster to perform replication in the "yellow" state to then return to a "green" state before proceeding to upgrade the next Elasticsearch node in the cluster.
These steps can complicate what might otherwise be a more straightforward process to upgrade the entire Elasticsearch cluster while it is offline. And like a full-cluster restart, you need to make copies of Elasticsearch data.dir file systems for OpenSearch to reuse in a different file system location for its nodes' data.dir, unless you wish to forgo the potential of reverting.
Once all nodes have been successfully upgraded to OpenSearch and the cluster is in a healthy "green" state, the Graylog nodes must then be restarted as the final step in the upgrade process.
OpenSearch provides a detailed step-by-step description of how to upgrade Elasticsearch node(s) to OpenSearch node(s), including notation on specific steps to repeat when doing a rolling-restart upgrade.
New Cluster Upgrade
The new-cluster upgrade method requires a duplicate OpenSearch cluster configured exactly like your existing Elasticsearch cluster. This method can be done with virtual machines or other platforms that may not require new hardware and financial resources.
After installation and configuration validation, while running both clusters simultaneously, a snapshot of the data is created on the Elasticsearch cluster and restored to the OpenSearch cluster. After that, you must reconfigure Graylog to use the new OpenSearch cluster. Restart Graylog for the changes to take effect.
Another way of framing this method is a blue/green deployment. A great example of the new cluster upgrade method can be found with some vendors that offer Elasticsearch as a service and blue/green deployment features.
AWS OpenSearch Service
In some cases, Graylog environments make use of Elasticsearch as a service. The most common example is the Amazon AWS OpenSearch service, formerly Elasticsearch service. Upgrading from one major version of Elasticsearch to another (or to OpenSearch) is done via the new cluster upgrade method, e.g. blue/green deployment. This method only requires a change to the configuration of the AWS OSS domain that defines the version of Elasticsearch or OpenSearch to use, and AWS manages the rest of the upgrade.
As a best practice, create a snapshot before you initiate the upgrade. More information on this upgrade process can be found in the AWS documentation.
