Data Node Migration

The following guide provides information on the in-place migration wizard available in the Graylog interface. Note that this method is generally suitable for users meeting the prerequisites who wish to migrate in place; however, additional migration options may be available to you. If you are running more than three nodes in your existing OpenSearch/Elasticsearch cluster OR you have TLS or encryption enabled for data in transit on your OpenSearch/Elasticsearch instance, then you may reach out to Graylog Support for assistance with your Data Node migration. This assistance is available for users on both Graylog Open and Graylog Enterprise.

In-place migration allows you to transition from an existing self-managed OpenSearch instance to the Data Node architecture. The goal of an in-place migration is to minimize downtime, maintain data integrity, and reduce the need for extensive data movement or additional infrastructure.

The Data Node migration wizard walks you through the steps to complete your data migration from an existing self-managed search backend to the Graylog Data Node. If you are already using OpenSearch with a supported version for use with Graylog, using the wizard to transition to Data Node is recommended.

Hint: With in-place migration, data is not technically migrated. Instead, the new data node uses the existing data directory of OpenSearch to serve all data previously available in your existing OpenSearch node or cluster. In addition, you do not have a choice of what data to transition. All existing nodes and indices transition to Data Node.

Prerequisites

Graylog 6.1 or later.
Elasticsearch is not supported for in-place migration. You must have an existing self-managed OpenSearch instance with a version of 1.13 or later. Be aware that the OpenSearch version cannot be newer than version 2.15, which is installed with Data Node. For more information on migrating from Elasticsearch to OpenSearch, see the OpenSearch documentation.

Warning: Be aware that you are working with live and possibly production data. Any migration carries the risk of data loss. Be sure that you have created appropriate backups of the data you wish to migrate. For complete information, see Backup Considerations.

Perform an In-Place Migration

To perform an in-place migration to Data Node, follow the steps outlined here as well as the information provided on the page.

Warning: Several of the pages within the migration wizard include instructions for actions you need to complete outside of the Graylog web interface. It is crucial to your migration success that you read all on-screen instructions carefully and perform all actions required before continuing to the next step.

Navigate to the Data Node page from System > Data Node and select the Migration tab.

Hint: The Migration tab is available only if you are not already using Data Node. After you migrate, or if you have completed a fresh installation of Graylog using Data Node, this tab is not present.

The Welcome screen for the migration wizard provides information about Data Node, including some minimal requirements. Graylog also finds all search backends (nodes) you have configured and lists them here. These nodes contain the data that is available to migrate to Data Node.

When you are ready to proceed, go to the next step.
Create the certificate authority (CA) if none exists, or upload you own CA.

Hint: This step is automatically skipped if your existing cluster already has a valid certificate. Use the Configuration tab on the Data Nodes page to update certificates or renewal policies later if necessary.

Click Create CA to allow Graylog to configure a CA for your Data Nodes.

To use your own CA, click the Upload CA tab, then provide a single file that contains both the private key and the CA certificate as well as any intermediate certificates. The file can be formatted as PEM or PKCS #12. If the private key is encrypted, you also need to provide the password. Click Upload CA.

Click Configure certificate renewal policy to continue.
Set the certificate renewal policy.

Hint: This step is automatically skipped if your existing cluster already has a valid certificate. Use the Configuration tab on the Data Nodes page to update certificates or renewal policies later if necessary.

Click Configure Certificate Renewal Policy. In the dialog box, select the Certificate Renewal Mode:
- Automatic: (Default) Renews all expiring certificates without user interaction.
- Manual: Creates a system notification when one or more certificates are about to expire. You must manually renew certificates.
Set the Certificate Lifetime. This value determines the length of the validity of newly created certificates. The default value is 30 days.

Click Update configuration, then click Go to migration steps to continue.
Complete the following actions detailed on the page outside the Graylog web interface:
- Install Data Node on every OpenSearch instance from your previous setup. Follow the installation instructions for your operating system to install the correct package.
- Increase your journal size to account for journal downtime during migration.
  
  Hint: You are also prompted at Step 7 below about journal size, where you receive additional information from your environment to help you determine the correct journal size. This action is the one from this list that you can safely wait to complete until prompted again.
- Ensure the opensearch_data_location property in the Data Nodes configuration file (datanode.conf) for every node points to the correct existing OpenSearch data directory.
- Add the JWT authentication snippet, found on screen, to your opensearch-security/config.yml file, and replace the signing key with your GRAYLOG_PASSWORD_SECRET in base64 encoding.
Warning: You must complete each of the steps above outside of the Graylog web interface for your migration to be successful!

After you complete all external steps, click Run directory compatibility check to continue.
Run compatibility checks.

This stage in the wizard runs compatibility checks automatically and tells you if your data can be migrated to Data Node. Errors might include:
- Non-Graylog data in an OpenSearch node.
- OpenSearch version higher than the Data Node OpenSearch version.
The checks are performed across all nodes that have been identified. If any issues are detected, you are unable to proceed with migration.

Hint: This portion of the wizard also displays the OpenSearch version that is installed with the migration and will run as your Data Node search backend as well as the data node location (path). This area also displays a gray box that shows the total number of indices the wizard has identified, which could help you validate that it has identified all the data you expect.

Click the node link to open the detail page for information about the node. This information can be useful for troubleshooting.

Click Next to continue.
Provision the data node’s certificate.

Hint: This step is skipped if certificates are already provisioned for each node.

The wizard provisions the Data Node using the CA and certificate information provided previously.

When provisioning is complete, click Next to continue.
Acknowledge the journal downtime warning.

During the migration, data processing stops on your Graylog node, which results in the journal size growing. If you are unable to complete the next three steps before your journal size is exceeded, you will begin to lose data.

This section shows your current journal size and current journal throughput, along with an estimation of the maximum amount of downtime before you would start losing data. Again, the downtime is the amount of time it takes you to complete the next three steps, which all must be completed outside of Graylog.

If you will not be able to perform the required configuration changes in the stated timeframe, you should increase your journal volume size. To change journal size, open your server.conf file and update the message_journal_max_size property as necessary.

Click Next to continue.
Stop the original search backend.

You must stop your original OpenSearch node or nodes via the command line. After the switch to Data Node, Graylog manages the OpenSearch service. The actual command you use varies depending on how and where you are running OpenSearch. For example, if you are on Ubuntu with the default installation location, you could use:
Copy
```
sudo systemctl stop opensearch.service
```
After you complete this step, click Next.
Remove (or comment out) the elasticsearch_hosts line from server.conf file.

Removing this configuration property stops Graylog from looking for an independent search backend and allows Data Node to start.
After all data nodes are AVAILABLE, restart the Graylog server via the command line. For an Ubuntu installation, use:
Copy
```
sudo systemctl restart graylog-server.service
```
Click Next to complete the migration wizard.

At this point, your search backend management has switched to Data Node. Select the Data Nodes tab to view and manage your Data Nodes.