Upgrade EMQX Cluster from 4.4 to 5.x

This page provides instructions on how to upgrade your EMQX cluster to the latest version.

Since EMQX 5.x is not backward compatible with version 4.x in terms of configurations, management APIs, and clustering APIs, a rolling upgrade from an early version is not supported. To ensure a successful upgrade, read the Considerations Before You Start carefully before you start the upgrading procedure.

If you encounter any problems during the upgrade, contact EMQX Support.

TIP

Note that performing a fresh installation of the current version will not preserve your existing cluster configuration. You can refer to Installation for a fresh installation.

Intended Audience

This instruction is intended for anyone who needs to upgrade from earlier versions of EMQX and experienced Linux system administrators familiar with data center operations.

Considerations Before You Start

Before you start the upgrade, be aware of the requirements, incompatible changes, and potential pitfalls described in this section.

Upgrade Version Path

To upgrade an existing EMQX Cluster to version 5.1 or later, you must currently be running a 4.4.x release.

If you are running a version earlier than 4.4.x, you must first upgrade through successive major releases until you reach version 4.4.x. For example, if you are currently running version 4.3.x, you must first upgrade to version 4.4 before proceeding to upgrade to 5.x. Refer to the 4.4 upgrade guide for instructions.

Incompatible Changes

You need to resolve all incompatibilities or conflicts with your current deployment before starting the upgrade. To identify the potential compatibility issues and breaking changes that may affect your applications and deployments, you can refer to Incompatible Changes between EMQX 5.1 and EMQX 4.4, and the following incompatible changes documents in later versions:

It is also advisable to thoroughly test your application in a staging environment before deploying the upgrade to your production environment. This will help ensure a smooth transition and minimize any potential disruptions.

Client Applications and Data Bridge Compatibility

Running upgraded deployments with incompatible clients and data bridge versions may result in unexpected or undefined behavior. Therefore, it is important to make sure that your client applications and data bridge backend services are compatible with the latest EMQX version. You can refer to Data Integration Incompatibility Between EMQX 5.1 and EMQX 4.4 and Client SDKs to verify the compatibility with EMQX 5.x.

Potential Pitfalls

During the upgrade process, it is important to be aware of common potential pitfalls, including:

Incompatibilities between the upgraded EMQX version and your client applications.
Configuration changes that may be required to adapt to the new version.
Dependencies on external systems or services that may need to be updated or reconfigured.

To mitigate these pitfalls, read the latest version of EMQX documentation carefully and perform thorough testing in a staging environment before applying the upgrade to your production environment. Additionally, consider engaging the support services provided by EMQX to ensure a smooth and successful upgrade.