Migrate or upgrade OpenSearch

The OpenSearch Project releases regular updates that include new features, enhancements, and bug fixes. OpenSearch uses Semantic Versioning, which means that breaking changes are only introduced between major version releases. To learn about upcoming features and fixes, review the OpenSearch Project Roadmap on GitHub. To view a list of previous releases or to learn more about how OpenSearch uses versioning, see Release schedule and maintenance policy.

Upgrading or migrating OpenSearch is essential for maintaining optimal performance, security, and access to the latest features. Whether you’re upgrading an existing OpenSearch deployment or migrating from another system such as Elasticsearch OSS, choosing the right approach is critical to a successful transition.

This page outlines upgrade planning guidance and four supported methods: rolling upgrades, snapshot and restore, remote reindexing, and using Migration Assistant.

---

Before you begin

Take time to plan the process before making any changes to your cluster:

• How long will the upgrade process take?
• Can your system tolerate downtime?
• Do you have the ability to test in a staging environment?

Make sure to:

• Review breaking changes.
• Check plugin compatibility.
• Review the OpenSearch tools compatibility matrices.
• Back up configuration files.
• Take a snapshot.

Stop nonessential indexing before upgrading.

---

Migration and upgrade methods

Rolling upgrade

Upgrade one node at a time while keeping the cluster operational.

Pros:

• Minimal downtime.
• No new infrastructure needed.

Cons:

• Supports only adjacent major versions.
• Multiple upgrade cycles for larger version gaps.
• Reindexing may be required.
• Manual reindexing may be required for full feature compatibility.

Perform a rolling upgrade.

---

Snapshot and restore

Take a snapshot of your current cluster and restore to a new OpenSearch version.

Pros:

• Supports large datasets and cold storage.
• Reversion is possible because the original cluster is untouched. However, there may be a loss of data if no change data capture (CDC) solution is in place.

Cons:

• Requires downtime or a CDC solution.
• Requires provisioning a new cluster.
• Manual reindexing may be required for full feature compatibility.

Get started with snapshot and restore.

---

Migration Assistant

Migration Assistant provides the most automated and resilient upgrade path.

Pros:

• Handles multi-version hops, allowing for seamless upgrades across multiple versions.
• Live data capture allows for little to zero downtime, ensuring data consistency during migrations.
• Ability to revert changes if issues arise during or after the upgrade.

Cons:

• Requires additional setup.
• Requires additional infrastructure.

Get started with Migration Assistant.

---

Remote reindexing

Reindex data from the old cluster into the new OpenSearch cluster.

Pros:

• No downtime.
• Supports large version jumps.

Cons:

• Slower and more resource intensive.
• Can degrade source cluster performance.

Learn more in the Reindex API documentation.

---

Additional considerations

Before proceeding with your chosen migration or upgrade method, review the following compatibility requirements.

Reviewing the OpenSearch tools compatibility matrices

If your OpenSearch cluster interacts with other services in your environment, like Logstash or Beats, then you should check the OpenSearch tools compatibility matrices to determine whether other components will need to be upgraded.

Reviewing plugin compatibility

Review your plugins to determine compatibility with the target version of OpenSearch. Official OpenSearch Project plugins can be found in the OpenSearch Project repository on GitHub. If you use any third-party plugins, then you should check the documentation for those plugins to determine whether they are compatible.

Go to Available plugins to see a reference table that highlights version compatibility for bundled OpenSearch plugins.

Major, minor, and patch plugin versions must match OpenSearch major, minor, and patch versions in order to be compatible. For example, plugin versions 2.3.0.x work only with OpenSearch 2.3.0.

---

Backing up configuration files

Back up important files such as opensearch.yml, plugin configurations, and TLS certifications from these paths:

• opensearch/config
• opensearch-dashboards/config

See this security configuration guidance.

---

Creating a snapshot

We recommend that you back up your cluster state and indexes using snapshots. Snapshots you take before an upgrade can be used as restore points if you need to roll back the cluster to its original version.

You can further reduce the risk of data loss by storing your snapshots in external storage, such as a mounted Network File System (NFS) or a cloud storage solution like those listed in the following table.

---

Index compatibility reference

_{A dash (—) indicates that no version contains the listed Lucene version.}