Upgrade to OpenSearch 3.x with Data Node

Graylog's Data Node ships with both OpenSearch 2.19.x and OpenSearch 3.x bundled together. Data Node can manage the upgrade of your embedded OpenSearch from 2.19.x to 3.x via a wizard for most environments.

If any of your indices were created under an OpenSearch version older than 2.0, they are incompatible with OpenSearch 3.x and prevent the automatic upgrade from completing. Graylog notifies you when incompatible indices are present. This article explains how to resolve incompatible indices so Data Node can complete the OpenSearch upgrade.

Important: Upgrading to OpenSearch 3.x when incompatible indices are present is not supported for Graylog installations that use self-managed OpenSearch. Additional support for self-managed OpenSearch upgrades is planned for a future release. New installations of Graylog that use self-managed OpenSearch can use OpenSearch 3.x.

Prerequisites

Before proceeding, ensure that the following prerequisites are met:

You must be a Graylog administrator.
Back up your Graylog, MongoDB, and Data Node data before starting. See Backup and Restore Best Practices for more information.

Important: If you archive or delete incompatible indices as part of this upgrade, snapshots taken before that point may not restore correctly on OpenSearch 3.x. Take a new snapshot after you resolve incompatible indices and before you start the OpenSearch upgrade.

Review the OpenSearch Upgrade Status

To review the status of your OpenSearch upgrade:

Navigate to System > Cluster Configuration, then select the Data Node Upgrade tab.
Confirm the cluster health indicator reads GREEN before proceeding. If the indicator reads a different status, resolve the underlying cluster health issue before you continue.
Review the Upgrade Data Nodes' embedded OpenSearch section for your Current OpenSearch and Target OpenSearch versions.

Resolve Incompatible Indices

Indices created under an incompatible OpenSearch version are listed as follows, categorized as:

Managed: Indices Graylog created and manages, including indices on the hot and warm tiers.
System: Internal indices OpenSearch uses to operate.
Foreign: Indices not created by Graylog.

You must resolve every incompatible index before you can start the OpenSearch upgrade. You can act on each index individually using the action buttons in its row, or select multiple indices and use Bulk actions.

Resolve Managed Indices

Warning: You cannot reindex an incompatible managed index. You must delete it, optionally archiving it first.

Hint: Archiving is a Graylog Enterprise feature. A valid Graylog Enterprise license is required. If you do not have a license, or archiving is not configured, you can only delete incompatible managed indices.

For each incompatible managed index:

If the index is the active write index of its index set, rotate it. You cannot delete an index while it serves as the active write index.
Archive and delete the index, or delete it without archiving.

Confirm the action when prompted.

Resolve System Indices

For each incompatible system index, reindex it.

Resolve Foreign Indices

Warning: Deleting a foreign index is permanent and cannot be undone.

For each incompatible foreign index, delete it, then confirm the action when prompted.

Start the OpenSearch Upgrade

After you resolve every incompatible index, the upgrade action becomes available. The method depends on how many Data Nodes you are running.

Warning: After the upgrade starts, you cannot return to the previous OpenSearch version.

Upgrade a Cluster With Three or More Data Nodes

A rolling upgrade is available for clusters with three or more Data Nodes. Data Nodes are upgraded one at a time and the process is fully automated, so the cluster remains available with no downtime.

Important: The upgrade restarts every Data Node, one at a time, to move its embedded OpenSearch to the target version. The manager node restarts last. Shard allocation is paused during each node's restart, so the cluster stays available, though indexing and search may be briefly degraded while a node leaves and rejoins. After each node restarts, Graylog waits for the cluster to return to green before continuing. If the cluster does not return to green in time, the upgrade pauses and waits for you to resume.

Upgrade a Cluster With Fewer Than Three Data Nodes

A rolling upgrade is not available for clusters with fewer than three Data Nodes. Instead, you can apply the OpenSearch upgrade on the next restart. The upgrade takes effect when you restart your Data Nodes, which means you control when the downtime occurs.