Contact Free trial Login

Upgrading Mule Runtime Engine (Versions 4.x to 4.n)

To upgrade your current Mule instance to a later release of Mule runtime engine (version 4.x), you must follow some best practices. The following steps and recommendations help you to:

  • Update your standalone Mule instances.

  • Update your on-premises Mule instances managed through Runtime Manager.

  • Change the Mule version used to build your Mule applications, if necessary.

For guidance with migrations from Mule 3 to Mule 4, see Mule 4 for Mule 3 Users.

To change the Mule runtime engine version of your CloudHub workers, you need to use the runtime version drop-down box in the application settings deployment configuration page.

Ensuring Mule Application Compatibility

When you create a Mule application, you select the Mule runtime engine version that your application is intended to run on. This is the target Mule version of an application.

Because Mule runtime engine uses semantic versioning (MAJOR.MINOR.PATCH), Mule applications are:

  • Rarely compatible between major releases (3.9.3 to 4.1.0, for example).

  • Potentially compatible between minor releases (4.1.0 to 4.2.0, for example).

  • Fully compatible between patch releases (4.1.4 to 4.1.5 for example).

Sometimes it is necessary to change the target Mule version of your Mule applications to make them compatible with your new Mule runtime engine instance (either On-premises, or CloudHub worker).

Read the release notes for the Mule runtime engine version that you want to upgrade to and verify if you must make any compatibility changes to your Mule applications.

MuleSoft recommends executing a regression test cycle to validate compatibility between minor releases.

Changing the Target Mule Version of your Mule Application

In case you need to change your Mule application’s target Mule version, follow these steps:

  1. Download the desired Mule runtime engine in Anypoint Studio so that you can select that version in the IDE.

  2. For every application that you update:

    1. Import the application to Anypoint Studio as a Mule project.

    2. During the import process remember to change the target Mule version by selecting it from the Server Runtime menu.

      updating mule versions 415
    3. Make any other changes necessary to ensure compatibility with the Mule version you are transitioning to.

    4. Export your project as a Mule Deployable Archive (.jar file).

    5. Edit the pom.xml file to make the muleVersion property value match the target Mule version.

After you have successfully built the Mule Deployable Archives (.jar files) with the new target Mule version, and you have applied any other necessary changes to ensure compatibility, you can move on to upgrading the corresponding Mule runtime engine instances.

Upgrading a Standalone Mule Instance

To ensure less downtime and easier backups, first install the new Mule runtime engine on a separate server from that on which your current Mule runtime engine is installed. That way you can set everything up and only then initiate the new Mule instance and decouple the previous one.

If you are upgrading Mule in the same server or virtual machine, ensure that you remove the Mule service or daemon before you install the new Mule runtime engine as a service.

Steps to Upgrade the Mule Instance

  1. From the Customer Portal, download the Mule runtime engine version you want to upgrade to.

  2. If you run Mule as a service, install the new Mule version on a different server or virtual machine:

    • $MULE_HOME\bin\mule.bat install on Windows systems

    • $MULE_HOME/bin/mule install on Linux/Unix systems

  3. If any of your applications rely on a full or a partial custom patch to work properly (these are in the <MULE_HOME>/lib/patches directory), please verify that the fix is included in the new Mule version by reviewing the corresponding release notes page.

  4. Download a new copy of your license from the Customer Portal and install it on the new Mule instance (see Installing an Enterprise License for instructions).

  5. If you have custom configurations in your previous Mule instance (for example, if you defined a different maximum heap size in the wrapper.conf file), replicate these settings in the new Mule instance.

  6. Run your new Mule instance to verify that your installation is working as expected.

  7. After considering possible negative impact, you can shut down your previous Mule instance at this point.

  8. If you set environment variables such as MULE_HOME or PATH, verify that they point to the new Mule runtime engine’s installation path.

  9. Deploy your applications to your new Mule instance.

Upgrading an On-Premises Mule Instance Managed Through Runtime Manager

To ensure less downtime and easier backups, first install the new Mule runtime engine on a separate server from that on which your current Mule runtime engine is installed. That way you can set everything up. Shut down the previous Mule instance and only then initiate the new Mule instance.

To migrate following these steps, you must have the Runtime Manager Agent installed.

Steps to Upgrade the Mule Instance

  1. Go through steps 1 through to 5 of the previous section, Upgrading a Standalone Mule Instance.

  2. Copy the following three files from <MULE_HOME>/conf from your previous Mule instance into the same folder on the new Mule instance:

    • mule-agent.yml

    • mule-agent.jks

    • truststore.jks and/or anypoint-truststore.jks

  3. Copy the mule-agent-plugin folder from <MULE_HOME>/plugins from your previous Mule instance into the same folder on the new Mule instance.

  4. Shut down the previous Mule instance.

  5. Open a terminal window and navigate to the <MULE_HOME>/bin directory of your new Mule instance.

  6. Run the following command:

    amc_setup -U

    This command installs the latest version of the Runtime Manager Agent on your new Mule instance, ensuring compatibility. The files you copied from your previous Mule instance hold all of the configuration information to register the new Mule instance on Runtime Manager.

    Even when you’re installing your new Mule version on another server or VM, the copied configuration files should suffice to smoothly transition the Mule instance’s identity on Runtime Manager.

    If your previous Mule instance has apps deployed through Runtime Manager, there’s no need to manually copy them, as they automatically upload to your new Mule instance. This process automatically redeploys the applications to the new instance.

    If your previous Mule instance has apps that were manually deployed, you need to manually redeploy them.

    Applications must be running and showing as Started in Runtime Manager. This process does not migrate stopped Applications.

  7. At this point, your Mule instance is updated to the desired Mule version. Updating the target Mule version of your deployed applications is optional. If you decide to do so, then you must also:

    1. Follow the steps in Changing the Target Mule Version of your Mule Application.

    2. Find the application on the Applications tab on Runtime Manager and click Choose File to upload the new Mule Deployable Archive (.jar file).

Considerations About Clusters

Zero downtime cannot be guaranteed when upgrading the Mule runtime engine version of your Runtime Manager clusters. At some point during the upgrade, the cluster is in a mixed state, with coexisting nodes running two different Mule versions. This might lead to incompatible communication protocols between Hazelcast instances. When such errors occur, every node in the cluster must be shut down to proceed with the upgrade.

Was this article helpful?

💙 Thanks for your feedback!

Leave feedback…

We use cookies to make interactions with our websites and services easy and meaningful, to better understand how they are used and to tailor advertising. You can read more and make your cookie choices here. By continuing to use this site you are giving us your consent to do this.