Upgrading Lucenia

Lucenia releases regular updates that include new features, enhancements, and bug fixes. Lucenia uses Semantic Versioning, which means that breaking changes are only introduced between major version releases. To view a list of previous releases or to learn more about how Lucenia uses versioning, see Release Schedule and Maintenance Policy.

We recognize that users are excited about upgrading Lucenia in order to enjoy the latest features, and we will continue to expand on these upgrade and migration documents to cover additional topics, such as preserving custom configurations.

Workflow considerations

Take time to plan the process before making any changes to your cluster. For example, consider the following questions:

• How long will the upgrade process take?
• If your cluster is being used in production, how impactful is downtime?
• Do you have infrastructure in place to stand up the new cluster in a testing or development environment before you move it into production, or do you need to upgrade the production hosts directly?

The answers to questions like these will help you determine which upgrade path will work best in your environment.

At a minimum, you should be:

• Reviewing breaking changes.
• Reviewing the Lucenia tools compatibility matrices.
• Reviewing plugin compatibility.
• Backing up configuration files.
• Creating a snapshot.

Stop any nonessential indexing before you begin the upgrade procedure to eliminate unnecessary resource demands on the cluster while you perform the upgrade.

Reviewing breaking changes

It’s important to determine how the new version of Lucenia will integrate with your environment. Review Breaking changes before beginning any upgrade procedures to determine whether you will need to make adjustments to your workflow. For example, upstream or downstream components might need to be modified to be compatible with an API change.

Reviewing the Lucenia tools compatibility matrices

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

Reviewing plugin compatibility

Review the plugins you use to determine compatibility with the target version of Lucenia. 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 Lucenia plugins.

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

Backing up configuration files

Mitigate the risk of data loss by backing up any important files before you start an upgrade. Generally, these files will be located in either of two directories:

• lucenia/config
• opensearch-dashboards/config

Some examples include lucenia.yml, opensearch_dashboards.yml, plugin configuration files, and TLS certificates. Once you identify which files you want to back up, copy them to remote storage for safety.

If you use security features, make sure to read A word of caution for information about backing up and restoring your security settings.

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 on external storage, such as a mounted Network File System (NFS) or a cloud storage solution like those listed in the following table.

Upgrade methods

Choose an appropriate method for upgrading your cluster to a new version of Lucenia based on your requirements:

• A rolling upgrade upgrades nodes one at a time without stopping the cluster.
• A cluster restart upgrade upgrades services while the cluster is stopped.

Upgrades spanning more than a single major version of Lucenia will require additional effort due to the need for reindexing. For more information, refer to the Reindex API. See the Index compatibility reference table included later in this guide for help planning your data migration.

Rolling upgrade

A rolling upgrade is a great option if you want to keep your cluster operational throughout the process. Data may continue to be ingested, analyzed, and queried as nodes are individually stopped, upgraded, and restarted. A variation of the rolling upgrade referred to as “node replacement” follows exactly the same process except that hosts and containers are not reused for the new node. You might perform node replacement if you are upgrading the underlying host(s) as well.

Lucenia nodes cannot join a cluster if the cluster manager is running a newer version of Lucenia than the node requesting membership. To avoid this issue, upgrade the cluster-manager-eligible nodes last.

See Rolling Upgrade for more information about the process.

Cluster restart upgrade

Lucenia administrators might choose to perform a cluster restart upgrade for several reasons, such as if the administrator doesn’t want to perform maintenance on a running cluster or if the cluster is being migrated to a different environment.

Unlike a rolling upgrade, where only one node is offline at a time, a cluster restart upgrade requires you to stop Lucenia and OpenSearch Dashboards on all nodes in the cluster before proceeding. After the nodes are stopped, a new version of Lucenia is installed. Then Lucenia is started and the cluster bootstraps to the new version.

Compatibility

Lucenia nodes are compatible with other Lucenia nodes running any other minor version within the same major version release. For example, 0.1.0 is compatible with 0.1.7 because they are part of the same major version (0.x). Additionally, Lucenia nodes and indexes are backward compatible with the previous major version. That means, for example, that an index created by an Lucenia node running any 0.x version can be restored from a snapshot to an Lucenia cluster running any 1.x version.

Index compatibility is determined by the version of Apache Lucene that created the index. If an index was created by an Lucenia cluster running version 1.0.0, then the index can be used by any other Lucenia cluster running up to the latest 0.x or 1.x release. See the Index compatibility reference table for Lucene versions running in Lucenia 0.1.0 and later.

If your upgrade path spans more than a single major version and you want to retain any existing indexes, then you can use the Reindex API to make your indexes compatible with the target version of Lucenia before upgrading. One alternative to reindexing is to reingest data from the origin, such as by replaying a data stream or ingesting data from a database.

Index compatibility reference

If you plan to retain old indexes after the Lucenia version upgrade, then you might need to reindex or reingest the data. Refer to the following table for Lucene versions across recent Lucenia and OpenSearch releases.

_{A dash (—) indicates that there is no product version containing the specified version of Apache Lucene.}

---

Related articles

• Rolling Upgrade
• Upgrades appendix